release: 0.89.0 (improvement/e22_5-backend-logging)

chore(release): 0.89.0
fix(logs): deep-review round 3 — a failure nobody could record is one scrubbed line
2026-09-19 00:05:53 +02:00 · 2026-09-19 00:05:47 +02:00 · 2026-09-18 23:44:42 +02:00 · 2026-09-18 22:50:37 +02:00 · 2026-09-18 03:16:15 +02:00 · 2026-09-18 01:28:52 +02:00
557 changed files with 35575 additions and 5083 deletions
@@ -28,6 +28,14 @@ ALLOWED_EMAILS=
 # Admin emails (subset of the above) get the admin role.
 ADMIN_EMAILS=
 # Logging (E22). LOG_LEVEL is the BOOTSTRAP level — the level a process starts at and the only one
 # the worker/download child read; the API's running level is the admin Configuration page's
 # `log_level` knob, which takes effect without a restart. TRACE | DEBUG | INFO | WARNING | ERROR, in
 # any letter case; any other value stops the boot with an error. LOG_FORMAT is "json" (one object per
 # line — what a log collector ingests) or "text" (a readable line for a local terminal).
 LOG_LEVEL=INFO
 LOG_FORMAT=json
 # Optional: origin of a separately-served frontend dev server (enables CORS). Leave empty in production.
 FRONTEND_ORIGIN=
@@ -7,6 +7,173 @@ edit the release notes and re-run the generator.
 Upgrading, pinning a version and rolling back: [docs/self-hosting.md](docs/self-hosting.md#upgrading).
 ## 0.89.0 — 2026-09-19
 A release for the log rather than for the screen: what the server writes down when something fails is now complete, said once, and free of what you downloaded or searched for.
 ### Fixes
 - A download that failed because the server lost its database for a moment no longer shows the video's title and file path inside the database's own error message.
 ### Internal
 - No log line carries what a person typed, watched or downloaded: search terms, titles, channel names, file paths, links and video ids are taken out — also from yt-dlp's and ffmpeg's own text, from error stacks, and from database errors. The one exception is Full diagnostics, and only under the user's own consent.
 - Every one of the backend's 114 swallowed exceptions was ruled on: 44 now leave a line with an event code, the other 70 say in the code why they need none — and a test keeps it that way. A failure is logged once, with its stack when it is our own bug, and a stalled or killed download no longer fails without a line.
 - yt-dlp's own explanations (“Requested format is not available”, a sign-in wall) reach the log instead of a stdout nobody read, and a burst of identical lines is summarised instead of flooding the stored log.
 - Three adversarial review rounds: 49 findings raised, 42 survived three independent attempts to refute them, all fixed, and every regression test was proven to fail with its own fix removed.
 ## 0.88.0 — 2026-09-18
 When something goes wrong, you can now turn on detailed logging for yourself for 24 hours — and read your own log on the spot, before any of it is sent anywhere. Siftlode also has a privacy policy and terms at last, in both languages, saying exactly what is recorded and for how long.
 ### Features
 - Settings → Diagnostics: choosing Detailed or Full changes nothing until you confirm a box that tells you what will be recorded, that the server keeps it, for how long, and that it switches itself off after 24 hours. Going back to Basic needs no confirmation and takes effect at once.
 - “My log”, on the same tab, shows what your browser has recorded — newest first, any line openable. Nothing leaves the browser before you have consented.
 - What you search for and filter by is recorded only at Full, and only under your own consent — never an administrator's. Passwords, tokens, cookies and email addresses are recorded at no level, by anyone.
 - Your last sign-in is shown in your account panel, and in the administrator's user list.
 - A privacy policy and terms of service, in Hungarian and English, covering what the server logs and what each diagnostics level adds.
 - Administrators get a Diagnostics section in Configuration: the log level takes effect without a restart, and stored logs are cleaned up on a schedule (7 days by default).
 - Every setting with a fixed set of values is now picked from those values instead of typed in, so a wrong one can no longer be saved.
 ### Fixes
 - Every message arrived twice if you left a conversation and came back quickly: two chat connections stayed open where there should have been one.
 - Settings was unusable on a phone — the tab rail took the width and left almost nothing for the panel beside it.
 - Dates and numbers follow the language you picked in Siftlode, not the one your computer happens to be set to. An English Siftlode on a Hungarian machine no longer shows Hungarian dates.
 - An administrator setting shown as a dropdown opened on its first option instead of the one actually in force.
 - In Hungarian, the audit log and the new log settings had names you could not tell apart.
 - The scheduled feed poll now covers only channels somebody actually follows — on this instance 582 of 979 polled channels had no follower at all. The trade-off is deliberate: new uploads from a channel nobody follows no longer appear in the shared Library.
 ### Internal
 - One logging mechanism replaced four. The API, the worker, the downloader and the migration tool now write the same structured line; secrets are scrubbed where the line is written rather than at each of ~125 places that write one; and every request carries an id that joins a line from your browser to the server line of the same request. The browser's log uses the same shape and the same redaction rules, checked from both sides against one shared set of cases.
 - Two adversarial review rounds over the epic: 56 findings raised, 32 survived three independent attempts to refute each, all fixed. Every regression test was proven to fail with its own fix removed — which is how a test that passed only on leftover state from an earlier test was caught, and how a focus bug that jsdom could not reproduce at all was settled in a real browser.
 ## 0.87.1 — 2026-09-16
 A YouTube video that YouTube will only show to a signed-in viewer can now be downloaded: paste your YouTube cookies in Settings the way the failure message already told you to — until now that list had no YouTube in it.
 ### Features
 - YouTube joins the sites you can store download cookies for (Settings → Account → Download authentication). A signed-in YouTube download automatically uses the players that accept your login.
 ### Fixes
 - A YouTube download that stops at “Sign in to confirm you’re not a bot” says so in your language and points at a setting that now exists. If you had already added cookies, it tells you they were refused instead of asking for them again.
 - A video YouTube describes but then refuses to hand over is tried again with another player instead of failing at once, and it is no longer called a network error — nothing was wrong with the network.
 ### Internal
 - The gated video was measured end to end on an isolated stack before and after the fix: every player client, two yt-dlp versions, and finally the real download (519 MB) with cookies attached. One deep-review round — 25 findings raised, none survived adversarial verification, and the one real defect came out of the verification itself: a comment of mine named an error yt-dlp does not raise there. Running it settled what reading it could not.
 ## 0.87.0 — 2026-09-15
 A shared or library video keeps playing when you switch apps on an iPad, and a new tab opens as the account it belongs to without flashing another page first. Facebook reels keep their titles and an mp3 stays an mp3.
 ### Features
 - Background play on iPad (Brave): the shared-video page, the library player and the Plex player keep playing in another app and on the locked screen.
 - The shared-video page has a Repeat toggle, on by default.
 - Switching modules no longer flashes a loading screen: the pages load quietly in the background, and a slow answer shows its spinner only after a moment.
 ### Fixes
 - A new tab honours your Startup choice and opens as its own account — no Home page flash, no other account's language or settings on the first frame.
 - A signed-in Facebook reel keeps its real title instead of “Video” or “Facebook”, and an mp3 download stays an mp3 (it used to be wrapped into an mp4 an iPad would not play).
 - A tab whose account was signed out, suspended or signed out everywhere acts as nobody and comes back as the account still signed in, instead of writing into another account or sticking on the sign-in page.
 - Switching or adding an account no longer saves the video you were watching into the other account's resume position.
 - A new tab keeps the account's notification history instead of replacing it with its own first notice.
 - The shared-video page tells a failed load, a wrong password, too many attempts and an unreachable server apart, with Retry where it helps. Its password limit counts per viewer, so one person guessing cannot lock everyone else out.
 - Form errors on sign-in, the message passphrase, password change and setup are read out by screen readers — again on a second identical failure — and the setup wizard names what is wrong instead of a generic error.
 ### Internal
 - WebKit and iPad projects in the Playwright suite; the Vite dev proxy forwards websockets.
 - Four deep-review rounds (12 → 8 → 8 → 8, the last one targeted), every regression test mutation-checked; half of the later rounds' findings were older defects, fixed here.
 ## 0.86.0 — 2026-09-14
 A failed download now tells you why it failed and what you can do about it, instead of repeating yt-dlp's raw error. Facebook comes first: downloads that used to die on “Cannot parse data” go through, and a Facebook group post downloads its own video instead of a different one from the page.
 ### Features
 - A failure says why, in your language: the row names the cause (“Facebook needs you to be signed in”, “Facebook did not accept your cookies”, “No video found in this post”) and its details window says what to do next. The raw error text is still there below it.
 - A Facebook download with your cookies that stops at “Cannot parse data” is tried again as Chrome, which gets past it.
 - A Facebook group post link downloads the post's own video. Before, yt-dlp either found nothing or quietly downloaded another video from the page; a post without a video now says so.
 - Retry and Re-download use a cookie you added after the failure, so the Retry the message asks for actually goes out signed in.
 ### Fixes
 - A Re-download of a download that needed your cookies used to rebuild without them.
 - A job queued behind a download that already failed shows that failure's explanation instead of a bare “Download failed”.
 - A download yt-dlp reports no length for takes its length from the file, so its Edit / trim action appears.
 - Pressing Pause, Stop or Remove twice, or in two tabs, can no longer free a file another download still uses.
 - The confirm buttons in Downloads name the action (Stop download, Re-download, Remove) instead of repeating the question.
 ### Internal
 - Four sprints, each Facebook behaviour measured on the development server with a real cookie before it was built. Two epic-end review rounds (20 → 17 fixed, then a targeted 4 → 4), every regression test mutation-checked.
 ## 0.85.0 — 2026-09-13
 Siftlode can now be driven from the keyboard, and Back, dialogs and menus stop losing your place. j/k and the arrow keys walk every list and grid, Enter opens what you are on, and Back puts you on the item you opened a view from instead of at the top of the page.
 ### Features
 - j/k and the arrow keys walk the feed, the library, a channel page, the Home rails, every Plex grid and rail, the Channels, Playlists and Downloads tables and the conversation list; Enter opens the item you are on. After you hide or delete an item, the next j goes on from where it was.
 - Back returns you to the item a view was opened from — the Plex title you opened from a Home rail, the channel you opened from its row — with the keyboard still on it.
 - Shortcuts to get around: s jumps to the search field, g-chords jump to a module, and the cheat sheet (h) names every key in the language you are reading. PageUp/PageDown move a page at a time in the command palette and in every dropdown list.
 - The command palette ranks what you typed first: “theme” now puts the Theme rows above a channel whose handle happens to contain it.
 - A card reached with Tab or j shows one ring around the whole card, and a screen reader calls it by its title.
 ### Fixes
 - Back and overlays keep their books straight: Back after navigating over About also closes About, a late clean-up no longer undoes the navigation you just made, and Shift+W on Home closes the player.
 - Dialogs and menus hand the keyboard back where it came from. Escape from a card’s context menu returns to the card, not its thumbnail link; closing the player under another dialog no longer leaves the page unscrollable; a button that is busy with a request keeps the focus instead of dropping it to the page.
 - A write that fails says so, with the reason — several saves, share links and admin actions used to fail silently or in English under the Hungarian interface.
 - A split video export that fails part-way (the job limit) tells you how many clips were added and leaves only the rest selected, so trying again does not queue the first ones twice.
 - “Feed” is called Feed everywhere, in both languages.
 ### Internal
 - Five sprints: history integrity, one dialog/focus contract, palette ranking and accessibility, the keyboard layer, and a Hungarian/English keyboard-only pass. Focus and event-order questions were measured in a real browser before each fix, not argued.
 - Three epic-end review rounds — 19 → 14, 18 → 12 and a targeted 14 → 14 — each regression test mutation-checked. The last round's findings all sat inside the previous round's own fixes, which is where the loop was closed.
 ## 0.84.0 — 2026-09-12
 A bug-fix release, from a list you wrote while using Siftlode. Two of these were destroying your own data: a YouTube video rewound itself when you reopened it, and clearing a resume point on a half-watched Plex item told Plex nothing. Subtitles now appear in seconds instead of minutes, the Plex player's bitrate is a real measurement rather than a guess, and a channel you turn full history on for fills in front of you instead of looking frozen.
 ### Features
 - Subtitles arrive in seconds. Picking an embedded subtitle track used to take about two and a half minutes on a large film, and switching from Hungarian to English cost the same again — because the cost was never the conversion, it was reading the whole file. It now reads a window around where you are, shows that first, and finishes the rest behind it; every text track rides the SAME read, so switching tracks is instant. On a 17 GB film: 154 s before, 8 s for the window now. Nothing blocks while it works, there is a “Preparing subtitles” pill instead of a frozen player, and a track that can never be shown finally says so.
 - The Plex player's info panel tells you the truth. Bitrate is measured from the bytes actually arriving, not copied off the manifest — and it shows a dash until there is something to measure rather than a confident wrong number. It also lists the audio and the subtitle track you are on, which it never did.
 - A new admin switch: loudness normalisation for Plex playback (Configuration → Plex). Off by default, because it makes a film markedly louder and narrows its dynamic range — that is a taste call, not a fix. On a 5.1 film it moved the measured loudness from −35.2 to −17.2 LUFS, and it does not touch A/V sync.
 - Collections can be sorted. The collection page had no sort control at all and always ordered by release year — it now carries the same Sort control as the library grid, with the same options, and your choice survives a reload without re-sorting the library behind it. A collection opened from a shared link also shows its real name instead of a raw id.
 - Remove a video from a playlist without leaving the player, and the player steps to whatever followed instead of closing. Above the move-to submenu there is now a one-click “move to the list you last moved to”.
 - Live YouTube search results can be sorted — by views, date or length, over the results already on screen, so sorting rearranges what you are looking at instead of running a different search.
 - The channel name in the player is a real link again: middle-click and Ctrl-click open it in a new tab, the way the YouTube icon beside it always did, while a plain click still takes the in-app route.
 ### Fixes
 - A YouTube video no longer rewinds when you reopen it. Closing at 13:50 and coming back put you at 12:31 — the checkpoint reached the server but not the page's own cache, so the stale position won. It now goes forward: 811 → 816 → 825 s across reopens.
 - “Clear resume point” works on a half-watched Plex item. The push to Plex was skipped for exactly the case you would use it on, so Plex kept the old offset and handed it straight back on the next import. Verified against the real server, including a full 44,885-item re-import.
 - Turning full history on for a channel fills the page in front of you. The grid and the item count stayed frozen for the best part of a minute while the header counted up, because the request that starts the backfill returns before anything is stored. Measured: the count now moves 54 → 139 within about twelve seconds, no reload.
 - Starting or seeking a Plex film is about eight seconds faster. Every session start and every seek waited out a dead eight-second timer for a file the transcoder never writes — on a film with more than one audio track, which is most of them. A multi-audio session now starts in 0.9 s cold and 0.7 s on a seek.
 - A Plex session the server no longer has now recovers or says so, instead of spinning forever. A stream that kept being lost could restart itself indefinitely behind a spinner that never became an error.
 - A Plex stream request for something that cannot exist answers immediately rather than holding the server for 20–30 seconds. Enough of those at once could stall the whole app.
 - The Plex player no longer counts one viewing twice, and a failed “watched” mark no longer half-happens: it used to leave the item looking watched in the app while the server disagreed, or quietly mark it watched anyway a few seconds after telling you it had failed.
 - Dragging a Plex playlist into a new order sticks. Leaving and coming straight back showed the old order, and the next drag saved that.
 - A refused action says WHY, in the language you are reading. Several places showed a generic “couldn't do that” — or nothing at all — where the server had explained itself, including the Plex “Add to playlist” dialog, the collection editor and the upload dialog. The demo account gets its reason back too.
 - Dialogs behave for the keyboard. Opening one puts the cursor where you would expect (the jump-to box opens on its search field, not its close button), closing one hands the focus back to what you opened it from, and a dialog that closes underneath another one no longer steals the focus out of the one still on screen.
 - The regular micro-stutter in the Plex player is NOT Siftlode's, and this release does not pretend to fix it. Measured per frame: the player delivers every source frame with nothing dropped; the hold comes from a 23.976 fps film on a 120.0148 Hz display, and it reproduces identically outside Siftlode. Setting the display to 119.88 Hz removes it for every application, not just this one.
 ### Internal
 - The round started from sixteen items written from real use, not from an audit. Eleven were fixed, one was measured and closed without a code change (the display cadence above), two are parked for a reproducible case, and one — playlist multi-select and bulk actions — was scoped out to its own sprint. The measurements are the point: item 8's “35 s” turned out to be one file's number, and the real law is bytes-ffmpeg-must-read divided by ~140 MB/s, which is why the fix is a window rather than a faster conversion.
 - Seven deep-review rounds followed, each reviewing the previous round's own fix commits: 32 → 24 → 43 → 31 → 22 → 26 → 18 raised. Round 7 was run TARGETED rather than full — four reviewers on the six surfaces round 6 had changed, and adversarial verification spent only where a wrong fix could re-break the previous round's — which is seven agents instead of about thirty-six for two HIGH findings. Every regression test added in a fix round was mutation-checked: reverted, run, and confirmed red for the defect it is named after. Thirteen of round 7's mutations were, and two were instructive — one guard no test could drive, and one round-6 test whose mock modelled a server that accepts a write and then serves the pre-write state.
 - What the eight-lane gate structurally cannot catch, and what this round taught about it: every real defect of the last three rounds was a wrong belief about an external system, not broken logic. ffmpeg substitutes the VARIANT before the sequence in its segment filenames, so a guard written the other way round was inert on every multi-audio file and a warm-up waited eight seconds for a name that is never written. A reclaim budget's window was anchored at the first failure rather than the last, so any failure cadence between one and two minutes reset it forever — invisible to two tests that spaced their cases at zero and ten minutes. jsdom performs no default Tab, so a focus test can be green with no focus trap installed at all. The conclusion carried forward is to measure the boundary when writing the code, not when reviewing it: one ffmpeg run costs pennies, a review round costs a session.
 ## 0.83.0 — 2026-09-09
 Siftlode now opens on a page that answers one question: what should I watch right now. You say how much time you have — ten minutes, half an hour, a whole evening — and it gives you one suggestion, from YouTube or from Plex, with a button that picks up where you left off. Under it sits a shelf of the things you always come back to, which you fill yourself.
@@ -58,13 +58,14 @@ how it gets built. Concretely:
 `routes/*` (HTTP only: validation, auth-dependency, serialization) → domain packages `sync/`, `plex/`,
 `downloads/`, `youtube/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
 `sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`,
-`security`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
+`security`, `logs`, `logsink`, `diagnostics`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
 Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → module
 components → the **platform layer `components/ui/`** (domain-free primitives: the popover engine and
 its menus, `Modal`/`Overlay`, `Button`/`form`, `DataTable`/`VirtualGrid`, `QueryState`, …). That
 boundary is one-way and **lint-enforced**, not just described: a platform component may not import a
-feature component or a domain API slice (`no-restricted-imports` in `eslint.config.js`, with its own
+feature component or a domain API slice, and one layer down `lib/` may not import from `components/` at
-test). A new generic component goes in `ui/`; see [`frontend/src/components/ui/README.md`](frontend/src/components/ui/README.md).
+all, not even a type (`no-restricted-imports` in `eslint.config.js`, with its own test). A new generic
 component goes in `ui/`; see [`frontend/src/components/ui/README.md`](frontend/src/components/ui/README.md).
 Data via react-query (`qk` factory), per-account `localStorage`, and server prefs; API through
 `lib/api/*` slices over `core.req<T>`.
@@ -89,8 +90,13 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | FE per-account state    | `usePref`                                                    | raw `readAccount`/`writeAccount` or bespoke hooks      |
 | FE action button        | `ui/Button` — pick a `SIZES` rung                            | a hand-rolled `<button className="px-3 py-2 …">`       |
 | FE keyboard shortcut    | a row in `lib/keymap.ts` + `dispatch()`                      | a private `keydown` listener with its own key literals |
 | FE list/grid keys       | `NavGrid`/`keyboardNav` + `navItemAttrs` + `data-nav-open`   | a private arrow-key / roving-tabindex handler          |
 | FE view push (history)  | `rememberNavPosition()` right before `history.pushState`     | a push that forgets: Back strands focus on `<body>`    |
 | FE control              | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>`                                    |
 | FE loading/empty/error  | `QueryState` / `StateMessage`                                | ad-hoc conditionals                                    |
 | FE failed write         | `meta.failTitle`, else `notifyActionError(err, title)`       | a bare `catch {}` or `notify()` with no error attached |
 | FE network call         | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages) | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced) |
 | FE diagnostics          | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts` | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded |
 ## House rules that bite (learned from real bugs)
@@ -1 +1 @@
-0.83.0
+0.89.0
@@ -1,19 +0,0 @@
 FROM python:3.12-slim
 ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1
 WORKDIR /app
 COPY requirements.txt .
 RUN pip install -r requirements.txt
 COPY . .
 RUN adduser --disabled-password --gecos "" appuser && chown -R appuser /app
 USER appuser
 EXPOSE 8000
 CMD ["sh", "entrypoint.sh"]
@@ -1,6 +1,8 @@
 [alembic]
 script_location = alembic
 prepend_sys_path = .
 # Split the path list the way the OS does (alembic's legacy space/comma/colon split is deprecated).
 path_separator = os
 [loggers]
 keys = root,sqlalchemy,alembic
@@ -1,17 +1,17 @@
 from logging.config import fileConfig
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 from app.config import settings
 from app.db import Base
 from app.logs import configure_logging
 import app.models  # noqa: F401  (import so models register on Base.metadata)
 config = context.config
 config.set_main_option("sqlalchemy.url", settings.database_url)
-if config.config_file_name is not None:
+# Migrations run at container start (entrypoint.sh), so their output is part of the API's log
-    fileConfig(config.config_file_name)
+# stream — one format with everything else, not alembic.ini's own fileConfig shape.
 configure_logging("alembic")
 target_metadata = Base.metadata
@@ -0,0 +1,41 @@
 """add download_jobs.error_detail — the domain-specific entry of the failure catalog (E11.5 S1)
 Revision ID: 0084_dl_job_error_detail
 Revises: 0083_comfort_pins
 Create Date: 2026-09-13
 `error_code` is the generic category (it decides whether a Retry is offered). `error_detail` names
 the host-specific catalog entry `downloads.errors.classify` matched on top of it — `facebook.login_wall`
 and its siblings — so the UI can say what went wrong ON THAT SITE and what to do about it, instead of
 the category's generic sentence. Nullable: most failures have no host-specific entry.
 Backfill: a job's code is written once, at failure time, so a new rule never reaches the rows that
 failed before it. The one shape measured on prod (2026-09-13, jobs 9/66/75/145/156/157/182/256/257) is
 yt-dlp's `[facebook] <id>: Cannot parse data`, stored as `unknown`. Without a cookie that is Facebook's
 login wall. Whether a cookie was attached at the time is not recorded anywhere, so every old row gets
 the no-cookie entry — on prod no account had a Facebook cookie, so that is what they all were.
 """
 import sqlalchemy as sa
 from alembic import op
 revision: str = "0084_dl_job_error_detail"
 down_revision: str | None = "0083_comfort_pins"
 branch_labels: str | None = None
 depends_on: str | None = None
 def upgrade() -> None:
    op.add_column("download_jobs", sa.Column("error_detail", sa.String(length=48), nullable=True))
    op.execute(
        sa.text(
            "UPDATE download_jobs SET error_code = 'login_required', "
            "error_detail = 'facebook.login_wall' "
            "WHERE (error_code IS NULL OR error_code = 'unknown') "
            "AND error ILIKE '%[facebook]%cannot parse data%'"
        )
    )
 def downgrade() -> None:
    op.drop_column("download_jobs", "error_detail")
@@ -0,0 +1,26 @@
 """add users.last_login_at — when the account last signed in (E22 S1)
 Revision ID: 0085_users_last_login_at
 Revises: 0084_dl_job_error_detail
 Create Date: 2026-09-16
 Stamped by the one sign-in path (`routes/auth._establish_session`), which the Google callback and
 password login share. No backfill is possible: the signal exists only at sign-in, so existing rows
 read NULL until each account signs in again, and the admin UI says so rather than inventing a date.
 """
 import sqlalchemy as sa
 from alembic import op
 revision: str = "0085_users_last_login_at"
 down_revision: str | None = "0084_dl_job_error_detail"
 branch_labels: str | None = None
 depends_on: str | None = None
 def upgrade() -> None:
    op.add_column("users", sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True))
 def downgrade() -> None:
    op.drop_column("users", "last_login_at")
@@ -0,0 +1,48 @@
 """add log_events — stored log events for diagnostics (E22 S3)
 Revision ID: 0086_log_events
 Revises: 0085_users_last_login_at
 Create Date: 2026-09-17
 Written by app/logsink.py's background writer (WARNING and above, request lines), pruned by the log_gc
 job after `log_retention_days`. Sized against prod on 2026-09-16: ~2k rows on a normal day, ~14k on a
 YouTube-RSS-outage day before flood control — a few MB over the 7-day window. `user_id` carries no
 foreign key on purpose (see models.LogEvent).
 """
 import sqlalchemy as sa
 from alembic import op
 from sqlalchemy.dialects import postgresql
 revision: str = "0086_log_events"
 down_revision: str | None = "0085_users_last_login_at"
 branch_labels: str | None = None
 depends_on: str | None = None
 def upgrade() -> None:
    op.create_table(
        "log_events",
        sa.Column("id", sa.BigInteger(), primary_key=True),
        sa.Column("ts", sa.DateTime(timezone=True), nullable=False),
        sa.Column("level", sa.String(10), nullable=False),
        sa.Column("sev", sa.SmallInteger(), nullable=False),
        sa.Column("source", sa.String(16), nullable=False),
        sa.Column("logger", sa.String(128), nullable=False),
        sa.Column("event", sa.String(64), nullable=True),
        sa.Column("msg", sa.Text(), nullable=False),
        sa.Column("attrs", postgresql.JSONB(), nullable=True),
        sa.Column("exc", sa.Text(), nullable=True),
        sa.Column("request_id", sa.String(64), nullable=True),
        sa.Column("user_id", sa.Integer(), nullable=True),
        sa.Column("debug_session_id", sa.String(64), nullable=True),
        sa.Column("job_id", sa.Integer(), nullable=True),
        sa.Column("version", sa.String(64), nullable=True),
    )
    op.create_index("ix_log_events_ts", "log_events", ["ts"])
    op.create_index("ix_log_events_request_id", "log_events", ["request_id"])
    op.create_index("ix_log_events_user_ts", "log_events", ["user_id", "ts"])
 def downgrade() -> None:
    op.drop_table("log_events")
@@ -0,0 +1,31 @@
 """add users.diagnostics_level + diagnostics_until — a user's consented diagnostics level (E22 S5)
 Revision ID: 0087_users_diagnostics_level
 Revises: 0086_log_events
 Create Date: 2026-09-17
 Both NULL = the base level (Alap). A raised level is ALWAYS paired with its expiry, computed by the
 server at consent time (`app/diagnostics.py`), so no client can ask for a level that never ends.
 Columns rather than `users.preferences`: that JSON is written wholesale by the client, and a consent
 with a lifetime must not be something a client can write.
 """
 import sqlalchemy as sa
 from alembic import op
 revision: str = "0087_users_diagnostics_level"
 down_revision: str | None = "0086_log_events"
 branch_labels: str | None = None
 depends_on: str | None = None
 def upgrade() -> None:
    op.add_column("users", sa.Column("diagnostics_level", sa.String(8), nullable=True))
    op.add_column(
        "users", sa.Column("diagnostics_until", sa.DateTime(timezone=True), nullable=True)
    )
 def downgrade() -> None:
    op.drop_column("users", "diagnostics_until")
    op.drop_column("users", "diagnostics_level")
@@ -20,9 +20,10 @@ Three layers, by *who* runs the code — not by feature:
   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline.
 3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth`, `sysconfig`, `quota`, `audit`,
-   `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, … are single-file primitives many
+   `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, `logs` (the one logging
-   layers import. They depend on nothing above them (a core module must never import a `routes/…`
+   configuration), `logsink` (its `log_events` table) and `diagnostics` (a user's consented log
-   module).
+   level), … are single-file primitives many layers import. They depend on nothing above them (a core
   module must never import a `routes/…` module).
 **Extraction trigger: the SECOND consumer.** Keep new logic inline in its first caller. The moment a
 *second* caller needs it (a worker as well as a route; a scheduler as well as a route), extract it down
@@ -1,17 +1,17 @@
 import logging
 import httpx
 from fastapi import BackgroundTasks, Depends, HTTPException, Request
 from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 from starlette.requests import HTTPConnection
 from app import diagnostics
 from app import email as email_mod
 from app import logs
 from app import mailtext
 from app import sysconfig
 from app.config import settings
 from app.db import get_db
-from app.models import Invite, User
+from app.models import Invite, LogEvent, User
 from app.security import decrypt_optional
 from app.utils import canonical_email
@@ -37,7 +37,7 @@ READ_SCOPES = f"{BASE_SCOPES} {READ_SCOPE}"
 WRITE_SCOPES = f"{BASE_SCOPES} {READ_SCOPE} {WRITE_SCOPE}"
 _YOUTUBE_SCOPES = frozenset({READ_SCOPE, WRITE_SCOPE})
-log = logging.getLogger("siftlode.auth")
+log = logs.get_logger(__name__)
 def google_enabled(db: Session) -> bool:
@@ -220,7 +220,7 @@ def revoke_google_token(token: str | None) -> None:
            timeout=10,
        )
        log.info("Google token revoke: status=%s", resp.status_code)
-    except Exception:
+    except Exception:  # noqa: BLE001 — a revoke we cannot make must not fail the sign-out
        log.warning("Google token revoke failed", exc_info=True)
@@ -245,6 +245,12 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
    )
    # Raw delete so Postgres applies ON DELETE CASCADE / SET NULL on every dependent table.
    db.execute(delete(User).where(User.id == user_id))
    # Stored log events name the account by id with no foreign key to cascade from (models.LogEvent),
    # so they go explicitly — they are request history, i.e. personal data. Forgotten FIRST: this very
    # request's access line, a queued row, a later background task would otherwise put rows back
    # under the id after this DELETE (logs.forget_user).
    logs.forget_user(user_id)
    db.execute(delete(LogEvent).where(LogEvent.user_id == user_id))
    # Every canonically-equal invite goes, not just the literal spelling: is_allowed matches on the
    # canonical form, so leaving a sibling row behind would keep granting access to a mailbox whose
    # account was just erased — and prod really does carry approved pairs for one mailbox.
@@ -269,51 +275,84 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
 ACTIVE_ACCOUNT_HEADER = "x-siftlode-account"
-def resolved_user_id(conn: HTTPConnection) -> tuple[int | None, bool]:
+def resolved_user_id(conn: HTTPConnection, *, strict: bool = True) -> tuple[int | None, bool]:
    """Which account this connection acts as, and whether that's the session's default account.
    Takes any HTTPConnection — an HTTP Request OR a WebSocket — so the WS push channel shares this
    exact per-tab resolution instead of re-implementing it.
    The signed cookie holds the *wallet* (`account_ids`, every account signed into this browser)
-    plus a default `user_id`. A caller may override the default with the X-Siftlode-Account header,
+    plus a default `user_id`. A caller may name its account with the X-Siftlode-Account header (or
-    but ONLY for an account already in the wallet — so a tab can't impersonate an account that never
+    `?account=`), but ONLY an account in the wallet — so a tab can't impersonate an account that
-    authenticated here. Everything else (WebSocket, plain navigations) keeps using the cookie default.
+    never authenticated here. A connection that names no account acts as the cookie default.
    A connection naming an account NOT in the wallet acts as nobody (`None`) — typically a tab still
    pinned to an account that was signed out in another tab. It must not fall back to the default:
    that tab would go on acting as an account it never showed, its player checkpoints and pref saves
    landing there and its Sign out signing THAT account out. Only the bootstrap /api/me probe passes
    `strict=False` and gets the default, which is how such a tab learns who it now is (the frontend
    re-pins it and reloads). An account whose session ended while it stayed in the wallet (deleted,
    suspended, revoked) leaves the wallet when it is refused (`_session_user`), so a tab pinned to it
    takes the same way back.
    """
    default_id = conn.session.get("user_id")
    wallet = conn.session.get("account_ids") or []
    # Header for normal XHR; ?account= for contexts that can't set headers (WebSocket, and a
-    # plain <a> file download). Both are wallet-gated below, so neither can impersonate an
+    # plain <a> file download). Both are wallet-gated below.
    # account that never signed into this browser.
    hdr = conn.headers.get(ACTIVE_ACCOUNT_HEADER) or conn.query_params.get("account")
    if hdr:
        try:
            hid = int(hdr)
        except ValueError:
            # Under `strict` this becomes a 401 and the tab authenticates as nobody, which reads
            # in the browser exactly like a session that expired. The value itself stays out —
            # it came from a request, and `wallet` says which accounts were actually on offer.
            log.debug(
                "the active-account header could not be read as an id",
                extra=logs.event("auth.account_header.invalid", accounts=len(wallet)),
            )
            hid = None
        if hid is not None and hid in wallet:
            return hid, hid == default_id
        if strict:
            return None, False
    return default_id, True
 def drop_from_wallet(session: dict, user_id: int) -> None:
    """Take one account out of this browser's wallet (`account_ids`); the session default is untouched."""
    session["account_ids"] = [a for a in (session.get("account_ids") or []) if a != user_id]
 def _end_account_session(request: Request, user_id: int, is_default: bool) -> None:
    """An account whose session here is no longer valid. Only nuke the whole session when it is the
    SESSION DEFAULT; a per-tab account just leaves the wallet (other tabs' default may still be valid).
    Leaving is what lets a tab pinned to it recover: its next /api/me names an account no longer signed
    in here and gets the default. Left in, it answered "signed out" — the landing page, with the default
    still signed in, and no way off it but closing the tab."""
    if is_default:
        request.session.clear()
    else:
        drop_from_wallet(request.session, user_id)
 def current_user(request: Request, db: Session = Depends(get_db)) -> User:
-    user_id, is_default = resolved_user_id(request)
+    return _session_user(request, db, *resolved_user_id(request))
 def _session_user(request: Request, db: Session, user_id: int | None, is_default: bool) -> User:
    if not user_id:
        raise HTTPException(status_code=401, detail="Not authenticated")
    user = db.get(User, user_id)
    if user is None or not user.is_active or user.is_suspended:
-        # Suspended/deactivated mid-session → drop the session so the block takes effect at once.
+        # Suspended/deactivated mid-session → end it so the block takes effect at once.
-        # But only nuke the whole session when the SESSION DEFAULT identity is gone; a stale
+        _end_account_session(request, user_id, is_default)
        # per-tab header account just 401s that one tab (other tabs' default may still be valid).
        if is_default:
            request.session.clear()
        raise HTTPException(status_code=401, detail="Not authenticated")
    # SA4: reject a cookie whose recorded epoch is behind the account's current one (revoked by a
    # password reset/change or "log out everywhere"). A cookie with no recorded epoch (pre-SA4, or an
    # account signed in before this shipped) is treated as epoch 0 — so the FIRST bump revokes it too.
    epochs = request.session.get("epochs") or {}
    if int(epochs.get(str(user_id), 0)) != (user.session_epoch or 0):
-        if is_default:
+        _end_account_session(request, user_id, is_default)
            request.session.clear()
        raise HTTPException(status_code=401, detail="Not authenticated")
    # Always keep the session default in the switchable list — covers sessions created before
    # multi-session existed (their account_ids was never seeded), so the switcher isn't empty.
@@ -322,16 +361,40 @@ def current_user(request: Request, db: Session = Depends(get_db)) -> User:
    if default_id and default_id not in accounts:
        accounts.append(default_id)
        request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
    # Attribute this request's log lines to the account (E22). Here, not in the request middleware:
    # this is the one place a session becomes an account, and the middleware runs outside both the
    # session middleware and this task's context. `request.state` is shared across middleware layers
    # (it lives on the ASGI scope), so the access-log line can read it back. The user's consented
    # diagnostics level rides along: their requests are logged — and stored — in that detail (S5).
    logs.set_user(user.id, diagnostics.effective_level(user), user.diagnostics_until)
    request.state.user_id = user.id
    return user
 def optional_current_user(request: Request, db: Session = Depends(get_db)) -> User | None:
    """Like `current_user` but returns None instead of raising 401 when there's no valid session.
    Used by the bootstrap /api/me probe so the logged-out landing doesn't log a failed request to
-    the browser console (a non-2xx fetch is a console error no matter how the app handles it)."""
+    the browser console (a non-2xx fetch is a console error no matter how the app handles it).
    The one lenient resolution (`strict=False`): a tab naming an account no longer signed in here gets
    the default account, which is how it learns who it now is — see `resolved_user_id`. That includes an
    account refused right here, which `_session_user` has just taken out of the wallet."""
    user_id, is_default = resolved_user_id(request, strict=False)
    try:
-        return current_user(request, db)
+        return _session_user(request, db, user_id, is_default)
    # silent-ok: this is the anonymous case as much as the refused one — every landing page hit
    # comes through here. The second attempt below is the handling, and it reports.
    except HTTPException:
        if is_default:
            return None
    try:
        return _session_user(request, db, *resolved_user_id(request, strict=False))
    except HTTPException:
        # Both the pinned account AND the default one were refused, so the tab is signed out
        # without being told why — and it got here from a session that named a real account.
        log.info(
            "a session was resolved to nobody: neither the named nor the default account held",
            extra=logs.event("auth.session.probe_rejected", user_id=user_id),
        )
        return None
@@ -341,7 +404,11 @@ def require_human(user: User = Depends(current_user)) -> User:
    no token, so has_read_scope/has_write_scope are False); this makes the boundary explicit
    where there's no scope check to lean on."""
    if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        # Structured, because `req` leaves 403 to the caller and `notifyActionError` only shows a
        # STRUCTURED detail — a plain string here reached the demo user as their caller's generic
        # "couldn't do that", with no hint that the demo account is the reason (round 6). Affordances
        # this gate sits behind are not all UI-gated on `is_demo` (the comfort shelf is not).
        raise HTTPException(status_code=403, detail={"code": "demo"})
    return user
@@ -1,6 +1,7 @@
 from pathlib import Path
 from typing import Literal, get_args, get_origin
-from pydantic import model_validator
+from pydantic import ValidationInfo, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 # Shipped placeholder; production must override it. Used by the startup guard below.
@@ -15,11 +16,40 @@ def _version_from_file() -> str:
            v = p.read_text(encoding="utf-8").strip()
            if v:
                return v
        # silent-ok: this runs at import, and `app.logs` imports THIS module — a log call here
        # would be a circular import. The loop tries the other location, then falls back to "dev".
        except OSError:
            continue
    return "dev"
 # Closed value sets. A setting typed with one of these is a CHOICE: pydantic rejects anything else at
 # boot, and sysconfig derives the admin picker's options from the same Literal — so the list lives in
 # exactly one place and a consumer never has to guess what a typo should fall back to.
 SearchSource = Literal["scrape", "api"]
 DownloadLayout = Literal["plex", "flat"]
 LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"]
 LogFormat = Literal["json", "text"]
 TranscodeHw = Literal["auto", "on", "off"]
 # libx264's presets, fastest first (`placebo` left out on purpose: no measurable gain for its cost).
 TranscodePreset = Literal[
    "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"
 ]
 def choices_of(annotation: object) -> tuple[str, ...]:
    """The allowed values of a choice-typed setting, or () for any other type."""
    return tuple(get_args(annotation)) if get_origin(annotation) is Literal else ()
 def canonical_choice(options: tuple[str, ...], raw: object) -> str | None:
    """The option `raw` names, in its canonical spelling (any letter case, surrounding space
    ignored), or None. The ONE matching rule for a choice value from the env and from the admin
    API, so a spelling one accepts the other cannot refuse."""
    folded = str(raw).strip().casefold()
    return next((option for option in options if option.casefold() == folded), None)
 class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
@@ -57,7 +87,7 @@ class Settings(BaseSettings):
    # VPS Caddy front door. A request from any other peer (someone hitting the app port directly)
    # is NOT trusted and its raw socket IP is used, so it can't spoof its rate-limit identity via
    # XFF. Empty = trust no proxy (use the direct peer) — correct for a directly-exposed / local-dev
-    # deploy. Comma-separated. See routes.auth._client_ip + the deploy docs.
+    # deploy. Comma-separated. See ratelimit.client_key + the deploy docs.
    trusted_proxy_ips: str = ""
    # --- Outbound email (onboarding: access-request + approval notices) ---
@@ -85,7 +115,7 @@ class Settings(BaseSettings):
    search_daily_limit_per_user: int = 70
    # Source for live YouTube search: "scrape" (InnerTube, no API quota) or "api" (search.list,
    # 100 units/page). Scrape is the default; flip to "api" if scraping is blocked/breaks.
-    search_source: str = "scrape"
+    search_source: SearchSource = "scrape"
    # Recent-first backfill: how far back to fetch on the first pass per channel.
    backfill_recent_max_videos: int = 100
    backfill_recent_max_days: int = 365
@@ -155,6 +185,9 @@ class Settings(BaseSettings):
    # per-client responses are flaky, and android_vr can get bot-flagged under heavy load) the
    # worker retries with the FALLBACK set — the POT-capable web clients (web needs the token +
    # Deno) plus android for audio. Both admin-tunable when YouTube shifts what works.
    # A SIGNED-IN download (the user added YouTube cookies) keeps only the cookie-capable clients
    # of these two sets — yt-dlp drops the rest, so android_vr / android / ios never run there.
    # See adapters.YouTubeAdapter._COOKIE_CAPABLE.
    download_player_clients: str = "android_vr"
    download_player_clients_fallback: str = "web_safari,web,android"
@@ -221,10 +254,27 @@ class Settings(BaseSettings):
    audit_retention_days: int = 180
    audit_gc_minutes: int = 1440
    # On-disk layout: "plex" (Channel/Season YYYY/… [id].ext + .nfo/poster) or "flat".
-    download_layout: str = "plex"
+    download_layout: DownloadLayout = "plex"
    # Default SponsorBlock (skip sponsor segments) for new custom profiles.
    sponsorblock_default: bool = False
    # --- Diagnostics / logging (E22) ---
    # BOOTSTRAP level only: the running level is the `log_level` admin knob (sysconfig), applied at
    # startup and on change without a restart. This is what a process logs at before it can reach
    # the database — and the only knob the worker/runner children read, since they are short-lived.
    # TRACE (below DEBUG) is the "Teljes" diagnostics level; see app/logs.py.
    log_level: LogLevel = "INFO"
    # "json" (one object per line — what Loki and the log_events sink ingest) or "text" (a readable
    # line for a local terminal). Redaction applies to both.
    log_format: LogFormat = "json"
    # Also write events to the `log_events` table (app/logsink.py): WARNING and above, the request
    # lines, and — once they exist — client batches. Off only where no table is wanted (the tests).
    log_db_sink: bool = True
    # Days a `log_events` row is kept (the privacy policy promises this), and how often the log_gc job
    # enforces it — hourly, so a row never outlives the promise by more than an hour.
    log_retention_days: int = 7
    log_gc_minutes: int = 60
    # --- Plex integration (optional) ---
    # The Plex module plays the LOCAL physical media file directly (our own ffmpeg/direct-serve);
    # Plex is used only for metadata + optional watch-state sync. Requires the Plex server to be
@@ -266,12 +316,17 @@ class Settings(BaseSettings):
    # Hardware-encoder policy: "auto" = VAAPI (h264_vaapi) when the iGPU render node is present AND the
    # source codec is hardware-decodable, else libx264 software; "on" = force VAAPI wherever the render
    # node exists (skip the decodability gate); "off" = always software. See plex/stream.py `_select_encode`.
-    plex_transcode_hw: str = "auto"
+    plex_transcode_hw: TranscodeHw = "auto"
    # Software-fallback libx264 tuning (IGNORED on the VAAPI path). `preset` trades CPU for size; `crf`
    # trades quality for size (lower = better + bigger). `max_height` caps the SOFTWARE transcode's output
    # height (0 = keep source) so a CPU re-encode of a tall source stays affordable — the GPU path always
    # encodes at source resolution.
-    plex_transcode_preset: str = "veryfast"
+    # Loudness normalisation of the downmixed stereo audio on the HLS path (EBU R128 `loudnorm`).
    # OFF by default: it makes a film ~11 dB louder and narrows its dynamic range, which is a taste
    # call, not a fix. Only affects files that go through remux/transcode — a direct-played file is
    # served untouched, but those are browser-native stereo anyway, not the 5.1 mixes this is for.
    plex_audio_loudnorm: bool = False
    plex_transcode_preset: TranscodePreset = "veryfast"
    plex_transcode_crf: int = 20
    plex_transcode_max_height: int = 1080
    # Where on-the-fly HLS remux segments are written (transient, reaped). Empty → a `.plex-hls`
@@ -320,6 +375,17 @@ class Settings(BaseSettings):
        https OAUTH_REDIRECT_URL as the signal for 'real deployment' vs local dev."""
        return self.oauth_redirect_url.lower().startswith("https://")
    @field_validator("*", mode="before")
    @classmethod
    def _canonical_choice(cls, value: object, info: ValidationInfo) -> object:
        """A choice setting accepts its value in any letter case (`LOG_LEVEL=debug`) and stores the
        canonical spelling; an unknown value still fails the boot with pydantic's own message."""
        field = cls.model_fields.get(info.field_name or "")
        options = choices_of(field.annotation) if field else ()
        if options and isinstance(value, str):
            return canonical_choice(options, value) or value
        return value
    @model_validator(mode="after")
    def _enforce_production_secrets(self) -> "Settings":
        """Fail fast rather than boot a public instance with the shipped placeholder
@@ -20,6 +20,10 @@ engine = create_engine(
    max_overflow=30,
    pool_timeout=30,
    future=True,
    # A database error renders its bound parameters into its message — a title, an uploader, a
    # file path, a URL — and that message is logged and stored as a job's error text. The SQL
    # stays; the values are data, and the ids an operator needs are on the line already.
    hide_parameters=True,
 )
 SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)
@@ -0,0 +1,61 @@
 """A user's diagnostics level (E22 S5): what they consented to, and for how long.
 Three levels, named in the UI Alap / Részletes / Teljes:
  * INFO  — the base, for everyone, no consent. The browser keeps its log in memory; nothing extra
            is sent or stored.
  * DEBUG — consented. The server logs this user's requests in detail and stores every line of
            them, and the browser streams its own log to `POST /api/diagnostics/events`.
  * TRACE — consented. As DEBUG, plus what the user typed into a search.
 A raised level always lapses after `ELEVATION_HOURS`: the expiry is computed HERE at consent time,
 never taken from the client, and an expired level reads as INFO without anything having to clear it.
 The shared demo account cannot raise its level — its log would mix every visitor's session.
 Core layer: imports `models` and `sysconfig`.
 """
 from datetime import datetime, timedelta, timezone
 from typing import Literal, get_args
 from sqlalchemy.orm import Session
 from app import sysconfig
 from app.models import User
 DiagnosticsLevel = Literal["INFO", "DEBUG", "TRACE"]
 LEVELS: tuple[str, ...] = get_args(DiagnosticsLevel)
 BASE: DiagnosticsLevel = "INFO"
 ELEVATION_HOURS = 24
 def effective_level(user: User, now: datetime | None = None) -> DiagnosticsLevel:
    """The level in force for `user` right now: the consented one until it expires, else BASE."""
    level, until = user.diagnostics_level, user.diagnostics_until
    if level not in LEVELS or level == BASE or until is None:
        return BASE
    if until <= (now or datetime.now(timezone.utc)):
        return BASE
    return level  # type: ignore[return-value] — narrowed by the LEVELS check above
 def state(db: Session, user: User) -> dict:
    """The `/api/me` view of it: the level in force, when a raised one lapses, and how long stored
    log lines are kept — the consent text states that number, so it must be the instance's own."""
    level = effective_level(user)
    return {
        "level": level,
        "until": user.diagnostics_until.isoformat() if level != BASE else None,
        "retention_days": sysconfig.get_int(db, "log_retention_days"),
    }
 def set_level(user: User, level: DiagnosticsLevel) -> None:
    """Record a consent (or its withdrawal). The caller commits. Raising the level again restarts
    the clock — each consent is for the next ELEVATION_HOURS, not an extension of an older one."""
    if level == BASE:
        user.diagnostics_level = None
        user.diagnostics_until = None
        return
    user.diagnostics_level = level
    user.diagnostics_until = datetime.now(timezone.utc) + timedelta(hours=ELEVATION_HOURS)
@@ -62,6 +62,8 @@ def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, obje
        return (col, sh.id) if sh is not None else None
    try:
        pid = int(ref)
    # silent-ok: validating a reference the client supplied. "Not an integer" is answered as "no
    # such pin target", which is the same answer this function gives for one that does not exist.
    except ValueError:
        return None
    pl = db.get(Playlist, pid)
@@ -11,9 +11,22 @@ Resolution works both before extraction (from source_kind / URL host) and after
 `extractor_key` in the info dict), so a non-YouTube "url" job still lands on the right adapter.
 """
 import re
 from urllib.parse import urlparse
 import yt_dlp
 from yt_dlp.networking.impersonate import ImpersonateTarget
 from app.config import settings
 from app.downloads.stated import StatedFailure
 # Facebook's "Cannot parse data": the page yt-dlp got was a wall, not the content. Both the Chrome retry
 # below and the failure catalog (errors.py) decide on it, so the wording exists once.
 FACEBOOK_PARSE_WALL = "cannot parse data"
 # A source's own verdicts on a link, raised from `resolve_url`. errors.py classifies them; it imports
 # them from here because this module must not import errors (errors → credentials → adapters).
 POST_WITHOUT_VIDEO_MESSAGE = "No single video was found in this post."
 POST_NOT_SHOWN_MESSAGE = "Facebook did not show this post to the signed-in session."
 class SourceAdapter:
@@ -22,9 +35,21 @@ class SourceAdapter:
    key = "generic"
    # --- extraction (worker._extract_with_fallback / backfill) ---------------------------------
-    def client_sets(self) -> list:
+    def resolve_url(self, url: str, ydl_opts: dict) -> str:
-        """Player-client sets to attempt, in order. A generic source needs no client override, so a
+        """The link to hand yt-dlp for `url`, resolved BEFORE the first attempt. `ydl_opts` are the
-        single default attempt (`[None]`) — the per-client fallback is a YouTube-only concept."""
+        download's own options (cookie, timeouts, address family) for any page this needs to read.
        Raises a RuntimeError carrying one of this module's verdicts when the page read shows the
        download cannot go ahead: the content is there but holds no single video
        (`POST_WITHOUT_VIDEO_MESSAGE`), or the page is not the content at all — the login page a
        refused cookie gets (`POST_NOT_SHOWN_MESSAGE`), never the no-video verdict. A failed page read
        is raised as itself, so it is classified like any other download error. Generic: `url`."""
        return url
    def client_sets(self, authed: bool = False) -> list:
        """Attempts to make, in order — each entry is handed back to `ydl_opts_extra`, and the next one
        is tried when `retriable` says so. A generic source makes a single default attempt (`[None]`).
        `authed` is whether the acting user's cookie file goes with the download."""
        return [None]
    def ydl_opts_extra(self, clients) -> dict:
@@ -37,6 +62,10 @@ class SourceAdapter:
        return False
    # --- metadata -----------------------------------------------------------------------------
    def title(self, info: dict) -> str | None:
        """The download's raw title, before `titles.normalize_title` cleans it. Generic: yt-dlp's."""
        return info.get("title")
    def uploader_url(self, info: dict) -> str | None:
        """The channel/uploader page URL. Generic: whatever yt-dlp exposes directly (YouTube gives
        `channel_url`), else None (reddit / a raw media URL have no derivable channel page)."""
@@ -65,12 +94,46 @@ class YouTubeAdapter(SourceAdapter):
        "Requested format is not available",
        "Only images are available",
        "Sign in to confirm",
        # Measured 2026-09-16: a gated video whose EXTRACTION succeeds and whose media fetch is then
        # refused by the CDN ("unable to download video data: HTTP Error 403"). The wall moves
        # between the player response and the stream, so this is the same per-client flakiness one
        # step later — and it used to end the job on attempt 1, because the text classifies as
        # `network` and nothing here matched it. The format URLs belong to the client that minted
        # them, so the next client set is a real second chance.
        "unable to download video data",
    )
    # Measured in the worker against a REAL account cookie (2026-09-16, yt-dlp 2026.07.04): with
    # `player_client=android_vr` yt-dlp logs `Skipping client "android_vr" since it does not support
    # cookies`, drops it, and the request that is left with no client fails with "Requested format is
    # not available" — which is already a retriable marker above, so the cost is a wasted attempt
    # rather than a hard failure. Our primary set is android_vr ALONE, so without this filter every
    # signed-in download would burn its first attempt that way before reaching the POT-backed web
    # fallback the cookie exists for. The list is yt-dlp's own INNERTUBE_CLIENTS[...]
    # ["SUPPORTS_COOKIES"], pinned by test_adapters against the installed yt-dlp, so a version bump
    # that moves the table turns the gate red instead of silently un-authing every YouTube download.
    _COOKIE_CAPABLE = frozenset(
        {
            "mweb",
            "tv",
            "tv_downgraded",
            "web",
            "web_creator",
            "web_embedded",
            "web_music",
            "web_safari",
        }
    )
    # Where a signed-in download lands when the admin's knobs hold no cookie-capable client at all.
    # Both clients in ONE set: yt-dlp queries each and merges their formats, which is the cover for
    # the per-client flakiness that the two-tier ladder gives a signed-out download.
    _AUTHED_DEFAULT = ("web_safari", "web")
-    def client_sets(self) -> list:
+    def client_sets(self, authed: bool = False) -> list:
-        return [
+        sets = [c for c in (settings.player_client_list, settings.player_client_fallback_list) if c]
-            c for c in (settings.player_client_list, settings.player_client_fallback_list) if c
+        if authed:
-        ] or [None]
+            kept = [[c for c in s if c in self._COOKIE_CAPABLE] for s in sets]
            return [s for s in kept if s] or [list(self._AUTHED_DEFAULT)]
        return sets or [None]
    def ydl_opts_extra(self, clients) -> dict:
        # == --extractor-args "youtube:player_client=…;youtubepot-bgutilhttp:base_url=…" (list values).
@@ -93,6 +156,63 @@ class YouTubeAdapter(SourceAdapter):
 class FacebookAdapter(SourceAdapter):
    key = "facebook"
    # Measured (E11.5, yt-dlp 2026.07.04): with the user's cookie, some reels answer a plain request
    # with "Cannot parse data" and parse only when the request looks like Chrome. Impersonation is a
    # SECOND attempt behind that one error, not the default: the links that already download with the
    # cookie keep their proven path, and only the ones stuck at the wall go through curl_cffi. Without
    # a cookie the same error is the login wall, which no disguise gets past.
    _IMPERSONATE = "impersonate"
    # A post page is ~4–5 MB of inline JSON; anything far past that is not a post page.
    _POST_PAGE_MAX_BYTES = 16 * 1024 * 1024
    def resolve_url(self, url: str, ydl_opts: dict) -> str:
        # Measured (E11.5 S4): given a group post's link, yt-dlp either finds no formats or — worse —
        # downloads ANOTHER video from the page's feed data. The post's own video is the one Video node
        # in the page scripts that carry the post id; its watch link downloads (plain first, then the
        # Chrome retry above). Needs the cookie: signed out, the page is the login wall.
        post_id = facebook_group_post_id(url)
        if post_id is None or not ydl_opts.get("cookiefile"):
            return url
        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
            raw = ydl.urlopen(url).read(self._POST_PAGE_MAX_BYTES)
        page = raw.decode("utf-8", "replace")
        # Measured (E11.5 review): a refused or expired cookie gets the login page (~450 KB, a login
        # form, no post id at all), which is not a post without a video — the user's cookie is the cause.
        if _quoted(post_id) not in page:
            raise StatedFailure(POST_NOT_SHOWN_MESSAGE)
        video_id = facebook_post_video_id(page, post_id)
        if video_id is None:
            # Never fall back to the post link: that is exactly where the wrong video comes from.
            raise StatedFailure(POST_WITHOUT_VIDEO_MESSAGE)
        return f"https://www.facebook.com/watch/?v={video_id}"
    def client_sets(self, authed: bool = False) -> list:
        return [None, self._IMPERSONATE] if authed else [None]
    def ydl_opts_extra(self, clients) -> dict:
        if clients == self._IMPERSONATE:
            return {"impersonate": ImpersonateTarget.from_str("chrome")}
        return {}
    def retriable(self, error_text: str) -> bool:
        return FACEBOOK_PARSE_WALL in error_text.lower()
    # Measured (2026-09-14): a SIGNED-IN read gives the placeholder "Video" (plain and as Chrome), and an
    # 18+ reel only readable as Chrome gives "Facebook"; the post's text is still in `description`. A
    # signed-out read titles the page with that same text behind the engagement counts, cut short.
    _PLACEHOLDER_TITLES = frozenset({"video", "facebook"})
    def title(self, info: dict) -> str | None:
        raw = info.get("title")
        if (raw or "").strip().lower() not in self._PLACEHOLDER_TITLES:
            return raw
        line = next(
            (ln.strip() for ln in (info.get("description") or "").splitlines() if ln.strip()), ""
        )
        # The whole first line, never cut here with an ellipsis: normalize_title's NFKC turns "…" into
        # "..." and then collapses it to ".", which read as a finished sentence ("… live at."). The
        # stored title is unbounded; display_name and the file name clip it themselves.
        return line or raw  # no description either (the 18+ reel): nothing better on the page
    def uploader_url(self, info: dict) -> str | None:
        # Facebook gives neither channel_url nor uploader_url, but exposes a numeric `uploader_id`
@@ -107,6 +227,39 @@ class FacebookAdapter(SourceAdapter):
        return True
 _FB_GROUP_POST_PATH = re.compile(r"^/groups/[^/]+/(?:permalink|posts)/(\d+)/?$")
 _SCRIPT_BLOCK = re.compile(r"<script[^>]*>(.*?)</script>", re.S)
 _VIDEO_NODE = re.compile(r'"__typename":"Video","id":"(\d+)"')
 def _quoted(post_id: str) -> str:
    # How the page JSON carries the id: quoted, so a longer id that merely starts with it never counts.
    return f'"{post_id}"'
 def facebook_group_post_id(url: str) -> str | None:
    """The post id of a Facebook group post link (`/groups/<group>/permalink|posts/<id>/`), else None."""
    parsed = urlparse(url)
    if not _host_is(parsed.netloc.lower(), "facebook.com"):
        return None
    match = _FB_GROUP_POST_PATH.match(parsed.path)
    return match.group(1) if match else None
 def facebook_post_video_id(page: str, post_id: str) -> str | None:
    """The id of the one video attached to `post_id`, read from its page: the Video nodes of the script
    blocks that carry the post id (the page's other ~10 videos — feed, reels — sit in other blocks).
    None for no video AND for more than one: guessing between two would be the wrong-video bug again."""
    quoted = _quoted(post_id)
    ids = {
        vid
        for block in _SCRIPT_BLOCK.findall(page)
        if quoted in block
        for vid in _VIDEO_NODE.findall(block)
    }
    return ids.pop() if len(ids) == 1 else None
 class RedditAdapter(SourceAdapter):
    key = "reddit"
@@ -11,11 +11,12 @@ Run once per environment:
    docker exec siftlode-worker-1 python -c "from app.downloads import backfill; print(backfill.run())"
 """
-import logging
+from urllib.parse import urlsplit
 import yt_dlp
 from sqlalchemy import select
 from app import logs
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import adapters
@@ -23,12 +24,17 @@ from app.downloads import edit as editmod
 from app.downloads import formats, service
 from app.models import MediaAsset
-log = logging.getLogger("siftlode.backfill")
+log = logs.get_logger(__name__)
-def _extract_meta(url: str, adapter: adapters.SourceAdapter) -> dict | None:
+def _extract_meta(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
    """Metadata-only yt-dlp extraction, using the source adapter's client sets + options (YouTube
    needs the POT/player-client strategy even just to extract)."""
    with formats.hiding(url):
        return _extract_meta_scoped(url, adapter, asset_id)
 def _extract_meta_scoped(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
    for clients in adapter.client_sets():
        opts = formats.build_ydl_opts(
            {}, "%(id)s.%(ext)s", lambda d: None, extra=adapter.ydl_opts_extra(clients)
@@ -40,7 +46,19 @@ def _extract_meta(url: str, adapter: adapters.SourceAdapter) -> dict | None:
            if info:
                return info
        except Exception as exc:  # noqa: BLE001 — best-effort backfill, keep going
-            log.info("meta extract failed for %s (%s): %s", url, clients, str(exc)[:100])
+            # The asset id, not the URL. A source URL is a row of this user's download
            # history, and `redact_text` only takes credential params out of it — the rest
            # of it goes in whole. The id names the same asset to anyone holding the
            # database and nothing at all to anyone who is not; the host is kept because it
            # is what decides which client set was tried. yt-dlp's message goes through
            # `log_safe` for the same reason: it opens with the URL or the video id.
            log.info(
                "meta extract failed for asset %s on %s (%s): %s",
                asset_id,
                urlsplit(url).hostname or "?",  # log-pii-ok: the host, never the path or query
                clients,
                formats.log_safe(exc)[:100],
            )
    return None
@@ -60,12 +78,14 @@ def run() -> dict:
            adapter = adapters.resolve_adapter(a.source_kind, a.source_ref)
            if a.uploader_url is None and adapter.wants_metadata_backfill():
                url = a.source_webpage_url or service.source_url(a.source_kind, a.source_ref)
-                info = _extract_meta(url, adapter)
+                info = _extract_meta(url, adapter, a.id)
                uu = adapter.uploader_url(info) if info else None
                if uu:
                    a.uploader_url = uu
                    filled_url += 1
-                    log.info("asset %s uploader_url <- %s", a.id, uu)
+                    log.info(
                        "asset %s uploader_url filled", a.id
                    )  # the URL names what they downloaded
            if a.poster_path is None:
                # Record a self-hosted poster for every download (the reliable og:image source):
                # ensure_poster returns the existing <base>.jpg thumbnail sidecar, or cuts a frame.
@@ -73,7 +93,7 @@ def run() -> dict:
                if rel:
                    a.poster_path = rel
                    filled_poster += 1
-                    log.info("asset %s poster <- %s", a.id, rel)
+                    log.info("asset %s poster filled", a.id)  # the path carries the title
            db.commit()
    result = {
        "assets": len(assets),
@@ -1,15 +1,17 @@
 """Per-user, per-host download cookies — the single source of truth for "does the acting user's
 cookie apply to this download, and how does that keep the result private".
-Two call sites depend on ONE consistent answer (house rule: an invariant lives in shared code, not
+Two sides depend on ONE consistent answer (house rule: an invariant lives in shared code, not
 in prose):
  * `enqueue` salts the MediaAsset cache signature with the user id WHEN a cookie applies, so the
-    authed download becomes a PRIVATE asset that is never cache-served to another user.
+    authed download becomes a PRIVATE asset that is never cache-served to another user. Retry
    (`service.resume`) and Re-download (`service.redownload`) ask the same question again, so a
    cookie the user added after a failure goes with the next attempt.
  * the worker attaches the cookie file to yt-dlp ONLY when a cookie still applies AND the asset it
    is downloading into is that private, salted identity — so a cookie can never poison a shared
    asset (the load-bearing cross-user privacy fix).
-Both go through `cookie_salt` / `authed_format_sig` / `host_key_for_url` here, so they can't drift.
+Both key the private identity on `cookie_salt` / `host_key_for_url` here, so they can't drift.
 Security controls enforced here:
  * **host scope (SEC-12)** — `host_key_for_url` matches the download URL's netloc against a curated
@@ -21,19 +23,19 @@ Security controls enforced here:
    logged, or written to a job's error/snapshot.
 """
 import logging
 import os
 from pathlib import Path
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from app import logs
 from app.downloads import formats
 from app.downloads.adapters import _host_is
-from app.models import DownloadCredential
+from app.models import DownloadCredential, MediaAsset
 from app.security import decrypt_optional, encrypt
-log = logging.getLogger("siftlode.downloads.credentials")
+log = logs.get_logger(__name__)
 class HostSpec:
@@ -53,6 +55,11 @@ class HostSpec:
 # all derive from this, so there is nothing else to wire up.
 SUPPORTED_HOSTS: tuple[HostSpec, ...] = (
    HostSpec("facebook", "Facebook", ("facebook.com", "fb.watch")),
    # YouTube gates INDIVIDUAL videos behind "Sign in to confirm you're not a bot" (measured on prod
    # job 273: every player client fails on that one video while its neighbours download fine, and
    # the newest yt-dlp fails the same way — a signed-in session is the only way through). Without a
    # row here the `login_required` copy sent the user to a dropdown that could not help them.
    HostSpec("youtube", "YouTube", ("youtube.com", "youtu.be", "youtube-nocookie.com")),
    HostSpec("instagram", "Instagram", ("instagram.com",)),
    HostSpec("twitter", "X (Twitter)", ("twitter.com", "x.com")),
    HostSpec("tiktok", "TikTok", ("tiktok.com",)),
@@ -99,11 +106,38 @@ def cookie_salt(user_id: int, host_key: str) -> str:
 def authed_format_sig(spec: dict, user_id: int, host_key: str) -> str:
-    """The salted `format_sig` an authed download for (user, host) resolves to — the private asset
+    """The salted `format_sig` an authed download for (user, host) resolves to under the current
-    identity. Both enqueue (to create it) and the worker (to recognise it) compute it HERE."""
+    signature version — the private asset enqueue creates, and one of the identities `is_authed_asset`
    recognises. Neither calls it; the tests use it to hold the two to each other."""
    return formats.format_sig(spec, salt=cookie_salt(user_id, host_key))
 def rebuild_salt(asset_id: int, cookie: str | None) -> str:
    """The salt of a Re-download's fresh asset: its OWN row id (so every rebuild is a new identity no
    enqueue can ever compute), prefixed with the user's `cookie_salt` when a cookie applies. The id is
    what makes it recognisable — the worker has the asset row, so `is_authed_asset` can recompute this
    one, where a salt built from the job's previous asset id could not be."""
    return f"{cookie}:rebuild:{asset_id}" if cookie else f"rebuild:{asset_id}"
 def is_authed_asset(asset: MediaAsset, spec: dict, user_id: int, url: str | None) -> bool:
    """Whether an asset is `user_id`'s private, cookie-salted identity for `url`'s host — the one
    kind of asset a cookie is ever attached to: the one enqueue creates (`authed_format_sig`), or a
    Re-download's rebuild of it (`rebuild_salt`). The worker's cookie gate asks it before a download,
    and the failure diagnosis asks it after one (a failure on this asset happened WITH the cookie).
    Either signature version counts (`formats.format_sigs`): a job queued before a deploy that bumped
    the version still downloads into the asset it was given."""
    host_key = host_key_for_url(url)
    if host_key is None:
        return False
    salt = cookie_salt(user_id, host_key)
    if asset.format_sig in formats.format_sigs(spec, salt=salt):
        return True
    return asset.id is not None and asset.format_sig in formats.format_sigs(
        spec, salt=rebuild_salt(asset.id, salt)
    )
 def salt_for_enqueue(db: Session, user_id: int, url: str | None) -> str | None:
    """At enqueue: the cache salt to apply if this user has a cookie for `url`'s host, else None (a
    normal shared download). Returns the salt string so the caller passes it straight to
@@ -199,20 +233,19 @@ def status_list(db: Session, user_id: int) -> list[dict]:
 # --- worker: resolve + write the cookie file --------------------------------------------------
-def resolve_cookiefile(
+def usable_cookie(
-    db: Session,
+    db: Session, user_id: int, url: str | None, asset: MediaAsset, spec: dict
-    user_id: int,
+) -> str | None:
-    url: str | None,
+    """The user's cookie text a download of `url` into `asset` goes with, or None — the ONE decision
-    asset_format_sig: str,
+    whether a download is signed in. The worker child writes it out for yt-dlp (`resolve_cookiefile`);
-    spec: dict,
+    the worker asks it again for a job that inherits a failed asset. That second ask sees the
-    staging: Path,
+    credential as it is when the job is claimed: a cookie the user removed or added since the failed
-) -> Path | None:
+    download changes this job's explanation to fit the cookie its Retry would go with.
    """In the worker child: the cookies.txt to hand yt-dlp for this download, or None.
    The double gate that prevents cross-user leakage:
      1. a credential must still exist for `url`'s host (host-scoped via `host_key_for_url`), AND
      2. the asset being downloaded into must BE this user's private, salted identity
-         (`asset_format_sig == authed_format_sig(...)`).
+         (`is_authed_asset`).
    If (2) fails the asset is the SHARED (unsalted) one — attaching the cookie would poison the
    global cache with a private-group video, so we attach nothing. An unreadable blob (rotated key →
@@ -224,18 +257,31 @@ def resolve_cookiefile(
    cred = get_credential(db, user_id, host_key)
    if cred is None:
        return None
-    if asset_format_sig != authed_format_sig(spec, user_id, host_key):
+    if not is_authed_asset(asset, spec, user_id, url):
        return None  # shared asset — never attach a cookie to a non-private identity
    raw = decrypt_optional(cred.cookies_enc)
    if not raw:
        log.warning(
            "download cookie for user %s host %s could not be decrypted (rotated key?) — "
-            "proceeding without it",
+            "treated as no cookie",
            user_id,
            host_key,
        )
        return None
-    return _write_cookiefile(raw, staging)
+    return raw
 def resolve_cookiefile(
    db: Session,
    user_id: int,
    url: str | None,
    asset: MediaAsset,
    spec: dict,
    staging: Path,
 ) -> Path | None:
    """In the worker child: the cookies.txt to hand yt-dlp for this download (`usable_cookie`), or None."""
    raw = usable_cookie(db, user_id, url, asset, spec)
    return _write_cookiefile(raw, staging) if raw else None
 def _write_cookiefile(raw: str, staging: Path) -> Path:
@@ -23,7 +23,6 @@ for a player hover-preview later.
 import hashlib
 import json
 import logging
 import math
 import os
 import queue
@@ -33,9 +32,11 @@ import threading
 import time
 from pathlib import Path
 from app import logs
 from app.config import settings
 from app.downloads.stated import StatedFailure
-log = logging.getLogger("siftlode.edit")
+log = logs.get_logger(__name__)
 def encode_thread_cap() -> int:
@@ -71,7 +72,13 @@ def normalize_edit_spec(spec: dict | None) -> dict:
    if crop:
        try:
            c = {k: int(round(float(crop[k]))) for k in ("x", "y", "w", "h")}
-        except (KeyError, TypeError, ValueError):
+        except (KeyError, TypeError, ValueError) as exc:
            # The clip still renders — uncropped. The user asked for a crop, got a whole frame,
            # and nothing anywhere called it a failure; this line is the only trace there is.
            log.warning(
                "the crop in an edit spec could not be read and was dropped",
                extra=logs.event("edit.spec.crop_dropped", reason=type(exc).__name__),
            )
            c = None
        if c and c["w"] > 0 and c["h"] > 0 and c["x"] >= 0 and c["y"] >= 0:
            out["crop"] = c
@@ -80,6 +87,7 @@ def normalize_edit_spec(spec: dict | None) -> dict:
    segs = spec.get("segments")
    if isinstance(segs, list) and segs:
        norm: list[dict] = []
        unreadable = 0
        for s in segs:
            try:
                st = max(0.0, float((s or {}).get("start_s") or 0.0))
@@ -88,9 +96,18 @@ def normalize_edit_spec(spec: dict | None) -> dict:
                    continue
                en = float(end_raw)
            except (TypeError, ValueError):
                # silent-ok: counted, not logged here — one cut-list can drop several, and the
                # join that comes out is simply shorter than the one the user built. Reported
                # once after the loop.
                unreadable += 1
                continue
            if en > st:
                norm.append({"start_s": round(st, 3), "end_s": round(en, 3)})
        if unreadable:
            log.warning(
                "some segments of a cut list could not be read and were dropped",
                extra=logs.event("edit.spec.segments_dropped", dropped=unreadable, kept=len(norm)),
            )
        norm.sort(key=lambda x: x["start_s"])
        # SEC-13: an accurate join builds one ffmpeg `filter_complex` with two filters per segment,
        # so an unbounded list becomes an unbounded command line and an ffmpeg that never finishes.
@@ -114,7 +131,13 @@ def normalize_edit_spec(spec: dict | None) -> dict:
            start = max(0.0, float(trim.get("start_s") or 0.0))
            end_raw = trim.get("end_s")
            end = float(end_raw) if end_raw is not None else None
-        except (TypeError, ValueError):
+        except (TypeError, ValueError) as exc:
            # Either a 400 the user cannot act on, or — beside a crop — a full-length clip where
            # they asked for a cut. Both are worth one line saying the spec was the problem.
            log.warning(
                "the trim in an edit spec could not be read and was dropped",
                extra=logs.event("edit.spec.trim_dropped", reason=type(exc).__name__),
            )
            start, end = 0.0, None
        t: dict = {"start_s": round(start, 3)}
        if end is not None and end > start:
@@ -306,11 +329,14 @@ def _parse_out_time(line: str) -> float | None:
    if line.startswith("out_time_us="):
        try:
            return int(line.split("=", 1)[1]) / 1_000_000
        # silent-ok: one line of ffmpeg's `-progress` stream, several per second. None means "this
        # line carried no usable time", which the caller already treats as "no progress yet".
        except ValueError:
            return None
    if line.startswith("out_time_ms="):  # (some builds mislabel this as microseconds)
        try:
            return int(line.split("=", 1)[1]) / 1_000_000
        # silent-ok: as above, the other spelling of the same line.
        except ValueError:
            return None
    return None
@@ -329,7 +355,9 @@ def _pump(stream, sink: "queue.Queue[str | None]") -> None:
    try:
        for line in stream:
            sink.put(line)
-    except (ValueError, OSError):  # pipe closed under us by the kill path
+    # silent-ok: the pipe was closed under us by our OWN kill path — the expected end of a
    # cancelled or timed-out run, and the code that did the killing is the code that reports it.
    except (ValueError, OSError):
        pass
    finally:
        sink.put(None)
@@ -347,6 +375,8 @@ def _drain_tail(stream, sink: list[str]) -> None:
            sink.append(line)
            if len(sink) > 200:
                del sink[:100]
    # silent-ok: same closed pipe as `_pump` above, and the tail collected so far is still handed
    # to whoever reports the failure.
    except (ValueError, OSError):
        pass
@@ -362,13 +392,17 @@ def escalate_kill(proc: subprocess.Popen, terminate, kill, grace_s: float, label
    try:
        proc.wait(timeout=grace_s)
        return
    # silent-ok: the escalation below IS the handling of this timeout, and surviving THAT is what
    # the line under the second wait reports.
    except subprocess.TimeoutExpired:
        pass
    kill()
    try:
        proc.wait(timeout=grace_s)
    except subprocess.TimeoutExpired:
-        log.error("%s pid %s survived SIGKILL", label, proc.pid)
+        # noqa TRY400: the exception IS the message here. A TimeoutExpired's traceback is this
        # `wait` call and nothing else — it would add three frames and no fact the line lacks.
        log.error("%s pid %s survived SIGKILL", label, proc.pid)  # noqa: TRY400
 def _stop(proc: subprocess.Popen) -> None:
@@ -404,6 +438,8 @@ def run_ffmpeg(
        while True:
            try:
                line = lines.get(timeout=1.0)
            # silent-ok: not a failure — the one-second timeout is how this loop gets a turn to
            # poll for cancellation while ffmpeg is quiet.
            except queue.Empty:
                line = ""
            if line is None:  # stdout hit EOF — ffmpeg is done (or dying)
@@ -416,11 +452,11 @@ def run_ffmpeg(
            if should_cancel():
                raise EditAborted
            if time.monotonic() - last_output > stall_timeout_s:
-                raise RuntimeError(f"ffmpeg stalled: no progress for {int(stall_timeout_s)}s")
+                raise StatedFailure(f"ffmpeg stalled: no progress for {int(stall_timeout_s)}s")
        try:
            ret = proc.wait(timeout=_FFMPEG_EXIT_GRACE_S)
        except subprocess.TimeoutExpired:  # pipes closed but the process lingers
-            raise RuntimeError("ffmpeg did not exit after closing its output")
+            raise StatedFailure("ffmpeg did not exit after closing its output")
    except BaseException:
        # ONE exit path stops the process, so the invariant is unconditional: nothing leaves this
        # function with ffmpeg still running. Not just our own EditAborted/stall — `on_progress`
@@ -435,7 +471,7 @@ def run_ffmpeg(
            if pipe:
                pipe.close()
    if ret != 0:
-        raise RuntimeError(f"ffmpeg failed ({ret}): {''.join(err_tail)[-300:]}")
+        raise StatedFailure(f"ffmpeg failed ({ret}): {''.join(err_tail)[-300:]}")
 # --- ffmpeg: universal browser playability --------------------------------------------------
@@ -471,7 +507,13 @@ def run_ffprobe_json(
    try:
        out = subprocess.run(args, capture_output=True, text=True, timeout=30, check=True).stdout
        return json.loads(out)
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError):
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
        # None makes every field it would have filled read as absent, and a file with no streams
        # and no duration is indistinguishable here from one that is not media at all.
        log.warning(
            "ffprobe could not read a file",
            extra=logs.event("media.ffprobe_failed", reason=type(exc).__name__),
        )
        return None
@@ -525,7 +567,13 @@ def probe_duration(path: Path) -> int:
            check=True,
        ).stdout.strip()
        return int(float(out)) if out else 0
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError):
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
        # Zero is the denominator of the re-encode progress bar, so a failed probe leaves the user
        # watching a bar that never moves rather than a job that says it went wrong.
        log.info(
            "the duration probe failed; progress for this job has no total",
            extra=logs.event("media.duration_probe_failed", reason=type(exc).__name__),
        )
        return 0
@@ -670,15 +718,28 @@ def _run_ffmpeg_best_effort(cmd: list[str], timeout_s: int) -> Exception | None:
    try:
        subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
        return None
    # silent-ok: the exception is the RETURN VALUE. This helper exists so the three callers share
    # one run/timeout policy, and each logs the failure with the context only it has.
    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
        return exc
 def _step_failure(err: BaseException) -> str:
    """What a best-effort image step's failure line says: the kind and, for ffmpeg, its exit
    status. Never `str(err)`: a CalledProcessError or TimeoutExpired quotes ffmpeg's argv, and an
    OSError its file name — the source path either way, which is built from the channel and the
    title."""
    code = getattr(err, "returncode", None)
    return f"{type(err).__name__} {code}" if code is not None else type(err).__name__
 def _is_jpeg(path: Path) -> bool:
    """True if the file starts with the JPEG SOI marker (FF D8 FF)."""
    try:
        with path.open("rb") as f:
            return f.read(3) == b"\xff\xd8\xff"
    # silent-ok: False only means "do not copy this straight through" — the caller then goes the
    # ffmpeg route, which opens the same file and reports it properly if it really is unreadable.
    except OSError:
        return False
@@ -699,13 +760,15 @@ def thumbnail_to_jpg(src: Path | None, dest: Path, timeout_s: int = 30) -> Path
            shutil.copyfile(src, dest)
            return dest
        except OSError as exc:
-            log.info("thumbnail copy failed (%s); poster falls back to a cut frame", str(exc)[:120])
+            log.info(
                "thumbnail copy failed (%s); poster falls back to a cut frame", _step_failure(exc)
            )
            return None
    err = _run_ffmpeg_best_effort(build_thumbnail_jpg_cmd(src, dest), timeout_s)
    if err is not None:
        log.info(
            "thumbnail->jpg conversion failed (%s); poster falls back to a cut frame",
-            str(err)[:120],
+            _step_failure(err),
        )
        return None
    return dest if dest.exists() else None
@@ -730,7 +793,7 @@ def ensure_poster(asset, download_root: str, timeout_s: int = 30) -> str | None:
    at = min(3.0, (asset.duration_s or 10) * 0.1)
    err = _run_ffmpeg_best_effort(build_poster_cmd(src, dest, at), timeout_s)
    if err is not None:
-        log.info("poster gen skipped for asset %s: %s", asset.id, str(err)[:120])
+        log.info("poster gen skipped for asset %s: %s", asset.id, _step_failure(err))
        return None
    return rel if dest.exists() else None
@@ -761,7 +824,7 @@ def ensure_storyboard(asset, download_root: str, timeout_s: int = 90) -> dict |
    cmd = build_storyboard_cmd(src, dest, asset.duration_s, geom)
    err = _run_ffmpeg_best_effort(cmd, timeout_s)
    if err is not None:
-        log.info("storyboard gen skipped for asset %s: %s", asset.id, str(err)[:120])
+        log.info("storyboard gen skipped for asset %s: %s", asset.id, _step_failure(err))
        return None
    if not dest.exists():
        return None
@@ -1,4 +1,5 @@
-"""Classify a raw yt-dlp / ffmpeg failure string into a stable category code.
+"""Classify a raw yt-dlp / ffmpeg failure string into a stable category code — and, where a site's
 failure has been measured, into that site's entry of the failure catalog.
 The worker stores the raw exception text (truncated) for technical detail, but a raw
 `ERROR: [youtube] <id>: Private video. Sign in…` is noise to a user. `classify()` maps that text
@@ -6,21 +7,51 @@ to one of a small set of category codes; the frontend turns the code into a loca
 explanation (and decides whether a retry makes sense). The raw text stays available behind a
 "details" disclosure. This is the same string-matching approach the worker already trusts for
 `_RETRIABLE_MARKERS` — kept here as the single source of truth for "what kind of failure is this".
 **The failure catalog** (`_CATALOG`, E11.5). A category is generic: "Sign-in required" cannot tell a
 Facebook user that the cookie they already gave was refused, and yt-dlp words several different
 Facebook walls identically (`Cannot parse data`). A catalog entry is scoped to ONE host and may also
 depend on whether a cookie was attached and on the kind of link, and names a `detail` code the UI has
 its own sentence for — why it failed on that site, and what the user can do. `diagnose()` tries the
 catalog first and falls back to the category. How an entry is added, every time a failure is reported:
  1. reproduce it on dev (with and without the user's cookie) and keep the verbatim yt-dlp text;
  2. add the entry below, scoped as narrowly as the measurement allows (a marker that is yt-dlp's
     generic wording for every site must never match without its host; a marker another module also
     decides on — the Facebook Chrome retry's FACEBOOK_PARSE_WALL — is imported, never retyped);
  3. pin the real text in `tests/test_download_errors.py`;
  4. add `downloads.errors.fail.catalog.<detail>.{short,body}` in EN and HU (a contract test checks it;
     the group is not called `detail`, which `actionErrors.contract` reads as a raw `HttpError.detail`).
 """
-# Two worker-authored strings that this module owns because both are coupled to `_RULES`.
+from collections.abc import Callable
 from dataclasses import dataclass
 from typing import NamedTuple
 from app.downloads.adapters import (
    FACEBOOK_PARSE_WALL,
    POST_NOT_SHOWN_MESSAGE,
    POST_WITHOUT_VIDEO_MESSAGE,
    facebook_group_post_id,
 )
 from app.downloads.credentials import host_key_for_url
 # Worker-authored strings that this module owns because each is coupled to `_RULES`.
 #
 # QUOTA_FULL_MESSAGE is raised by the worker and must classify back to `quota_exceeded`; its rule
 # below matches a fragment of it, and test_download_errors pins the pair, because a message and its
 # rule drifting apart is exactly how a category silently becomes unreachable.
 #
-# NETWORK_REDACTED_MESSAGE is the opposite direction: it REPLACES a message after classification, so
+# NETWORK_REDACTED_MESSAGE REPLACES a message after classification (`user_error_text`). It is written
-# it deliberately has no rule. Nothing re-classifies a stored `job.error` today; if anything ever
+# to the shared asset too, and a second job that inherits that failed asset re-diagnoses the stored
-# does, it must carry the original code rather than re-deriving one from this text.
+# text (`worker._process_job`), so it has a rule of its own that gives the category back.
 #
 # Other worker-raised texts are still inline literals at their raise sites. The ffmpeg ones and
 # "produced no output file" have markers here; the urlguard refusal deliberately has none and
 # classifies as `unknown` — it is a refusal, not a diagnosis, and no category would say more.
 #
 # A source adapter's verdicts on a link (`SourceAdapter.resolve_url`, E11.5 S4) are adapters.py's
 # constants, imported above; each has a rule below that gives its category back, and a catalog entry
 # that gives the site's sentence.
 QUOTA_FULL_MESSAGE = "Your download storage is full — free up space, then try again."
 NETWORK_REDACTED_MESSAGE = "The server could not reach that address."
@@ -30,6 +61,12 @@ _RULES: tuple[tuple[str, str], ...] = (
    # Our own refusal: the worker found the user already at their storage cap (SEC-13). Placed
    # first — it is our wording, so it can never be a false match on an upstream message.
    ("download storage is full", "quota_exceeded"),
    # Our own redaction of a transport failure (see NETWORK_REDACTED_MESSAGE) — our wording too.
    (NETWORK_REDACTED_MESSAGE.lower(), "network"),
    # Our own verdicts on a post link (adapters.py) — our wording too: its page holds no single video,
    # or the site answered the signed-in read with something that is not the post at all.
    (POST_WITHOUT_VIDEO_MESSAGE.lower(), "format_unavailable"),
    (POST_NOT_SHOWN_MESSAGE.lower(), "login_required"),
    # Login / age / members / bot-check — the user must be signed in (we deliberately are not).
    ("sign in to confirm your age", "login_required"),
    ("confirm your age", "login_required"),
@@ -101,6 +138,120 @@ _RULES: tuple[tuple[str, str], ...] = (
 )
 class Diagnosis(NamedTuple):
    """What a failure was: the generic `code` (category) and, when a catalog entry matched, its
    host-specific `detail`."""
    code: str
    detail: str | None = None
@dataclass(frozen=True)
 class _Entry:
    """One measured failure of one site. It matches when the download URL belongs to `host`
    (`credentials.SUPPORTED_HOSTS`), every one of `markers` is in the message, the cookie state is
    `cookie` (None: either), and — when `link` is given — it recognises the URL (a truthy result). A
    link predicate is the adapter's own, so the catalog and the download agree on what a link is."""
    host: str
    markers: tuple[str, ...]
    code: str
    detail: str
    cookie: bool | None = None
    link: Callable[[str], object] | None = None
 _CATALOG: tuple[_Entry, ...] = (
    # Facebook answers a signed-out client with a page yt-dlp cannot parse — an 18+ reel, a closed
    # group's post (measured 2026-09-13: prod jobs 145, 156, 256 download once the owner's cookie is
    # attached). "Cannot parse data" is yt-dlp's generic wording for a broken extractor on EVERY site,
    # which is why the entry is scoped to Facebook and never becomes a general rule.
    _Entry(
        host="facebook",
        markers=("[facebook]", FACEBOOK_PARSE_WALL),
        code="login_required",
        detail="facebook.login_wall",
        cookie=False,
    ),
    # The same text WITH a cookie: an expired / signed-out cookie, or a page that also needs
    # impersonation (prod job 257). Telling this user to add cookies would be wrong — they have.
    _Entry(
        host="facebook",
        markers=("[facebook]", FACEBOOK_PARSE_WALL),
        code="login_required",
        detail="facebook.cookie_rejected",
        cookie=True,
    ),
    # A group post read with a cookie that Facebook answered with its login page (measured with a
    # refused cookie: no post id anywhere on the page) — the same refused cookie, found by the adapter.
    _Entry(
        host="facebook",
        markers=(POST_NOT_SHOWN_MESSAGE.lower(),),
        code="login_required",
        detail="facebook.cookie_rejected",
        cookie=True,
    ),
    # A group post with no single video of its own. With a cookie the adapter reads the post's page
    # and says so itself (POST_WITHOUT_VIDEO_MESSAGE); without one yt-dlp is given the post link and
    # answers "No video formats found" (measured on prod jobs 66 and 145, whose videos are reshared
    # clips). With a cookie yt-dlp only ever gets the post's VIDEO link, so the same text there is about
    # that video, not the post — the category says it. Only for group post links (the adapter's own
    # test of one): a reel with no formats is a different failure.
    _Entry(
        host="facebook",
        markers=(POST_WITHOUT_VIDEO_MESSAGE.lower(),),
        code="format_unavailable",
        detail="facebook.group_post_video",
        link=facebook_group_post_id,
    ),
    _Entry(
        host="facebook",
        markers=("[facebook]", "no video formats found"),
        code="format_unavailable",
        detail="facebook.group_post_video",
        cookie=False,
        link=facebook_group_post_id,
    ),
    # YouTube gates INDIVIDUAL videos behind "Sign in to confirm you're not a bot" (measured on prod
    # job 273, a festival set: all 12 of yt-dlp's player clients fail on that one video while its
    # neighbours download fine, the POT sidecar is live and answering, and the newest yt-dlp fails
    # identically — so this is the video's own signed-out gate, not a broken stack or a stale yt-dlp).
    # The marker is quote-agnostic on purpose: YouTube writes the apostrophe as U+2019, so
    # "you're not a bot" with a straight quote never matches the real text.
    _Entry(
        host="youtube",
        markers=("[youtube]", "not a bot"),
        code="login_required",
        detail="youtube.bot_wall",
        cookie=False,
    ),
    # The same wall WITH a cookie. Not yet reproduced with a real YouTube cookie (this user's first
    # one is being added now) — but "add cookies" is provably the wrong advice for someone who has,
    # and yt-dlp names the likeliest cause itself: "The provided YouTube account cookies are no
    # longer valid. They have likely been rotated in the browser as a security measure."
    _Entry(
        host="youtube",
        markers=("[youtube]", "not a bot"),
        code="login_required",
        detail="youtube.cookie_rejected",
        cookie=True,
    ),
    # The same gate one step later: the player response comes back, and then the CDN refuses the
    # stream itself ("unable to download video data: HTTP Error 403"). Measured 2026-09-16 on the
    # very same video, ~90 minutes after it was answering with the bot message — signed out it
    # 403'd on every attempt; with the owner's cookie attached it downloaded in full (519 MB). So
    # the category this text carries generically, `network`, is a lie here: nothing was wrong with
    # the network. Scoped to a cookie-less YouTube download, where that is what we measured.
    _Entry(
        host="youtube",
        markers=("unable to download video data", "403"),
        code="login_required",
        detail="youtube.media_forbidden",
        cookie=False,
    ),
 )
 def classify(msg: str | None) -> str:
    """Return a category code for a raw failure message (``"unknown"`` if nothing matches)."""
    if not msg:
@@ -112,6 +263,27 @@ def classify(msg: str | None) -> str:
    return "unknown"
 def diagnose(
    msg: str | None, *, url: str | None = None, cookie_attached: bool = False
 ) -> Diagnosis:
    """The catalog entry for this failure of this link, else just its category (see the module doc).
    `url` is the address yt-dlp was given; `cookie_attached` whether the acting user's cookie went
    with it. Without a URL only the category can be known."""
    host = host_key_for_url(url) if msg and url else None
    if host is not None:
        low = msg.lower()  # type: ignore[union-attr] — `host` is only set when `msg` is truthy
        for e in _CATALOG:
            if (
                e.host == host
                and all(m in low for m in e.markers)
                and (e.cookie is None or e.cookie == cookie_attached)
                and (e.link is None or e.link(url))  # type: ignore[arg-type] — as `msg` above
            ):
                return Diagnosis(e.code, e.detail)
    return Diagnosis(classify(msg))
 def user_error_text(source_kind: str, msg: str, code: str) -> str:
    """The failure text to STORE on the job, given the raw message and its category.
@@ -17,8 +17,134 @@ spec shape (all keys optional; defaults + browser-playability clamp applied by `
 `container`/`vcodec` keys survive only so an old stored profile deserializes without error.
 """
 import contextlib
 import contextvars
 import hashlib
 import json
 import logging
 import os
 import re
 import urllib.parse
 from collections.abc import Iterator
 from app import logs
 log = logs.get_logger(__name__)
 # yt-dlp names what it is working on in these shapes, and each one is a row of someone's download
 # history: the source URL, the `[extractor] <id>:` prefix on nearly every warning and error, the
 # file path it writes to (`storage.rel_path` builds it from the channel and the title), a
 # playlist's title, and an id quoted mid-sentence. The job id is already on every line
 # (`logs.set_job` in the download child), so none of them adds anything an operator needs. What
 # stays: the host (it says which extractor is failing) and the extractor tag. Every pattern below
 # is a shape measured in yt-dlp's own source (2026.07.04), pinned in test_ytdlp_logging.py.
 _URL_RE = re.compile(r"https?://([^/\s]+)\S*")
 # `Destination:` is yt-dlp's own word in `[download] Destination: <path>`, not an id — the path
 # after it is what `_PATH_RE` takes out.
 _ID_PREFIX_RE = re.compile(r"(\[[\w:.-]+\] )(?!Destination:)[^\s:\[\]]+:")
 # The generic extractor's "id" is the URL's basename, percent-DECODED: `My%20Holiday.mp4` is
 # `My Holiday` — spaces, brackets, colons and all, which no pattern can bound (`Our Trip: Day 1`
 # ends at which `: `?). The job knows its own URL, so the exact name is taken out as a literal
 # (`hiding`). This pattern is the fallback for a line logged outside that scope: up to the first
 # `: `. Only this extractor: every other one names a site id, and letting the prefix run to `: `
 # everywhere would take the words out of lines like `[VideoConvertor] Converting …; Destination:`.
 _GENERIC_ID_RE = re.compile(r"(\[generic\] )(?!Destination:)[^\[\]\n]+?:(?= |$)", re.M)
 # `[youtube:tab] Playlist <title>: Downloading 5 items` — the title is not an id, and has spaces.
 _PLAYLIST_TITLE_RE = re.compile(r"(\] Playlist ).+?(?=: Downloading )")
 # `[download] Finished downloading playlist: <title>`, `[download] Downloading playlist: <title>`,
 # `… Skipping already downloaded playlist: <title>` — the title runs to the end of the line.
 _TITLE_TAIL_RE = re.compile(r"(playlist: |\[download\] Downloading \w+: ).*", re.I)
 # An id quoted mid-sentence, not as a prefix: `… not available for <id>`, and `--no-playlist`'s
 # `Downloading just the video <id>` (`_yes_playlist`) / `Downloading just video <id>` (multifeed).
 _BARE_ID_RE = re.compile(
    r"((?:subtitles not available for|Downloading just (?:the )?\w+) )[^\s,;]+"
 )
 # Two segments or more, and not glued to a word: `www.youtube.com/…` is what the URL pattern
 # leaves behind, and it must survive this one.
 _PATH_RE = re.compile(r"(?<![\w.…])/(?:[^/\s\"']+/)+[^/\s\"']*")
 _HIDDEN: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar(
    "formats_hidden", default=()
 )
 def generic_id(url: str) -> str:
    """The name yt-dlp's generic extractor gives a URL: its basename, extension off, percent-
    decoded — `InfoExtractor._generic_id` (2026.07.04), pinned against it in the tests."""
    return urllib.parse.unquote(os.path.splitext(url.rstrip("/").split("/")[-1])[0])
@contextlib.contextmanager
 def hiding(url: str | None) -> Iterator[None]:
    """For the work on one URL: `log_safe` also takes out the name yt-dlp's generic extractor
    gives it, exactly, where yt-dlp puts it (`[generic] <name>:`). A context variable, so it
    holds for yt-dlp's logger calls too — they run on the same thread as the extraction."""
    name = generic_id(url) if url else ""
    token = _HIDDEN.set((*_HIDDEN.get(), name) if name else _HIDDEN.get())
    try:
        yield
    finally:
        _HIDDEN.reset(token)
 def log_safe(text: object) -> str:
    """yt-dlp's text (its own lines, or a DownloadError's message) with the parts that name a
    person's download taken out. Every log line that carries yt-dlp's words goes through here,
    not just the adapter's: yt-dlp raises the same text it has just logged, so a line that skipped
    it would put back one line later exactly what the adapter took out."""
    text = str(text)
    for name in _HIDDEN.get():
        text = text.replace(f"[generic] {name}:", "[generic] …:")
    text = _URL_RE.sub(lambda m: f"{m.group(1)}/…", text)
    text = _ID_PREFIX_RE.sub(r"\1…:", text)
    text = _GENERIC_ID_RE.sub(r"\1…:", text)
    text = _PLAYLIST_TITLE_RE.sub(r"\1…", text)
    text = _TITLE_TAIL_RE.sub(r"\1…", text)
    text = _BARE_ID_RE.sub(r"\1…", text)
    return _PATH_RE.sub("…", text)
 class _YdlLog:
    """yt-dlp's logger protocol, pointed at ours.
    Without it yt-dlp explains itself to nobody: `quiet` sends its output to a stdout we do not
    read, so "Requested format is not available", a signature-extraction failure or a POT refusal
    reached us only as whatever text ended up in the raised exception. Measured against yt-dlp
    2026.07.04: with `logger` set it calls `debug` for extraction and progress lines and
    `warning`/`error` for the rest, and `quiet`/`no_warnings` do NOT gate those calls.
    `debug` goes to TRACE: it is several lines per second during a download, so it shows only
    when the whole process runs at TRACE. (Not under a user's own Teljes consent — that lives in
    the API process's request scope, and the download child that runs yt-dlp has none.)
    `error` goes to WARNING, not ERROR. yt-dlp calls it from `trouble()` just before it raises,
    on EVERY failed attempt — including the ones the pipeline then recovers from with its fallback
    client set. Whether the job failed is the pipeline's verdict (`download.job.failed`), and that
    is the one line whose level should say so."""
    def _emit(self, level: int, msg: str) -> None:
        # The line goes as an ARGUMENT, not as the format string. yt-dlp writes progress as
        # `[download]  53.2% of 12.00MiB`, and while stdlib logging only applies `%` formatting to
        # a record that has args, this way the question never arises — and it is the shape ruff's
        # `G` rules ask for. (The sink's flood limiter groups a bare `%s` by the text itself, so
        # distinct yt-dlp warnings do not share one bucket — `logsink._template`.)
        log.log(level, "%s", log_safe(msg), extra=logs.event("download.ytdlp"))
    def debug(self, msg):
        self._emit(logs.TRACE, msg)
    def info(self, msg):
        self._emit(logging.DEBUG, msg)
    def warning(self, msg):
        self._emit(logging.WARNING, msg)
    def error(self, msg):
        self._emit(logging.WARNING, msg)
 _YDL_LOG = _YdlLog()
 # Fields that affect the produced file — and therefore the cache identity.
 _SIG_KEYS = (
@@ -57,6 +183,10 @@ _DEFAULTS = {
 # opt-out), so any asset cached under an old non-compat spec — or a stale non-H.264 mp4 that slipped
 # the v3 net — must re-derive through the current browser-safe guarantee.
 _SIG_VERSION = 4
 # Audio-only downloads version on their own, so a change to the audio bytes doesn't re-download every
 # cached video. v5: an extracted .mp3/.m4a is stored as itself instead of remuxed into an .mp4 that
 # iPad's WebKit refuses to play, so a cached remuxed audio asset must re-derive.
 _AUDIO_SIG_VERSION = 5
 _SPONSORBLOCK_CATEGORIES = ["sponsor", "selfpromo", "interaction"]
@@ -74,7 +204,13 @@ def normalize(spec: dict) -> dict:
        # rather than raising an unhandled 500 at enqueue.
        try:
            s["max_height"] = int(s["max_height"])
-        except (TypeError, ValueError):
+        except (TypeError, ValueError) as exc:
            # "best" is the opposite of what a height cap asks for: the user set a ceiling to save
            # bandwidth or disk, and the download quietly takes the largest rendition there is.
            log.warning(
                "the height cap on a download could not be read and was dropped",
                extra=logs.event("download.format.max_height_dropped", reason=type(exc).__name__),
            )
            s["max_height"] = None
    for b in ("embed_subs", "embed_chapters", "embed_thumbnail", "sponsorblock"):
        s[b] = bool(s[b])
@@ -96,20 +232,34 @@ def normalize(spec: dict) -> dict:
    return s
-def format_sig(spec: dict, salt: str | None = None) -> str:
+def _sig_version(s: dict) -> int:
    return _AUDIO_SIG_VERSION if s["mode"] == "a" else _SIG_VERSION
 def format_sig(spec: dict, salt: str | None = None, *, version: int | None = None) -> str:
    """Stable short hash of the output-affecting spec — the MediaAsset cache key component.
    `salt` forks a distinct, non-dedup identity for the same spec (used by force-redownload so it
-    always re-fetches into its own asset instead of sharing a cached file with other jobs)."""
+    always re-fetches into its own asset instead of sharing a cached file with other jobs).
    `version` hashes under a signature version other than the current one (see `format_sigs`)."""
    s = normalize(spec)
    data = {k: s[k] for k in _SIG_KEYS}
-    data["_v"] = _SIG_VERSION
+    data["_v"] = _sig_version(s) if version is None else version
    if salt is not None:
        data["_salt"] = salt
    payload = json.dumps(data, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(payload.encode()).hexdigest()[:24]
 def format_sigs(spec: dict, salt: str | None = None) -> tuple[str, str]:
    """`format_sig` under the current signature version and under the one before it. An asset keeps
    the signature it was created with, so a job queued before a deploy that bumped the version and
    run after it downloads into an asset carrying the previous one — which must still be recognised
    as that user's private asset (`credentials.is_authed_asset`), or it downloads without its cookie."""
    previous = _sig_version(normalize(spec)) - 1
    return format_sig(spec, salt), format_sig(spec, salt, version=previous)
 def build_ydl_opts(
    spec: dict,
    outtmpl: str,
@@ -163,6 +313,12 @@ def build_ydl_opts(
    if extra:
        opts.update(extra)
    # With a logger attached, `quiet` and `no_warnings` stop deciding whether yt-dlp explains itself
    # and only decide where — so both stay on above and the explanation comes here instead of to a
    # stdout nothing reads. AFTER the adapter merge, like `cookiefile` and the size cap: an adapter
    # must not be able to silence the one account of what went wrong that a failed job leaves.
    opts["logger"] = _YDL_LOG
    # SEC-13: hard ceiling on a single download. AFTER the adapter merge, for the same reason
    # `cookiefile` is — a source adapter must not be able to raise a limit the quota layer set.
    #
@@ -16,7 +16,6 @@ Five passes each run:
 Runs in the API process (which mounts DOWNLOAD_ROOT). Pure disk/DB work — no YouTube quota.
 """
 import logging
 import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
@@ -24,14 +23,13 @@ from pathlib import Path
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.downloads import storage
 from app.models import DownloadJob, MediaAsset
 from app.notifications import create_notification
-log = logging.getLogger("siftlode.downloads.gc")
+log = logs.get_logger(__name__)
 # Dot-prefixed top-level trees that are NOT part of the Plex/flat asset layout — the orphan sweep
 # never touches them (user clips, Plex HLS/img caches, in-progress staging, editor storyboards).
 _SYSTEM_TREE = {".edits", ".plex-hls", ".plex-img-cache", ".staging", ".storyboards"}
@@ -99,6 +97,7 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
        if pause_s and touched % batch == 0:
            time.sleep(pause_s)
    unreclaimed = 0
    for entry in root.iterdir():
        if entry.name.startswith("."):  # .edits / .plex-* / .staging / .storyboards + any dotfile
            continue
@@ -111,7 +110,9 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
                f.unlink()
                removed += 1
            except OSError:
-                pass
+                # silent-ok: counted, not logged per file — a broken mount would put one line
                # under every orphan. The total is reported once at the end of the sweep.
                unreclaimed += 1
        if entry.is_dir():  # prune emptied dirs (deepest first), then the channel dir itself
            for d in sorted(
                (p for p in entry.rglob("*") if p.is_dir()),
@@ -120,12 +121,20 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
            ):
                try:
                    d.rmdir()
                # silent-ok: `rmdir` refusing means the directory still holds files, which is
                # the ordinary answer here — this prune only takes the ones that emptied.
                except OSError:
                    pass
            try:
                entry.rmdir()
            # silent-ok: the same prune one level up, at the channel directory.
            except OSError:
                pass
    if unreclaimed:
        log.warning(
            "some orphaned download files could not be reclaimed",
            extra=logs.event("download.gc.unreclaimed", files=unreclaimed, removed=removed),
        )
    return removed
@@ -49,6 +49,8 @@ def check_grant(token: str, grant: str | None, password_version: int) -> bool:
    exp_s, sig = grant.split(".", 1)
    try:
        exp = int(exp_s)
    # silent-ok: an untrusted grant that does not parse is simply not a valid grant, and the
    # honest answer to it — a password prompt — is the same as for one that expired.
    except ValueError:
        return False
    if exp < datetime.now(timezone.utc).timestamp():
@@ -66,6 +66,8 @@ def _jpeg_size(path: Path) -> tuple[int, int] | None:
                    width = (data[3] << 8) + data[4]
                    return width, height
                f.seek(length - 2, 1)  # skip this segment's payload
    # silent-ok: None omits width/height from the unfurl card, which is what the card does for
    # every poster whose dimensions were never asked for. Nothing is claimed that is not true.
    except OSError:
        return None
@@ -1,6 +1,5 @@
 """Child-side download/edit pipeline — the yt-dlp download + ffmpeg edit that runs in the spawned subprocess."""
 import logging
 import re
 import shutil
 import time
@@ -8,9 +7,8 @@ from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 import yt_dlp
 from sqlalchemy import select
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
@@ -25,12 +23,13 @@ from app.downloads.jobdb import (
    _staging_dir,
    _touch_job,
 )
 from app.downloads.stated import StatedFailure
 from app.downloads.status import JobStatus
 from app.models import DownloadJob, MediaAsset
 from app.notifications import create_notification
 from app.titles import normalize_title
-log = logging.getLogger("siftlode.worker")
+log = logs.get_logger(__name__)
 class _Aborted(Exception):
@@ -99,6 +98,8 @@ def _parse_upload_date(raw) -> date | None:
        return None
    try:
        return datetime.strptime(str(raw), "%Y%m%d").date()
    # silent-ok: a date we cannot read becomes a date the card does not show, which is what the
    # card shows for every source that never supplies one. Absent is the honest rendering.
    except ValueError:
        return None
@@ -114,9 +115,10 @@ def _fill_asset_meta_early(asset_id: int, info: dict) -> None:
        # `or info.get("id")` avoids a blank card while downloading when the cleaned title is empty
        # (e.g. a title that was only a social engagement prefix); the completion path later sets
        # the final title with its own source_ref fallback.
-        asset.title = normalize_title(info.get("title")) or info.get("id")
+        adapter = adapters.resolve_adapter(None, None, info)
        asset.title = normalize_title(adapter.title(info)) or info.get("id")
        asset.uploader = info.get("uploader") or info.get("channel")
-        asset.uploader_url = adapters.resolve_adapter(None, None, info).uploader_url(info)
+        asset.uploader_url = adapter.uploader_url(info)
        asset.thumbnail_url = info.get("thumbnail")
        asset.duration_s = int(info["duration"]) if info.get("duration") else None
        asset.upload_date = _parse_upload_date(info.get("upload_date"))
@@ -138,7 +140,14 @@ def _make_progress_hook(job_id: int, asset_id: int):
            try:
                _fill_asset_meta_early(asset_id, d["info_dict"])
            except Exception:  # noqa: BLE001 — metadata is best-effort, never fail a download
-                pass
+                # Best-effort is about the DOWNLOAD, not about knowing. What this swallows is
                # anything from a shape change in yt-dlp's info dict to the database being down,
                # and all the user sees is a card with an id on it until the job finishes.
                log.info(
                    "early metadata could not be filled in for this download",
                    extra=logs.event("download.meta.early_fill_failed", asset_id=asset_id),
                    exc_info=True,
                )
        if d.get("status") != "downloading":
            return
        if not allow_write():
@@ -299,7 +308,7 @@ def _produced_file(info: dict, staging: Path) -> Path:
        and not _YTDLP_TEMP_RE.search(p.name)
    ]
    if not cands:
-        raise RuntimeError("yt-dlp produced no output file")
+        raise StatedFailure("yt-dlp produced no output file")
    return max(cands, key=lambda p: p.stat().st_size)
@@ -323,14 +332,33 @@ def _extract_with_fallback(
 ):
    """Download via yt-dlp using the source `adapter`'s client sets + options. For YouTube the adapter
    supplies the primary player-client set then a POT-backed fallback (retried on a bot/DRM/format
-    error); other sources make a single attempt. Returns the info dict of the successful attempt.
+    error); a Facebook download WITH a cookie is retried as Chrome behind "Cannot parse data"; other
    sources make a single attempt. Returns the info dict of the successful attempt.
    Before the first attempt the adapter may resolve `url` to the link that really holds the video (a
    Facebook group post → its video's watch link); when the page shows no single video there, or is not
    the post at all (a refused cookie's login page), the adapter raises its own verdict
    (adapters.POST_*_MESSAGE) instead of letting yt-dlp guess, and a failed page read fails the
    download as itself.
    `cookiefile` (S6) is the acting user's per-host cookies.txt, already gated by
    `credentials.resolve_cookiefile`; passed to every attempt so the fallback stays authenticated.
    `max_bytes` (SEC-13) is the owner's remaining storage budget, applied to every attempt."""
-    client_sets = adapter.client_sets()
+    client_sets = adapter.client_sets(authed=cookiefile is not None)
    outtmpl = str(staging / "%(id)s.%(ext)s")
    # Resolving may read a page first — network time the stall watchdog must not see as a stall.
    _touch_job(job_id)
    target = adapter.resolve_url(
        url,
        formats.build_ydl_opts(
            spec,
            outtmpl,
            _make_progress_hook(job_id, asset_id),
            cookiefile=cookiefile,
            max_bytes=max_bytes,
        ),
    )
    last_exc: Exception | None = None
    for i, clients in enumerate(client_sets):
        opts = formats.build_ydl_opts(
@@ -348,7 +376,7 @@ def _extract_with_fallback(
        # killed — acceptable, as socket_timeout + extractor_retries bound one attempt well under it.)
        try:
            with yt_dlp.YoutubeDL(opts) as ydl:
-                return ydl.extract_info(url, download=True)
+                return ydl.extract_info(target, download=True)
        except yt_dlp.utils.DownloadError as exc:
            last_exc = exc
            if i < len(client_sets) - 1 and adapter.retriable(str(exc)):
@@ -356,13 +384,22 @@ def _extract_with_fallback(
                    "job %s: clients %s failed (%s); retrying with fallback",
                    job_id,
                    clients,
-                    str(exc)[:70],
+                    formats.log_safe(exc)[:70],
                )
                for p in list(staging.iterdir()):  # drop partials before the retry
                    try:
                        p.unlink()
-                    except OSError:
+                    except OSError as exc:
-                        pass
+                        # A partial left behind is not inert: the next client set resumes into it,
                        # so the retry this loop exists to make clean starts dirty instead.
                        log.info(
                            "a partial file could not be removed before the retry",
                            extra=logs.event(
                                "download.retry.partial_unlink_failed",
                                job_id=job_id,
                                reason=type(exc).__name__,
                            ),
                        )
                _set_job(job_id, progress=0, phase="downloading")
                continue
            raise
@@ -385,8 +422,12 @@ def _ensure_browser_playable(job_id: int, produced: Path, spec: dict, info: dict
    or just remux when the codecs are fine but the container isn't. **Scope:** only the mp4 compat
    profile is normalized; an explicit `vcodec` or a non-mp4 custom profile is the user opting out
    of the guarantee and is left as-is (so a `webm` profile can still ship VP9/Opus). Returns the
-    file to store (converted, or the original) and corrects `info`'s codec fields to match disk."""
+    file to store (converted, or the original) and corrects `info`'s codec fields to match disk.
-    if spec.get("container") != "mp4" or spec.get("vcodec"):
+
    An audio download (mode "a") is never touched: yt-dlp already extracted it to .mp3 / .m4a, which
    every browser plays as audio/mpeg / audio/mp4. Remuxing it into .mp4 served an mp3 as video/mp4,
    which iPad's WebKit refuses to play (prod job 268)."""
    if spec.get("mode") == "a" or spec.get("container") != "mp4" or spec.get("vcodec"):
        return produced
    vcodec, acodec = editmod.probe_codecs(produced)
    is_mp4 = produced.suffix.lower() == ".mp4"
@@ -425,6 +466,7 @@ def _download(
 ) -> None:
    staging = _staging_dir(asset_id)
    cookiefile: Path | None = None
    url: str | None = None  # read by the failure branch, which can run before it is resolved
    try:
        if staging.exists():
            shutil.rmtree(staging, ignore_errors=True)
@@ -440,17 +482,15 @@ def _download(
            try:
                urlguard.check_url(url)
            except urlguard.BlockedUrl as e:
-                raise RuntimeError(f"Refusing to download from this address ({e.reason}).") from e
+                raise StatedFailure(f"Refusing to download from this address ({e.reason}).") from e
        # S6: attach the acting user's per-host cookie ONLY when it's host-scoped to this URL AND
        # this asset is that user's private, salted identity (the double gate lives in credentials).
        remaining_bytes: int | None = None
        with SessionLocal() as cdb:
-            asset_sig = cdb.execute(
+            target = cdb.get(MediaAsset, asset_id)
-                select(MediaAsset.format_sig).where(MediaAsset.id == asset_id)
+            if target is not None:
            ).scalar_one_or_none()
            if asset_sig is not None:
                cookiefile = credentials.resolve_cookiefile(
-                    cdb, user_id, url, asset_sig, spec, staging
+                    cdb, user_id, url, target, spec, staging
                )
            # SEC-13: what this user has left. `check_enqueue` only compared the footprint as it
            # stood when the job was QUEUED — a download's size is unknown until it finishes, so a
@@ -484,13 +524,19 @@ def _download(
        produced = _produced_file(info, staging)
        produced = _ensure_browser_playable(job_id, produced, spec, info)
        ext = produced.suffix.lstrip(".").lower()
        # Codecs/dims/duration come from a PROBE of the produced file — the ground truth — NOT yt-dlp's
        # `info` dict, whose fields are absent for some sources (Facebook among them): deriving
        # media_kind from those nulls misclassified a real H.264 video as a download-only 'file', and a
        # missing duration hid the trim action. Probed before the sidecars so the .nfo runtime has it
        # too. Same probe the upload ingest uses.
        vcodec, acodec, width, height, duration_s = probe.resolve_media_facts(produced, info)
        meta = storage.MediaMeta(
            video_id=info.get("id") or source_ref,
-            title=normalize_title(info.get("title")) or source_ref,
+            title=normalize_title(adapter.title(info)) or source_ref,
            uploader=info.get("uploader") or info.get("channel") or "Unknown Channel",
            upload_date=_parse_upload_date(info.get("upload_date")),
            uniqueid_type=adapter.nfo_uniqueid_type(),
-            duration_s=int(info["duration"]) if info.get("duration") else None,
+            duration_s=duration_s,
            description=info.get("description"),
            thumbnail_url=info.get("thumbnail"),
        )
@@ -516,12 +562,11 @@ def _download(
                asset.rel_path = rel
                asset.size_bytes = size
                asset.duration_s = meta.duration_s
-                # Codecs/dims come from a PROBE of the finished file — the ground truth — NOT yt-dlp's
+                asset.vcodec, asset.acodec, asset.width, asset.height = (
-                # `info` dict, whose codec fields are absent for some sources (Facebook among them):
+                    vcodec,
-                # deriving media_kind from those nulls misclassified a real H.264 video as a
+                    acodec,
-                # download-only 'file' with no in-app play/edit. Same probe the upload ingest uses.
+                    width,
-                asset.vcodec, asset.acodec, asset.width, asset.height = probe.resolve_media_facts(
+                    height,
                    final, info
                )
                asset.container = ext
                asset.media_kind = mediakind.derive(asset.vcodec, asset.acodec)
@@ -559,13 +604,23 @@ def _download(
            db.commit()
            if finalized:
                _notify_download_done(db, owner_id, meta.title, job_id, kind="download")
-                log.info("job %s done: %s", job_id, rel)
+                # The asset id, not `rel`: the path is built from the channel and the title.
                log.info(
                    "job %s done: asset %s",
                    job_id,
                    asset_id,
                    extra=logs.event("download.job.done", job_id=job_id, asset_id=asset_id),
                )
    except (_Aborted, editmod.EditAborted):
        # Paused/canceled mid-download or mid-transcode: free the asset for a later retry; keep the
        # job's status (the route set it to paused/canceled). ref_count is adjusted by the route.
        _reset_asset_pending(asset_id)
-        log.info("job %s aborted (pause/cancel)", job_id)
+        log.info(
            "job %s aborted (pause/cancel)",
            job_id,
            extra=logs.event("download.job.aborted", job_id=job_id),
        )
    except _OwnerRefused as exc:
        # Fail this job only. The asset is never marked `error`; it goes back to `pending` (below),
        # so another user's job for the same video is claimed and downloaded normally instead of
@@ -578,6 +633,7 @@ def _download(
                status=JobStatus.ERROR,
                error=msg,
                error_code=dlerrors.classify(msg),
                error_detail=None,
                phase=None,
            )
            db.commit()
@@ -585,29 +641,41 @@ def _download(
        # it, and this one must already be out of the way. (The staging tree is still torn down in
        # `finally` below — the same narrow window the pause/cancel path above has always had.)
        _reset_asset_pending(asset_id)
-        log.info("job %s refused for its owner: %s", job_id, msg)
+        log.info(
            "job %s refused for its owner: %s",
            job_id,
            formats.log_safe(msg),
            extra=logs.event("download.job.refused", job_id=job_id),
        )
    except Exception as exc:  # noqa: BLE001 — surface any failure to the user, keep worker alive
        msg = str(exc)[:500]
-        code = dlerrors.classify(msg)
+        # The catalog needs the link and whether the user's cookie went with it: the same yt-dlp
        # text is Facebook's login wall without one and a refused cookie with one.
        diagnosis = dlerrors.diagnose(msg, url=url, cookie_attached=cookiefile is not None)
        # SEC-12: redact a transport-level readout for user-supplied URLs (see user_error_text).
-        msg = dlerrors.user_error_text(source_kind, msg, code)
+        msg = dlerrors.user_error_text(source_kind, msg, diagnosis.code)
        with SessionLocal() as db:
            asset = db.get(MediaAsset, asset_id)
            if asset:
                asset.status = "error"
                asset.error = msg
-            # Atomic fail: only while still running, so a route-set cancel/pause is never overwritten
+            # Atomic fail: only while still running, so a route-set cancel/pause is never
-            # with `error` (error also holds the asset → would re-open the double-release class).
+            # overwritten with `error` (error also holds the asset → would re-open the
            # double-release class).
            service.finalize_if_running(
                db,
                job_id,
                status=JobStatus.ERROR,
                error=msg,
-                error_code=code,
+                error_code=diagnosis.code,
                error_detail=diagnosis.detail,
                phase=None,
            )
            db.commit()
-        log.warning("job %s failed: %s", job_id, msg)
+        # After the write: a job the write could not fail is not a failed job. When it raises,
        # the runner reports this failure with it (`runner._run`) and the worker fails the job.
        # silent-ok: not silent — `_log_download_failed` is the report.
        _log_download_failed(job_id, msg, diagnosis.code, exc)
    finally:
        # Unlink the decrypted cookie file explicitly (the rmtree below removes the whole staging
        # tree too, but never leave a plaintext session cookie on disk a moment longer than needed).
@@ -616,7 +684,50 @@ def _download(
        shutil.rmtree(staging, ignore_errors=True)
-def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
+def _failure_stack(exc: BaseException) -> dict[str, str]:
    """The `extra=` fragment that puts a failure's traceback on its line — or nothing.
    Nothing for yt-dlp's DownloadError and for our own `StatedFailure` (`ffmpeg failed (1): …`):
    their message is the whole story, and their stack is only the `except` that caught them.
    Everything else keeps it — a TypeError on an odd info dict, a plain RuntimeError, an OSError,
    a database error: that is our code or our platform failing, and the stack is the lead.
    Scrubbed, link by link (`logs.scrubbed_stack`): a stack's messages are data — an OSError names
    its file, and a database error raised inside `except DownloadError` carries yt-dlp's
    unscrubbed text as its context."""
    if isinstance(exc, (yt_dlp.utils.DownloadError, StatedFailure)):
        return {}
    return logs.scrubbed_stack(exc, formats.log_safe)
 def _log_download_failed(job_id: int, msg: str, code: str | None, exc: BaseException) -> None:
    """The child's `download.job.failed` line. `msg` is the user's copy and keeps their URL; the
    log's copy goes through `log_safe`, or it would put back one line later the URL and id the
    yt-dlp adapter took out of the line before it. The stack only when the classifier could not
    place the failure: a recognised one is fully described by its code."""
    unplaced = code in (None, "", "unknown")
    log.warning(
        "job %s failed: %s",
        job_id,
        formats.log_safe(msg),
        extra={
            **logs.event(
                "download.job.failed",
                job_id=job_id,
                error_code=code,
                error_type=type(exc).__name__,
            ),
            **(_failure_stack(exc) if unplaced else {}),
        },
    )
 def _fail_edit(job_id: int, asset_id: int, msg: str, exc: BaseException | None = None) -> None:
    """Fail an edit job, and say so ONCE — every way an edit fails comes through here, so this is
    where its line and its event code live. `exc` is the exception when there was one.
    Its traceback goes with the line unless the message already tells it all (`_failure_stack`).
    Logged after the write, as on the download error path."""
    with SessionLocal() as db:
        asset = db.get(MediaAsset, asset_id)
        if asset:
@@ -632,7 +743,22 @@ def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
            phase=None,
        )
        db.commit()
-    log.warning("edit job %s failed: %s", job_id, msg)
+    # `msg` is the user's copy; ffmpeg's stderr tail in it can name the source file, whose path is
    # built from the channel and the title.
    log.warning(
        "edit job %s failed: %s",
        job_id,
        formats.log_safe(msg),
        extra={
            **logs.event(
                "edit.job.failed",
                job_id=job_id,
                asset_id=asset_id,
                **({"error_type": type(exc).__name__} if exc is not None else {}),
            ),
            **(_failure_stack(exc) if exc is not None else {}),
        },
    )
 def _process_edit(job_id: int, asset_id: int) -> None:
@@ -684,7 +810,7 @@ def _process_edit(job_id: int, asset_id: int) -> None:
            should_cancel=_cancel_poll(job_id),
        )
        if not dest_staging.exists():
-            raise RuntimeError("ffmpeg produced no output file")
+            raise StatedFailure("ffmpeg produced no output file")
        rel = storage.edit_rel_path(user_id, asset_id, out_ext)
        storage.place_file(dest_staging, settings.download_root, rel)
@@ -720,13 +846,24 @@ def _process_edit(job_id: int, asset_id: int) -> None:
            db.commit()
            if finalized:
                _notify_download_done(db, owner_id, dl_title, job_id, kind="edit")
-                log.info("edit job %s done: %s", job_id, rel)
+                # The asset id, not `rel`: the path is built from the channel and the title.
                log.info(
                    "edit job %s done: asset %s",
                    job_id,
                    asset_id,
                    extra=logs.event("edit.job.done", job_id=job_id, asset_id=asset_id),
                )
    except editmod.EditAborted:
        # Paused/canceled mid-encode: free the asset for a later retry (ref_count is the route's job).
        _reset_asset_pending(asset_id)
-        log.info("edit job %s aborted (pause/cancel)", job_id)
+        log.info(
            "edit job %s aborted (pause/cancel)",
            job_id,
            extra=logs.event("edit.job.aborted", job_id=job_id),
        )
    except Exception as exc:  # noqa: BLE001 — surface the failure, keep the worker alive
-        _fail_edit(job_id, asset_id, str(exc)[:500])
+        # silent-ok: not silent — `_fail_edit` is the report, and it takes `exc` for its stack.
        _fail_edit(job_id, asset_id, str(exc)[:500], exc)
    finally:
        shutil.rmtree(staging, ignore_errors=True)
@@ -64,6 +64,8 @@ def _facts_from_probe(
        raw = fmt.get("duration")
        if raw is not None:
            duration = int(float(raw))
    # silent-ok: an unusable duration is stored as no duration, which the UI renders as unknown
    # rather than as zero — the honest state, and the one a re-probe can still fill in.
    except (TypeError, ValueError):
        duration = None
    return vcodec, acodec, width, height, duration
@@ -81,10 +83,12 @@ def probe_media(path: Path) -> tuple[str | None, str | None, int | None, int | N
 def resolve_media_facts(
    path: Path, info: dict
-) -> tuple[str | None, str | None, int | None, int | None]:
+) -> tuple[str | None, str | None, int | None, int | None, int | None]:
-    """(vcodec, acodec, width, height) for the stored download asset: PROBE the finished file on disk
+    """(vcodec, acodec, width, height, duration_s) for the stored download asset: PROBE the finished
-    (the ground truth). yt-dlp's `info` omits codec/dimension fields for some sources (Facebook among
+    file on disk (the ground truth). yt-dlp's `info` omits codec/dimension fields for some sources
-    them), so deriving media_kind from it there labelled a real H.264 video a download-only 'file'.
+    (Facebook among them), so deriving media_kind from it there labelled a real H.264 video a
    download-only 'file'. It omits the duration too (a Facebook reel, an Instagram reel), and a NULL
    duration hides the Library row's trim action although the file plays for minutes.
    Precedence is by whether the probe RAN, not per-field: if ffprobe read the file, its codec verdict
    is authoritative — INCLUDING a deliberate None (cover-art-only audio, a still image). A per-field
@@ -92,16 +96,23 @@ def resolve_media_facts(
    have (yt-dlp reports a progressive `vcodec` for an audio-mode download whose video it then strips),
    mislabelling an audio download as a broken in-app 'video'. Only when ffprobe could NOT read the
    file at all do we fall back to `info` (the pre-probe behaviour, a safety net); the cosmetic
-    dimensions still gap-fill from `info` in either case."""
+    dimensions and the duration still gap-fill from `info` in either case."""
    data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
    info_v = info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
    info_a = info.get("acodec") if info.get("acodec") not in (None, "none") else None
    info_w = int(info["width"]) if info.get("width") else None
    info_h = int(info["height"]) if info.get("height") else None
    info_d = int(info["duration"]) if info.get("duration") else None
    if data is None:
        # ffprobe could not read the file — fall back to the extractor's info entirely.
-        return info_v, info_a, info_w, info_h
+        return info_v, info_a, info_w, info_h, info_d
-    pv, pa, pw, ph, _dur = _facts_from_probe(data)
+    pv, pa, pw, ph, pd = _facts_from_probe(data)
    # Probe ran → its codecs win outright (a None means "no such track", not "unknown"); info only
-    # gap-fills the cosmetic width/height the probe couldn't read.
+    # gap-fills the width/height/duration the probe couldn't read.
-    return pv, pa, pw if pw is not None else info_w, ph if ph is not None else info_h
+    return (
        pv,
        pa,
        pw if pw is not None else info_w,
        ph if ph is not None else info_h,
        pd if pd is not None else info_d,
    )
@@ -11,18 +11,20 @@ writes the terminal job/asset state itself (done / error, or a cooperative pause
 progress hook), then exits 0. An unexpected crash exits non-zero and the parent fails the job.
 """
 import logging
 import os
 import shutil
 import subprocess
 import sys
 from app import logs
 from app import logsink
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
 from app.downloads import formats
 from app.models import DownloadJob
-log = logging.getLogger("siftlode.worker.runner")
+log = logs.get_logger(__name__)
 def _deprioritize() -> None:
@@ -52,12 +54,21 @@ def _deprioritize() -> None:
 def main() -> None:
-    logging.basicConfig(level=logging.INFO)
+    logs.configure_logging("runner")
    _deprioritize()
    if len(sys.argv) != 2:
-        print("usage: python -m app.downloads.runner <job_id>", file=sys.stderr)
+        # noqa T201: a usage line is for the person who typed the command. Logging is already
        # configured here, and in a deployment it writes JSON records — the one reader of this
        # line wants the bare sentence, not a record with a request id they do not have.
        print(  # noqa: T201
            "usage: python -m app.downloads.runner <job_id>", file=sys.stderr
        )
        raise SystemExit(2)
    job_id = int(sys.argv[1])
    # This whole process exists to run ONE job — tag every line it prints with it, so the child's
    # output joins up with the worker's and the API's view of the same download.
    logs.set_job(job_id)
    logsink.start()  # flushed at exit (atexit) — this process has no shutdown hook of its own
    with SessionLocal() as db:
        job = db.get(DownloadJob, job_id)
@@ -71,14 +82,40 @@ def main() -> None:
    if asset_id is None:
        return
    _run(job_id, asset_id, job_kind, source_kind, source_ref, spec, user_id)
 def _run(job_id, asset_id, job_kind, source_kind, source_ref, spec, user_id) -> None:
    """Run the job, and be the last stop before Python's own exception hook.
    What gets past the pipeline is a failure it could not even record (the database refused the
    write that fails the job). Python's hook would print it to stderr raw — and its context is the
    download's own failure, whose text is the URL or ffmpeg's stderr naming the file. Here it is
    one line with the whole chain scrubbed; the non-zero exit then has the worker fail the job
    (`cause=child_exit`)."""
    # Imported here (not at module top) so the child pays the yt-dlp import cost only when it has
    # real work, and to keep the import graph obvious: runner is a thin entry over the pipeline.
    from app.downloads.pipeline import _download, _process_edit
-    if job_kind == "edit":
+    with formats.hiding(source_ref):
-        _process_edit(job_id, asset_id)
+        try:
-    else:
+            if job_kind == "edit":
-        _download(job_id, asset_id, source_kind, source_ref, spec, user_id)
+                _process_edit(job_id, asset_id)
            else:
                _download(job_id, asset_id, source_kind, source_ref, spec, user_id)
        except Exception as exc:  # noqa: BLE001 — whatever it is, it is reported here or raw
            # noqa TRY400: the stack goes with it scrubbed (`scrubbed_stack`); `exc_info` is raw.
            log.error(  # noqa: TRY400
                "the download child for job %s failed",
                job_id,
                extra={
                    **logs.event(
                        "download.child.failed", job_id=job_id, error_type=type(exc).__name__
                    ),
                    **logs.scrubbed_stack(exc, formats.log_safe),
                },
            )
            raise SystemExit(1) from None
 if __name__ == "__main__":
@@ -7,6 +7,7 @@ handles everything else. State transitions used by the routes (pause/resume/canc
 the worker live in `worker.py` / the routes; this module owns enqueue + asset bookkeeping.
 """
 import uuid
 from datetime import datetime, timezone
 from sqlalchemy import func, select, update
@@ -80,11 +81,15 @@ def get_or_create_asset(
        status="pending",
        ref_count=0,
    )
    db.add(asset)
    try:
-        db.flush()
+        # A SAVEPOINT: losing the race undoes only this insert, never the caller's own pending writes
        # (Retry clears the job's error before it gets here; a whole-session rollback threw that away).
        with db.begin_nested():
            db.add(asset)
            db.flush()
    # silent-ok: the expected outcome of the race this savepoint exists for — two jobs wanting the
    # same asset. Losing it means the other insert won, and re-selecting is the whole handling.
    except IntegrityError:
        db.rollback()
        asset = db.execute(stmt).scalar_one()
    return asset
@@ -341,13 +346,20 @@ def pause(db: Session, job: DownloadJob) -> None:
 def resume(db: Session, job: DownloadJob) -> None:
    """Requeue a paused/errored job for a fresh attempt, clearing its error. If the SHARED asset itself
    failed, reset it to pending so the worker actually re-downloads — otherwise the requeued job would
-    instantly re-inherit the asset's stale error (the worker short-circuits an errored asset)."""
+    instantly re-inherit the asset's stale error (the worker short-circuits an errored asset).
    A cookie the user added AFTER the job was queued moves the job onto their private asset first
    (`_follow_the_cookie`): the worker only ever attaches a cookie to that identity, so without the move
    the Retry a login-wall message asks for would fail on the same wall."""
    if job.status in (JobStatus.PAUSED, JobStatus.ERROR):
        job.progress = 0
        job.error = None
        job.error_code = None
        job.error_detail = None
        if job.asset_id:
            asset = db.get(MediaAsset, job.asset_id)
            if asset is not None:
                asset = _follow_the_cookie(db, job, asset)
            if asset and asset.status == "error":  # MediaAsset.status (no enum), not a JobStatus
                asset.status = "pending"
                asset.error = None
@@ -355,6 +367,32 @@ def resume(db: Session, job: DownloadJob) -> None:
        db.commit()
 def _follow_the_cookie(db: Session, job: DownloadJob, asset: MediaAsset) -> MediaAsset:
    """Re-point a requeued job at the asset enqueue would pick NOW, when the user has a cookie for the
    link's host but the job still holds an asset the worker won't attach it to (queued before the
    cookie existed). Returns the asset the job holds afterwards.
    Only a `pending` / `error` asset moves — neither has a file nor a download in flight. A `ready` one
    already has the file, and a `downloading` one may be this job's own child still being stopped by
    the pause; the next Retry after it settles moves the job then. Removing a cookie never moves a job
    back: the worker attaches nothing without a credential, so the private asset is as good as any."""
    if asset.status not in ("pending", "error"):
        return asset
    url = source_url(job.source_kind, job.source_ref)
    salt = credentials.salt_for_enqueue(db, job.user_id, url)
    spec = formats.normalize(job.profile_snapshot)
    if salt is None or credentials.is_authed_asset(asset, spec, job.user_id, url):
        return asset
    target = get_or_create_asset(
        db, job.source_kind, job.source_ref, formats.format_sig(spec, salt=salt)
    )
    populate_from_catalog(db, target)
    release_asset(db, job)  # drop the old hold BEFORE re-pointing — it keys off job.asset_id
    incr_ref_count(db, target.id)
    job.asset_id = target.id
    return target
 def cancel(db: Session, job: DownloadJob) -> None:
    """Cancel a job unless it's already done/canceled, releasing its asset hold WHILE it still counts
    as holding — `canceled` ∉ HOLDING, so a later delete won't double-release."""
@@ -373,13 +411,31 @@ def delete(db: Session, job: DownloadJob) -> None:
 def redownload(db: Session, job: DownloadJob) -> None:
    """Rebuild a finished/failed job's file into a FRESH, private asset (the cache sig is salted with
-    the job id + current asset id, so it never reuses the dedup pool) and requeue the SAME job row —
+    the new asset's own id, so it never reuses the dedup pool) and requeue the SAME job row —
    so any public share link (DownloadLink -> job_id) keeps resolving to the newly-downloaded file.
    The old hold is dropped first (freeing the old file iff this job was its last holder). The caller
-    has already rejected edit clips + still-in-progress jobs (HTTP 409)."""
+    has already rejected edit clips + still-in-progress jobs (HTTP 409).
    When the user has a cookie for the link's host, the salt carries it (`credentials.rebuild_salt`),
    so the worker recognises the rebuild as their private identity and attaches the cookie — a cookie
    download, or one the user added after a failure, rebuilds with the cookie."""
    spec = formats.normalize(job.profile_snapshot)
-    sig = formats.format_sig(spec, salt=f"{job.id}:{job.asset_id}")
+    cookie = credentials.salt_for_enqueue(
-    asset = get_or_create_asset(db, job.source_kind, job.source_ref, sig)
+        db, job.user_id, source_url(job.source_kind, job.source_ref)
    )
    # The salt names the row's own id, which exists only once the row does: insert it under a unique
    # placeholder, then write the real signature in the same transaction (nobody sees the placeholder).
    asset = MediaAsset(
        source_kind=job.source_kind,
        source_ref=job.source_ref,
        format_sig=f"rebuild:{uuid.uuid4().hex}",
        status="pending",
        ref_count=0,
    )
    db.add(asset)
    db.flush()
    asset.format_sig = formats.format_sig(spec, salt=credentials.rebuild_salt(asset.id, cookie))
    db.flush()
    populate_from_catalog(db, asset)
    # Drop the old hold BEFORE re-pointing the job — release_asset keys off the job's current asset.
    release_asset(db, job)
@@ -389,6 +445,8 @@ def redownload(db: Session, job: DownloadJob) -> None:
    job.progress = 0
    job.phase = None
    job.error = None
    job.error_code = None  # a rebuild that fails again gets its own diagnosis, never the old one
    job.error_detail = None
    job.speed_bps = None
    job.eta_s = None
    # Re-derive the display name from the freshly cleaned title on completion (else an older, un-cleaned
@@ -0,0 +1,13 @@
 """The failures the download pipeline raises itself, with the whole story in the message.
 `ffmpeg failed (1): …`, `yt-dlp produced no output file`, a post that shows no video: the message
 says what happened, and the stack is only the `except` that caught it. A failure line leaves that
 stack off (`pipeline._failure_stack`) — but ONLY for these. A plain `RuntimeError` is also what
 Python raises for a bug of ours (a dict changed size during iteration, a generator's
 StopIteration, `RecursionError`, `NotImplementedError`), and that one's stack is the only lead.
 """
 class StatedFailure(RuntimeError):
    """A failure we raised on purpose, whose message is its full explanation. A `RuntimeError` so
    every `except RuntimeError` that caught these before still does."""
@@ -19,8 +19,11 @@ from datetime import date
 from pathlib import Path
 from xml.sax.saxutils import escape
 from app import logs
 from app.downloads import mediakind
 log = logs.get_logger(__name__)
 # Reserve room for the "_id.ext" suffix + parent dirs within the 255-char component limit.
 _MAX_TITLE = 120
 # User-facing (Content-Disposition) names can be longer than an on-disk component.
@@ -294,7 +297,13 @@ def write_sidecars(download_root: str, rel: str, meta: MediaMeta, thumb_src: Pat
        if thumb_src and thumb_src.exists():
            shutil.copyfile(str(thumb_src), str(_sidecar(media, ".jpg")))
        return True
-    except OSError:
+    except OSError as exc:
        # The download itself still completes, so the job reads as done while the library it was
        # downloaded FOR has no .nfo to read and no poster to show.
        log.warning(
            "the sidecars beside a download could not be written",
            extra=logs.event("download.sidecars.write_failed", reason=type(exc).__name__),
        )
        return False
@@ -304,14 +313,23 @@ def delete_asset_files(download_root: str, rel: str) -> None:
    for p in (media, _sidecar(media, ".nfo"), _sidecar(media, ".jpg")):
        try:
            p.unlink()
-        except OSError:
+        except FileNotFoundError:
-            pass
+            pass  # silent-ok: already gone is the outcome this function wanted
        except OSError as exc:
            # The row goes and the bytes stay. Nothing else ever revisits this path, so the disk
            # quietly keeps a file no account has any way to see, let alone delete.
            log.info(
                "a deleted download left a file behind",
                extra=logs.event("download.asset.file_unlink_failed", reason=type(exc).__name__),
            )
    # Prune empty Season/Channel dirs up to (but not including) the root.
    root = Path(download_root).resolve()
    parent = media.parent
    while parent != root and root in parent.parents:
        try:
            parent.rmdir()  # only succeeds if empty
        # silent-ok: this `rmdir` failing is the loop's stop condition — the parent still
        # holds another download's files, so the prune has gone as far up as it may.
        except OSError:
            break
        parent = parent.parent
@@ -11,7 +11,6 @@ to be a person telling them nothing arrived.
 """
 import html
 import logging
 import re
 import smtplib
 import ssl
@@ -21,15 +20,14 @@ from email.utils import formatdate
 from sqlalchemy import select
 from sqlalchemy.orm import Session
-from app import mailtext, sysconfig
+from app import logs, mailtext, sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.models import User
 from app.notifications import create_notification
 from app.ratelimit import RateLimiter
-log = logging.getLogger("siftlode.email")
+log = logs.get_logger(__name__)
 # One admin notice an hour per reason. A relay that is down fails every send, and the inbox must
 # stay readable; the log keeps the full record either way.
 _alert_throttle = RateLimiter(max_events=1, window_seconds=3600)
@@ -155,7 +153,15 @@ def _send(to: list[str], subject: str, body: str, reply_to: str | None = None) -
        return False
    c = _smtp()
    if not (c["host"] and c["user"] and c["password"]):
-        log.info("SMTP not configured; skipping email %r to %s", subject, recipients)
+        # The count, not the addresses: `redact_text` rewrites every one of them to `[email]`
        # before either sink sees the line, so the list only ever printed as noise. The subject
        # stays — the templates are static, and the one that interpolates (`admin_new_request`)
        # interpolates an address, which the same redactor covers.
        log.info(
            "SMTP not configured; skipping email %r to %d recipient(s)",
            subject,
            len(recipients),  # log-pii-ok: how many, not who
        )
        _alert_admins("not_configured", subject, recipients)
        return False
    msg = EmailMessage()
@@ -176,10 +182,12 @@ def _send(to: list[str], subject: str, body: str, reply_to: str | None = None) -
            s.starttls(context=ssl.create_default_context())
            s.login(c["user"], c["password"])
            s.send_message(msg)
-        log.info("Sent email %r to %s", subject, recipients)
+        # log-pii-ok: how many, not who
        log.info("Sent email %r to %d recipient(s)", subject, len(recipients))
        return True
    except Exception:
-        log.exception("SMTP send failed (%r to %s)", subject, recipients)
+        # log-pii-ok: how many, not who
        log.exception("SMTP send failed (%r to %d recipient(s))", subject, len(recipients))
        _alert_admins("send_failed", subject, recipients)
        return False
@@ -0,0 +1,774 @@
 """Structured logging for every Siftlode process — the ONE place logging is configured.
 Before this module a single deployment printed FOUR different log formats: uvicorn's
 `log_config.json` for the API, a hand-rolled StreamHandler in `main.py` for everything that did not
 start under uvicorn (tests, scripts), `logging.basicConfig()` in the worker and in the download
 child (no timestamp at all), and alembic's `fileConfig`. None of them carried a correlation id, and
 uvicorn's access log printed the query string of every request (`?account=1`, `?source=feed`) — so
 the logs were both unjoinable and leaky. `configure_logging()` replaces all four.
 Event shape — the OpenTelemetry log data model, without the SDK; one JSON object per line:
    ts · level · sev · source · logger · event · msg · attrs
 plus whatever correlation the context carries (`request_id`, `user_id`, `debug_session_id`,
 `job_id`) and the app version. That shape is what E22.6's admin console filters on and what a Gitea
 issue attachment will carry, so it is deliberately flat and stable.
 Call sites stay ordinary stdlib logging:
    log = logs.get_logger(__name__)  # app/downloads/pipeline.py -> siftlode.downloads.pipeline
    log.info("job finished", extra=logs.event("download.job.done", job_id=7, bytes=n))
 `event()` is optional — a bare `log.info("…")` still comes out well-formed — but the dotted code is
 what makes a line queryable later, so add one wherever the line matters.
 REDACTION IS APPLIED AT THE HANDLER, not at the call site: every message, every attr value and
 every traceback passes `redact()` on the way out. That is the whole point — a secret cannot be
 leaked by forgetting to redact it at one of ~125 call sites, and a new call site is safe by
 default. Never logged, at any level: passwords, tokens (session, reset/verify, setup, share,
 OAuth), cookie blobs, secret config values, and email addresses.
 """
 import contextlib
 import contextvars
 import json
 import logging
 import logging.config
 import re
 import sys
 import threading
 import time
 import traceback
 import uuid
 from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 from urllib.parse import parse_qsl
 from app.config import settings
 from app.ratelimit import RateLimiter, client_key
 # One level below DEBUG for the "Teljes / TRACE" diagnostics level (search strings, redacted request
 # bodies). Registered on import so `logging.getLogger(...).log(logs.TRACE, …)` and a `LOG_LEVEL=TRACE`
 # both work in every process, including one that never calls configure_logging (a test).
 TRACE = 5
 logging.addLevelName(TRACE, "TRACE")
 # OpenTelemetry severity numbers for our level names. Kept beside the level because the number is
 # what a log backend sorts and filters on; the name is for humans reading a terminal.
 SEVERITY: dict[str, int] = {
    "TRACE": 1,
    "DEBUG": 5,
    "INFO": 9,
    "WARNING": 13,
    "ERROR": 17,
    "CRITICAL": 21,
 }
 # Which process this is. Set by configure_logging; every line carries it so one Loki/DB query can
 # separate the API's view of a job from the worker's.
 _source = "api"
 # --- correlation context -------------------------------------------------------------------
 # contextvars, like quota's actor attribution (app/quota.py): set at an entry point, read by the
 # formatter, never threaded through call signatures. A child task copies the context at creation,
 # so anything set before `await call_next(...)` is visible to the whole request.
 _request_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
    "log_request_id", default=None
 )
 _user_id: contextvars.ContextVar[int | None] = contextvars.ContextVar("log_user_id", default=None)
 _debug_session: contextvars.ContextVar[str | None] = contextvars.ContextVar(
    "log_debug_session", default=None
 )
 _job_id: contextvars.ContextVar[int | None] = contextvars.ContextVar("log_job_id", default=None)
 _CONTEXT_VARS = {
    "request_id": _request_id,
    "user_id": _user_id,
    "debug_session_id": _debug_session,
    "job_id": _job_id,
 }
 class _RequestScope:
    """What the auth dependency learns about a request, for every line logged after it.
    A MUTABLE object behind a contextvar, not plain contextvars, because of how a request actually
    runs: FastAPI resolves a sync dependency (`auth.current_user`) in a threadpool on a COPY of the
    context, so a `ContextVar.set()` there is gone by the time the handler runs — measured: that is
    how the account never reached a handler's own lines. `log_requests` installs one scope per
    request; every copied context shares the same object, so what the dependency writes is seen by
    the handler and by the request line itself."""
    __slots__ = ("user_id", "level")
    def __init__(self) -> None:
        self.user_id: int | None = None
        # The user's consented diagnostics level as a logging number; None at the base level.
        self.level: int | None = None
 _scope: contextvars.ContextVar[_RequestScope | None] = contextvars.ContextVar(
    "log_request_scope", default=None
 )
 def set_user(user_id: int | None, level: str = "INFO", until: datetime | None = None) -> None:
    """Attribute the rest of this request's log lines to `user_id`, and log them at the user's
    consented diagnostics `level` until `until` (E22 S5; "INFO" = no elevation). Called from the
    auth dependency — the one place the session is actually resolved into an account — rather than
    from the request middleware, which runs OUTSIDE the session middleware."""
    _user_id.set(user_id)
    scope = _scope.get()
    if scope is None:  # outside log_requests (a script, a unit test): this context only
        scope = _RequestScope()
        _scope.set(scope)
    elevated = level != "INFO" and until is not None and until > datetime.now(timezone.utc)
    scope.user_id = user_id
    scope.level = resolve_level(level) if elevated else None
    if user_id is not None:
        _track_elevation(user_id, scope.level, until)
 def set_job(job_id: int | None) -> None:
    """Attribute this process's log lines to a download job — for the download CHILD, whose whole
    life is one job (the worker uses `bind()` per job instead, since it juggles several)."""
    _job_id.set(job_id)
@contextlib.contextmanager
 def bind(**fields: Any):
    """Bind correlation fields for the duration of a block (a worker job, a scheduler run):
        with logs.bind(job_id=job.id):
            ...
    Unknown field names are ignored rather than raising — a caller binding a field this module does
    not know about is a typo, not a reason to take down a download."""
    tokens = [(_CONTEXT_VARS[k].set(v)) for k, v in fields.items() if k in _CONTEXT_VARS]
    keys = [k for k in fields if k in _CONTEXT_VARS]
    try:
        yield
    finally:
        for key, token in zip(keys, tokens):
            _CONTEXT_VARS[key].reset(token)
 def event(code: str, /, **attrs: Any) -> dict[str, Any]:
    """`extra=` payload for a log call: a stable dotted event code plus structured attributes.
    Returns a plain dict so it composes with stdlib logging and costs nothing when the level is off
    (the dict is built either way; keep the attrs cheap — no DB reads inside the call).
    `code` is positional-only so that no attribute name is reserved: `event("x", code=...)` means
    the attribute, not this parameter. Without the `/` it was a TypeError, and `code` is exactly
    the word a caller reaches for when the thing that failed has one of its own."""
    return {"event": code, "attrs": attrs}
 # --- redaction -----------------------------------------------------------------------------
 # Substring matching, not exact keys: the same secret travels as `password`, `current_password`,
 # `new_password`, `smtp_password`, `plex_server_token`, `access_token`, … Matching on the PART is
 # what makes a key we have never seen safe by default.
 _SECRET_KEY_PARTS = (
    "password",
    "passphrase",
    "token",
    "secret",
    "cookie",
    "authorization",
    "auth_header",
    "ciphertext",
    "private_key",
    "api_key",
    "apikey",
    "credential",
    "session_key",
 )
 # Query/fragment parameters that carry a credential in a URL we log (OAuth `code`/`state`, our own
 # `?token=` setup and share links, `#verify=` / `#reset=` fragments).
 _SECRET_PARAM_NAMES = (
    "access_token",
    "refresh_token",
    "id_token",
    "token",
    "code",
    "state",
    "key",
    "secret",
    "password",
    "pwd",
    "sig",
    "signature",
    "verify",
    "reset",
    "setup",
 )
 _SECRET_PARAM_RE = re.compile(
    r"\b((?:" + "|".join(_SECRET_PARAM_NAMES) + r")=)([^&\s\"']+)",
    re.IGNORECASE,
 )
 # Deliberately loose: over-matching redacts a non-address that looks like one (harmless), while
 # under-matching puts a real address in a log we attach to an issue (not harmless).
 _EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
 REDACTED = "[redacted]"
 # `extra={PERSIST: False}` keeps a line out of the `log_events` table while stdout still gets it —
 # how `log_requests` caps anonymous traffic per client (app/logsink.py reads it).
 PERSIST = "persist"
 REDACTED_EMAIL = "[email]"
 def redact_text(text: str) -> str:
    """Scrub a free-text string: credential-bearing URL params and email addresses."""
    scrubbed = _SECRET_PARAM_RE.sub(lambda m: f"{m.group(1)}{REDACTED}", text)
    return _EMAIL_RE.sub(REDACTED_EMAIL, scrubbed)
 def redact_query(query: str) -> str:
    """Scrub a raw query string. DECODED first: the text rules match what was typed, and a browser
    sends it percent-encoded — `someone%40example.com` is an address `_EMAIL_RE` cannot see. Each
    parameter also goes through the key rules, so `?new_password=` goes as `redact` would drop it."""
    pairs = parse_qsl(query, keep_blank_values=True)
    return "&".join(f"{key}={_redact_param(key, value)}" for key, value in pairs)
 def _redact_param(key: str, value: str) -> str:
    """One decoded `key=value` pair. The parameter-NAME rule is applied to the key here rather than
    left to `_SECRET_PARAM_RE` over the rebuilt pair: that pattern was written for the raw,
    percent-encoded query, where a value holds no literal space, `&` or quote, and its value class
    stops at the first one. On decoded text `?state=a%20b` would keep its tail and `?code=%20abc`
    would not match at all — the whole credential straight into the line."""
    if key.lower() in _SECRET_PARAM_NAMES:
        return REDACTED
    return str(redact(value, key=key))
 def redact(value: Any, *, key: str = "") -> Any:
    """Recursively scrub a structure destined for the log.
    A value whose KEY names a secret is dropped whole (we never log a prefix of a token — a prefix
    is still a leak and still useless). Everything else is scrubbed as text. Depth is bounded by
    the structures we actually log (attrs dicts), and non-JSON types fall through to `str`."""
    lowered = key.lower()
    if key and any(part in lowered for part in _SECRET_KEY_PARTS):
        return REDACTED
    if isinstance(value, dict):
        return {k: redact(v, key=str(k)) for k, v in value.items()}
    if isinstance(value, (list, tuple)):
        return [redact(v, key=key) for v in value]
    if isinstance(value, str):
        return redact_text(value)
    return value
 # --- formatters ----------------------------------------------------------------------------
 _SCRUBBED_STACK = "scrubbed_stack"
 def scrubbed_stack(exc: BaseException, scrub: Callable[[BaseException], str]) -> dict[str, str]:
    """`extra=` fragment: `exc`'s traceback, rendered where an `exc_info` stack goes, with the
    message of every exception in it put through `scrub`.
    For a failure whose message can name someone's data (a download's URL, a file path, a video
    id). The frames name code and are kept whole; the text at the foot of each link is the data.
    A plain `exc_info` renders the chain too — the `__cause__`/`__context__` a DB error raised
    inside `except DownloadError` carries — so scrubbing only the line's own message is not
    enough. Merge it into the call's `extra`: `{**event(...), **scrubbed_stack(...)}`."""
    links: list[BaseException] = []
    link: BaseException | None = exc
    while link is not None and all(link is not seen for seen in links):
        links.append(link)
        link = link.__cause__ or (None if link.__suppress_context__ else link.__context__)
    parts: list[str] = []
    for i in range(len(links) - 1, -1, -1):  # the oldest first, as Python prints a chain
        link = links[i]
        kind = type(link)
        name = kind.__qualname__
        if kind.__module__ not in ("builtins", "__main__"):
            name = f"{kind.__module__}.{name}"
        try:
            message = scrub(link)
        # silent-ok: the message is what could not be rendered, and the placeholder says so — the
        # caller is in the middle of reporting one failure and must not get a second from here.
        except Exception:  # noqa: BLE001 — a `__str__` that raises, of any shape
            message = "<unprintable>"
        frames = "".join(traceback.format_tb(link.__traceback__))
        head = f"Traceback (most recent call last):\n{frames}" if frames else ""
        parts.append(f"{head}{name}: {message}" if message else f"{head}{name}")
        if i:
            parts.append(
                "\nThe above exception was the direct cause of the following exception:\n"
                if links[i - 1].__cause__ is link
                else "\nDuring handling of the above exception, another exception occurred:\n"
            )
    return {_SCRUBBED_STACK: "\n".join(parts)}
 # Attributes every LogRecord carries; anything else a caller passed via `extra=` is a structured
 # attribute and is merged into `attrs` (so `extra={"job_id": 7}` works as well as `event(...)`).
 _RECORD_STANDARD = frozenset(
    vars(logging.LogRecord("", 0, "", 0, "", None, None)).keys()
    | {"message", "asctime", "taskName", "event", "attrs", PERSIST, "elevated", _SCRUBBED_STACK}
 )
 class ContextFilter(logging.Filter):
    """Copies the correlation contextvars onto the record. A Filter (not the formatter) so the
    values are captured at emit time, before a QueueHandler can move the record to another
    thread — the DB sink in S3 depends on that."""
    def filter(self, record: logging.LogRecord) -> bool:
        for name, var in _CONTEXT_VARS.items():
            value = var.get()
            if value is not None and not hasattr(record, name):
                setattr(record, name, value)
        scope = _scope.get()
        if scope is not None and scope.user_id is not None and not hasattr(record, "user_id"):
            record.user_id = scope.user_id
        return True
 class LevelGate(logging.Filter):
    """The configured level, enforced at the HANDLER, with one exception: the lines of a request
    whose user raised their diagnostics level (E22 S5).
    The root logger's level cannot do this alone: it is one number for the whole process, and the
    point is to log ONE user's requests in detail while everyone else's stay at the base level. So
    the root is lowered to the lowest level any active elevation needs (`_track_elevation`), and
    this gate drops what only an elevation let through unless the line belongs to that elevated
    request. It also marks such a line `elevated`, which is what makes the `log_events` sink keep
    every line of that request, not just its warnings."""
    def filter(self, record: logging.LogRecord) -> bool:
        scope = _scope.get()
        if scope is not None and scope.level is not None:
            record.elevated = True
            return record.levelno >= min(scope.level, _base_level)
        return record.levelno >= _base_level
 def _record_attrs(record: logging.LogRecord) -> dict[str, Any]:
    extra = {k: v for k, v in vars(record).items() if k not in _RECORD_STANDARD}
    attrs = dict(getattr(record, "attrs", None) or {})
    attrs.update({k: v for k, v in extra.items() if k not in _CONTEXT_VARS})
    return attrs
 def _safe_message(record: logging.LogRecord) -> str:
    """`record.getMessage()` raises if the args don't match the format string. A broken log call
    must not take down the caller, so the failure is reported IN the line instead."""
    try:
        return record.getMessage()
    # silent-ok: the failure is reported IN the returned line. Logging it would re-enter this same
    # formatter with a record built out of the one that just failed.
    except Exception as exc:  # noqa: BLE001 — any formatting error, reported not raised
        return f"{record.msg!r} (log formatting failed: {exc})"
 def record_fields(record: logging.LogRecord) -> dict[str, Any]:
    """The event as structured fields, REDACTED — the one definition both the stdout line and the
    `log_events` row are built from, so the two sinks can never disagree about what is safe to keep.
    Absent optional fields are left out; `ts` is an aware datetime."""
    fields: dict[str, Any] = {
        "ts": datetime.fromtimestamp(record.created, timezone.utc),
        "level": record.levelname,
        "sev": SEVERITY.get(record.levelname, 9),
        "source": _source,
        "logger": record.name,
        "msg": redact_text(_safe_message(record)),
    }
    code = getattr(record, "event", None)
    if code:
        fields["event"] = code
    for name in _CONTEXT_VARS:
        value = getattr(record, name, None)
        if value is not None:
            fields[name] = value
    attrs = _record_attrs(record)
    if attrs:
        fields["attrs"] = redact(attrs)
    if record.exc_info:
        fields["exc"] = redact_text(logging.Formatter().formatException(record.exc_info))
    elif getattr(record, _SCRUBBED_STACK, None):
        fields["exc"] = redact_text(getattr(record, _SCRUBBED_STACK))
    elif record.exc_text:
        # A QueueHandler-style hand-off formats the traceback into exc_text and drops exc_info.
        fields["exc"] = redact_text(record.exc_text)
    fields["version"] = settings.app_version
    return fields
 class JsonFormatter(logging.Formatter):
    """One JSON object per line — the shape Loki and the `log_events` table both ingest."""
    def format(self, record: logging.LogRecord) -> str:
        payload = record_fields(record)
        payload["ts"] = payload["ts"].isoformat(timespec="milliseconds")
        return json.dumps(payload, ensure_ascii=False, default=str)
 class TextFormatter(logging.Formatter):
    """Human-readable single line for a terminal (`LOG_FORMAT=text`): the same content, ordered for
    reading. Redaction applies here too — a dev log is still a log someone pastes into an issue."""
    def format(self, record: logging.LogRecord) -> str:
        stamp = datetime.fromtimestamp(record.created, timezone.utc).strftime("%H:%M:%S.%f")[:-3]
        head = f"{stamp} {record.levelname:<5} [{record.name}]"
        rid = getattr(record, "request_id", None)
        if rid:
            head += f" {rid}"
        code = getattr(record, "event", None)
        line = f"{head} {code + ' — ' if code else ''}{redact_text(_safe_message(record))}"
        attrs = _record_attrs(record)
        if attrs:
            line += f" {json.dumps(redact(attrs), ensure_ascii=False, default=str)}"
        if record.exc_info:
            line += "\n" + redact_text(self.formatException(record.exc_info))
        elif getattr(record, _SCRUBBED_STACK, None):
            line += "\n" + redact_text(getattr(record, _SCRUBBED_STACK))
        return line
 # --- configuration -------------------------------------------------------------------------
 # Third-party loggers that are noisy at our own level. Pinned explicitly so the diagnostics knob can
 # lower the ROOT level to DEBUG/TRACE without drowning the output in SQL statements and HTTP chatter
 # — raising THESE is a deliberate, separate act (E22.6's console).
 _THIRD_PARTY_LEVELS = {
    "sqlalchemy": "WARNING",
    "sqlalchemy.engine": "WARNING",
    "apscheduler": "WARNING",
    "urllib3": "WARNING",
    "httpx": "WARNING",
    "httpcore": "WARNING",
    "asyncio": "WARNING",
    "multipart": "WARNING",
    "PIL": "WARNING",
    "alembic": "INFO",
    # uvicorn's own startup/shutdown/WebSocket lines are worth keeping; its ACCESS log is not —
    # it is one line per request with the query string in it, replaced by `log_requests` below.
    "uvicorn": "INFO",
    "uvicorn.error": "INFO",
    "uvicorn.access": "CRITICAL",
 }
 def get_logger(name: str) -> logging.Logger:
    """The logger for one module: `logs.get_logger(__name__)` in `app/plex/sync.py` is
    `siftlode.plex.sync`.
    The names were literals before, and 25 of them covered 34 modules — six different Plex modules
    all called themselves `siftlode.plex`, so neither a level pinned per logger nor E22.6's console
    filter could tell a sync line from a stream line. Derived from `__name__` there is exactly one
    name per module, it cannot drift from the file it sits in, and `test_logger_names.py` fails if a
    module hand-rolls one again.
    `__main__` is resolved to the module it really is. The worker runs as `python -m app.worker`
    and spawns `python -m app.downloads.runner`, so in the two long-running processes `__name__`
    is `__main__` — taken at its word, both would log as the bare root. `-m` records the real name
    on the module's spec; a plain script has none and stays the root."""
    if name == "__main__":
        spec = getattr(sys.modules.get("__main__"), "__spec__", None)
        name = getattr(spec, "name", None) or name
    stem = name.removeprefix("app.") if name.startswith("app.") else ""
    # logger-name-ok: this call IS the derivation
    return logging.getLogger(f"siftlode.{stem}" if stem else "siftlode")
 def resolve_level(name: str) -> int:
    """Level name → number. Both ways in (the `LOG_LEVEL` env and the `log_level` admin knob) are
    already held to the `LogLevel` choices, so an unknown name here is a programming error."""
    value = logging.getLevelName(name)
    if not isinstance(value, int):
        raise ValueError(f"unknown log level {name!r}")
    return value
 def configure_logging(source: str) -> None:
    """Configure logging for THIS process. Call once, first thing, in every entry point:
    `main.py` (api), `worker.main`, `downloads/runner.main`, `alembic/env.py`.
    `source` names the process in every line. The level starts at `LOG_LEVEL` (the bootstrap default);
    the runtime admin knob goes through `set_level()` instead, so changing it needs no restart.
    Our loggers deliberately keep `propagate=True` and own no handler: everything reaches the single
    root StreamHandler. That is what keeps `caplog` working in tests, and it means a new logger name
    is configured the moment it is created."""
    global _source
    _source = source
    formatter = settings.log_format
    logging.config.dictConfig(
        {
            "version": 1,
            # Never disable loggers created at import time (module-level `getLogger` calls run
            # before this function does).
            "disable_existing_loggers": False,
            "formatters": {
                "json": {"()": f"{__name__}.JsonFormatter"},
                "text": {"()": f"{__name__}.TextFormatter"},
            },
            "filters": {
                "context": {"()": f"{__name__}.ContextFilter"},
                "gate": {"()": f"{__name__}.LevelGate"},
            },
            "handlers": {
                "stdout": {
                    "class": "logging.StreamHandler",
                    "stream": sys.stdout,
                    "formatter": formatter,
                    "filters": ["context", "gate"],
                }
            },
            "root": {"level": resolve_level(settings.log_level), "handlers": ["stdout"]},
            "loggers": {name: {"level": lvl} for name, lvl in _THIRD_PARTY_LEVELS.items()},
        }
    )
    set_level(settings.log_level)
 def set_level(name: str) -> None:
    """Change the running process's level (the `log_level` admin knob). Third-party loggers keep
    their pinned levels, so turning on DEBUG shows OUR detail, not SQLAlchemy's."""
    global _base_level
    _base_level = resolve_level(name)
    _apply_root_level(force=True)
 def current_level() -> str:
    """The configured level — not the root logger's, which an active elevation may have lowered."""
    return logging.getLevelName(_base_level or logging.getLogger().getEffectiveLevel())
 # --- per-user elevation (E22 S5) -----------------------------------------------------------
 # The base level (`LOG_LEVEL`, then the admin knob). NOTSET until configure_logging runs — a unit
 # test, a script — so the gate lets everything through there, as it did before the gate existed.
 _base_level = logging.NOTSET
 # user id → (level number, expiry) for every elevation this process has seen and not yet expired.
 _elevations: dict[int, tuple[int, datetime]] = {}
 _elevations_lock = threading.Lock()
 _root_applied: int | None = None
 def _track_elevation(user_id: int, level: int | None, until: datetime | None) -> None:
    with _elevations_lock:
        if level is None or until is None:
            _elevations.pop(user_id, None)
        else:
            _elevations[user_id] = (level, until)
        active = bool(_elevations)
    if active or _root_applied != _base_level:
        _apply_root_level()
 def _apply_root_level(force: bool = False) -> None:
    """Root level = the lowest of the base and every unexpired elevation (expired ones are pruned
    here). `setLevel` clears every logger's level cache, so it runs only when the number changes."""
    global _root_applied
    if _base_level == logging.NOTSET:
        return  # not configured: the root keeps whatever the process set up
    now = datetime.now(timezone.utc)
    # The level is SET under the lock too, not just computed: two threads that each computed a
    # different answer would otherwise apply them in either order, and the older one could win —
    # the root back at the base while an elevation is still active.
    with _elevations_lock:
        for user_id in [u for u, (_, until) in _elevations.items() if until <= now]:
            del _elevations[user_id]
        lowest = min([_base_level, *(lvl for lvl, _ in _elevations.values())])
        if force or lowest != _root_applied:
            logging.getLogger().setLevel(lowest)
            _root_applied = lowest
 # --- erased accounts ------------------------------------------------------------------------
 # `auth.purge_user` deletes an account's `log_events` rows, but a line about that account can still
 # be on its way: the erasing request's own access line is logged AFTER the handler committed, a queued
 # row waits for the sink's writer, a background task logs later. Those rows are stored without the
 # account (`logsink` asks here). Remembered for an hour in this process — a line later than that has
 # no request left to come from, and the retention job is the backstop for any other process.
 ERASED_MEMORY_SECONDS = 3600.0
 _erased: dict[int, float] = {}
 _erased_lock = threading.Lock()
 # Held by whoever checks rows against `is_erased` AND writes them (`erasure_guard`). `forget_user`
 # takes it too, so an erasure waits for a write that already passed the check to commit — and the
 # purge's DELETE, which runs after `forget_user`, then removes those rows as well. Without it a row
 # checked a moment before the erasure could be inserted a moment after the DELETE.
 _erasure_guard = threading.Lock()
 def erasure_guard() -> threading.Lock:
    """Hold this around "drop erased accounts from these rows, insert them, commit"."""
    return _erasure_guard
 def forget_user(user_id: int) -> None:
    """Mark `user_id` erased: no line logged about it from now on is stored under its id. Call BEFORE
    deleting its rows (see `_erasure_guard`)."""
    now = time.monotonic()
    with _erasure_guard, _erased_lock:
        for stale in [u for u, at in _erased.items() if now - at > ERASED_MEMORY_SECONDS]:
            del _erased[stale]
        _erased[user_id] = now
    with _elevations_lock:
        _elevations.pop(user_id, None)
    # That pop can have removed the lowest elevation, and the root level is the lowest of the base
    # and every unexpired one. Recomputed here rather than left to whichever later request happens
    # to call `_track_elevation` — the invariant `_apply_root_level` documents holds at every pop.
    _apply_root_level()
 def is_erased(user_id: int | None) -> bool:
    if user_id is None:
        return False
    with _erased_lock:
        at = _erased.get(user_id)
    return at is not None and time.monotonic() - at <= ERASED_MEMORY_SECONDS
 def current_source() -> str:
    """The process name `configure_logging` was given (api, worker, runner, alembic)."""
    return _source
 # --- request logging -----------------------------------------------------------------------
 # A client may supply its own request id so a browser log line and a server line join up (E22 S4).
 # Accepted only in this shape: it ends up in a log field, and an unbounded header would be a way to
 # write arbitrary text into the log.
 _REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9._-]{8,64}$")
 # Paths whose success is logged at DEBUG rather than INFO: the container healthcheck runs every 15s
 # (5.7k lines/day saying nothing) and hashed static assets are served by the hundred per page load.
 # A FAILURE on either still logs at WARNING/ERROR — this lowers the floor, it does not hide.
 _QUIET_PREFIXES = ("/healthz", "/assets/", "/static/")
 # Not `siftlode.logs`: this is the replacement for uvicorn's ACCESS log, and `siftlode.http` is
 # what an operator pins a level on when they want request lines and nothing else. The module it
 # happens to live in is not what the name is about.
 _request_log = logging.getLogger("siftlode.http")  # logger-name-ok: named for the traffic
 async def log_requests(request, call_next):
    """The single access-log line, replacing uvicorn's.
    What changes versus `uvicorn.access`: the ROUTE TEMPLATE instead of the concrete path (so
    `/api/videos/{video_id}` groups), never the query string (it carried `?account=`, and at TRACE
    the redacted query belongs in attrs, not in the URL), a request id echoed back in
    `X-Request-Id` (with the template in `X-Route`), the duration, and the account — read from `request.state`, which the auth
    dependency fills, because this middleware sits outside both the session middleware and the
    downstream task's context."""
    incoming = request.headers.get("x-request-id", "")
    rid = incoming if _REQUEST_ID_RE.match(incoming) else uuid.uuid4().hex[:16]
    token = _request_id.set(rid)
    scope = _RequestScope()
    scope_token = _scope.set(scope)
    request.state.request_id = rid
    started = time.perf_counter()
    try:
        response = await call_next(request)
    except Exception:
        # The unhandled-exception path: FastAPI's ServerErrorMiddleware re-raises after its own
        # 500, so without this the ONE request that most needs a log line is the one with no
        # access-log entry at all.
        _request_log.exception(
            "request failed",
            extra={
                **event(
                    "http.request",
                    method=request.method,
                    path=_route_template(request),
                    duration_ms=round((time.perf_counter() - started) * 1000, 1),
                ),
                **_request_owner(request, logging.ERROR),
            },
        )
        _scope.reset(scope_token)
        _request_id.reset(token)
        raise
    duration_ms = round((time.perf_counter() - started) * 1000, 1)
    status = response.status_code
    quiet = request.url.path.startswith(_QUIET_PREFIXES)
    if status >= 500:
        level = logging.ERROR
    elif status >= 400:
        level = logging.WARNING
    else:
        level = logging.DEBUG if quiet else logging.INFO
    attrs: dict[str, Any] = {
        "method": request.method,
        "path": _route_template(request),
        "status": status,
        "duration_ms": duration_ms,
    }
    # Teljes (TRACE) the user consented to: the query string too — redacted, and in attrs only, never
    # in the message.
    if request.url.query and _traced(scope):
        attrs["query"] = redact_query(request.url.query)
    _request_log.log(
        level,
        "%s %s %s",
        request.method,
        _route_template(request),
        status,
        extra={**event("http.request", **attrs), **_request_owner(request, level)},
    )
    response.headers["X-Request-Id"] = rid
    # The template, so the browser's copy of this line groups the same way (frontend lib/http.ts).
    # Only a MATCHED route's: a template never carries a path parameter's value (a share token stays
    # `{token}`), while the raw-path fallback of an unmatched request could — the browser then
    # templates the path itself.
    matched = _matched_route(request)
    if matched:
        response.headers["X-Route"] = matched
    _scope.reset(scope_token)
    _request_id.reset(token)
    return response
 def consented_trace() -> bool:
    """Whether the current request's OWN user turned Teljes (TRACE) on — the gate for a line that
    carries what they typed or what was quoted back to them. The level alone is not enough: an
    admin running the whole process at TRACE would pass it for every user, and a scheduler thread,
    which has no request, for none of them in particular. Guard such a line with this, then log it
    at TRACE."""
    scope = _scope.get()
    return scope is not None and _traced(scope)
 def _traced(scope: _RequestScope) -> bool:
    """Whether this request's query string is logged: only under its OWN user's Teljes consent. An
    admin setting the whole process to TRACE gets more detail, not every user's search terms — the
    privacy policy promises those are kept only for a user who agreed to it."""
    return scope.level is not None and scope.level <= TRACE
 # Anonymous request lines kept per client per minute. Signed-in traffic is not capped: it is a known
 # account and exactly what an admin needs to see. Anonymous traffic is where the volume can come from
 # nobody in particular — a scanner walking `/wp-login.php`, a bot on a share link — and each of its
 # 404s is a WARNING that would otherwise land in `log_events` without limit. The client key is an
 # in-memory counter key only; no address is ever written to a log line or a row.
 ANONYMOUS_LINES_PER_MINUTE = 60
 _anonymous_lines = RateLimiter(ANONYMOUS_LINES_PER_MINUTE, 60.0)
 def _request_owner(request, level: int) -> dict[str, Any]:
    """`extra=` fields naming who the request belongs to, and whether its line may be stored. The
    account comes from `request.state` (filled by the auth dependency), so it lands in the line's
    top-level `user_id` — the correlation field — rather than in `attrs`."""
    user_id = getattr(request.state, "user_id", None)
    if user_id is not None:
        return {"user_id": user_id}
    if level < logging.INFO:
        return {}  # a quiet line is never stored anyway — don't spend the client's allowance on it
    return {} if _anonymous_lines.allow(client_key(request)) else {PERSIST: False}
 def _matched_route(request) -> str | None:
    """The matched route's template (`/api/videos/{video_id}`), or None when nothing matched."""
    return getattr(request.scope.get("route"), "path", None)
 def _route_template(request) -> str:
    """The matched route's template, else the raw path for a 404 or a static file. Never the query
    string."""
    return _matched_route(request) or request.url.path
@@ -0,0 +1,345 @@
 """The `log_events` sink (E22 S3): the stored copy of the log the diagnostics console reads.
 stdout stays the complete log (docker keeps 3×50 MB of it); this table keeps the part worth querying
 for `log_retention_days`:
  * every WARNING and above,
  * the `http.request` line of every request at INFO or above (not the DEBUG-level health checks and
    static files),
  * every line of a request whose user raised their diagnostics level (E22 S5 — `logs.LevelGate`
    marks them), which is the detail they consented to have kept,
  * nothing a caller marked `extra={logs.PERSIST: False}` — how the request log caps anonymous
    traffic per client.
 What the table must never do is slow down or break the code that logs. So a line is redacted and
 turned into a row on the CALLER's thread (the same `logs.record_fields` the stdout line is built
 from), put on a bounded queue without blocking, and written in batches by one background thread
 on its own connection — never inside a request's transaction. A full queue drops the row and
 counts it; a failed write drops the batch and says so on stderr. Both are reported rather than
 retried: a log that retries into a sick database is how a small outage becomes a big one.
 Flood control is the second half. On 2026-09-16 a YouTube RSS outage made prod log 11k near-identical
 warnings in four hours. stdout keeps them all; the table keeps `REPEATS_PER_MINUTE` of each message
 template per minute and one `log.repeats_suppressed` row saying how many more there were.
 Core layer: imports `logs`, `db`, `models`, `config` — nothing above them.
 """
 import atexit
 import json
 import logging
 import queue
 import re
 import sys
 import threading
 import time
 from datetime import datetime, timedelta, timezone
 from typing import Any
 from sqlalchemy import delete, insert
 from sqlalchemy.engine import Engine
 from sqlalchemy.orm import Session
 from app import logs
 from app.config import settings
 from app.db import engine
 from app.models import LogEvent
 QUEUE_MAX = 10_000
 BATCH_MAX = 500
 FLUSH_SECONDS = 1.0
 REPEATS_PER_MINUTE = 30
 REPEAT_WINDOW_SECONDS = 60.0
 # Distinct templates tracked per window. Past this many, a new template is stored without counting
 # — the limiter must not become the unbounded thing it exists to prevent.
 _REPEAT_KEYS_MAX = 2_000
 # Column widths from models.LogEvent. A value past its column would fail the WHOLE batch it rides in.
 _LIMITS = {
    "level": 10,
    "source": 16,
    "logger": 128,
    "event": 64,
    "request_id": 64,
    "debug_session_id": 64,
    "version": 64,
    "msg": 8_000,
    "exc": 32_000,
 }
 _log = logs.get_logger(__name__)
 def should_store(record: logging.LogRecord) -> bool:
    """Whether this record belongs in `log_events` (see the module docstring)."""
    if getattr(record, logs.PERSIST, True) is False:
        return False
    if record.levelno >= logging.WARNING or getattr(record, "elevated", False):
        return True
    return getattr(record, "event", None) == "http.request" and record.levelno >= logging.INFO
 def _without_nul(value: Any) -> Any:
    """`value` with every NUL character replaced, in keys and nested values alike. Postgres refuses
    NUL in text and `\\u0000` in JSONB, and a refused row fails the WHOLE batch it rides in — every
    user's rows with it. Anything logged can carry one (`GET /assets/%00` logs the decoded path)."""
    if isinstance(value, str):
        return value.replace("\x00", "�")
    if isinstance(value, dict):
        return {_without_nul(k): _without_nul(v) for k, v in value.items()}
    if isinstance(value, list):
        return [_without_nul(v) for v in value]
    return value
 def to_row(fields: dict[str, Any]) -> dict[str, Any]:
    """`logs.record_fields` output → a `log_events` row: known columns only, text clipped to its
    column and free of NUL, attrs made JSON-safe (anything exotic becomes its `str`, as on stdout)."""
    row = {
        column: fields.get(column) for column in LogEvent.__table__.columns.keys() if column != "id"
    }
    for column, limit in _LIMITS.items():
        value = row.get(column)
        if isinstance(value, str):
            value = _without_nul(value)
            row[column] = value[: limit - 1] + "…" if len(value) > limit else value
    if row["attrs"] is not None:
        row["attrs"] = _without_nul(
            json.loads(json.dumps(row["attrs"], ensure_ascii=False, default=str))
        )
    return row
 def without_erased(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """The rows, with the account taken off any whose account was erased meanwhile
    (`logs.forget_user`). Checked right before the INSERT, under `logs.erasure_guard()` held until
    the commit: a row built before the erasure can still be waiting for its batch."""
    for row in rows:
        if logs.is_erased(row.get("user_id")):
            row["user_id"] = None
    return rows
 def _notice(code: str, msg: str, **attrs: Any) -> dict[str, Any]:
    """A row the sink writes about ITSELF. Built directly, not logged: logging it would route it back
    through this sink (and the writer thread's own records are deliberately ignored)."""
    return to_row(
        {
            "ts": datetime.now(timezone.utc),
            "level": "WARNING",
            "sev": logs.SEVERITY["WARNING"],
            "source": logs.current_source(),
            "logger": _log.name,
            "event": code,
            "msg": msg,
            "attrs": attrs,
            "version": settings.app_version,
        }
    )
 _DIGITS = re.compile(r"\d+")
 def _template(record: logging.LogRecord) -> str:
    """The flood limiter's grouping key: the message template. Except when the template is a bare
    `%s` — a pass-through for someone else's text (yt-dlp's lines, `formats._YdlLog`), where the
    template says nothing and every distinct line would share one bucket. Then the text itself
    groups, with its numbers folded, so `Retrying fragment 5 (1/10)` and `(2/10)` are still one
    repeat and a different warning is not crowded out by them."""
    msg = str(record.msg)
    if msg != "%s" or not record.args:
        return msg
    return _DIGITS.sub("#", record.getMessage())[:200]
 class _Repeats:
    """Per-template admission for one minute at a time. Used by the writer thread only (unlocked)."""
    def __init__(self, per_window: int, window_seconds: float):
        self.per_window = per_window
        self.window = window_seconds
        self.started = time.monotonic()
        self.seen: dict[tuple[str, str, int], int] = {}
    def admit(self, key: tuple[str, str, int] | None) -> bool:
        if key is None:
            return True
        count = self.seen.get(key)
        if count is None and len(self.seen) >= _REPEAT_KEYS_MAX:
            return True
        self.seen[key] = (count or 0) + 1
        return self.seen[key] <= self.per_window
    def roll(self, now: float, *, final: bool = False) -> list[dict[str, Any]]:
        """Close the window if it is over — or, `final`, because the process is: one notice per
        template that went past the limit. Without `final` a process that lives under a minute
        (every download child) would drop its repeats and never say so."""
        if not final and now - self.started < self.window:
            return []
        notices = [
            _notice(
                "log.repeats_suppressed",
                f"{count - self.per_window} more like this were not stored",
                logger=logger,
                template=logs.redact_text(template),
                suppressed=count - self.per_window,
                window_seconds=int(self.window),
            )
            for (logger, template, _level), count in self.seen.items()
            if count > self.per_window
        ]
        self.seen.clear()
        self.started = now
        return notices
 class LogSink(logging.Handler):
    """The handler plus its writer. `start()` runs the writer thread; a test drives `write_pending()`
    directly instead, on its own thread, with no timing involved."""
    def __init__(self, bind: Engine = engine):
        super().__init__(level=logging.NOTSET)
        # Correlation fields are contextvars: capture them now, on the thread that logged.
        self.addFilter(logs.ContextFilter())
        self._bind = bind
        self._queue: queue.Queue[tuple[tuple[str, str, int] | None, dict[str, Any]]] = queue.Queue(
            QUEUE_MAX
        )
        self._dropped = 0
        self._dropped_lock = threading.Lock()
        self._repeats = _Repeats(REPEATS_PER_MINUTE, REPEAT_WINDOW_SECONDS)
        self._stopping = threading.Event()
        self._writer: threading.Thread | None = None
    # --- caller side ---------------------------------------------------------------------------
    def emit(self, record: logging.LogRecord) -> None:
        if threading.current_thread() is self._writer:
            return  # the writer's own trouble (a driver warning mid-insert) must not feed itself
        if not should_store(record):
            return
        try:
            row = to_row(logs.record_fields(record))
        # silent-ok: `handleError` is the report — logging's own out-of-band channel to stderr.
        # A log call here would be handed to this handler, which is the one that just failed.
        except Exception:  # noqa: BLE001 — a record we cannot turn into a row is reported, not raised
            self.handleError(record)
            return
        # Request lines are one per request by nature; only the repeated SAME message is a flood.
        key = (
            None
            if row["event"] == "http.request"
            else (record.name, _template(record), record.levelno)
        )
        try:
            self._queue.put_nowait((key, row))
        # silent-ok: counted, not logged — the count goes out as the `log.sink.dropped` notice row
        # the writer emits, which is the one report that does not feed this queue again.
        except queue.Full:
            with self._dropped_lock:
                self._dropped += 1
    # --- writer side ---------------------------------------------------------------------------
    def write_pending(self, wait: float = 0.0, *, final: bool = False) -> int:
        """Write one batch: whatever is queued (up to BATCH_MAX), waiting up to `wait` seconds for the
        first item. Returns the number of rows written, notices included. `final` closes the
        repeat window early — the last batch before the process exits."""
        rows: list[dict[str, Any]] = []
        try:
            item = self._queue.get(timeout=wait) if wait > 0 else self._queue.get_nowait()
        # silent-ok: an idle sink. Nothing failed; there was simply nothing waiting.
        except queue.Empty:
            item = None
        while item is not None:
            key, row = item
            if self._repeats.admit(key):
                rows.append(row)
            if len(rows) >= BATCH_MAX:
                break
            try:
                item = self._queue.get_nowait()
            # silent-ok: the batch ends here because the queue ran dry, which is the normal end.
            except queue.Empty:
                item = None
        rows.extend(self._repeats.roll(time.monotonic(), final=final))
        with self._dropped_lock:
            dropped, self._dropped = self._dropped, 0
        if dropped:
            rows.append(
                _notice("log.sink.dropped", f"{dropped} log events were dropped", dropped=dropped)
            )
        if not rows:
            return 0
        try:
            # The connection is checked out BEFORE the guard, and every request path takes them in
            # that order too (its session already holds a connection when it reaches the guard). The
            # other way round, this thread would hold a process-global lock while waiting up to
            # `pool_timeout` for a connection, and the requests that could return one are the ones
            # blocked on the lock. The guard still spans the check, the insert and the commit.
            with self._bind.connect() as conn, logs.erasure_guard(), conn.begin():
                conn.execute(insert(LogEvent), without_erased(rows))
        except Exception as exc:  # noqa: BLE001 — the database is down or refused the batch
            # silent-ok / noqa T201: the sink's OWN failure. A log call here would be handed to
            # this sink, which is the thing that just failed — straight into a loop. stderr is
            # the one way out that does not re-enter.
            print(  # noqa: T201
                f"log sink: could not store {len(rows)} log events: "
                f"{logs.redact_text(str(exc))[:300]}",
                file=sys.stderr,
            )
            return 0
        return len(rows)
    def _run(self) -> None:
        while not self._stopping.is_set():
            self.write_pending(wait=FLUSH_SECONDS)
        while self.write_pending():  # drain what arrived before the stop
            pass
        self.write_pending(final=True)  # and the repeat notices of a window cut short
    def start(self) -> None:
        self._writer = threading.Thread(target=self._run, name="log-sink", daemon=True)
        self._writer.start()
    def stop(self, timeout: float = 5.0) -> None:
        self._stopping.set()
        if self._writer is not None:
            self._writer.join(timeout)
 _sink: LogSink | None = None
 def start() -> None:
    """Attach the sink to the root logger and start its writer. Call after `logs.configure_logging`
    (which replaces the root handlers) and once the schema exists. A no-op when `LOG_DB_SINK` is off
    or it is already running."""
    global _sink
    if _sink is not None or not settings.log_db_sink:
        return
    _sink = LogSink()
    # The same level gate as stdout: the root may be lowered for one user's elevated requests, and
    # everyone else's detail must not reach the table through that gap either.
    _sink.addFilter(logs.LevelGate())
    logging.getLogger().addHandler(_sink)
    _sink.start()
    # A short-lived process (the download child) exits without a lifespan: flush on the way out.
    atexit.register(stop)
 def stop() -> None:
    """Detach the sink and write what is still queued."""
    global _sink
    if _sink is None:
        return
    logging.getLogger().removeHandler(_sink)
    _sink.stop()
    _sink = None
 def gc(db: Session, retention_days: int) -> int:
    """Stage the deletion of rows older than `retention_days` (at least one day — stored logs always
    expire). The caller commits. Returns the number of rows removed."""
    cutoff = datetime.now(timezone.utc) - timedelta(days=max(1, retention_days))
    result = db.execute(delete(LogEvent).where(LogEvent.ts < cutoff))
    return result.rowcount or 0
@@ -175,7 +175,7 @@ MAIL_TEXT: dict[str, dict[str, str]] = {
        "en": (
            "Hi,\n\n"
            "Someone has opened up Siftlode for you — a quiet, self-hosted reader for your YouTube "
-            "subscriptions. Every upload from the channels you follow lands in one feed you can "
+            "subscriptions. Every upload from the channels you follow lands in one Feed you can "
            "actually filter and sort, with no algorithm deciding what you see, and no Shorts or "
            "livestreams unless you want them.\n\n"
            "{next_step}\n\n"
@@ -186,7 +186,7 @@ MAIL_TEXT: dict[str, dict[str, str]] = {
            "Szia,\n\n"
            "Valaki megnyitotta előtted a Siftlode-ot — ez egy csendes, saját üzemeltetésű olvasó "
            "a YouTube-feliratkozásaidhoz. A követett csatornák minden feltöltése egyetlen "
-            "hírfolyamba érkezik, amit tényleg tudsz szűrni és rendezni; nincs algoritmus, ami "
+            "Feedbe érkezik, amit tényleg tudsz szűrni és rendezni; nincs algoritmus, ami "
            "eldönti, mit látsz, és nincs Shorts vagy élő adás, hacsak nem kéred.\n\n"
            "{next_step}\n\n"
            "Nem sürget semmi — az ajtó nyitva marad.\n\n"
@@ -1,38 +1,42 @@
 import asyncio
-import logging
+import math
 import sys
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Request
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
-# When started via uvicorn --log-config the "siftlode" logger is already configured
+# Logging is configured HERE, before the route modules are imported, so every logger they create at
-# (see log_config.json). This block is a timestamped fallback for other entrypoints
+# import time is already covered. ONE format for the api, the worker, the download child and alembic
-# (tests, scripts) so our logs are never silently dropped.
+# alike (app/logs.py) — this replaces the old uvicorn --log-config + the hand-rolled fallback that
-_siftlode_logger = logging.getLogger("siftlode")
+# used to live here, and uvicorn's access log is replaced by the `http.request` middleware below.
-if not _siftlode_logger.handlers:
+from app import logs
-    _handler = logging.StreamHandler(sys.stdout)
+from app.logs import configure_logging, current_level, log_requests, set_level
    _handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-5s [%(name)s] %(message)s"))
    _siftlode_logger.addHandler(_handler)
    _siftlode_logger.setLevel(logging.INFO)
    _siftlode_logger.propagate = False
-log = logging.getLogger("siftlode.app")
+configure_logging("api")
 log = logs.get_logger(__name__)
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware
 from app import logsink
 from app import state
 from app import sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.plex import stream as plex_stream
 from app.plex import subtitles as plex_subtitles
 from app.routes import (
    admin,
    audit as audit_routes,
    auth as auth_routes,
    channels,
    config as config_routes,
    diagnostics as diagnostics_routes,
    discover as discover_routes,
    downloads,
    feed,
@@ -58,16 +62,28 @@ from app.scheduler import shutdown_scheduler, start_scheduler
@asynccontextmanager
 async def lifespan(app: FastAPI):
    log.info("Siftlode starting up")
    # The stored copy of the log (log_events). The entrypoint has already migrated the schema.
    logsink.start()
    # First-run: if the instance isn't configured yet, mint a fresh one-time setup token and print
    # the wizard URL so the operator can open it (the app runs in setup mode until they finish).
    with SessionLocal() as db:
        # The admin's runtime level (sysconfig `log_level`) wins over the LOG_LEVEL bootstrap
        # default, so a level chosen in the UI survives a restart without touching the environment.
        # Best-effort on purpose: a LOGGING knob must never be the thing that stops the app from
        # booting — an unreachable or not-yet-migrated database has to start into the env level.
        try:
            set_level(sysconfig.get_str(db, "log_level"))
        except Exception:  # noqa: BLE001 — any DB/config failure keeps the bootstrap level
            # With the traceback: this catch spans a connection, a query and a coercion at boot,
            # and `%s` of the exception does not say which of them raised.
            log.exception("could not read the stored log level; staying at %s", current_level())
        if not state.is_configured(db):
            token = state.rotate_setup_token(db)
            url = f"{settings.app_base}/setup?token={token}"
            log.warning(
                "FIRST-RUN SETUP REQUIRED — this instance isn't configured yet.\n"
                "    Open the install wizard (internal access only):\n    %s",
-                url,
+                url,  # log-pii-ok: this instance's OWN setup URL, and `?token=` is redacted
            )
    # No HLS session survives a restart (they live in this process), so anything still on disk is
    # a crashed run's segments — sweep them or they accumulate forever. FIRE AND FORGET, not
@@ -77,6 +93,7 @@ async def lifespan(app: FastAPI):
    # alone doesn't buy that; not waiting does. The sweep only touches directories no live session
    # owns, so racing it against early playback is safe.
    sweep = asyncio.create_task(_sweep_hls_orphans())
    reaper = asyncio.create_task(_reap_hls_sessions())
    start_scheduler()
    try:
        yield
@@ -86,10 +103,37 @@ async def lifespan(app: FastAPI):
        # pending ("Task was destroyed but it is pending!" — noise that reads like a bug during
        # triage). Cancelling does NOT interrupt the rmtree thread itself; this only makes our own
        # bookkeeping honest.
-        sweep.cancel()
+        for task in (sweep, reaper):
-        with suppress(asyncio.CancelledError):
+            task.cancel()
-            await sweep
+            with suppress(asyncio.CancelledError):
                await task
        shutdown_scheduler()
        # Kills a running subtitle extraction: its worker would otherwise hold interpreter exit for
        # the rest of the read (see plex_subtitles.shutdown).
        plex_subtitles.shutdown()
        logsink.stop()  # last: write what the shutdown itself just logged
 # How often idle HLS sessions are reaped (see plex/stream.py `reap_idle`).
 _HLS_REAP_EVERY_S = 60.0
 async def _reap_hls_sessions() -> None:
    """The periodic reaper plex/stream.py's docstring promises. `reap_idle` used to run only inside
    the NEXT session request, so after the last playback of the day an abandoned session — its
    ffmpeg still working through the film, its directory a whole segmented copy of it — lived until
    somebody pressed play again or the process restarted.
    A FINISHED session is reaped on the short rule here, not kept for the full idle window: an open
    player checkpoints every 10 s and that route touches the session, so a paused viewer is no longer
    invisible to this pass (see `reap_idle`). Keeping every finished session for ten minutes instead
    held one whole segmented copy of a film per item on the download volume (round 5)."""
    while True:
        await asyncio.sleep(_HLS_REAP_EVERY_S)
        try:
            await asyncio.to_thread(plex_stream.reap_idle)
        except Exception:
            log.exception("HLS session reap failed")
 async def _sweep_hls_orphans() -> None:
@@ -108,6 +152,34 @@ async def _sweep_hls_orphans() -> None:
 app = FastAPI(title=settings.app_name, lifespan=lifespan)
@app.exception_handler(RequestValidationError)
 async def _validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
    """FastAPI's own 422, in its own shape — except that it can be ENCODED. The JSON parser accepts
    `NaN`/`Infinity`, a float field refuses them, and the refusal echoes the value back: the default
    handler then failed to serialise its own error (JSON has no NaN) and the request became a 500
    with a traceback. A non-finite value is echoed as its name instead."""
    finite = {float: lambda x: x if math.isfinite(x) else str(x)}
    return JSONResponse(
        status_code=422, content={"detail": jsonable_encoder(exc.errors(), custom_encoder=finite)}
    )
@app.exception_handler(DataError)
 async def _nul_in_text(request: Request, exc: DataError) -> JSONResponse:
    """A NUL byte in a string the request sent is a 422, on every route at once. Postgres cannot hold
    NUL in text, so the driver refuses to even send the query — and a `%00` in a query parameter or
    an escaped NUL in a JSON body (a playlist's `contains=`, a reorder's key list, a collection
    search) was a 500 with a traceback wherever it reached a comparison. Guarding each site did not
    hold: round 3 guarded the by-rating_key lookup and missed the rest. Any other DataError is left
    alone — re-raised, it stays the 500 it always was."""
    if "NUL (0x00)" not in str(exc.orig):
        raise exc
    return JSONResponse(
        status_code=422, content={"detail": {"code": "invalid_input", "reason": "nul"}}
    )
 app.add_middleware(
    SessionMiddleware,
    secret_key=settings.secret_key,
@@ -183,6 +255,14 @@ async def security_headers(request, call_next):
    return response
 # The access log (app/logs.py): request id, route template, status, duration — one line, never a
 # query string. Registered LAST so it is the OUTERMOST http middleware and therefore times the whole
 # request, including what the three above do. Being outermost also puts it OUTSIDE SessionMiddleware,
 # which is why the account comes from `request.state.user_id` (set by the auth dependency, the one
 # place a session is actually resolved into an account) rather than from `request.session`.
 app.middleware("http")(log_requests)
 app.include_router(health.router)
 app.include_router(auth_routes.router)
 app.include_router(sync.router)
@@ -191,6 +271,7 @@ app.include_router(feed.router)
 app.include_router(discover_routes.router)
 app.include_router(search_routes.router)
 app.include_router(me.router)
 app.include_router(diagnostics_routes.router)
 app.include_router(notifications.router)
 app.include_router(messages.router)
 app.include_router(channels.router)
@@ -12,6 +12,7 @@ from sqlalchemy import (
    Index,
    Integer,
    JSON,
    SmallInteger,
    String,
    Text,
    UniqueConstraint,
@@ -24,6 +25,11 @@ from app.db import Base
 from app.utils import canonical_email
 # The resume-position columns (VideoState / PlexState.position_seconds) are int4. The checkpoint
 # routes bound their bodies by this, so an out-of-range position is a 422 rather than a 500.
 POSITION_MAX_S = 2**31 - 1
 class TimestampMixin:
    """Adds a server-defaulted `created_at`. Models that index created_at or order it
    differently (QuotaEvent, Notification, Message) keep their own column on purpose."""
@@ -97,6 +103,16 @@ class User(Base, TimestampMixin, CanonicalEmailMixin):
    # current_user rejects any cookie whose epoch is stale, so a stolen/copied cookie dies on those
    # events (client-side signed cookies otherwise stay valid until they expire).
    session_epoch: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    # When this account last signed in (Google or password), stamped by the one sign-in path,
    # routes/auth._establish_session. NULL = not since the column existed (0085; no backfill is
    # possible). The shared demo account is never stamped — its "last login" would mean nobody.
    last_login_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    # The diagnostics level this user consented to (E22 S5) and when it lapses back to the base
    # level. Both NULL = base. Written only by `PUT /api/me/diagnostics`, which computes the expiry
    # itself; read through `app.diagnostics.effective_level`, never directly (an expired level is
    # not cleared eagerly — it simply stops counting).
    diagnostics_level: Mapped[str | None] = mapped_column(String(8))
    diagnostics_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    display_name: Mapped[str | None] = mapped_column(String(255))
    avatar_url: Mapped[str | None] = mapped_column(String(1024))
    role: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
@@ -423,6 +439,7 @@ class VideoState(Base, UpdatedAtMixin):
    # status: a partially-watched video keeps status "new" but a non-zero position, so
    # it can render a progress bar and match the "in progress" feed filter. 0 = not
    # started / finished (trivially-early and near-finished positions are not stored).
    # int4: a checkpoint body must stay under POSITION_MAX_S, or the flush is a DataError (a 500).
    position_seconds: Mapped[int] = mapped_column(
        Integer, default=0, server_default="0", nullable=False
    )
@@ -533,6 +550,37 @@ class AuditLog(Base):
    )
 class LogEvent(Base):
    """One stored log event (E22 S3) — the `log_events` table the diagnostics console reads. Rows are
    written by app/logsink.py's background writer, never inside a request's transaction, already
    redacted (the same `logs.record_fields` the stdout line is built from).
    `user_id` has NO foreign key on purpose: the writer runs behind the event, so a line about an
    account can arrive after that account was purged, and a constraint would make it fail the whole
    batch it travels in. `auth.purge_user` deletes an account's rows explicitly instead, after
    `logs.forget_user` makes every later write in this process store such a line without the account;
    the retention job (`log_retention_days`) bounds whatever another process writes late."""
    __tablename__ = "log_events"
    __table_args__ = (Index("ix_log_events_user_ts", "user_id", "ts"),)
    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
    ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), index=True)
    level: Mapped[str] = mapped_column(String(10))
    sev: Mapped[int] = mapped_column(SmallInteger)
    source: Mapped[str] = mapped_column(String(16))
    logger: Mapped[str] = mapped_column(String(128))
    event: Mapped[str | None] = mapped_column(String(64))
    msg: Mapped[str] = mapped_column(Text)
    attrs: Mapped[dict | None] = mapped_column(JSONB)
    exc: Mapped[str | None] = mapped_column(Text)
    request_id: Mapped[str | None] = mapped_column(String(64), index=True)
    user_id: Mapped[int | None] = mapped_column(Integer)
    debug_session_id: Mapped[str | None] = mapped_column(String(64))
    job_id: Mapped[int | None] = mapped_column(Integer)
    version: Mapped[str | None] = mapped_column(String(64))
 class AppState(Base):
    """Single-row global app state (admin-controlled)."""
@@ -865,6 +913,8 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
    error_code: Mapped[str | None] = mapped_column(
        String(24)
    )  # category, see downloads.errors.classify
    # The host-specific failure-catalog entry on top of the category (`facebook.login_wall`), or NULL.
    error_detail: Mapped[str | None] = mapped_column(String(48))  # see downloads.errors.diagnose
    queue_pos: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
@@ -6,16 +6,15 @@ metadata, image proxying, and (P5) optional watch-state write-back. Requests JSO
 ``Accept: application/json`` header (Plex serves XML by default).
 """
 import logging
 from urllib.parse import quote
 import httpx
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 class PlexError(Exception):
@@ -106,7 +105,18 @@ class PlexClient:
        Best-effort (needs the library's related data) — returns [] if Plex has none."""
        try:
            mc = self._get(f"/library/metadata/{rating_key}/related")
-        except PlexError:
+        except PlexError as exc:
            # An empty list is also the answer for an item that genuinely has no related titles,
            # so the caller cannot tell the two apart — and it deliberately declines to CACHE an
            # empty one for exactly that reason. This line is what says which it was.
            log.debug(
                "the related items for a Plex item could not be read",
                extra=logs.event(
                    "plex.client.related_unavailable",
                    rating_key=rating_key,
                    reason=type(exc).__name__,
                ),
            )
            return []
        out: list[dict] = []
        for hub in mc.get("Hub", []) or []:
@@ -139,6 +149,8 @@ class PlexClient:
            raise PlexError(str(e)) from e
        try:
            return (r.json() or {}).get("MediaContainer", {}) or {} if r.content else {}
        # silent-ok: the HTTP call already succeeded — this is a write endpoint, and Plex answers
        # those with an empty or non-JSON body as a matter of course.
        except ValueError:
            return {}
@@ -197,7 +209,12 @@ class PlexClient:
        )
    def unscrobble(self, rating_key: str) -> None:
-        """Mark the item *unwatched* on the token's Plex account (clears viewCount)."""
+        """Mark the item *unwatched* on the token's Plex account.
        Clears the view count AND the resume point (`viewOffset`) — measured against the live server
        on 2026-09-09, from both a watched+offset state and an offset-only one. This one call is the
        whole un-mark; `/:/timeline?time=0` and `/:/progress?time=0` were both tried there and do
        NOT clear an offset, so do not reach for them."""
        self._write(
            "GET",
            f"/:/unscrobble?identifier={self._LIBRARY_IDENTIFIER}"
@@ -22,6 +22,8 @@ def rich_detail(meta: dict) -> dict:
        if str(r.get("image") or "").startswith("imdb://"):
            try:
                imdb_rating = round(float(r.get("value")), 1)
            # silent-ok: no IMDb score, which is the common and legitimate case — the UI has a
            # separate audience score to fall back on and shows nothing if neither exists.
            except (TypeError, ValueError):
                pass
            break
@@ -11,10 +11,13 @@ The cache directory (``cache.CACHE_DIR``) is shared with the subtitle cache (see
 from fastapi import Response
 from sqlalchemy.orm import Session
 from app import logs
 from app.models import PlexCollection, PlexItem, PlexSeason, PlexShow
 from app.plex.cache import CACHE_DIR
 from app.plex.lookups import by_rating_key
 log = logs.get_logger(__name__)
 _EXT_CT = [("jpg", "image/jpeg"), ("png", "image/png"), ("webp", "image/webp")]
 _CT_EXT = {ct: ext for ext, ct in _EXT_CT}
 # Target box per variant — Plex resizes to these server-side. Posters fill ≤176px cells (grid/info/
@@ -46,6 +49,8 @@ def read(key: str) -> tuple[bytes, str] | None:
        try:
            if p.exists() and p.stat().st_size > 0:
                return p.read_bytes(), ct
        # silent-ok: a miss. The caller fetches from Plex and writes the file again, and the write
        # path below is the one that reports a cache that cannot be used.
        except OSError:
            pass
    return None
@@ -58,8 +63,14 @@ def write(key: str, data: bytes, ct: str) -> None:
        tmp = CACHE_DIR / f"{key}.{ext}.tmp"
        tmp.write_bytes(data)
        tmp.replace(CACHE_DIR / f"{key}.{ext}")  # atomic publish
-    except OSError:
+    except OSError as exc:
-        pass  # cache is best-effort
+        # Best-effort, and silently so: with an unwritable cache every poster on every grid goes
        # to Plex live, for as long as nobody notices. Debug, because a grid is ~100 images and
        # the point is the condition, not the count.
        log.debug(
            "the Plex image cache could not be written",
            extra=logs.event("plex.imgcache.write_failed", reason=type(exc).__name__),
        )
 def response(data: bytes, ct: str) -> Response:
@@ -11,5 +11,11 @@ _M = TypeVar("_M")
 def by_rating_key(db: Session, model: type[_M], rating_key: str) -> _M | None:
    """The mirrored row for a Plex rating_key, or None. `model` is any of the rating_key-keyed Plex
    tables (PlexItem / PlexShow / PlexSeason / PlexCollection); the return type is that model, so call
-    sites keep their `Model | None` static type."""
+    sites keep their `Model | None` static type.
    A key with a NUL in it (`%00` in a path segment) names no row — a 404, like any unknown key.
    Postgres refuses NUL in text, so asking would be a DataError; the app-wide handler turns the
    places that DO ask (lists and filters compared to rating_key) into a 422 (see main.py)."""
    if "\x00" in str(rating_key):
        return None
    return db.execute(select(model).where(model.rating_key == str(rating_key))).scalars().first()
@@ -12,7 +12,9 @@ from pathlib import Path
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 log = logs.get_logger(__name__)
 def parse_map(raw: str) -> list[tuple[str, str]]:
@@ -47,6 +49,13 @@ def local_media_path(db: Session, plex_path: str | None) -> Path | None:
        return None
    try:
        p = Path(map_path(db, plex_path)).resolve()
-    except OSError:
+    except OSError as exc:
        # None is answered as a 404 "no local file", which is also the answer for a title the
        # server does not hold — so a dead mount or a wrong path map reads as missing media for
        # the whole library at once. The path itself stays out: it carries the title.
        log.warning(
            "a Plex media path could not be resolved locally",
            extra=logs.event("plex.paths.resolve_failed", reason=type(exc).__name__),
        )
        return None
    return p if p.is_file() else None
@@ -14,6 +14,22 @@ from app.models import PlexItem, PlexLibrary
 TS_CONFIG = "public.unaccent_simple"
 # The ONE Plex sort vocabulary, shared by every surface that offers the Sort control (the browse grid
 # and the collection info page) and mirrored by the frontend's `plexSort.ts`. It lives here rather than
 # inside a router because the two surfaces order DIFFERENT things — browse orders a union subquery in
 # SQL, a collection orders its already-loaded member list in Python — and a key that one of them cannot
 # honour would put an option in the UI that silently does nothing. Tests pin both implementations to
 # this tuple, so adding a key here fails the gate until every surface can order by it.
 PLEX_SORT_KEYS: tuple[str, ...] = (
    "added",
    "lastwatched",
    "release",
    "year",
    "rating",
    "duration",
    "title",
 )
 # --- Language-aware column pickers (E5 S6) ----------------------------------
 #
 # The HU-overlay twin (E5 S5) stores Hungarian metadata in `*_hu` columns on the SAME EN row. When
@@ -18,26 +18,26 @@ segments. The remux is CPU-light (video copy + a tiny audio transcode), so it ru
 CPU-only prod host; only P3's full transcode is CPU-heavy.
 """
 import logging
 import os
 import re
 import secrets
 import shutil
 import subprocess
 import threading
 import time
 from collections.abc import Sequence
 from pathlib import Path
 from sqlalchemy.orm import Session as DbSession
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.downloads.edit import encode_thread_cap
 from app.models import PlexItem
 from app.plex import paths
 from app.plex.sync import HW_DECODABLE_CODECS
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 _HLS_ROOT = (
    Path(settings.plex_hls_dir)
    if settings.plex_hls_dir
@@ -55,6 +55,10 @@ _SEG_SECONDS = 6
 # worse than the old zero-buffer behaviour).
 _WARMUP_SEGMENTS = 3
 _WARMUP_SEG_TIMEOUT_S = 8.0
 # The HLS variant ffmpeg gives the VIDEO rendition of a multi-audio session. `-var_stream_map` names
 # each audio rendition (`name:a0`, `a1`, …) but leaves the video one unnamed, so ffmpeg falls back to
 # its index for that one. See `segment_name` for why this is a constant and not a comment.
 _VIDEO_VARIANT = "0"
 _SESSION_IDLE_S = 600  # reap a session with no access for this long
 # A session directory is named `{rating_key}_{int(start_s)}_{tag}_{aoff:+.2f}` (see start_session);
 # before multi-audio it was just `{rating_key}_{int(start_s)}`. `sweep_orphans` deletes ONLY names
@@ -94,11 +98,19 @@ class HlsSession:
        directory: Path,
        proc: subprocess.Popen,
        start_s: float,
-        entry: str,
+        variants: "Sequence[str]",
        transcode: bool = False,
        hw: bool = False,
        tonemap: bool = False,
    ):
        # Unguessable per-session id, carried in the URLs the client is handed. Sessions are keyed
        # by rating_key alone, so a seek-restart or a SECOND viewer of the same item replaces the
        # registered one — and the old viewer's next request for `seg_12.ts`, resolved by rating_key,
        # was answered 200 with the NEW session's twelfth segment, produced from a different offset
        # under `-copyts`. Wrong bytes, not an error, so the client's reclaim never fired on it
        # (deep-review round 5). A request naming a session that is no longer registered is a 404,
        # which the player recovers from by restarting at the playhead.
        self.id = secrets.token_urlsafe(9)
        self.key = key
        self.dir = directory
        self.proc = proc
@@ -113,8 +125,16 @@ class HlsSession:
        # subtitle cue-shift both key off the true content position — no drift. Provisional = X until
        # the first segment is probed.
        self.media_start_s = start_s
-        self.entry = entry  # the playlist filename hls.js should load (master.m3u8 with subs, else index.m3u8)
+        # The rendition names this session's ffmpeg was told to write — () for a single-audio
        # session. Held on the session because it is what `artifact_may_arrive` needs to tell a name
        # this session CAN produce from one belonging to the other argv branch (see it).
        self.variants = tuple(variants)
        # The playlist filename hls.js should load: the master of a multi-audio session, else the
        # single index. Derived, not passed, so it cannot disagree with the argv.
        self.entry = _MASTER_PL if self.variants else _INDEX_PL
        self.last_access = time.time()
        # `artifact_may_arrive` reports a refusing session directory once, not per segment.
        self.probe_failure_reported = False
 def _seek_opts(start_s: float) -> list[str]:
@@ -212,7 +232,15 @@ def _probe_video_kind(src: Path) -> str:
            text=True,
            timeout=10,
        )
-    except (subprocess.SubprocessError, OSError):
+    except (subprocess.SubprocessError, OSError) as exc:
        # The safe kind is a real answer, but it is the answer for an 8-bit SDR source — a blind
        # ffprobe sends every HDR file down it, so playback quietly degrades to a software
        # transcode with nothing anywhere saying why. The path stays out of the line: it is the
        # title of whatever is playing.
        log.info(
            "video-kind probe failed; assuming the HW-safe pipeline",
            extra=logs.event("plex.stream.probe_kind_failed", reason=type(exc).__name__),
        )
        return _VK_HWSAFE
    pix_fmt = bits = transfer = ""
    for line in out.stdout.splitlines():
@@ -241,7 +269,14 @@ def _opencl_present() -> bool:
    software libx264. Its own function so it's monkeypatchable in tests, mirroring _render_node_present."""
    try:
        return any(_OPENCL_ICD_DIR.glob("*.icd"))
-    except OSError:
+    except OSError as exc:
        # A MISSING directory does not come through here — `glob` simply yields nothing for one.
        # This is a directory we cannot read, and the answer it forces (no OpenCL) costs every HDR
        # source the hardware tonemap path.
        log.info(
            "the OpenCL ICD directory could not be read; treating OpenCL as absent",
            extra=logs.event("plex.stream.opencl_probe_failed", reason=type(exc).__name__),
        )
        return False
@@ -271,6 +306,30 @@ def _hwaccel_in_opts(hw: bool, tonemap: bool = False) -> list[str]:
    return ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", _VAAPI_DEVICE]
 # Audio is ALWAYS re-encoded on the HLS path: the source is typically AC3/DTS 5.1, which no browser
 # plays, so it is downmixed to stereo AAC. `-ac 2` uses ffmpeg's standard downmix matrix; nothing is
 # normalised, which is why a film mastered for a cinema arrives with whispered dialogue and deafening
 # action (bug hunt 2026-09, item 14).
 _AUDIO_ENC = ["-c:a", "aac", "-ac", "2", "-b:a", "192k"]
 # Optional loudness normalisation (admin knob `plex_audio_loudnorm`, default OFF). EBU R128 single-pass
 # `loudnorm` — two-pass is impossible here, since a seek-restart session must start emitting segments
 # immediately and cannot analyse the file first.
 #
 # The downmix is FORCED FIRST (`aformat=channel_layouts=stereo`) rather than left to `-ac 2`: measuring
 # 5.1 and then folding it down would normalise something other than what the viewer hears. `loudnorm`
 # runs its own resampler at 192 kHz internally, so the chain resamples back to 48 kHz for the AAC
 # encoder. Measured on a real 5.1 AC3 film (Westworld S1E6, 60 s from 15:00): I -27.6 → -16.6 LUFS,
 # LRA 13.3 → 9.8 LU — the quiet/loud gap narrows, and everything gets ~11 dB louder, so expect to turn
 # the volume down after switching this on. The filter's 3 s lookahead does NOT desync A/V: measured
 # under this pipeline's own `-copyts`, the audio start PTS is identical with and without it.
 _LOUDNORM_AF = "aformat=channel_layouts=stereo,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000"
 def _aenc_opts(loudnorm: bool) -> list[str]:
    """Audio encoder args for one output, with the normalisation filter when the admin enabled it."""
    return [*_AUDIO_ENC, *(["-af", _LOUDNORM_AF] if loudnorm else [])]
 def _venc_opts(
    transcode: bool,
    hw: bool,
@@ -360,7 +419,7 @@ def _select_encode(db: DbSession, item: PlexItem, transcode: bool, src: Path) ->
    source that has an OpenCL runtime, while a 10-bit SDR source drops to software."""
    if not transcode:
        return (False, False)
-    mode = (sysconfig.get_str(db, "plex_transcode_hw") or "auto").lower()
+    mode = sysconfig.get_str(db, "plex_transcode_hw")
    if mode == "off" or not _render_node_present():
        return (False, False)
    if mode == "on":
@@ -403,6 +462,8 @@ def _sw_child_preexec() -> None:
    playback."""
    try:
        os.nice(_SW_TRANSCODE_NICE)
    # silent-ok: this runs in the forked child, between fork and exec. Logging there can deadlock
    # on a lock some other thread held at fork time, and the child is about to become ffmpeg.
    except OSError:
        pass
@@ -429,7 +490,14 @@ def _probe_audio_langs(src: Path) -> list[str]:
            timeout=10,
        )
        return [ln.strip() for ln in out.stdout.splitlines()]
-    except (subprocess.SubprocessError, OSError):
+    except (subprocess.SubprocessError, OSError) as exc:
        # An empty list IS the single-audio path, so a failed probe silently collapses a file with
        # several audio tracks down to one — and the viewer gets a player with no language picker
        # rather than an error.
        log.warning(
            "audio-track probe failed; falling back to a single-audio session",
            extra=logs.event("plex.stream.probe_audio_failed", reason=type(exc).__name__),
        )
        return []
@@ -446,6 +514,7 @@ def _ffmpeg_cmd(
    preset: str = "veryfast",
    crf: int = 20,
    max_height: int = 0,
    loudnorm: bool = False,
 ) -> list[str]:
    # For a transcode session the video is re-encoded (VAAPI or libx264) instead of stream-copied; the
    # hwaccel decode options go before -i, the encoder args replace `-c:v copy` below. Everything else is
@@ -469,11 +538,15 @@ def _ffmpeg_cmd(
    if audio_langs:
        # MULTI-RENDITION: map EVERY audio track as an alternate HLS rendition in one group, so hls.js
        # switches audio CLIENT-SIDE on the same timeline (no session restart, no drift) — the premium
-        # audio-switch path. Produces master.m3u8 + stream_%v.m3u8 (v0=video, v1..=audio) + seg_%v_%d.ts.
+        # audio-switch path. Produces master.m3u8 + one stream_%v.m3u8 and seg_%v_*.ts per variant,
        # where %v is the video rendition's index ("0") and each audio rendition's `name:` (a0, a1,
        # …). Those names are spelled by `segment_name` / `variant_playlist_name` below, which the
        # guard and the warm-up read back — see them for the measurement behind the ordering.
        args += ["-map", "0:v:0"]
        for i in range(len(audio_langs)):
            args += ["-map", f"{ai}:a:{i}?"]
-        args += ["-sn", *venc, "-c:a", "aac", "-ac", "2", "-b:a", "192k"]
+        # One `-af` covers EVERY audio output of this file, so each rendition is normalised.
        args += ["-sn", *venc, *_aenc_opts(loudnorm)]
        var = ["v:0,agroup:aud"]
        for i, lang in enumerate(audio_langs):
            entry = f"a:{i},agroup:aud,name:a{i}"
@@ -482,23 +555,25 @@ def _ffmpeg_cmd(
            if i == 0:
                entry += ",default:yes"
            var.append(entry)
        # The name patterns come from the vocabulary functions, with ffmpeg's own placeholders passed
        # through them — so the producer and the parser cannot spell the layout differently (round 7).
        args += _HLS_TAIL + [
            "-master_pl_name",
-            "master.m3u8",
+            _MASTER_PL,
            "-var_stream_map",
            " ".join(var),
            "-hls_segment_filename",
-            str(out_dir / "seg_%v_%d.ts"),
+            str(out_dir / segment_name("%d", "%v")),
-            str(out_dir / "stream_%v.m3u8"),
+            str(out_dir / variant_playlist_name("%v")),
        ]
    else:
        ao = audio_ord if audio_ord is not None else 0
        args += ["-map", "0:v:0", "-map", f"{ai}:a:{ao}?", "-sn"]
-        args += [*venc, "-c:a", "aac", "-ac", "2", "-b:a", "192k"]
+        args += [*venc, *_aenc_opts(loudnorm)]
        args += _HLS_TAIL + [
            "-hls_segment_filename",
-            str(out_dir / "seg_%d.ts"),
+            str(out_dir / segment_name("%d")),
-            str(out_dir / "index.m3u8"),
+            str(out_dir / _INDEX_PL),
        ]
    return args
@@ -531,8 +606,14 @@ def _probe_first_pts(seg: Path) -> float | None:
            tok = line.strip().strip(",")
            if tok:
                return float(tok)
-    except (subprocess.SubprocessError, ValueError, OSError):
+    except (subprocess.SubprocessError, ValueError, OSError) as exc:
-        pass
+        # None means "keep the offset the client asked for", and the whole point of this probe is
        # that the two differ: without it the subtitle track is shifted by whatever the container
        # started its timestamps at. Seconds of drift, and nothing on screen calls it a failure.
        log.warning(
            "first-PTS probe failed; the requested offset is used as-is",
            extra=logs.event("plex.stream.first_pts_probe_failed", reason=type(exc).__name__),
        )
    return None
@@ -541,10 +622,18 @@ def _kill(s: HlsSession) -> None:
        s.proc.terminate()
        try:
            s.proc.wait(timeout=3)
        # silent-ok: the escalation IS the handling. A transcode that ignores TERM for three
        # seconds gets KILL, which is exactly what this branch does.
        except subprocess.TimeoutExpired:
            s.proc.kill()
-    except Exception:
+    except Exception as exc:  # noqa: BLE001 — teardown finishes whatever the process does
-        pass
+        # Not nothing: what survives this is an ffmpeg nobody owns any more, holding a VAAPI
        # handle and a core, and the transcode cap that is supposed to bound them counts rows in
        # `_sessions` rather than processes. One line is the only way that ever surfaces.
        log.info(
            "could not stop the transcode process",
            extra=logs.event("plex.stream.kill_failed", key=s.key, reason=type(exc).__name__),
        )
    shutil.rmtree(s.dir, ignore_errors=True)
@@ -557,6 +646,13 @@ def _enforce_cap(cap: int) -> None:
    if len(tx) <= cap:
        return
    for key, s in sorted(tx, key=lambda kv: kv[1].last_access)[: len(tx) - cap]:
        # Somebody's playback stops here. The route turns the missing session into a retryable
        # 404 and the player restarts at the playhead, so from the server nothing failed — and
        # "my film keeps rebuffering" has no other explanation anywhere.
        log.info(
            "a transcode session was dropped to stay under the cap",
            extra=logs.event("plex.stream.session_culled", key=key, cap=cap, sessions=len(tx)),
        )
        _kill(s)
        _sessions.pop(key, None)
@@ -579,16 +675,26 @@ def start_session(
    src = paths.local_media_path(db, item.file_path)
    if src is None:
        return None
    # Read once, here: the knob has to be identical for the directory name and the ffmpeg argv, and a
    # session respawn (the HW->SW fallback) must not pick up a mid-playback config change.
    loudnorm = sysconfig.get_bool(db, "plex_audio_loudnorm")
    key = item.rating_key
    start_s = max(0.0, float(start_s))
    audio_langs = _probe_audio_langs(src) if multi else []
    is_multi = len(audio_langs) > 1  # only worth a master playlist when there really are ≥2 tracks
-    tag = "multi" if is_multi else str(audio_ord)
+    # The rendition names the argv below will produce — one source for the argv, the warm-up's
    # segment names, the entry playlist and the artifact guard.
    variants = session_variants(audio_langs if is_multi else None)
    # Loudness normalisation changes the AUDIO THE SEGMENTS CONTAIN, so it belongs in the directory
    # name beside the other parameters that do (offset, audio track, A/V offset): a session left over
    # from before the admin flipped the knob must not be mistaken for one that honours it. Appended to
    # the tag with a DASH — `_SESSION_DIR_RE` treats the tag as one underscore-free field, and that
    # regex is the only thing keeping the orphan sweep off a shared scratch path (see its comment).
    tag = ("multi" if is_multi else str(audio_ord)) + ("-ln" if loudnorm else "")
    directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
    def _seg(i: int) -> Path:
-        # multi-audio: the video rendition is variant v0 → seg_{i}_0.ts; single-audio → seg_{i}.ts
+        return directory / segment_name(i, _VIDEO_VARIANT if variants else None)
        return directory / (f"seg_{i}_0.ts" if is_multi else f"seg_{i}.ts")
    def _spawn(
        hw: bool, tonemap: bool = False, *, replace_only: "HlsSession | None" = None
@@ -603,7 +709,7 @@ def start_session(
        # remux ignore preset/crf/max_height, and remux must not touch the DB for them).
        preset, crf, max_height = "veryfast", 20, 0
        if transcode and not hw:
-            preset = sysconfig.get_str(db, "plex_transcode_preset") or "veryfast"
+            preset = sysconfig.get_str(db, "plex_transcode_preset")
            crf = sysconfig.get_int(db, "plex_transcode_crf")
            max_height = sysconfig.get_int(db, "plex_transcode_max_height")
        # Nice the SOFTWARE transcode child (not the HW path, and not remux) so a CPU-bound re-encode
@@ -632,6 +738,7 @@ def start_session(
                    preset=preset,
                    crf=crf,
                    max_height=max_height,
                    loudnorm=loudnorm,
                ),
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
@@ -642,12 +749,27 @@ def start_session(
                directory,
                proc,
                start_s,
-                "master.m3u8" if is_multi else "index.m3u8",
+                variants,
                transcode=transcode,
                hw=hw,
                tonemap=tonemap,
            )
            _sessions[key] = s
            # The one line that says which pipeline a session actually got. Everything downstream
            # — the cap, the HW→SW fallback, the subtitle offset — is about this choice, and until
            # now it was only inferable from the ffmpeg command nobody keeps.
            log.info(
                "an HLS session started",
                extra=logs.event(
                    "plex.stream.session_started",
                    key=key,
                    transcode=transcode,
                    hw=hw,
                    tonemap=tonemap,
                    variants=len(variants or ()),
                    start_s=round(start_s, 1),
                ),
            )
            # Admin-configurable concurrency cap (Configuration → Plex → Max concurrent transcodes);
            # at least 1 so playback can't be capped to zero.
            _enforce_cap(max(1, sysconfig.get_int(db, "plex_max_transcodes")))
@@ -666,7 +788,8 @@ def start_session(
        # ONE lock in _spawn, so we can never tear down the newer session. s.hw is now False, so the route
        # honestly reports "CPU" and the player's Preparing-stream state stays correct.
        log.warning(
-            "plex transcode: HW session produced no segments — falling back to software key=%s", key
+            "the hardware transcode produced no segments; falling back to software",
            extra=logs.event("plex.stream.hw_fallback", key=key),
        )
        respawned = _spawn(False, False, replace_only=s)
        if respawned is None:
@@ -714,6 +837,117 @@ def current_session(key: str) -> HlsSession | None:
        return s
 # The names ffmpeg writes into a session directory, in ONE place — and "one place" means the argv
 # BUILDS its patterns from these same functions (`segment_name("%d", "%v")`), not that a comment
 # says so. Getting this wrong is invisible in both directions: a name we failed to anticipate used
 # to fall back to "wait and see" (round 6's HIGH), and now that the rule is positive it falls back
 # to a 404 instead — so the producer and the parser have to be literally the same spelling.
 #
 # MEASURED (ffmpeg 7.1.5 in the API container — the binary that actually writes these files — and
 # re-checked on 8.1.1): `-hls_segment_filename seg_%v_%d.ts` substitutes `%v` with the VARIANT and
 # `%d` with the SEQUENCE — variant FIRST. A dual-audio session writes seg_0_0.ts… (video, the
 # unnamed variant) plus seg_a0_0.ts… / seg_a1_0.ts… (the `name:aN` audio renditions), and the
 # playlists beside them are master.m3u8 + stream_0/a0/a1.m3u8. Single-audio uses `seg_%d.ts` +
 # index.m3u8, with no variant field at all.
 #
 # The two argv branches are DISJOINT vocabularies, which is why the guard below is keyed to the
 # SESSION and not to HLS in general: a single-audio session can never write `master.m3u8`,
 # `stream_*.m3u8` or any `seg_<variant>_<n>.ts`, and a multi-audio one can never write `index.m3u8`
 # or `seg_<n>.ts`. Accepting the union meant a hopeless name of the other shape was waited out for
 # the full playlist/segment timeout — the threadpool parking this guard exists to end (round 7).
 _MASTER_PL = "master.m3u8"
 _INDEX_PL = "index.m3u8"
 _SEG_NAME_RE = re.compile(r"^seg_(?:([0-9a-z]{1,4})_)?(\d{1,9})\.ts$")
 def session_variants(audio_langs: "Sequence[str | None] | None") -> tuple[str, ...]:
    """The `-var_stream_map` rendition names a session will write, or () for a single-audio one.
    The video rendition is left unnamed in the map, so ffmpeg falls back to its index
    (`_VIDEO_VARIANT`); each audio rendition is named `aN` in track order."""
    if not audio_langs:
        return ()
    return (_VIDEO_VARIANT, *(f"a{i}" for i in range(len(audio_langs))))
 def segment_name(seq: "int | str", variant: "str | None" = None) -> str:
    """The file ffmpeg writes for the `seq`-th segment of `variant`.
    `variant=None` is a single-audio session, whose argv carries no `%v` field at all. `seq` and
    `variant` are typed loosely because `_ffmpeg_cmd` builds its own `-hls_segment_filename` pattern
    through this function, passing ffmpeg's `"%d"` / `"%v"` placeholders — that is what keeps the
    producer and the parser from drifting, rather than a comment asking the next editor not to."""
    return f"seg_{variant}_{seq}.ts" if variant else f"seg_{seq}.ts"
 def variant_playlist_name(variant: str) -> str:
    """The sub-playlist ffmpeg writes for one rendition of a multi-audio session."""
    return f"stream_{variant}.m3u8"
 def playlist_names(variants: "Sequence[str]") -> frozenset[str]:
    """Every playlist name this session's argv can write — the master plus one per rendition, or
    just `index.m3u8` for a single-audio session."""
    if not variants:
        return frozenset({_INDEX_PL})
    return frozenset({_MASTER_PL, *(variant_playlist_name(v) for v in variants)})
 def artifact_may_arrive(s: "HlsSession", filename: str) -> bool:
    """Whether waiting for `filename` can possibly end in a file OF THIS SESSION.
    Positive rule, not a blocklist: a session produces segments and playlists and NOTHING else, so
    any other name is refused at once. ffmpeg also produces segments strictly in order, so a segment
    whose PREDECESSOR does not exist yet is not the next one — it is beyond the generated region,
    and no amount of waiting will conjure it. Playlists are the one thing that must still be waited
    for: they are rewritten continuously and have no ordering to read.
    Keyed to the SESSION's own vocabulary, not to HLS's: the two argv branches are disjoint, so a
    name belonging to the other shape is as hopeless here as a random string. Reading those as "an
    HLS name, so wait and see" left the whole class reachable — measured through the real route
    against a live single-audio session, `master.m3u8` and `stream_q7z.m3u8` were 404s after 30.0 s
    and `seg_a0_0.ts` / `seg_zzzz_0.ts` after 20.1 s each (deep-review round 7).
    Saying no at once matters because the route that waits is a SYNC one: it holds a thread off the
    ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An ordinary seek past
    the produced region was enough to park one for 20 s, and forty concurrent requests for a name
    that will never exist parked the whole API (deep-review round 5). Round 5's guard read only
    single-audio segment names, so both halves of that were still fully reachable: every multi-audio
    name fell through, and so did any `.m3u8`/`.vtt` name at all."""
    if filename in playlist_names(s.variants):
        return True
    m = _SEG_NAME_RE.match(filename)
    if m is None:
        return False
    variant, seq = m.group(1), int(m.group(2))
    # The variant field must be one THIS session writes: present and known for a multi-audio
    # session, absent for a single-audio one.
    if variant not in (s.variants or (None,)):
        return False
    if seq == 0:
        return True
    try:
        return (s.dir / segment_name(seq - 1, variant)).exists()
    except OSError as exc:
        # `exists()` answers False for a missing file without raising, so this is the session
        # directory itself refusing — a full or unmounted disk. Every segment then 404s, which the
        # player shows as a stall. Once per session: this runs for every segment request and
        # every hls.js retry of one, and the sink's limiter still stores 30 a minute of a
        # template — stdout would get them all.
        if not s.probe_failure_reported:
            s.probe_failure_reported = True
            log.warning(
                "a session segment could not be checked",
                extra=logs.event(
                    "plex.stream.segment_probe_failed",
                    key=s.key,
                    seq=seq,
                    reason=type(exc).__name__,
                ),
            )
        return False
 def wait_for(path: Path, timeout: float = 20.0, proc: subprocess.Popen | None = None) -> bool:
    """Wait until a session file (playlist / segment) exists and is non-empty. Segments are
    produced ~faster than realtime, so a segment just ahead of playback appears quickly; a segment
@@ -727,12 +961,16 @@ def wait_for(path: Path, timeout: float = 20.0, proc: subprocess.Popen | None =
        try:
            if path.exists() and path.stat().st_size > 0:
                return True
        # silent-ok: this is a 150 ms poll — a line here is a line every 150 ms for the whole
        # timeout. The final check below decides, and the 404 the caller then returns is honest.
        except OSError:
            pass
        if proc is not None and proc.poll() is not None:
            # the producer exited — no more segments are coming; one last check then give up.
            try:
                return path.exists() and path.stat().st_size > 0
            # silent-ok: one last look after the producer exited. False here becomes a 404 the
            # player recovers from, which is the honest answer either way.
            except OSError:
                return False
        time.sleep(0.15)
@@ -765,7 +1003,16 @@ def sweep_orphans(older_than: float | None = None) -> int:
    dropped = 0
    try:
        entries = list(_HLS_ROOT.iterdir())
-    except OSError:  # the root doesn't exist yet — nothing to sweep
+    # silent-ok: nothing has been transcoded yet, so there is nothing to sweep.
    except FileNotFoundError:
        return 0
    except OSError as exc:
        # Any OTHER reason the root will not list is not "nothing to sweep": the sweep reports 0
        # like a clean run while every crashed session's segments stay on disk forever.
        log.warning(
            "the HLS root could not be listed; no orphans were swept",
            extra=logs.event("plex.stream.sweep_root_unreadable", reason=type(exc).__name__),
        )
        return 0
    for p in entries:
        if not _SESSION_DIR_RE.match(p.name):
@@ -775,7 +1022,9 @@ def sweep_orphans(older_than: float | None = None) -> int:
        try:
            if p.stat().st_mtime >= cutoff:
                continue  # this run made (or reused) it — never ours to delete
-        except OSError:  # vanished under us (a concurrent restart of that session)
+        # silent-ok: vanished under us — a concurrent restart of that session removed it, which
        # is the outcome this sweep wanted anyway.
        except OSError:
            continue
        with _lock:
            if any(s.dir == p for s in _sessions.values()):
@@ -785,14 +1034,47 @@ def sweep_orphans(older_than: float | None = None) -> int:
    return dropped
-def reap_idle() -> int:
+# How long a session whose ffmpeg has FINISHED may go unfetched before a new session request reaps
 # it (see reap_idle).
 _FINISHED_IDLE_S = 30
 def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
    """Kill sessions nobody has said they still want for `_SESSION_IDLE_S` — or, once their ffmpeg
    has finished, for `finished_idle_s`.
    A finished session is also what a PAUSED viewer has: a remux runs far faster than realtime, so
    ffmpeg is done a minute or two in and writes ENDLIST; hls.js then stops asking for the playlist,
    and with its forward buffer full a paused player fetches nothing at all. With the 30 s rule that
    killed a one-minute pause, and playback died ~30 s after resuming (deep-review round 4).
    What makes the short rule safe again is that fetching is no longer the only signal: a player
    parked MID-ITEM checkpoints its position every 10 s, and that route calls `touch_session`, so a
    viewer who is merely paused says so far more often than this rule asks (round 5). The heartbeat
    stops once the item is finished or before a position is known (`usePlexProgress.flush`) — both
    states where reaping is correct, and where the player's 404 → reclaim recovers a viewer who
    scrubs back in anyway. Do not restate this as "every 10 s whether or not it is playing": round 6
    found that claim in two comments and not in the code. Round 4's blanket
    `reap_abandoned` bought the same safety by keeping every finished session for ten minutes — each
    one a whole segmented copy of the film on a volume shared with the download center."""
    now = time.time()
    dropped = 0
    with _lock:
        for key, s in list(_sessions.items()):
            done = s.proc.poll() is not None
-            if now - s.last_access > _SESSION_IDLE_S or (done and now - s.last_access > 30):
+            idle = now - s.last_access
            if idle > _SESSION_IDLE_S or (done and idle > finished_idle_s):
                _kill(s)
                _sessions.pop(key, None)
                dropped += 1
    return dropped
 def touch_session(key: str) -> None:
    """Say a viewer is still there for `key`, without fetching anything. `last_access` used to move
    only on an HLS file fetch, which a paused player does not do — so the only way to keep a paused
    viewer's session alive was to keep EVERY abandoned one just as long."""
    with _lock:
        s = _sessions.get(key)
        if s is not None:
            s.last_access = time.time()
@@ -1,16 +1,58 @@
-"""WebVTT conversion, HLS-clock time-shift, and on-disk cache for Plex subtitle streams.
+"""WebVTT conversion, HLS-clock time-shift, and the on-disk cache + background extractor for Plex
 subtitle streams.
 Text subtitles (embedded or external) are turned into WebVTT so the browser <track> can render them;
 bitmap subtitles (Blu-ray/DVD) can't be (would need burn-in). Converted VTTs are cached on the shared
 Plex on-disk cache root (``cache.CACHE_DIR``).
 WHY THERE IS A BACKGROUND EXTRACTOR HERE — measured on prod, 2026-09-10, against a 17.06 GB 1080p
 MKV with two embedded SubRip tracks on the 81 TB array:
 ===========================================================  ========
  full pass, ONE track (what this module used to do)           154 s
  full pass, BOTH text tracks in a SINGLE ffmpeg run           111 s
  `-c:s copy` instead of converting to WebVTT                  143 s
  from 1:00:00 to the end of the file                           66 s
  a 630 s WINDOW at 1:00:00, both tracks                          8 s
 ===========================================================  ========
 The conversion is not the cost (dropping it saved 7%): ffmpeg has to stream every byte of the
 container between its seek point and its stop point, and the array delivers ~140 MB/s — so the time
 is (bytes read) / 140 MB/s, and the ONLY lever is reading less. Hence:
 * extract a WINDOW around the playhead first — the viewer sees subtitles in seconds — then complete
  the whole track in the background so every later seek is instant and the next session is free;
 * extract EVERY embedded text track in ONE pass, because the read is shared: picking Hungarian used
  to cost a full read and then switching to English cost another one (the "hektikus" report);
 * never do any of it inside a request (it froze the <track> with no feedback AND held an API worker
  thread for the whole read).
 `-copyts` CANNOT be used for a window: it makes ffmpeg ignore `-t`/`-to` (measured — a [0, 600 s]
 window still took the full 145 s and emitted the whole track), so windows are extracted on a
 zero-based clock and shifted back to absolute time here with `shift_vtt`.
 """
 import json
 import re
 import subprocess
 import tempfile
 import threading
 import time
 import logging
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from sqlalchemy.orm import Session
 from app import logs
 from app.db import SessionLocal
 from app.models import PlexItem
 from app.plex import paths as plex_paths
 from app.plex.cache import CACHE_DIR
-from app.plex.client import PlexError
+from app.plex.client import PlexClient, PlexError
 from app.plex.lookups import by_rating_key
 log = logs.get_logger(__name__)
 # Image-based subtitle codecs (Blu-ray/DVD) — can't be turned into text WebVTT (would need burn-in).
 BITMAP_SUBS = {
    "pgs",
@@ -31,6 +73,9 @@ def srt_to_vtt(text: str) -> str:
 def _vtt_ts_to_s(ts: str) -> float:
    # Also reads ffmpeg's spelling of a NEGATIVE time (a windowed pass, see `_ffmpeg_extract`): its
    # webvtt muxer splits the milliseconds with C's truncating division, so every field carries the
    # sign — -5.005 s is `00:-5.-05`, -65.3 s is `-1:-5.-300` — and summing the signed fields is exact.
    parts = ts.split(":")
    h = "0" if len(parts) == 2 else parts[0]
    m, rest = parts[-2], parts[-1]
@@ -39,16 +84,12 @@ def _vtt_ts_to_s(ts: str) -> float:
 def _vtt_s_to_ts(x: float) -> str:
-    x = max(0.0, x)
+    # Rounded to whole milliseconds FIRST, then split: rounding the fraction last carried a rounded-up
-    h = int(x // 3600)
+    # millisecond into the seconds and no further, so 59.9996 came out as `00:00:60.000` — a timestamp
-    x -= h * 3600
+    # the WebVTT parser rejects, silently dropping that cue.
-    m = int(x // 60)
+    h, rest = divmod(int(round(max(0.0, x) * 1000)), 3_600_000)
-    x -= m * 60
+    m, rest = divmod(rest, 60_000)
-    s = int(x)
+    s, ms = divmod(rest, 1000)
    ms = int(round((x - s) * 1000))
    if ms >= 1000:
        s += 1
        ms -= 1000
    return f"{h:02d}:{m:02d}:{s:02d}.{ms:03d}"
@@ -63,6 +104,7 @@ def shift_vtt(vtt: str, offset: float) -> str:
    straddling 0 is clamped to start at 0."""
    if not offset:
        return vtt
    unshifted = 0
    out_blocks: list[str] = []
    for block in re.split(r"\n[ \t]*\n", vtt):
        if "-->" not in block:
@@ -80,7 +122,12 @@ def shift_vtt(vtt: str, offset: float) -> str:
                st = _vtt_ts_to_s(left.strip()) - offset
                en = _vtt_ts_to_s(rparts[0]) - offset
            except (ValueError, IndexError):
-                break  # unparseable timing → leave the block as-is
+                # silent-ok: left as-is means left UNSHIFTED — the viewer sees that one cue at
                # the wrong moment. Counted rather than logged here: this is per cue, and the file
                # being parsed is one ffmpeg wrote for us a moment ago, so a broken timestamp is
                # a fact about the extraction, reported once below.
                unshifted += 1
                break
            if en <= 0:
                keep = False  # whole cue is before the session start → drop the block
            else:
@@ -90,6 +137,11 @@ def shift_vtt(vtt: str, offset: float) -> str:
            break
        if keep:
            out_blocks.append("\n".join(lines))
    if unshifted:
        log.info(
            "some cues could not be shifted and stay at their original time",
            extra=logs.event("plex.subtitles.cues_unshifted", cues=unshifted, offset_s=offset),
        )
    return "\n\n".join(out_blocks)
@@ -109,7 +161,7 @@ def ffmpeg_to_vtt(src: str, sub_ord: int | None) -> str:
        "webvtt",
        "pipe:1",
    ]
-    r = subprocess.run(cmd, capture_output=True)
+    r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S)
    if r.returncode != 0 or not r.stdout:
        raise PlexError(
            (r.stderr or b"").decode("utf-8", "replace")[:200] or "ffmpeg subtitle convert failed"
@@ -121,15 +173,779 @@ def cache_read(key: str) -> str | None:
    try:
        p = CACHE_DIR / f"{key}.vtt"
        return p.read_text(encoding="utf-8") if p.exists() else None
-    except OSError:
+    except OSError as exc:
        # None is the same answer as "never cached", so a cache we cannot read looks exactly like
        # a cold one — and every request re-extracts instead of saying the disk is the problem.
        log.warning(
            "the cached subtitle could not be read",
            extra=logs.event(
                "plex.subtitles.cache_read_failed", key=key, reason=type(exc).__name__
            ),
        )
        return None
-def cache_write(key: str, vtt: str) -> None:
+def cache_write(key: str, vtt: str) -> bool:
    """Atomically replace the cached VTT; False when it could not be written (`publish` must then
    not claim the region it was carrying)."""
    try:
        CACHE_DIR.mkdir(parents=True, exist_ok=True)
        tmp = CACHE_DIR / f"{key}.vtt.tmp"
        tmp.write_text(vtt, encoding="utf-8")
        tmp.replace(CACHE_DIR / f"{key}.vtt")  # atomic publish
-    except OSError:
+        return True
-        pass
+    except OSError as exc:
        # `publish` turns False into "the region was not claimed" and moves on, so the track just
        # never appears. Which errno it was — full disk, read-only mount, permissions — is the
        # whole diagnosis, and it exists only here.
        log.warning(
            "the subtitle cache could not be written",
            extra=logs.event(
                "plex.subtitles.cache_write_failed", key=key, reason=type(exc).__name__
            ),
        )
        return False
 # --- cache identity -----------------------------------------------------------------------------
 # The cached VTT holds ABSOLUTE cue times (per rating_key + subtitle ordinal); the per-session shift
 # is applied on the way out, so a resume/seek to any offset reuses the same file. Beside it, a small
 # JSON sidecar records WHICH absolute-time ranges the file actually covers — a windowed extraction
 # publishes a usable but incomplete track, and "incomplete" must never be mistaken for "all there is".
 _FULL_END_S = 1_000_000_000.0  # stand-in for "to the end of the file" (JSON can't hold infinity)
 def cache_key(rating_key: str, sub_ord: int) -> str:
    return f"sub_{rating_key}_{sub_ord}"
 def _vtt_path(key: str) -> Path:
    return CACHE_DIR / f"{key}.vtt"
 def _meta_path(key: str) -> Path:
    return CACHE_DIR / f"{key}.json"
 def read_meta(key: str) -> tuple[list[list[float]], bool]:
    """Covered absolute-time ranges + whether the track is fully extracted. A VTT with no sidecar
    (written by an older build, which only ever cached complete tracks) counts as complete."""
    try:
        raw = json.loads(_meta_path(key).read_text(encoding="utf-8"))
        return [[float(a), float(b)] for a, b in raw.get("ranges", [])], bool(raw.get("complete"))
    # silent-ok: no sidecar at all is the documented older-build case the fallback exists for.
    except FileNotFoundError:
        return ([[0.0, _FULL_END_S]], True) if _exists(_vtt_path(key)) else ([], False)
    except (OSError, ValueError, TypeError) as exc:
        # A sidecar that EXISTS and will not parse is different, and the fallback is the dangerous
        # answer to it: beside a cached VTT it reports the track as complete, so a partial track is
        # never extended again and the viewer loses every cue past the window that was cached.
        log.warning(
            "the subtitle sidecar could not be read; the cached track is taken as complete",
            extra=logs.event("plex.subtitles.meta_unreadable", key=key, reason=type(exc).__name__),
        )
        return ([[0.0, _FULL_END_S]], True) if _exists(_vtt_path(key)) else ([], False)
 def _exists(p: Path) -> bool:
    """`Path.exists` that answers False for a path the OS refuses outright: pathlib swallows only
    ENOENT-like errors, so an over-long name (ENAMETOOLONG, from an absurd rating_key or ordinal)
    escaped as a 500 from the status route."""
    try:
        return p.exists()
    # silent-ok: this function's whole job is to answer False for a path the OS refuses. The
    # refusal IS the return value; a caller that needs to report one reports it itself.
    except (OSError, ValueError):
        return False
 def _write_meta(key: str, ranges: list[list[float]], complete: bool) -> None:
    try:
        CACHE_DIR.mkdir(parents=True, exist_ok=True)
        tmp = CACHE_DIR / f"{key}.json.tmp"
        tmp.write_text(json.dumps({"ranges": ranges, "complete": complete}), encoding="utf-8")
        tmp.replace(_meta_path(key))
    except OSError as exc:
        # Without the sidecar beside it, a cached window reads back as a COMPLETE track (see
        # `read_meta`) — so one failed write here permanently costs the rest of that subtitle.
        log.warning(
            "the subtitle sidecar could not be written",
            extra=logs.event(
                "plex.subtitles.meta_write_failed",
                key=key,
                complete=complete,
                reason=type(exc).__name__,
            ),
        )
 def generation(key: str) -> int:
    """Monotonic id of the cached file's current content. It goes into the <track> URL so that when a
    window is superseded by a wider one the browser refetches instead of keeping the short VTT."""
    try:
        return _vtt_path(key).stat().st_mtime_ns
    # silent-ok: 0 for a track that is not cached yet, which is the ordinary case on every first
    # request. (ValueError: a NUL in the key — `stat` refuses the path outright.)
    except (OSError, ValueError):
        return 0
 def merge_ranges(ranges: list[list[float]]) -> list[list[float]]:
    """Sort + coalesce touching/overlapping covered ranges."""
    out: list[list[float]] = []
    for a, b in sorted((r for r in ranges if r[1] > r[0]), key=lambda r: r[0]):
        if out and a <= out[-1][1]:
            out[-1][1] = max(out[-1][1], b)
        else:
            out.append([a, b])
    return out
 def covers(ranges: list[list[float]], at: float) -> bool:
    return any(a <= at <= b for a, b in ranges)
 def merge_vtt(*sources: str) -> str:
    """Union of the cue blocks of several absolute-time VTTs, ordered by start time.
    Two extraction passes over the same file emit identical cues for the region they share, so they
    are de-duplicated — but NOT on the raw timing text. The two passes do not spell a timestamp the
    same way: a window comes back through `shift_vtt`, which always writes `HH:MM:SS.mmm`, while a
    full pass is ffmpeg's own output, and its webvtt muxer drops the hour below one hour
    (`10:00.123`). Keyed on the text, every cue of a window in the first hour survived twice and the
    viewer saw each line stacked on itself. So each timing line is parsed and re-emitted in one
    canonical form, and the key is that canonical timing PLUS the cue text: two different cues that
    happen to share a time (two speakers, a sign over dialogue) are both kept."""
    seen: set[str] = set()
    cues: list[tuple[float, str]] = []
    dropped = 0
    for src in sources:
        for block in re.split(r"\n[ \t]*\n", src or ""):
            stripped = block.strip()
            canon = _canonical_cue(stripped)
            if canon is None:
                # A block WITH a timing line that still would not parse is a cue we are throwing
                # away, not a header — and the merged track would simply be missing those lines.
                if "-->" in stripped:
                    dropped += 1
                continue  # header / NOTE / STYLE — the merged file gets its own single header
            start, key, text = canon
            if key in seen:
                continue
            seen.add(key)
            cues.append((start, text))
    if dropped:
        log.info(
            "some cues were dropped from the merged subtitle: their timing would not parse",
            extra=logs.event("plex.subtitles.cues_dropped", cues=dropped, kept=len(cues)),
        )
    cues.sort(key=lambda c: c[0])
    return "WEBVTT\n\n" + "\n\n".join(b for _, b in cues) + "\n"
 def _canonical_cue(block: str) -> tuple[float, str, str] | None:
    """(start seconds, identity, the block with its timing line canonicalised) — or None for a block
    that is not a cue. The identity leaves out anything before the timing line (an SRT-style cue
    number), which is a label, not content."""
    lines = block.split("\n")
    for i, ln in enumerate(lines):
        if "-->" not in ln:
            continue
        left, _, right = ln.partition("-->")
        rparts = right.strip().split(None, 1)
        settings = (" " + rparts[1]) if len(rparts) > 1 else ""
        try:
            st = _vtt_ts_to_s(left.strip())
            en = _vtt_ts_to_s(rparts[0])
        # silent-ok: None here means "not a cue", and the caller tells a header apart from a
        # broken timing line by whether the block had a `-->` at all — see `merge_vtt`.
        except (ValueError, IndexError):
            return None
        lines[i] = f"{_vtt_s_to_ts(st)} --> {_vtt_s_to_ts(en)}{settings}"
        return st, "\n".join(lines[i:]), "\n".join(lines)
    return None
 def _last_cue_end(vtt: str) -> float:
    """Where the last cue of a VTT ends — how far a pass that died early provably got."""
    end = 0.0
    for ln in vtt.split("\n"):
        if "-->" not in ln:
            continue
        try:
            end = max(end, _vtt_ts_to_s(ln.partition("-->")[2].strip().split(None, 1)[0]))
        # silent-ok: this is a floor — "how far the pass provably got". Skipping a line it cannot
        # read makes the answer smaller, never larger, so the error is always on the safe side.
        except (ValueError, IndexError):
            continue
    return end
 def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) -> bool:
    """Merge a freshly extracted region into the cached track and widen its covered ranges. False
    when the region did not land (the cache is unwritable, or the VTT there cannot be read) — the
    caller must then record a FAILED pass: returning quietly let the next poll schedule the same read
    again, a whole-container pass every time, while the player said "preparing" for good.
    A read-merge-write, so it runs under `_PUBLISH_LOCK`: two jobs publish into the same keys (a
    window and the full pass, and every embedded track of the file rides each of them), and without
    the lock the later writer drops whatever the earlier one merged — permanently, once `complete` is
    set. It is also the only writer of the cache files, which is what keeps their fixed `.tmp`
    staging names safe."""
    with _PUBLISH_LOCK:
        old = cache_read(key)
        if old is None and _vtt_path(key).exists():
            # There, but unreadable (`cache_read` swallows the OSError). Merging into "" would replace
            # a whole track with this one region while its sidecar still claimed all of it.
            log.warning("subtitle cache %s unreadable; not publishing into it", key)
            return False
        old_ranges, was_complete = read_meta(key)
        if old is None:
            # A sidecar with no VTT behind it claims cues that are not there, so it is not merged
            # into. And a VTT with no sidecar reads as a COMPLETE track (see read_meta — how older
            # builds cached), while a publish is two renames: so before a key's first VTT lands, its
            # sidecar is made to claim nothing. Dying between the two then leaves a window that is
            # extracted again, never one taken for the whole track for good.
            old_ranges, was_complete = [], False
            _write_meta(key, [], False)
        if not cache_write(key, merge_vtt(old or "", vtt)):
            log.warning("subtitle cache %s could not be written", key)
            return False  # the region never landed, so the sidecar must not claim it
        _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
        return True
 # --- background extraction ----------------------------------------------------------------------
 # How much of the track to extract before the viewer sees anything. WINDOW_PRE_S starts a little
 # before the playhead so a cue that is already on screen is not missed; WINDOW_LEN_S is the span
 # published as the first, provisional VTT (~4 s of work on the measured file). It only has to hold
 # until the full pass lands behind it — 111 s for that file — so it is deliberately much longer than
 # any realistic full pass.
 WINDOW_PRE_S = 30.0
 WINDOW_LEN_S = 300.0
 # …but it does not always land: a full pass can be backed off (FULL_RETRY_S) or simply slower than
 # the window lasts (a file past ~40 GB, or several passes sharing the array). A window was only asked
 # for once the playhead had LEFT coverage, so every edge unmounted the track for a poll plus an
 # extraction. Within this distance of a covered stretch's end, the next window is read ahead.
 LOOKAHEAD_S = 60.0
 # Ceiling on one ffmpeg run so a wedged extraction can't hold a pool thread forever (the old
 # in-request extraction had no timeout at all).
 EXTRACT_TIMEOUT_S = 900.0
 # How long a timed-out ffmpeg gets, after a TERM, to close its outputs before it is killed.
 _TERM_GRACE_S = 10.0
 # A failed track (or window) is remembered briefly so a 1 s status poll doesn't respawn ffmpeg every
 # second, and forgotten again soon after so fixing the file (or Plex coming back) doesn't need a
 # restart.
 FAIL_TTL_S = 60.0
 # …except a FULL pass that failed. That is a read of the whole container (minutes), a failure that
 # reproduces does so every time, and the viewer is typically inside what it did publish — so the
 # short memo re-armed a whole-file read every minute for as long as they watched. Windows around the
 # playhead still run meanwhile; only the full pass waits this out.
 FULL_RETRY_S = 3600.0
 # The furthest position the status poll accepts. No film is this long, and an absurd one used to
 # reach ffmpeg's `-ss` (which rejects anything past its int64 microseconds).
 MAX_POSITION_S = 100_000.0
 # Windows and full passes run on SEPARATE pools, so a window never waits behind a full pass. They
 # shared one FIFO pool of three whose comment promised "room for a window" that nothing enforced:
 # stepping through three episodes with subtitles on left three full passes (minutes each) holding every
 # worker, and a seek window on the third queued behind them. Two of each: bounded, so a burst can't
 # thrash the array.
 _WIN_POOL = ThreadPoolExecutor(max_workers=2, thread_name_prefix="plex-subs-win")
 _FULL_POOL = ThreadPoolExecutor(max_workers=2, thread_name_prefix="plex-subs-full")
 # Bounds on what may wait for those pools — separate too, so held full-pass slots (minutes each)
 # cannot refuse a window (seconds). The queues are unbounded and every job is a read of the library:
 # a viewer scrubbing through a film queued a window per stop (the one where they stopped ran LAST),
 # and a script could queue thousands. Past a bound nothing is queued — the next poll asks again, by
 # which time something has finished.
 _MAX_WINDOWS_INFLIGHT = 8
 _MAX_FULL_INFLIGHT = 6
 _MAX_TRACK_WINDOWS = 2
 _LOCK = threading.Lock()
 # Queued or running jobs → the absolute span a window job reads (None for a full pass).
 _INFLIGHT: dict[tuple, tuple[float, float] | None] = {}
 # Track-level failures: a track that cannot be served at all (no item, a bitmap track, Plex down…).
 _FAILURES: dict[str, tuple[str, float]] = {}
 # rating_key → when its full pass last failed (see FULL_RETRY_S).
 _FULL_FAILED: dict[str, float] = {}
 # cache key → the spans windows failed to read, with when. A failed window says nothing about the rest
 # of the track — the full pass may be about to deliver it — so it is remembered as a SPAN: it must be
 # neither respawned every poll nor taken as a failure of positions it never tried. (It used to set the
 # track-level memo, which told every viewer at any uncovered position "failed" — a final answer that
 # ends the player's poll — including one planted by a request for an absurd position.)
 _WIN_FAILED: dict[str, list[tuple[float, float, float]]] = {}
 _PUBLISH_LOCK = threading.Lock()
 # The ffmpeg children currently running, so a shutdown can kill them (see `shutdown`), and whether it
 # has: a worker that reaches its Popen after the kill sweep must not start a read.
 _PROCS: set[subprocess.Popen] = set()
 _STOPPING = False
 class SubtitleUnavailable(Exception):
    """A track that cannot be served as text, carrying the stable code the route maps to a status."""
    def __init__(self, code: str):
        super().__init__(code)
        self.code = code
 # code -> HTTP status. An extraction/upstream failure is 422 with a structured detail (502 is
 # reserved for the raw byte proxies); the rest are genuine "no such thing" / "not text".
 UNAVAILABLE_STATUS = {
    "no_item": 404,
    "no_track": 404,
    "no_file": 404,
    "not_fetchable": 404,
    "bitmap": 415,
    "extract_failed": 422,
    "plex_error": 422,
 }
 # The codes that are a FINAL answer about the track: it can never be served as text, so the player
 # stops asking. The others (`plex_error`, `extract_failed`) are about now or about one stretch — a
 # memo that lapses, a window that failed where the rest is fine — and answered as `unavailable`: said,
 # but asked again. Given as `failed`, one Plex hiccup ended the subtitles for the rest of the session,
 # at cached positions too, and after the full pass had completed behind it.
 FINAL_CODES = frozenset({"no_item", "no_track", "no_file", "not_fetchable", "bitmap"})
 def reset_state() -> None:
    """Drop the in-flight/failure registries (tests; nothing in the app needs it)."""
    global _STOPPING
    with _LOCK:
        _INFLIGHT.clear()
        _FAILURES.clear()
        _FULL_FAILED.clear()
        _WIN_FAILED.clear()
        _STOPPING = False
 def shutdown() -> None:
    """Stop extracting, for the app's shutdown. The pool's workers are non-daemon threads and Python
    joins them at interpreter exit — so a worker still inside a full pass (minutes on a big file, up
    to EXTRACT_TIMEOUT_S) held the process open after uvicorn had stopped, until the container runtime
    SIGKILLed it. Queued jobs are dropped and running ffmpeg children are killed, which returns their
    workers at once — and a worker still BEFORE its ffmpeg (the Plex lookup, the DB) finds the flag
    and never starts one. Nothing that matters is lost: an interrupted publish cannot pass for a whole
    track (see `publish`), and an interrupted track is simply extracted again on the next poll."""
    global _STOPPING
    with _LOCK:
        _STOPPING = True
        procs = list(_PROCS)
    for pool in (_WIN_POOL, _FULL_POOL):
        pool.shutdown(wait=False, cancel_futures=True)
    for p in procs:
        p.kill()
 def _sweep_memos() -> None:
    """(Caller holds _LOCK.) Drop every lapsed failure memo. They were only ever pruned when the SAME
    key was read again, and the status route takes any rating_key/ordinal — so a script polling fresh
    keys grew the API process without bound. Swept on every write, they hold at most a TTL's worth."""
    now = time.monotonic()
    for k in [k for k, (_, t) in _FAILURES.items() if now - t >= FAIL_TTL_S]:
        del _FAILURES[k]
    for k in [k for k, t in _FULL_FAILED.items() if now - t >= FULL_RETRY_S]:
        del _FULL_FAILED[k]
    for k in list(_WIN_FAILED):
        _live_window_failures(k)
 def _fail(key: str, code: str) -> None:
    with _LOCK:
        _sweep_memos()
        _FAILURES[key] = (code, time.monotonic())
 def _recent_failure(key: str) -> str | None:
    with _LOCK:
        hit = _FAILURES.get(key)
        if hit and time.monotonic() - hit[1] < FAIL_TTL_S:
            return hit[0]
        _FAILURES.pop(key, None)
        return None
 def _full_failed(rating_key: str) -> bool:
    with _LOCK:
        when = _FULL_FAILED.get(rating_key)
        if when is not None and time.monotonic() - when < FULL_RETRY_S:
            return True
        _FULL_FAILED.pop(rating_key, None)
        return False
 def _live_window_failures(key: str) -> list[tuple[float, float, float]]:
    """(Caller holds _LOCK.) The key's failed-window spans that are still remembered."""
    now = time.monotonic()
    live = [f for f in _WIN_FAILED.get(key, []) if now - f[2] < FAIL_TTL_S]
    if live:
        _WIN_FAILED[key] = live
    else:
        _WIN_FAILED.pop(key, None)
    return live
 def _window_fail(key: str, span: tuple[float, float]) -> None:
    with _LOCK:
        _sweep_memos()
        _WIN_FAILED[key] = [*_live_window_failures(key), (span[0], span[1], time.monotonic())]
 def _window_failed(key: str, at: float) -> bool:
    with _LOCK:
        return any(a <= at <= b for a, b, _ in _live_window_failures(key))
 def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
    """State of one subtitle track, scheduling whatever extraction is still missing. NEVER blocks.
    ``ready`` = fully extracted · ``partial`` = usable, covers ``at``, still growing · ``preparing``
    = nothing to show for ``at`` yet · ``unavailable`` = nothing for ``at`` and nothing being read
    for it right now (``code`` says why), ask again · ``failed`` = the track can never be shown
    (``code`` says why) — the only final answer. ``gen`` changes whenever the cached file grows, so
    the client can refetch a window that has been superseded; 0 = nothing is cached at all."""
    key = cache_key(rating_key, sub_ord)
    ranges, complete = read_meta(key)
    have = cache_read(key) is not None
    covered = have and covers(ranges, at)
    gen = generation(key)
    if complete and have:
        return {"state": "ready", "code": None, "gen": gen}
    if not have and _exists(_vtt_path(key)):
        # On disk but unreadable (permissions, a bad volume): nothing can serve it, and no extraction
        # can help — `publish` refuses to merge into it, and a job whose sidecar covers the position
        # skips as already done — so scheduling only kept the player on "preparing" for good. `gen` 0:
        # there is nothing a <track> could fetch.
        return {"state": "unavailable", "code": "cache_unreadable", "gen": 0}
    code = _recent_failure(key)
    if code and not covered:
        return {
            "state": "failed" if code in FINAL_CODES else "unavailable",
            "code": code,
            "gen": gen,
        }
    # Nothing left that could cover the position for now: the full pass failed, AND so did a window
    # here. Still not final — the memos lapse, and the rest of the track may be right there.
    full_failed = _full_failed(rating_key)
    window_failed = not covered and _window_failed(key, at)
    if full_failed and window_failed:
        return {"state": "unavailable", "code": "extract_failed", "gen": gen}
    if not code:
        probe, want_window = at, not covered and not window_failed
        if covered:
            # Read ahead of an edge instead of waiting to fall off it (see LOOKAHEAD_S). The probe is
            # just PAST the edge: `covers` is inclusive, so the edge itself reads as already done.
            edge = max(b for a, b in ranges if a <= at <= b)
            if edge - at <= LOOKAHEAD_S and edge < _FULL_END_S:
                probe = edge + 1.0
                want_window = not _window_failed(key, probe)
        _schedule(rating_key, sub_ord, probe, want_window=want_window, want_full=not full_failed)
    return {"state": "partial" if covered else "preparing", "code": None, "gen": gen}
 def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]:
    """What the <track> fetch can serve RIGHT NOW, scheduling nothing: the cached VTT (whatever it
    covers), else the recent failure that explains why there is none.
    Scheduling belongs to `ensure` — the status poll, which knows where the viewer is. The fetch does
    not: when it scheduled too, it judged readiness at position 0, so a viewer who resumed an hour in
    got an unrequested window over the head of the file (plus a remount when it landed), and with a
    failure memo alive it was refused a window that WAS on disk while the poll called it showable."""
    key = cache_key(rating_key, sub_ord)
    hit = cache_read(key)
    return (hit, None) if hit is not None else (None, _recent_failure(key))
 def _schedule(
    rating_key: str, sub_ord: int, at: float, want_window: bool, want_full: bool = True
 ) -> None:
    """Kick off the jobs this track still needs: the window that makes it watchable now, and the one
    full pass that makes it complete. A 1 s status poll (or a second viewer) joins a job already
    queued or running instead of starting another ffmpeg.
    A window is joined when one of this track's in-flight windows will COVER the position asked about
    — decided by what it reads, not by an identity derived from the position. The poll sends the live
    playhead, so a position-keyed window was a new job every second; bucketing the position instead
    still queued a second read when the playhead crossed a bucket edge, and joined a backward seek to
    a window that could not cover it. Nor may it be one window per track: a window cut around the
    wrong spot (the first poll after a resume can still report 0) made the right one wait for it. The
    full pass is per ITEM, because one read fans out to every embedded text track of the file."""
    jobs: list[tuple[tuple, float | None]] = []
    with _LOCK:
        if _STOPPING:
            return
        n_windows = sum(1 for span in _INFLIGHT.values() if span is not None)
        n_full = len(_INFLIGHT) - n_windows
        if want_window and n_windows < _MAX_WINDOWS_INFLIGHT:
            spans = [
                span
                for ident, span in _INFLIGHT.items()
                if span is not None and ident[1:3] == (rating_key, sub_ord)
            ]
            if not any(a <= at <= b for a, b in spans) and len(spans) < _MAX_TRACK_WINDOWS:
                # Rounded to what ffmpeg is told (`-ss %.3f`): the cues come back on ffmpeg's zero,
                # and shifting them by an unrounded start put them up to half a millisecond off —
                # enough to spell a timestamp differently from the full pass and double the cue.
                w_start = float(f"{max(0.0, at - WINDOW_PRE_S):.3f}")
                ident = ("win", rating_key, sub_ord, w_start)
                _INFLIGHT[ident] = (w_start, w_start + WINDOW_PRE_S + WINDOW_LEN_S)
                jobs.append((ident, w_start))
        if want_full and n_full < _MAX_FULL_INFLIGHT and ("full", rating_key) not in _INFLIGHT:
            _INFLIGHT[("full", rating_key)] = None
            jobs.append((("full", rating_key), None))
    for ident, window_start in jobs:
        pool = _FULL_POOL if window_start is None else _WIN_POOL
        pool.submit(_run, ident, rating_key, sub_ord, window_start, at)
 def _already_done(key: str, window_start: float | None, at: float) -> bool:
    """A queued job looks again before it reads anything. While it waited, another job may have
    covered it: every embedded track rides each pass over its file, so a window for one language also
    publishes the others."""
    if not _exists(_vtt_path(key)):
        return False
    ranges, complete = read_meta(key)
    return complete or (window_start is not None and covers(ranges, at))
 def _run(
    ident: tuple, rating_key: str, sub_ord: int, window_start: float | None, at: float
 ) -> None:
    key = cache_key(rating_key, sub_ord)
    try:
        if _STOPPING or _already_done(key, window_start, at):
            return
        _extract_and_publish(rating_key, sub_ord, window_start)
    except SubtitleUnavailable as e:
        # The player's own state was the only place this ever showed. `_pass_failed` backs the item
        # off for an hour and `_fail` records a code, but neither leaves a line, so "my subtitles
        # never appear" had nothing on the server to read.
        # A final code is a fact about the file (no such track, a bitmap subtitle); anything else
        # is this instance failing at something it could do.
        log.log(
            logging.INFO if e.code in FINAL_CODES else logging.WARNING,
            "subtitle extraction gave up",
            extra=logs.event(
                "plex.subtitles.pass_failed",
                rating_key=rating_key,
                sub_ord=sub_ord,
                code=e.code,
                windowed=window_start is not None,
            ),
        )
        if e.code == "extract_failed":
            _pass_failed(rating_key, [key], window_start)
        else:
            _fail(key, e.code)
    except PlexError as e:
        # No traceback on purpose: a PlexError carries httpx's own message, which names the method,
        # the URL and the status — the stack under it is this `except` and the client call, and
        # says nothing the message does not. (The URL holds no token; it travels as a header.)
        log.warning(
            "subtitle extraction failed talking to Plex: %s",
            e,
            extra=logs.event("plex.subtitles.plex_error", rating_key=rating_key, sub_ord=sub_ord),
        )
        _fail(key, "plex_error")
    except (
        Exception
    ):  # a worker thread has nobody to raise to — record it, let the next poll see it
        log.exception("subtitle extraction crashed for %s/%s", rating_key, sub_ord)
        _pass_failed(rating_key, [key], window_start)
    finally:
        with _LOCK:
            _INFLIGHT.pop(ident, None)
 def _pass_failed(
    rating_key: str,
    keys: list[str],
    window_start: float | None,
    span: tuple[float, float] | None = None,
 ) -> None:
    """Record an ffmpeg pass that failed: a full pass backs off the whole item (FULL_RETRY_S); a
    window marks only the stretch it failed to read, for the tracks it was reading."""
    if window_start is None:
        with _LOCK:
            _sweep_memos()
            _FULL_FAILED[rating_key] = time.monotonic()
        return
    for key in keys:
        _window_fail(key, span or (window_start, window_start + WINDOW_PRE_S + WINDOW_LEN_S))
 def _text_streams(db: Session, rating_key: str) -> tuple[PlexItem, list[dict]]:
    """The item plus its subtitle streams, in the ordinal order the API and the UI both use."""
    it = by_rating_key(db, PlexItem, rating_key)
    if it is None:
        raise SubtitleUnavailable("no_item")
    with PlexClient(db) as plex:
        part = ((plex.metadata(it.rating_key) or {}).get("Media") or [{}])[0].get("Part") or [{}]
        return it, [s for s in (part[0].get("Stream") or []) if s.get("streamType") == 3]
 def _is_bitmap(stream: dict) -> bool:
    return (stream.get("codec") or stream.get("format") or "").lower() in BITMAP_SUBS
 def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | None) -> None:
    """One extraction job. A sidecar track is fetched whole from Plex (cheap, no ffmpeg); an embedded
    one is extracted together with EVERY other embedded text track in the file, because they all ride
    on the same single read — the whole point of the measurement at the top of this module."""
    with SessionLocal() as db:
        it, subs = _text_streams(db, rating_key)
        if sub_ord < 0 or sub_ord >= len(subs):
            raise SubtitleUnavailable("no_track")
        want = subs[sub_ord]
        if _is_bitmap(want):
            raise SubtitleUnavailable("bitmap")
        if want.get("key"):
            # An external sidecar is one small fetch from Plex, never a read of the media file, so a
            # window job fetches the whole thing too. It must not be left to the full job: that
            # identity is per ITEM (the embedded fan-out shares it), so a sidecar picked while an
            # embedded track's full pass was running sat behind that pass for minutes.
            vtt = _sidecar_vtt(db, want)
            if not publish(cache_key(rating_key, sub_ord), vtt, (0.0, _FULL_END_S), True):
                raise SubtitleUnavailable("extract_failed")
            return
        if want.get("index") is None:
            raise SubtitleUnavailable("not_fetchable")
        src = plex_paths.local_media_path(db, it.file_path)
        if src is None:
            raise SubtitleUnavailable("no_file")
        # Ordinal among the file's EMBEDDED subtitle streams — what `-map 0:s:N` counts. Sidecars sit
        # in the same list but not in the file, so they must not shift the mapping.
        targets = {
            sum(1 for x in subs[:i] if x.get("index") is not None): i
            for i, s in enumerate(subs)
            if s.get("index") is not None and not _is_bitmap(s)
        }
    start = window_start or 0.0
    length = (WINDOW_LEN_S + WINDOW_PRE_S) if window_start is not None else None
    end = _FULL_END_S if length is None else start + length
    texts, clean = _ffmpeg_extract(str(src), sorted(targets), window_start, length)
    for emb_ord, vtt in texts.items():
        key = cache_key(rating_key, targets[emb_ord])
        # A pass that exited non-zero holds only what ffmpeg reached before it died. Claim no more
        # than its last cue, never call it complete, and remember the failure: published as complete,
        # the track read "ready" for good while its subtitles stopped wherever ffmpeg did (the cache
        # has no eviction, so nothing would ever have extracted it again).
        covered_end = end if clean else start + _last_cue_end(vtt)
        landed = publish(
            key,
            shift_vtt(vtt, -start),  # zero-based window clock → absolute cue times
            (start, covered_end),
            clean and length is None,
        )
        if not landed:
            # A read that could not be kept is a failed read (see publish) — backed off like one.
            _pass_failed(rating_key, [key], window_start, (start, end))
        elif not clean:
            _pass_failed(rating_key, [key], window_start, (covered_end, end))
 def _sidecar_vtt(db: Session, stream: dict) -> str:
    """An external subtitle file, fetched through Plex and converted to WebVTT."""
    with PlexClient(db) as plex:
        raw = plex.raw_get(stream["key"])
    codec = (stream.get("codec") or stream.get("format") or "").lower()
    if codec in ("srt", "subrip", ""):
        return srt_to_vtt(raw.decode("utf-8", "replace"))
    with tempfile.NamedTemporaryFile(suffix="." + (codec or "sub"), delete=False) as fh:
        fh.write(raw)
        tmp = fh.name
    try:
        return ffmpeg_to_vtt(tmp, None)
    finally:
        Path(tmp).unlink(missing_ok=True)
 def _ffmpeg_extract(
    src: str, emb_ords: list[int], start: float | None, length: float | None
 ) -> tuple[dict[int, str], bool]:
    """Extract several embedded subtitle streams to WebVTT in ONE ffmpeg run (= one read of the file).
    Returns the texts and whether ffmpeg exited cleanly — a non-zero exit can still leave partial
    output, which is worth publishing but must never be taken for the whole track.
    `start`/`length` bound the read to a window. Without `-copyts` the cues come out on a zero-based
    clock (the caller shifts them back) — which is exactly why `-copyts` is absent: with it ffmpeg
    ignores `-t` and reads the whole container anyway (measured)."""
    if not emb_ords:
        return {}, True
    with tempfile.TemporaryDirectory(prefix="plexsub-") as tmpdir:
        cmd = ["ffmpeg", "-nostdin", "-loglevel", "error"]
        if start:
            cmd += ["-ss", f"{start:.3f}"]
        cmd += ["-i", src]
        outs = {o: Path(tmpdir) / f"{o}.vtt" for o in emb_ords}
        for emb_ord, out in outs.items():
            cmd += ["-map", f"0:s:{emb_ord}"]
            if length is not None:
                cmd += ["-t", f"{length:.3f}"]
                # The input seek lands on the keyframe at or BEFORE `start`, so a cue already running
                # at `start` comes out at a negative time — and by default the muxer then shifts the
                # WHOLE output so that cue sits at 0: every cue of the window late by the distance to
                # that keyframe (1–5 s measured on a real library file, a whole GOP on a synthetic
                # one), and doubled for good once the full pass merged in beside it. Kept negative, the
                # times are exact on the zero-based clock (`_vtt_ts_to_s` reads the sign).
                cmd += ["-avoid_negative_ts", "disabled"]
            cmd += ["-f", "webvtt", "-y", str(out)]
        # Popen rather than run(): the child is registered so `shutdown` can kill it — and one that
        # would start after the shutdown's kill sweep never does, or is killed right here.
        with _LOCK:
            if _STOPPING:
                raise SubtitleUnavailable("extract_failed")
        proc = subprocess.Popen(
            cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE
        )
        with _LOCK:
            _PROCS.add(proc)
            if _STOPPING:
                proc.kill()
        timed_out = False
        try:
            try:
                _, err = proc.communicate(timeout=EXTRACT_TIMEOUT_S)
            except subprocess.TimeoutExpired:
                # A pass that ran out of time is a pass that died partway: what it reached is kept and
                # published as partial (the caller's unclean path), like any other non-zero exit. It
                # used to be killed and its outputs deleted unread — and with the full-pass backoff, the
                # same doomed read came back every hour. TERM first: ffmpeg closes its outputs on it,
                # whereas a KILL leaves only what was already flushed in whole blocks (measured: none).
                timed_out = True
                proc.terminate()
                try:
                    _, err = proc.communicate(timeout=_TERM_GRACE_S)
                except subprocess.TimeoutExpired:
                    # TERM is what makes a timed-out pass worth keeping: ffmpeg closes its outputs
                    # on it. An ffmpeg that ignores TERM leaves only whole blocks already flushed,
                    # so the partial track is short for a reason the later line cannot tell apart.
                    log.info(
                        "the subtitle extraction ignored TERM and was killed",
                        extra=logs.event(
                            "plex.subtitles.extract_killed_after_term",
                            windowed=start is not None,
                        ),
                    )
                    proc.kill()
                    _, err = proc.communicate()
        finally:
            with _LOCK:
                _PROCS.discard(proc)
        got = {
            o: p.read_text(encoding="utf-8", errors="replace")
            for o, p in outs.items()
            if p.exists()
        }
    if not got:
        raise SubtitleUnavailable("extract_failed")
    clean = proc.returncode == 0 and not timed_out
    if not clean:
        log.warning(
            "ffmpeg subtitle pass %s: %s",
            "timed out" if timed_out else f"exited {proc.returncode}",
            (err or b"")[:200],
        )
    return got, clean
@@ -15,20 +15,18 @@ dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are
 item-detail/player path (P2), not here.
 """
 import logging
 from datetime import datetime, timezone
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 from app.models import PlexCollection, PlexItem, PlexLibrary, PlexSeason, PlexShow
 from app.plex import detail, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 # Codecs/containers a browser can play in a native <video> without any transcoding.
 _BROWSER_VIDEO = {"h264"}
 _BROWSER_AUDIO = {"aac", "mp3", "opus", "vorbis"}
@@ -102,6 +100,9 @@ def _video_stream_props(meta: dict) -> tuple[int | None, bool]:
                bd = s.get("bitDepth")
                try:
                    depth = int(bd) if bd else None
                # silent-ok: unknown bit depth, which is also what most listings report. The
                # playback class then falls back to the codec alone, and per-stream noise over a
                # whole library would drown the sync's own lines.
                except (TypeError, ValueError):
                    depth = None
                hdr = str(s.get("colorTrc") or "").lower() in _HDR_TRANSFERS
@@ -112,6 +113,8 @@ def _video_stream_props(meta: dict) -> tuple[int | None, bool]:
 def _epoch(v) -> datetime | None:
    try:
        return datetime.fromtimestamp(int(v), tz=timezone.utc) if v else None
    # silent-ok: a field Plex leaves out of most listing rows. None is a legitimate stored value,
    # and every caller treats it as "not known" rather than as an error.
    except (TypeError, ValueError, OSError):
        return None
@@ -120,6 +123,7 @@ def _date(v):
    """Parse a Plex 'YYYY-MM-DD' string (originallyAvailableAt) → date, or None."""
    try:
        return datetime.strptime(v, "%Y-%m-%d").date() if v else None
    # silent-ok: as `_epoch` above — an absent or unparsable air date is stored as no air date.
    except (TypeError, ValueError):
        return None
@@ -135,6 +139,7 @@ def _tags(meta: dict, key: str, limit: int | None = None) -> list | None:
 def _rating(meta: dict) -> float | None:
    try:
        return float(meta.get("audienceRating") or meta.get("rating"))
    # silent-ok: TypeError on `float(None)` is the ordinary path — most items carry no rating.
    except (TypeError, ValueError):
        return None
@@ -266,15 +271,19 @@ def sync(db: Session) -> dict:
            # becomes filterable over successive runs (the cheap listing above only stored the top ~3).
            try:
                stats["people_enriched"] = _enrich_people_batch(db, plex)
-            except Exception as e:  # best-effort — never fail the sync over the backfill
+            except Exception:  # noqa: BLE001 — best-effort; never fail the sync over a backfill
-                log.warning("Plex people enrich batch failed: %s", e)
+                # With the traceback: a blind catch over a batch that fetches AND writes can be
                # a Plex shape change, a DB error or our own bug, and `%s` told them apart badly.
                log.exception("the Plex people-enrich batch failed")
            # Probe a bounded batch of HW-decodable transcode items for bit-depth/HDR, so the
            # playback-class filter's HW/SW split is precise (a 10-bit/HDR HEVC → software) over
            # successive runs. Only HW-decodable-codec transcodes are probed — the rest are SW by codec.
            try:
                stats["media_probed"] = _probe_media_batch(db, plex)
-            except Exception as e:  # best-effort — never fail the sync over the backfill
+            except Exception:  # noqa: BLE001 — best-effort; never fail the sync over a backfill
-                log.warning("Plex media probe batch failed: %s", e)
+                log.exception("the Plex media-probe batch failed")
    # silent-ok: the return value IS the report. `{"skipped": …}` goes to the scheduler, which
    # logs the job result, and to the admin route, which answers it to the caller.
    except PlexNotConfigured as e:
        return {"skipped": str(e)}
    except PlexError as e:
@@ -285,8 +294,8 @@ def sync(db: Session) -> dict:
    # appear in ANY item's cast/directors — drop those rows, mirroring how Plex drops orphaned metadata.
    try:
        stats["people_pruned"] = people.prune_orphan_people(db)
-    except Exception as e:  # best-effort housekeeping — never fail the sync over it
+    except Exception:  # noqa: BLE001 — best-effort housekeeping; never fail the sync over it
-        log.warning("Plex people prune failed: %s", e)
+        log.exception("the Plex people prune failed")
    log.info("Plex sync done: %s", stats)
    return stats
@@ -325,7 +334,9 @@ def _probe_media_batch(db: Session, plex: PlexClient, limit: int = _PROBE_BATCH)
    for row in rows:
        try:
            meta = plex.metadata(row.rating_key) or {}
-        except Exception as e:  # transient — leave media_probed_at NULL so it retries next run
+        # No traceback and only debug: this is per item over a whole library, and the stack is
        # the same `plex.metadata` call every time. The retry next run is the handling.
        except Exception as e:  # noqa: BLE001 — transient; leave media_probed_at NULL to retry
            log.debug("Plex media probe fetch failed for %s: %s", row.rating_key, e)
            continue
        bit_depth, hdr = _video_stream_props(meta)
@@ -372,7 +383,8 @@ def _enrich_people_batch(db: Session, plex: PlexClient, limit: int = _ENRICH_BAT
    for row in [*movies, *shows]:
        try:
            meta = plex.metadata(row.rating_key) or {}
-        except Exception as e:
+        # As in `_probe_media_batch` above: per item, so the message without the stack.
        except Exception as e:  # noqa: BLE001 — transient; leave people_enriched_at NULL
            log.debug("Plex people enrich fetch failed for %s: %s", row.rating_key, e)
            continue  # leave people_enriched_at NULL so it's retried on a later run
        people.enrich_row_people(db, row, people.cast_from_meta(meta))
@@ -10,7 +10,6 @@ One-parser rule (mirrors app/plex/detail.py): `parse_tmdb` is the pure parser, `
 the row. The enrich batch + scheduler entry live here too so the whole TMDB integration is one module.
 """
 import logging
 import time
 from datetime import datetime, timezone
@@ -19,12 +18,11 @@ 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 import logs, sysconfig
 from app.config import settings
 from app.models import PlexItem, PlexPerson, PlexShow
-log = logging.getLogger("siftlode.tmdb")
+log = logs.get_logger(__name__)
 # Politeness throttle: TMDB tolerates ~50 req/s; ~33/s leaves comfortable headroom for a shared host.
 _MIN_INTERVAL = 0.03
@@ -142,6 +140,12 @@ def guid_to_tmdb_id(guid: str | None, media_type: str, tmdb: TmdbClient) -> int
        try:
            return int(ext)
        except ValueError:
            # The caller stamps the watermark on a None, so this title is never looked at again:
            # one unreadable guid costs it its artwork and its cast permanently.
            log.info(
                "a Plex guid named TMDB but did not carry a numeric id",
                extra=logs.event("plex.tmdb.guid_unparsable", provider=provider),
            )
            return None
    source = {"imdb": "imdb_id", "tvdb": "tvdb_id"}.get(provider)
    if not source:
@@ -499,7 +503,17 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
        # doesn't tie up a threadpool worker for the default 30s.
        with TmdbClient(db, timeout=8.0) as tmdb:
            payload = tmdb.fetch_person(person.tmdb_person_id)
-    except TmdbError:
+    except TmdbError as exc:
        # False leaves the person un-enriched and unstamped, so it is retried — but the page in
        # front of the user right now shows an empty biography with nothing to say why.
        log.warning(
            "the TMDB person lookup failed",
            extra=logs.event(
                "plex.tmdb.person_enrich_failed",
                person_id=person.id,
                reason=type(exc).__name__,
            ),
        )
        return False
    if payload is None:
        person.tmdb_enriched_at = datetime.now(timezone.utc)
@@ -17,14 +17,17 @@ and the incremental pull resolves a genuine divergence to Plex's state (see `_pu
 running a last-write-wins comparison.
 """
-import logging
+# On the PlexError lines in this module: none of them carries a traceback, deliberately. A
 # PlexError is httpx's own message — the method, the URL and the status of one call — and the stack
 # beneath it is always this `except` plus `PlexClient._get`. The attrs beside the line say which
 # user and which phase, which is the part the message cannot know.
 from datetime import datetime, timezone
 from sqlalchemy import func, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 from app.db import SessionLocal
 from app.models import PlexItem, PlexLink, PlexState
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
@@ -36,8 +39,7 @@ from app.plex.sync import (
    _paginate,
 )
-log = logging.getLogger("siftlode.plex.watch")
+log = logs.get_logger(__name__)
 # A resume position below this many seconds isn't worth mirroring — matches the player's own
 # _PROGRESS_MIN_S (a stray few-second seek is not "in progress").
 _PROGRESS_MIN_S = 5
@@ -148,6 +150,8 @@ def import_owner_watch_state(db: Session, link: PlexLink) -> dict:
            link.initial_import_done = True
            link.last_watch_sync_at = datetime.now(timezone.utc)
            db.commit()
    # silent-ok: the `{"skipped": …}` return is the report — the admin route answers it and the
    # scheduler logs it on the job line.
    except PlexNotConfigured as e:
        return {"skipped": str(e)}
    except PlexError as e:
@@ -326,8 +330,18 @@ def _resolve_account_id(db: Session, plex: PlexClient, link: PlexLink) -> int:
            if int(a.get("id") or -1) == 1:
                username = a.get("name")
                break
-    except PlexError:
+    except PlexError as exc:
-        pass
+        # The fallback account id 1 is right for the admin-token setup, so sync keeps working —
        # but the username is never stored, and the UI then has no name to show for the link,
        # exactly as if the server had not offered one.
        log.info(
            "the Plex account list could not be read; the link keeps the default account",
            extra=logs.event(
                "plex.watch.accounts_probe_failed",
                user_id=link.user_id,
                reason=type(exc).__name__,
            ),
        )
    link.plex_account_id = acct_id
    if username:
        link.plex_username = username
@@ -566,6 +580,7 @@ def run_plex_watch_sync(db: Session) -> dict:
                total["repushed"] += _repush_dirty(db, plex, link)
                link.last_watch_sync_at = now
                db.commit()
        # silent-ok: the `{"skipped": …}` return is the report, as above.
        except PlexNotConfigured as e:
            return {"skipped": str(e)}
        except PlexError as e:
@@ -617,6 +632,7 @@ def run_plex_watch_reconcile(db: Session) -> dict:
                total["repushed"] += _repush_dirty(db, plex, link)
                link.last_watch_sync_at = datetime.now(timezone.utc)
                db.commit()
        # silent-ok: the `{"skipped": …}` return is the report, as above.
        except PlexNotConfigured as e:
            return {"skipped": str(e)}
        except PlexError as e:
@@ -1,21 +1,30 @@
 """A tiny in-process sliding-window rate limiter.
-Generic groundwork: keyed by an arbitrary string (e.g. a client IP), so it can throttle any
+Generic groundwork: keyed by an arbitrary string (e.g. a client — `client_key`), so it can throttle any
 endpoint. Single-worker uvicorn → in-memory state is sufficient; it resets on restart, which
 is fine for abuse throttling (not for anything that must survive a deploy). Not shared across
 processes — if we ever run multiple workers, swap the backing store for Redis behind the same
 ``allow()`` interface.
 """
 import ipaddress
 import threading
 import time
 from fastapi import Request
 from app.config import settings
 class RateLimiter:
-    def __init__(self, max_events: int, window_seconds: float):
+    """At most `max_events` attempts per `window_seconds` per key — or, when each attempt passes a
    `cost`, at most that much total cost (a byte budget counts bytes, not calls)."""
    def __init__(self, max_events: float, window_seconds: float):
        self.max_events = max_events
        self.window = window_seconds
-        self._hits: dict[str, list[float]] = {}
+        # key → (monotonic time, cost) of every counted attempt still inside the window
        self._hits: dict[str, list[tuple[float, float]]] = {}
        self._lock = threading.Lock()
    def reset(self) -> None:
@@ -25,27 +34,74 @@ class RateLimiter:
        with self._lock:
            self._hits.clear()
-    def allow(self, key: str) -> bool:
+    def exhausted(self, key: str) -> bool:
-        """Record an attempt for ``key`` and return whether it is within the limit.
+        """Whether ``key``'s window is already full (``allow`` would refuse it), WITHOUT counting an
        attempt — for a limit that counts only some outcomes: ask it first, ``allow`` the ones that
        count."""
        cutoff = time.monotonic() - self.window
        with self._lock:
            return sum(c for t, c in self._hits.get(key, []) if t > cutoff) >= self.max_events
-        True  -> under the cap (the attempt is counted).
+    def allow(self, key: str, cost: float = 1) -> bool:
-        False -> the cap for the current window is already reached (attempt NOT counted, so a
+        """Record an attempt costing ``cost`` for ``key`` and return whether it is within the limit.
        True  -> within the cap (the attempt is counted).
        False -> the attempt would pass the cap for the current window (attempt NOT counted, so a
                 blocked caller can't keep pushing the window forward)."""
        now = time.monotonic()
        cutoff = now - self.window
        with self._lock:
-            hits = [t for t in self._hits.get(key, []) if t > cutoff]
+            hits = [(t, c) for t, c in self._hits.get(key, []) if t > cutoff]
-            if len(hits) >= self.max_events:
+            if sum(c for _, c in hits) + cost > self.max_events:
                self._hits[key] = hits
                return False
-            hits.append(now)
+            hits.append((now, cost))
            self._hits[key] = hits
            # Opportunistic cleanup so abandoned keys don't accumulate unboundedly.
            if len(self._hits) > 4096:
                for k in list(self._hits):
-                    fresh = [t for t in self._hits[k] if t > cutoff]
+                    fresh = [(t, c) for t, c in self._hits[k] if t > cutoff]
                    if fresh:
                        self._hits[k] = fresh
                    else:
                        del self._hits[k]
            return True
 def _norm_ip(s: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
    """Parse an IP for comparison, unwrapping IPv4-mapped IPv6 (`::ffff:10.0.0.1` → `10.0.0.1`) so a
    plain-IPv4 allowlist still matches a peer that surfaces in mapped form. None for a non-IP string."""
    try:
        ip = ipaddress.ip_address(s.strip())
    # silent-ok: parsing an untrusted header value, where "not an IP" is a documented answer this
    # function returns — and a line per request is what an attacker would aim for.
    except ValueError:
        return None
    return ip.ipv4_mapped if getattr(ip, "ipv4_mapped", None) else ip
 def client_key(request: Request) -> str:
    """Best-effort client identity for rate limiting: its IP, or for IPv6 the /64 the address sits in — a
    subscriber is handed a whole /64, so keyed on the full address one client would have endless identities
    to spread its attempts over. X-Forwarded-For is client-controlled, so we trust it
    ONLY when the request actually arrived from a configured reverse proxy (settings.trusted_proxy_ips
    — the address the proxy connects FROM, e.g. the VPS Caddy's WireGuard peer IP). Our proxy APPENDS
    the client it saw to XFF, so the RIGHTMOST entry is the real client and can't be forged by a
    client pre-seeding the header. Any other peer (someone hitting the app port directly, bypassing the
    proxy) is untrusted — we use its real socket IP, so it can't spoof its rate-limit identity.
    SAFETY: this relies on `request.client` being the TRUE socket peer. uvicorn is started WITHOUT
    `--proxy-headers` (see entrypoint.sh) precisely so it never rewrites `request.client` from XFF —
    do NOT add that flag, or the trust check below would compare against a forgeable value."""
    peer = request.client.host if request.client else "unknown"
    client = peer
    trusted = {_norm_ip(p) for p in settings.trusted_proxy_ip_set} - {None}
    if _norm_ip(peer) in trusted:
        xff = request.headers.get("x-forwarded-for")
        parts = [p.strip() for p in (xff or "").split(",") if p.strip()]
        if parts:
            client = parts[-1]
    ip = _norm_ip(client)
    if isinstance(ip, ipaddress.IPv6Address):
        return str(ipaddress.IPv6Network((ip, 64), strict=False))
    return client
@@ -13,12 +13,12 @@ mutated from a single thread.
 """
 import asyncio
 import logging
 from collections import defaultdict
 from starlette.websockets import WebSocket
 from app import logs
-log = logging.getLogger("siftlode.realtime")
+log = logs.get_logger(__name__)
 class ConnectionManager:
@@ -42,9 +42,16 @@ class ConnectionManager:
        for ws in list(self._conns.get(user_id, ())):
            try:
                await ws.send_json(payload)
-            except Exception:
+            except Exception as exc:  # noqa: BLE001 — one dead socket must not stop the others
-                # Stale socket; it'll be cleaned up by its own disconnect handler.
+                # Stale socket; it'll be cleaned up by its own disconnect handler. But this is
-                pass
+                # also where a live update goes missing: the UI simply never changes, and there
                # is no request behind it whose failure anyone could look up.
                log.debug(
                    "a live update could not be pushed to a socket",
                    extra=logs.event(
                        "realtime.push_failed", user_id=user_id, reason=type(exc).__name__
                    ),
                )
    def push(self, user_id: int, payload: dict) -> None:
        """Schedule a push onto the WebSocket event loop. Safe to call from a sync route
@@ -54,7 +61,7 @@ class ConnectionManager:
            return
        try:
            asyncio.run_coroutine_threadsafe(self._push(user_id, payload), loop)
-        except Exception:
+        except Exception:  # noqa: BLE001 — a closed loop or socket must not fail the caller
            log.debug("ws push failed", exc_info=True)
@@ -17,12 +17,20 @@ 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:
+def not_found(what: str = "generic") -> HTTPException:
    """The 404 for a row that is gone — structured, so the bilingual UI says it in the reader's
    language (`errors.notFound.<what>`, generic fallback). This is the 404 a user actually meets: the
    thing was deleted in another tab or on another device. It used to be a bare English string
    ("Unknown view", "Not found"), which the Hungarian UI toasted verbatim."""
    return HTTPException(status_code=404, detail={"code": "not_found", "reason": what})
 def get_or_404(db: Session, model: type[M], id_: Any, *, what: str = "generic") -> 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)
+        raise not_found(what)
    return obj
@@ -33,13 +41,13 @@ def owned_or_404(
    user: User,
    *,
    owner_attr: str = "user_id",
-    detail: str = "Not found",
+    what: str = "generic",
 ) -> 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)
+    obj = get_or_404(db, model, id_, what=what)
    if getattr(obj, owner_attr) != user.id:
-        raise HTTPException(status_code=404, detail=detail)
+        raise not_found(what)
    return obj
@@ -173,7 +173,7 @@ def _activate_user_by_email(db: Session, email: str) -> None:
 def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
    # Idempotency guard: only a still-pending invite can be decided. Without this a repeat/stale
    # approve or deny re-runs its side effects — re-activating a user, or (now that deny emails)
    # sending a duplicate decision mail, even flipping an already-approved invite to "denied" and
@@ -291,7 +291,7 @@ def send_invitation(
    Only an APPROVED row can be invited: there is nothing to invite someone to while their request is
    undecided, and inviting a denied address would contradict the decision."""
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
    if inv.status != "approved":
        raise HTTPException(
            status_code=409,
@@ -364,7 +364,7 @@ def delete_invite(
    falls back to the env ALLOWED_EMAILS / ADMIN_EMAILS bootstrap lists once no invite exists, so for
    an address on those the deletion leaves access intact (and an ADMIN_EMAILS address is still
    promoted to admin on its next Google sign-in). The admin has to hear that, not guess it."""
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
    if _accounts_for(db, [inv.email]):
        raise HTTPException(
            status_code=409,
@@ -408,6 +408,8 @@ def _serialize_user(u: User) -> dict:
        # confusing sign-in.
        "google_email": u.google_email if u.google_email != u.email else None,
        "created_at": iso(u.created_at),
        # NULL = no sign-in since the column existed (0085), or the shared demo account.
        "last_login_at": iso(u.last_login_at),
    }
@@ -434,9 +436,7 @@ def set_user_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)
+    target = get_or_404(db, User, user_id, what="user")
    if target is None:
        raise HTTPException(status_code=404, detail="No such user")
    if target.is_demo:
        raise HTTPException(status_code=400, detail="The demo account's role can't be changed.")
    if target.id == admin.id:
@@ -491,9 +491,7 @@ def set_user_suspended(
    un-suspend the user is emailed they can return (suspend is announced reactively, on a blocked
    sign-in)."""
    suspended = body.suspended
-    target = db.get(User, user_id)
+    target = get_or_404(db, User, user_id, what="user")
    if target is None:
        raise HTTPException(status_code=404, detail="No such user")
    if target.is_demo:
        raise HTTPException(status_code=400, detail="The demo account can't be suspended.")
    if target.id == admin.id:
@@ -537,9 +535,7 @@ def admin_delete_user(
    """Admin-triggered account deletion — the same full erasure a user can perform on themselves
    (cascade delete of all personal data + access-request cleanup + Google-grant revoke). Guards:
    not the demo account, not yourself (use Settings → Account), and not the last admin."""
-    target = db.get(User, user_id)
+    target = get_or_404(db, User, user_id, what="user")
    if target is None:
        raise HTTPException(status_code=404, detail="No such user")
    if target.is_demo:
        raise HTTPException(status_code=400, detail="The demo account can't be deleted.")
    if target.id == admin.id:
@@ -632,7 +628,7 @@ def user_access(
    Its own endpoint rather than extra columns on /users: `is_allowed` and `can_activate` each run a
    query, and the panel opens for ONE user at a time — folding them into the list would pay that cost
    per row on every load to answer a question nobody asked yet."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
    return _serialize_user(target) | {
        "is_allowed": is_allowed(db, target.email),
        "can_activate": can_activate(db, target),
@@ -657,7 +653,7 @@ def create_set_password_link(
    an instance with no mail — narrowing it to one of those would only make the admin's real case the
    one it refuses. The demo account is the single exception: it is shared, so handing anyone a way to
    change its password is handing them everyone else's session."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
    if target.is_demo:
        raise HTTPException(
            status_code=400, detail={"code": "setpw", "reason": "demo", "email": target.email}
@@ -693,7 +689,7 @@ def activate_user(
    This endpoint changes nothing about what an unauthenticated caller can cause — the admin could
    already do exactly this by re-entering the address in the whitelist box (`add_invite` →
    `_activate_user_by_email`). What was missing was any way to know they had to."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
    if target.is_demo:
        raise HTTPException(status_code=400, detail="The demo account can't be activated.")
    if target.is_active:
@@ -732,7 +728,7 @@ def resend_user_verification(
    Not rate-limited: an admin is not a threat model to enumerate against, and the deliberate silence
    of the public endpoint is exactly what this exists to escape."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
    if target.is_demo or target.email_verified:
        raise HTTPException(
            status_code=409,
@@ -3,7 +3,6 @@
 Split out of app/auth.py (R12 S2); the core auth surface (current_user, scopes, token
 helpers) stays in app/auth.py, imported below."""
 import ipaddress
 import secrets
 from datetime import datetime, timedelta, timezone
 from typing import NamedTuple
@@ -18,6 +17,7 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 from app import email as email_mod
 from app import logs
 from app import mailtext
 from app import sysconfig
 from app.auth import (
@@ -40,7 +40,7 @@ from app.auth import (
 from app.config import settings
 from app.db import SessionLocal, get_db
 from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
-from app.ratelimit import RateLimiter
+from app.ratelimit import RateLimiter, client_key
 from app.security import encrypt, hash_password, hash_token, verify_password
 from app.utils import canonical_email, valid_email
@@ -172,37 +172,6 @@ def is_demo_allowed(db: Session, email: str) -> bool:
    )
 def _norm_ip(s: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
    """Parse an IP for comparison, unwrapping IPv4-mapped IPv6 (`::ffff:10.0.0.1` → `10.0.0.1`) so a
    plain-IPv4 allowlist still matches a peer that surfaces in mapped form. None for a non-IP string."""
    try:
        ip = ipaddress.ip_address(s.strip())
    except ValueError:
        return None
    return ip.ipv4_mapped if getattr(ip, "ipv4_mapped", None) else ip
 def _client_ip(request: Request) -> str:
    """Best-effort client IP for rate limiting. X-Forwarded-For is client-controlled, so we trust it
    ONLY when the request actually arrived from a configured reverse proxy (settings.trusted_proxy_ips
    — the address the proxy connects FROM, e.g. the VPS Caddy's WireGuard peer IP). Our proxy APPENDS
    the client it saw to XFF, so the RIGHTMOST entry is the real client and can't be forged by a
    client pre-seeding the header. Any other peer (someone hitting the app port directly, bypassing the
    proxy) is untrusted — we use its real socket IP, so it can't spoof its rate-limit identity.
    SAFETY: this relies on `request.client` being the TRUE socket peer. uvicorn is started WITHOUT
    `--proxy-headers` (see entrypoint.sh) precisely so it never rewrites `request.client` from XFF —
    do NOT add that flag, or the trust check below would compare against a forgeable value."""
    peer = request.client.host if request.client else "unknown"
    trusted = {_norm_ip(p) for p in settings.trusted_proxy_ip_set} - {None}
    if _norm_ip(peer) in trusted:
        xff = request.headers.get("x-forwarded-for")
        parts = [p.strip() for p in (xff or "").split(",") if p.strip()]
        if parts:
            return parts[-1]
    return peer
 class InviteRequest(NamedTuple):
    """What an access request settled on.
@@ -418,7 +387,15 @@ async def callback(
        return _complete_link(request, db, link_uid, link_explicit, sub, userinfo, token)
    if not is_allowed(db, email):
-        log.warning("Login denied (not approved): %s", email or "<no email>")
+        # No uid to name — having no account here is the branch. And the address is left out on
        # purpose: `redact_text` turns it into `[email]` before either sink sees it, so a line
        # whose only variable is always `[email]` says nothing. WHO asked is in the pending
        # invite recorded just below, which is where an admin looks anyway.
        log.warning(
            "Google sign-in denied: address not approved",
            # log-pii-ok: whether an address came back, not what it was
            extra=logs.event("auth.login.denied", reason="not_approved", has_email=bool(email)),
        )
        # A denied Google login doubles as an access request: record it for the admin and
        # land the user on a friendly "request received" screen instead of a raw 403.
        if email:
@@ -451,15 +428,20 @@ async def callback(
            if existing.google_sub is not None and existing.google_sub != sub:
                # A different Google identity is already bound to this email — refuse rather than
                # hijack it. (Near-impossible with real Google accounts: email↔sub is stable.)
-                log.warning("Google login email collision (different sub): %s", email)
+                log.warning(
                    "Google sign-in refused: a different Google identity holds this address",
                    extra=logs.event("auth.login.denied", reason="sub_collision", uid=existing.id),
                )
                return RedirectResponse(url=_access_notice_url("denied"))
            if not userinfo.get("email_verified", False):
                # Adopting (and activating) a pre-existing password account requires Google to
                # actually attest the address — otherwise an unverified Google email that merely
                # collides with a pending registration could seize that account. Defense-in-depth.
                log.warning(
-                    "Google login: unverified email, refusing to adopt account: %s",
+                    "Google sign-in refused: unverified address, not adopting the account",
-                    email,
+                    extra=logs.event(
                        "auth.login.denied", reason="email_unverified", uid=existing.id
                    ),
                )
                return RedirectResponse(url=_access_notice_url("denied"))
            user = existing
@@ -477,7 +459,10 @@ async def callback(
    # A suspended account can't sign in by any method. Block before establishing the session and
    # tell the (verified) owner why — a successful Google auth proves they control this account.
    if user.is_suspended:
-        log.info("Suspended account blocked at Google login: %s", email)
+        log.info(
            "Google sign-in blocked: the account is suspended",
            extra=logs.event("auth.login.denied", reason="suspended", uid=user.id),
        )
        _notify_suspended(background, user)
        return RedirectResponse(url="/?login=suspended")
    # Record what Google actually answers with, beside the address the user registered with. The two
@@ -511,17 +496,12 @@ async def callback(
    db.flush()
    _store_token(db, user, token)
    _establish_session(request, user)
    db.commit()
-
+    log.info(
-    # Multi-session: remember every account that has authenticated in this browser so the
+        "signed in",
-    # user can switch between them without going through Google again. Only accounts that
+        extra=logs.event("auth.login.ok", method="google", uid=user.id, role=user.role),
-    # actually completed OAuth here land in this list (it's the proof they may be switched to).
+    )
    accounts = [a for a in (request.session.get("account_ids") or []) if a != user.id]
    accounts.append(user.id)
    request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
    request.session["user_id"] = user.id
    _remember_epoch(request, user)
    log.info("Login: %s (id=%s, role=%s)", email, user.id, user.role)
    return RedirectResponse(url="/")
@@ -631,6 +611,8 @@ async def logout(request: Request):
    out in one tab doesn't disturb another tab running a different account. If the account being
    removed was the session default, promote the most recent remaining account (or clear the
    session when none remain)."""
    # A tab still pinned to an account already signed out in another tab resolves to nobody, so it
    # signs nobody out — it used to fall back to the default and sign THAT account out in its place.
    active, is_default = resolved_user_id(request)
    remaining = [a for a in (request.session.get("account_ids") or []) if a != active]
    request.session["account_ids"] = remaining
@@ -672,7 +654,7 @@ async def request_access(
    email = (body.email or "").strip().lower()
    if not valid_email(email):
        raise HTTPException(status_code=400, detail="Enter a valid email address.")
-    if not _request_access_limiter.allow(_client_ip(request)):
+    if not _request_access_limiter.allow(client_key(request)):
        return {"status": "pending"}
    if is_allowed(db, email):
        return {"status": "pending"}  # already allowed — don't reveal it
@@ -689,7 +671,7 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
    so there is no visible 'demo login' button. Rate-limited per IP; when blocked it answers
    exactly like a non-match (authenticated=false) so the field can't be hammered as an
    enumeration oracle. On a match it sets the session and the client reloads into the app."""
-    if not _demo_limiter.allow(_client_ip(request)):
+    if not _demo_limiter.allow(client_key(request)):
        return {"authenticated": False}
    email = (body.email or "").strip().lower()
    if valid_email(email) and is_demo_allowed(db, email):
@@ -699,19 +681,25 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
        request.session.clear()
        request.session["user_id"] = demo.id
        _remember_epoch(request, demo)
-        log.info("Demo login (key=%s, demo_id=%s)", email, demo.id)
+        # The demo key IS an address, so it is not in the line — see the denied branch above.
        log.info("signed in", extra=logs.event("auth.login.ok", method="demo", uid=demo.id))
        return {"authenticated": True}
    return {"authenticated": False}
 def _establish_session(request: Request, user: User) -> None:
-    """Sign `user` in for this browser session, mirroring the Google callback's multi-account
+    """Sign `user` in for this browser session — the ONE sign-in path, shared by the Google callback
-    handling so password sign-in joins the same account switcher."""
+    and password login, so both join the same account switcher and both stamp `last_login_at` (the
    caller commits). Multi-session: every account that authenticated in this browser is remembered so
    the user can switch between them; only accounts that actually proved themselves HERE land in that
    wallet (it is the proof they may be switched to). The demo entry deliberately does not come
    through here: it clears the wallet instead, and its shared account has no meaningful last login."""
    accounts = [a for a in (request.session.get("account_ids") or []) if a != user.id]
    accounts.append(user.id)
    request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
    request.session["user_id"] = user.id
    _remember_epoch(request, user)
    user.last_login_at = datetime.now(timezone.utc)
 def _app_base() -> str:
@@ -835,7 +823,7 @@ def register(
        )
    if not sysconfig.get_bool(db, "allow_registration"):
        raise HTTPException(status_code=403, detail="Registration is currently closed.")
-    if not _register_limiter.allow(_client_ip(request)):
+    if not _register_limiter.allow(client_key(request)):
        return {"status": "ok"}  # silently throttle; uniform response
    # Do the existence check + account creation OFF the response path (a background task with its own
@@ -913,7 +901,12 @@ def _register_account(email: str, password: str, lang: str | None = None) -> Non
        except IntegrityError:
            # A concurrent registration for the same new email won the race between the pre-check
            # above and this flush (the unique-email constraint fires). Same already-registered
-            # no-op as the pre-check hit — roll back and stop.
+            # no-op as the pre-check hit — roll back and stop. The line carries nothing: the
            # answer to the caller is deliberately identical either way, and so is this.
            log.info(
                "a registration lost the race for its address",
                extra=logs.event("auth.register.race_lost"),
            )
            db.rollback()
            return
        upsert_pending_invite(db, email)  # admin-approval gate
@@ -1003,7 +996,7 @@ def verify_email_resend(
    and re-registering an already-registered email is a silent no-op, so a user who lost the first
    mail had no way back. Uniform response + timing regardless of whether the email has a pending
    account (the lookup runs off the response path), so it can't probe for registered emails."""
-    if not _verify_resend_limiter.allow(_client_ip(request)):
+    if not _verify_resend_limiter.allow(client_key(request)):
        return {"status": "ok"}  # silently throttle; uniform response
    email = (body.email or "").strip().lower()
    if valid_email(email):
@@ -1062,7 +1055,7 @@ def password_login(
    """Email+password sign-in. Wrong email/password give a single uniform 401 (no enumeration).
    Once the password is proven correct, the owner gets a specific reason if their account is
    still pending or suspended — that's not an enumeration leak (they already hold the password)."""
-    if not _login_limiter.allow(_client_ip(request)):
+    if not _login_limiter.allow(client_key(request)):
        raise _login_refused(429, "rate_limited")
    email = (body.email or "").strip().lower()
    password = body.password or ""
@@ -1081,7 +1074,11 @@ def password_login(
    if not user.is_active:
        raise _login_refused(403, "pending_approval", user)
    _establish_session(request, user)
-    log.info("Password login: %s (id=%s, role=%s)", email, user.id, user.role)
+    db.commit()
    log.info(
        "signed in",
        extra=logs.event("auth.login.ok", method="password", uid=user.id, role=user.role),
    )
    return {"ok": True}
@@ -1093,7 +1090,7 @@ def password_reset_request(
 ) -> dict:
    """Request a password-reset link. Uniform response + timing regardless of whether the email has a
    password account (the lookup runs off the response path), so it can't probe for registered emails."""
-    if not _reset_limiter.allow(_client_ip(request)):
+    if not _reset_limiter.allow(client_key(request)):
        return {"status": "ok"}
    email = (body.email or "").strip().lower()
    # Do the account lookup + token issue + email OFF the response path (a background task with its
@@ -1142,7 +1139,7 @@ def password_reset_check(body: TokenIn, request: Request, db: Session = Depends(
    told `true`, never `false`: this check may only ever save a user a wasted form, so when it cannot
    answer it must degrade to the old behaviour instead of declaring a live link dead.
    """
-    if not _reset_check_limiter.allow(_client_ip(request)):
+    if not _reset_check_limiter.allow(client_key(request)):
        return {"ok": True}
    return {"ok": any(_peek_token(db, body.token, k) is not None for k in _PASSWORD_TOKEN_KINDS)}
@@ -1246,7 +1243,7 @@ def logout_others(
    are rejected, then re-stamp THIS cookie so the caller stays signed in. For "I left myself logged
    in somewhere" / a suspected session compromise. The demo account (shared) is excluded."""
    if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        raise HTTPException(status_code=403, detail={"code": "demo"})
    # Commit the bump BEFORE re-stamping this cookie, so a failed commit can't strand the current
    # session at a newer epoch than the DB (see set_password).
    bump_session_epoch(user)
@@ -1293,7 +1290,7 @@ def set_password(
    account) needs no current password — the session already proves identity. Changing an
    existing one requires the current password, so a hijacked session can't silently rotate it."""
    if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        raise HTTPException(status_code=403, detail={"code": "demo"})
    new_password = body.password or ""
    if len(new_password) < PASSWORD_MIN_LEN:
        raise HTTPException(
@@ -2,7 +2,6 @@
 hidden, tags) and per-channel sync state. Local reads/writes plus YouTube-side writes
 (subscribe / unsubscribe) that require the optional write scope."""
 import logging
 from datetime import datetime, timezone
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
@@ -10,7 +9,7 @@ from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
-from app import quota
+from app import logs, quota
 from app.auth import admin_user, current_user, require_human, require_write_scope
 from app.db import get_db
 from app.models import (
@@ -26,7 +25,7 @@ from app.models import (
    User,
    Video,
 )
-from app.routes._common import owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
@@ -35,7 +34,7 @@ from app.youtube.client import YouTubeClient, YouTubeError
 router = APIRouter(prefix="/api/channels", tags=["channels"])
-log = logging.getLogger("siftlode.api")
+log = logs.get_logger(__name__)
@router.get("")
@@ -166,7 +165,15 @@ def discover_channels(
                user.yt_channel_id = own
                db.commit()
        except YouTubeError as exc:
-            log.warning("discovery: own-channel resolve failed (user %s): %s", user.id, exc)
+            # No traceback anywhere in this file's YouTube handlers: for an upstream answer
            # `_upstream_failure` already logged the structured `youtube.api.error`, and the
            # message names the call, its status and its reason (or, with no answer at all, the
            # transport failure). The stack under it is this `except` and the client call.
            log.warning(
                "discovery: own-channel resolve failed: %s",
                exc,
                extra=logs.event("channels.discovery.own_channel_failed", reason=exc.reason),
            )
    rows = _discovery_rows(db, user)
@@ -190,7 +197,11 @@ def discover_channels(
                rows, key=lambda r: (-int(r[1]), r[0].title is None, (r[0].title or "").lower())
            )
        except YouTubeError as exc:
-            log.warning("discovery: channel enrich failed (user %s): %s", user.id, exc)
+            log.warning(
                "discovery: channel enrich failed: %s",
                exc,
                extra=logs.event("channels.discovery.enrich_failed", reason=exc.reason),
            )
            db.rollback()
    return [
@@ -287,9 +298,7 @@ def channel_detail(
    needed — a stub, or a channel last enriched before those fields existed (published_at is a
    reliable sentinel: every real channel has a creation date). The enrich uses the API key
    (1 unit, cached after), so it's skipped for the quota-less demo account."""
-    channel = db.get(Channel, channel_id)
+    channel = get_or_404(db, Channel, channel_id, what="channel")
    if channel is None:
        raise HTTPException(status_code=404, detail="Unknown channel")
    if channel.published_at is None and not user.is_demo:
        try:
            with (
@@ -300,7 +309,13 @@ def channel_detail(
            db.commit()
            channel = db.get(Channel, channel_id)
        except YouTubeError as exc:
-            log.warning("channel detail enrich failed (%s): %s", channel_id, exc)
+            log.warning(
                "channel detail enrich failed: %s",
                exc,
                extra=logs.event(
                    "channels.detail.enrich_failed", channel_id=channel_id, reason=exc.reason
                ),
            )
            db.rollback()
    sub = db.execute(
        select(Subscription).where(
@@ -366,9 +381,7 @@ def explore_channel(
    it, then ingests one page of its uploads (newest-first) marked via_explore + enriched.
    Returns the next page token so the page can "load more". Guarded against the shared
    backfill quota reserve; blocked for the demo account (it spends shared quota)."""
-    channel = db.get(Channel, channel_id)
+    channel = get_or_404(db, Channel, channel_id, what="channel")
    if channel is None:
        raise HTTPException(status_code=404, detail="Unknown channel")
    if _is_blocked(db, user, channel_id):
        raise HTTPException(status_code=403, detail="You've blocked this channel.")
    if quota.backfill_reserve_reached():
@@ -426,7 +439,7 @@ def _user_subscription(db: Session, user: User, channel_id: str) -> Subscription
        )
    ).scalar_one_or_none()
    if sub is None:
-        raise HTTPException(status_code=404, detail="Not subscribed to this channel")
+        raise not_found("subscription")
    return sub
@@ -512,9 +525,7 @@ def reset_backfill(
    state (a "reset" trigger). Clears the channel's backfill markers, opts it back into deep
    backfill, and re-runs its recent pull immediately; the deep scheduler re-pages the full
    back-catalog on its next run. Idempotent — videos upsert by id, so nothing duplicates."""
-    channel = db.get(Channel, channel_id)
+    channel = get_or_404(db, Channel, channel_id, what="channel")
    if channel is None:
        raise HTTPException(status_code=404, detail="Unknown channel")
    channel.backfill_done = False
    channel.backfill_cursor = None
    channel.recent_synced_at = None
@@ -544,9 +555,7 @@ def subscribe(
    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)
+    channel = get_or_404(db, Channel, channel_id, what="channel")
    if channel is None:
        raise HTTPException(status_code=404, detail="Unknown channel")
    existing = db.execute(
        select(Subscription).where(
            Subscription.user_id == user.id, Subscription.channel_id == channel_id
@@ -567,8 +576,11 @@ def subscribe(
            # subscription resync fills in the resource id. Any other YouTube error is a real
            # problem — surface it with a clear message (422, not a 502 that the client would
            # mistake for a transient "connection lost").
-            msg = str(exc).lower()
+            # On the reason code, never on the prose: the error no longer carries the body (it is
-            if "already exists" in msg or "duplicate" in msg:
+            # the request quoted back), and a message YouTube rewords would silently turn "already
            # following" back into a 422 the user cannot act on. `reason` is comma-joined when the
            # body listed several.
            if "subscriptionDuplicate" in exc.reason.split(","):
                yt_sub_id = ""
            else:
                raise HTTPException(
@@ -582,7 +594,15 @@ def subscribe(
            try:
                apply_channel_details(db, yt.get_channels([channel_id]))
            except YouTubeError as exc:
-                log.warning("subscribe: stub enrich failed (%s): %s", channel_id, exc)
+                log.warning(
                    "subscribe: stub enrich failed: %s",
                    exc,
                    extra=logs.event(
                        "channels.subscribe.enrich_failed",
                        channel_id=channel_id,
                        reason=exc.reason,
                    ),
                )
    db.add(
        Subscription(
            user_id=user.id,
@@ -663,8 +683,7 @@ def block_channel(
    """Block a channel for this user: its videos won't appear in their live search (and won't be
    ingested for them) and are hidden from their feed / explore. Idempotent. The now-hidden
    un-kept search/explore videos are reclaimed by the discovery-cleanup job in due course."""
-    if db.get(Channel, channel_id) is None:
+    get_or_404(db, Channel, channel_id, what="channel")
        raise HTTPException(status_code=404, detail="Unknown channel")
    if not _is_blocked(db, user, channel_id):
        db.add(BlockedChannel(user_id=user.id, channel_id=channel_id))
        # Stop any active exploration of it so it can be cleaned up.
@@ -706,7 +725,7 @@ def attach_tag(
    _user_subscription(db, user, channel_id)
    # 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")
+    owned_or_404(db, Tag, body.tag_id, user, what="tag")
    exists = db.execute(
        select(ChannelTag).where(
            ChannelTag.channel_id == channel_id,
@@ -10,6 +10,7 @@ from sqlalchemy.orm import Session
 from app import audit
 from app import email as email_mod
 from app import logs
 from app import mailtext
 from app import sysconfig
 from app.audit import AuditAction
@@ -29,6 +30,14 @@ def _redact(v):
    return _URL_USERINFO.sub(r"\1***@", v) if isinstance(v, str) else v
 def _apply_runtime(db: Session, key: str) -> None:
    """Some knobs change how THIS process behaves, not just what a later read returns — they have to
    take effect now, without a restart. One dispatch for both call sites (set and reset), so the next
    such key can't be wired into one of them and forgotten in the other."""
    if key == "log_level":
        logs.set_level(sysconfig.get_str(db, "log_level"))
@router.get("")
 def get_config(_: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
    return sysconfig.describe(db)
@@ -80,6 +89,7 @@ def set_config(
            after=None if s.secret else {"value": _redact(new)},
        )
        db.commit()
    _apply_runtime(db, key)
    return sysconfig.describe(db)
@@ -104,6 +114,7 @@ def reset_config(
        before=None if s.secret else {"value": _redact(old)},
    )
    db.commit()
    _apply_runtime(db, key)
    return sysconfig.describe(db)
@@ -0,0 +1,179 @@
 """The browser's log, sent while its user has a raised diagnostics level (E22 S5).
 The client keeps its log in memory (frontend `lib/log.ts`). Only after the user consented to Részletes
 or Teljes in Settings → Diagnosztika does it stream that log here, in batches, and each batch lands in
 `log_events` beside the server's own rows: `source="web"`, the account from the SESSION (never from
 the body), and the request id each event carries, which is what joins a browser line to the server
 line of the same request.
 Nothing from the body is trusted as-is:
  * only a JSON Content-Type is read, and the whole body is capped before it is parsed, and so are
    the number of events and each event's attributes;
  * the pace is capped per account, and so is what an account may store per hour;
  * everything is redacted AGAIN with the server's own rules — the client redacts at capture, but a
    modified client would not;
  * an event below the consented level is dropped (a Részletes consent does not store what only
    Teljes may carry), and so is the whole batch once the level has lapsed;
  * the timestamp is clamped to the consent window, so a row cannot dodge the retention job by
    claiming to come from the future.
 """
 import json
 from datetime import datetime, timedelta, timezone
 from typing import Any, Literal
 from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel, Field, ValidationError
 from sqlalchemy import insert
 from sqlalchemy.orm import Session
 from app import diagnostics, logs, logsink
 from app.auth import current_user
 from app.db import get_db
 from app.models import LogEvent, User
 from app.ratelimit import RateLimiter
 router = APIRouter(prefix="/api/diagnostics", tags=["diagnostics"])
 BODY_MAX_BYTES = 512 * 1024
 EVENTS_MAX = 200
 ATTRS_MAX_BYTES = 16 * 1024
 # The client flushes every few seconds and when its buffer fills; this is room for a burst, not a
 # pace anything legitimate keeps up for a minute.
 _batches = RateLimiter(max_events=30, window_seconds=60)
 # What one account may STORE per hour. The pace cap alone still lets a self-consented account write
 # ~15 MiB a minute into the one shared database, kept for the whole retention window; a real session
 # at Teljes stores a few hundred kB an hour. Past the budget a batch is accepted and not stored (a
 # refusal would only make the client resend it), and one notice per hour says so.
 STORED_BYTES_PER_HOUR = 5 * 1024 * 1024
 _stored_bytes = RateLimiter(max_events=STORED_BYTES_PER_HOUR, window_seconds=3600)
 _budget_notices = RateLimiter(max_events=1, window_seconds=3600)
 ClientLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 class ClientEvent(BaseModel):
    ts: datetime
    level: ClientLevel
    event: str = Field(max_length=64, pattern=r"^[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$")
    msg: str = Field(max_length=8_000)
    attrs: dict[str, Any] | None = None
    request_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9._-]{8,64}$")
    tab_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{1,32}$")
    version: str | None = Field(default=None, max_length=64)
 class ClientEventsIn(BaseModel):
    events: list[ClientEvent] = Field(max_length=EVENTS_MAX)
 async def _capped_body(request: Request) -> bytes:
    """The request body, refused the moment it passes BODY_MAX_BYTES while still arriving. Counted,
    not taken from Content-Length: a declared length can be absent (chunked) or wrong, and counting
    stops reading at the same point a declared-length check would have."""
    body = bytearray()
    async for chunk in request.stream():
        body += chunk
        if len(body) > BODY_MAX_BYTES:
            raise HTTPException(status_code=413, detail={"code": "too_large"})
    return bytes(body)
 async def _parsed_events(request: Request) -> ClientEventsIn:
    """The body as the model — parsed only after the size cap, which is why this is a dependency and
    not a plain body parameter (FastAPI reads a declared body in full before anything else runs).
    JSON only, by its Content-Type, as a declared body would be. Parsing any body as JSON would let a
    CORS-simple `text/plain` form post from a same-site page write events into a signed-in user's
    log; the app's own client always sends `application/json`, the unload beacon included."""
    media_type = request.headers.get("content-type", "").split(";")[0].strip().lower()
    if media_type != "application/json" and not media_type.endswith("+json"):
        raise HTTPException(status_code=415, detail={"code": "json_required"})
    raw = await _capped_body(request)
    try:
        return ClientEventsIn.model_validate_json(raw)
    except ValidationError as exc:
        raise HTTPException(status_code=422, detail=json.loads(exc.json())) from exc
 def _row(item: ClientEvent, user: User, now: datetime, window_start: datetime) -> dict[str, Any]:
    attrs = logs.redact(item.attrs) if item.attrs else None
    if attrs is not None:
        size = len(json.dumps(attrs, ensure_ascii=False, default=str).encode())
        if size > ATTRS_MAX_BYTES:
            attrs = {"attrs_dropped_bytes": size}
    if item.tab_id:
        attrs = {**(attrs or {}), "tab_id": item.tab_id}
    ts = item.ts if item.ts.tzinfo else item.ts.replace(tzinfo=timezone.utc)
    return logsink.to_row(
        {
            "ts": min(max(ts, window_start), now),
            "level": item.level,
            "sev": logs.SEVERITY[item.level],
            "source": "web",
            "logger": "web",
            "event": item.event,
            "msg": logs.redact_text(item.msg),
            "attrs": attrs,
            "request_id": item.request_id,
            "user_id": user.id,
            "version": item.version,
        }
    )
@router.post("/events")
 def ingest_events(
    # The account first: dependencies resolve in order, so an anonymous caller is refused before a
    # byte of its body is read.
    user: User = Depends(current_user),
    body: ClientEventsIn = Depends(_parsed_events),
    db: Session = Depends(get_db),
 ) -> dict:
    level = diagnostics.effective_level(user)
    if level == diagnostics.BASE:
        # Lapsed or withdrawn: the client stops streaming when it sees this.
        raise HTTPException(status_code=409, detail={"code": "diagnostics_off"})
    if not _batches.allow(str(user.id)):
        raise HTTPException(status_code=429, detail={"code": "rate_limited"})
    now = datetime.now(timezone.utc)
    window_start = now - timedelta(hours=diagnostics.ELEVATION_HOURS)
    floor = logs.SEVERITY[level]
    rows = [
        _row(item, user, now, window_start)
        for item in body.events
        if logs.SEVERITY[item.level] >= floor
    ]
    if not rows:
        return {"ok": True, "stored": 0}
    size = sum(len(json.dumps(row, ensure_ascii=False, default=str).encode()) for row in rows)
    stored = len(rows)
    if not _stored_bytes.allow(str(user.id), size):
        stored = 0
        if not _budget_notices.allow(str(user.id)):
            return {"ok": True, "stored": 0}
        rows = [_budget_notice(user, now)]
    # Under the erasure guard until the commit: an account erased meanwhile gets no rows back.
    with logs.erasure_guard():
        db.execute(insert(LogEvent), logsink.without_erased(rows))
        db.commit()
    return {"ok": True, "stored": stored}
 def _budget_notice(user: User, now: datetime) -> dict[str, Any]:
    return logsink.to_row(
        {
            "ts": now,
            "level": "WARNING",
            "sev": logs.SEVERITY["WARNING"],
            "source": "web",
            "logger": "web",
            "event": "diagnostics.budget_spent",
            # What the budget does, exactly: it is a SLIDING hour, and a refused batch is not
            # charged to it, so smaller batches keep landing while there is room for them. Saying
            # "the rest of the hour is not kept" would be a row contradicting the rows beneath it.
            "msg": "The browser log passed its hourly storage budget; a batch bigger than what is left of it is not kept",
            "attrs": {"budget_bytes": STORED_BYTES_PER_HOUR},
            "user_id": user.id,
        }
    )
@@ -168,7 +168,7 @@ def remove_pin(
    user: User = Depends(require_human),
    db: Session = Depends(get_db),
 ) -> dict:
-    pin = owned_or_404(db, ComfortPin, pin_id, user)
+    pin = owned_or_404(db, ComfortPin, pin_id, user, what="pin")
    db.delete(pin)
    db.commit()
    return {"deleted": pin_id}
@@ -38,6 +38,7 @@ from app.models import (
    MediaAsset,
    User,
 )
 from app.routes._common import get_or_404, not_found
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
@@ -106,6 +107,7 @@ def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
        "phase": job.phase,
        "error": job.error,
        "error_code": job.error_code,
        "error_detail": job.error_detail,
        "queue_pos": job.queue_pos,
        "created_at": iso(job.created_at),
        "source_kind": job.source_kind,
@@ -171,6 +173,32 @@ def _own_job(db: Session, user: User, job_id: int) -> DownloadJob:
    return job
 def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
    """`_own_job` for a transition that moves its asset's ref count (resume, cancel, delete, redownload)
    or writes the status those decide on (pause). The job is re-read under a row lock, so two
    overlapping requests for one job run one after the other and the second decides on the first's
    committed result — never both releasing the same hold, and never a pause turning a job a cancel
    just released back into a holder; either can free a file another job still holds.
    The asset is locked BEFORE the job: the order a finishing worker child takes them in
    (`service.finalize_if_running`), so the two can never deadlock."""
    while True:
        asset_id = _own_job(db, user, job_id).asset_id
        if asset_id is not None:
            db.execute(select(MediaAsset.id).where(MediaAsset.id == asset_id).with_for_update())
        job = db.execute(
            select(DownloadJob)
            .where(DownloadJob.id == job_id)
            .with_for_update()
            .execution_options(populate_existing=True)
        ).scalar_one_or_none()
        if job is None:
            raise HTTPException(status_code=404, detail="Unknown download")
        if job.asset_id == asset_id:
            return job
        db.rollback()  # another request moved the job to another asset meanwhile: lock that one
 # --- profiles ------------------------------------------------------------------------------
@@ -559,6 +587,8 @@ def _clean_url(raw) -> str | None:
    # authority. This one already has a "not a plausible URL" answer, so the typo belongs in it.
    try:
        parsed = urlparse(url)
    # silent-ok: a typo in a link someone pasted. None is this function's "not a plausible URL"
    # answer, the caller already has one, and any line here would carry the URL itself.
    except ValueError:
        return None
    if not parsed.netloc:
@@ -604,7 +634,7 @@ def update_download_meta(
 def pause_download(
    job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = _own_job_for_update(db, user, job_id)
    service.pause(db, job)
    return _serialize_job(db, job)
@@ -613,7 +643,7 @@ def pause_download(
 def resume_download(
    job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = _own_job_for_update(db, user, job_id)
    service.resume(db, job)
    return _serialize_job(db, job)
@@ -628,12 +658,13 @@ def redownload_download(
    resolves to the newly-downloaded file — a re-download never breaks a link you already sent out
    (only a *failed* re-download leaves the job in `error`, which is the intended broken-link case).
-    The rebuild always re-fetches into a FRESH, private asset (the cache sig is salted with the job
+    The rebuild always re-fetches into a FRESH, private asset (the cache sig is salted with the new
-    id + current asset id) rather than the dedup pool. That means it (a) always genuinely rebuilds
+    asset's own id, and the user's cookie salt when one applies — `credentials.rebuild_salt`) rather
    than the dedup pool. That means it (a) always genuinely rebuilds
    under the current format/naming rules — never silently reuses a shared cached file — and (b)
    never deletes a file another job/user still shares: the old asset is only removed if THIS job
    was its last holder."""
-    job = _own_job(db, user, job_id)
+    job = _own_job_for_update(db, user, job_id)
    if job.job_kind in ("edit", "upload"):
        # Neither has a re-fetchable source: an editor clip is derived locally, an upload IS the
        # source. Re-running yt-dlp against source_kind='upload'/'edit' would just fail.
@@ -648,7 +679,7 @@ def redownload_download(
 def cancel_download(
    job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = _own_job_for_update(db, user, job_id)
    service.cancel(db, job)
    return _serialize_job(db, job)
@@ -657,7 +688,7 @@ def cancel_download(
 def delete_download(
    job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = _own_job_for_update(db, user, job_id)
    service.delete(db, job)
    return {"deleted": job_id}
@@ -801,7 +832,7 @@ def share_download(
    # Uniform "no user" for a missing OR non-messageable (demo/suspended/deactivated) target, so
    # sharing can't be used to probe which addresses exist or to reach a suspended account.
    if not is_messageable_user(recipient):
-        raise HTTPException(status_code=404, detail="No user with that email.")
+        raise not_found("recipient")
    if recipient.id == user.id:
        raise HTTPException(status_code=400, detail="That's already your download.")
    exists = db.execute(
@@ -1091,8 +1122,7 @@ def admin_set_quota(
    admin: User = Depends(admin_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    if db.get(User, user_id) is None:
+    get_or_404(db, User, user_id, what="user")
        raise HTTPException(status_code=404, detail="Unknown user")
    cur = quota.resolve(db, user_id)
    row = db.get(DownloadQuota, user_id)
    if row is None:
@@ -1,7 +1,7 @@
 from datetime import date, datetime, timezone
 from fastapi import APIRouter, Depends, HTTPException, Query
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
@@ -22,12 +22,14 @@ from app.feedquery import (
    sort_keys,
 )
 from app.models import (
    POSITION_MAX_S,
    ChannelTag,
    Tag,
    User,
    Video,
    VideoState,
 )
 from app.routes._common import get_or_404
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
@@ -234,8 +236,7 @@ def set_video_state(
    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:
+    get_or_404(db, Video, video_id, what="video")
        raise HTTPException(status_code=404, detail="Unknown video")
    now = datetime.now(timezone.utc)
@@ -255,6 +256,8 @@ def set_video_state(
                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()
        return {"video_id": video_id, "status": "new"}
@@ -297,17 +300,23 @@ def clear_video_state(
        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()
    return {"video_id": video_id, "status": "new", "position_seconds": 0}
 class VideoProgressIn(BaseModel):
    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
    # one into a 500.
    model_config = ConfigDict(allow_inf_nan=False)
    # 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
+    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
-    duration_seconds: float = 0
+    position_seconds: float = Field(0, le=POSITION_MAX_S)
    duration_seconds: float = Field(0, le=POSITION_MAX_S)
@router.post("/videos/{video_id}/progress")
@@ -326,8 +335,7 @@ def set_video_progress(
    if position < 0:
        position = 0
-    if db.get(Video, video_id) is None:
+    get_or_404(db, Video, video_id, what="video")
        raise HTTPException(status_code=404, detail="Unknown video")
    # Decide whether this position is worth keeping (else clear it).
    near_end = duration > 0 and position > duration - FINISH_MARGIN_SECONDS
@@ -350,6 +358,7 @@ def set_video_progress(
            # 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()
        return {"video_id": video_id, "position_seconds": 0}
@@ -1,5 +1,7 @@
 from typing import Any
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
@@ -7,6 +9,7 @@ from app.auth import (
    count_admins,
    count_pending_activations,
    current_user,
    drop_from_wallet,
    google_enabled,
    has_read_scope,
    has_write_scope,
@@ -14,7 +17,9 @@ from app.auth import (
    optional_current_user,
    purge_user,
 )
 from app import diagnostics
 from app import email as email_mod
 from app import logs
 from app import sysconfig
 from app.db import get_db
 from app.models import Invite, User
@@ -65,24 +70,26 @@ def switch_account(
    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.")
    # An account `_session_user` would refuse — gone, deactivated, suspended, or its session revoked — is
    # refused here too, and dropped from the switch list the way `_session_user` drops it. Made the session
    # default instead, the next request's current_user would refuse it as the DEFAULT and clear the whole
    # wallet session, logging out every account here. (B-core-9)
    u = db.get(User, target)
    if u is None:
        drop_from_wallet(request.session, target)
        raise HTTPException(status_code=404, detail="That account no longer exists.")
    if not is_allowed(db, u.email):
        raise HTTPException(status_code=403, detail="That account no longer has access.")
    if not u.is_active:
        drop_from_wallet(request.session, target)
        raise HTTPException(status_code=403, detail="That account no longer has access.")
    if u.is_suspended:
-        # Don't make a suspended account the active one — the next request's current_user would
+        drop_from_wallet(request.session, target)
        # see the suspension and clear the WHOLE wallet session, logging out every account here.
        raise HTTPException(status_code=403, detail="That account is suspended.")
-    # Same reasoning for a REVOKED session (a password reset/change or "log out everywhere" bumped the
+    # Revoked: a password reset/change or "log out everywhere" bumped the account's epoch.
    # account's epoch): making it the session default would trip current_user's epoch check on the next
    # request and clear the whole wallet. Mirror the suspend guard — drop the stale account from the
    # switch list and refuse, rather than logging everyone out. (B-core-9)
    epochs = request.session.get("epochs") or {}
    if int(epochs.get(str(target), 0)) != (u.session_epoch or 0):
-        request.session["account_ids"] = [
+        drop_from_wallet(request.session, target)
            a for a in (request.session.get("account_ids") or []) if a != target
        ]
        raise HTTPException(
            status_code=403, detail="That account was signed out elsewhere — sign in again."
        )
@@ -144,6 +151,9 @@ def get_me(
        "pending_activations": pending_activations,
        "email_configured": email_configured,
        "preferences": user.preferences or {},
        # The consented diagnostics level in force and when it lapses (E22 S5). The client applies
        # it to its own log and streams that log while it is raised.
        "diagnostics": diagnostics.state(db, user),
    }
@@ -159,8 +169,13 @@ def delete_my_account(
    which all cascade on the users row. Quota-audit events are kept but anonymised (FK SET NULL).
    The shared demo account can't be deleted, and the last remaining admin can't delete itself
    (that would lock everyone out of the admin surfaces)."""
    # Structured, like the other three demo refusals: `req` leaves 403 to the caller and
    # `notifyActionError` discards a plain-string detail in favour of the caller's translated
    # fallback, so a hand-written English sentence here reaches a Hungarian UI as a generic
    # "couldn't do that" — or, on this affordance, as nothing at all. `reason` distinguishes it
    # from the other sites' bare `{code: "demo"}` so the UI can say what specifically is refused.
    if user.is_demo:
-        raise HTTPException(status_code=403, detail="The shared demo account can't be deleted.")
+        raise HTTPException(status_code=403, detail={"code": "demo", "reason": "delete_account"})
    if user.role == "admin" and count_admins(db) <= 1:
        raise HTTPException(
            status_code=400,
@@ -180,16 +195,45 @@ def delete_my_account(
    return {"deleted": True}
 class PreferencesIn(RootModel[dict[str, Any]]):
    """Free-form UI preferences — a JSON object of any keys (theme, filters, …), merged into the
    stored ones. A model rather than a bare `dict` parameter so a non-object body is a 422 at the
    boundary like every other request body."""
@router.put("/preferences")
 def update_preferences(
-    preferences: dict,
+    preferences: PreferencesIn,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
    # Merge so partial updates don't wipe other keys.
    merged = dict(user.preferences or {})
-    merged.update(preferences)
+    merged.update(preferences.root)
    user.preferences = merged
    db.add(user)
    db.commit()
    return {"preferences": merged}
 class DiagnosticsIn(BaseModel):
    level: diagnostics.DiagnosticsLevel
@router.put("/diagnostics")
 def update_diagnostics(
    body: DiagnosticsIn,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
    """Raise the diagnostics level (the user consented in Settings → Diagnosztika) or return to the
    base. The expiry is the server's: a raised level always lapses after
    `diagnostics.ELEVATION_HOURS`, whatever the client asks. The shared demo account cannot raise
    it — its log would interleave every visitor's session under one account."""
    if user.is_demo and body.level != diagnostics.BASE:
        raise HTTPException(status_code=403, detail={"code": "demo", "reason": "diagnostics"})
    diagnostics.set_level(user, body.level)
    db.commit()
    # The rest of THIS request, and the process's elevation registry, follow the new level now.
    logs.set_user(user.id, diagnostics.effective_level(user), user.diagnostics_until)
    return {"ok": True, "diagnostics": diagnostics.state(db, user)}
@@ -46,7 +46,7 @@ WELCOME = {
        "This is your private message inbox. Conversations with other members are end-to-end "
        "encrypted — only you and the person you're chatting with can read them, not even an "
        "admin. To start messaging someone, set up secure messaging with a passphrase first.\n\n"
-        "Enjoy your feed!"
+        "Enjoy your Feed!"
    ),
    "hu": (
        "Üdv a Siftlode-on! 👋\n\n"
@@ -423,9 +423,10 @@ async def messages_ws(ws: WebSocket) -> None:
    """Live push channel: authenticated by the session cookie, registers the connection so
    sent messages reach this user's open tabs instantly. We don't consume client→server frames
    (sending goes through POST /api/messages); the receive loop only detects disconnect."""
-    # Which signed-in account this socket acts as — the SHARED per-tab resolution (wallet-gated
+    # Which signed-in account this socket acts as — the SHARED per-tab resolution (a wallet-gated
-    # ?account= override, session default otherwise). A browser WebSocket can't send the
+    # ?account=, the session default when none is named, nobody for an account no longer signed in
-    # X-Siftlode-Account header, so resolved_user_id falls through to the ?account= query param.
+    # here). A browser WebSocket can't send the X-Siftlode-Account header, so resolved_user_id falls
    # through to the ?account= query param.
    uid, _ = resolved_user_id(ws)
    if not uid:
        await ws.close(code=1008)
@@ -448,6 +449,8 @@ async def messages_ws(ws: WebSocket) -> None:
    try:
        while True:
            await ws.receive_text()
    # silent-ok: the ordinary way a chat socket ends — a closed tab. The `finally` below is the
    # whole handling, and nothing failed.
    except WebSocketDisconnect:
        pass
    finally:
@@ -23,6 +23,7 @@ from app.sync.playlists import (
    sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
 from app.routes._common import get_or_404, owned_or_404
 from app.youtube.client import YouTubeClient, YouTubeError
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -48,10 +49,13 @@ def _check_pull_cooldown(user: User) -> None:
 def _own_playlist(db: Session, user: User, playlist_id: int) -> Playlist:
-    pl = db.get(Playlist, playlist_id)
+    return owned_or_404(db, Playlist, playlist_id, user, what="playlist")
-    if pl is None or pl.user_id != user.id:
+
-        raise HTTPException(status_code=404, detail="Unknown playlist")
+
-    return pl
+def _refused(status: int, reason: str) -> HTTPException:
    """A playlist action the server refuses, as a reason the UI translates
    (`playlists.errors.<reason>`) — a bare English detail reached the Hungarian UI verbatim."""
    return HTTPException(status_code=status, detail={"code": "playlist", "reason": reason})
 def _touch(pl: Playlist) -> None:
@@ -256,7 +260,7 @@ def create_playlist(
 ) -> dict:
    name = body.name.strip()
    if not name:
-        raise HTTPException(status_code=400, detail="name is required")
+        raise _refused(400, "name_required")
    pl = Playlist(user_id=user.id, name=name, position=_next_playlist_position(db, user.id))
    db.add(pl)
    db.commit()
@@ -288,8 +292,7 @@ def add_watch_later(
 ) -> dict:
    """Bookmark shortcut: add a video to the built-in Watch later playlist."""
    video_id = body.video_id
-    if db.get(Video, video_id) is None:
+    get_or_404(db, Video, video_id, what="video")
        raise HTTPException(status_code=404, detail="Unknown video")
    pl = _watch_later(db, user)
    _add_item(db, pl, video_id, mark_dirty=False)
    return {"saved": True, "playlist_id": pl.id}
@@ -317,10 +320,7 @@ def sync_youtube(
    """Pull the user's YouTube playlists into local mirrors now (read-only direction).
    Also runs automatically on the scheduler; this is the manual 'sync now'."""
    if not has_read_scope(user):
-        raise HTTPException(
+        raise _refused(403, "youtube_read_scope")
            status_code=403,
            detail="Connect YouTube (read access) to sync your playlists.",
        )
    _check_pull_cooldown(user)
    with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
        return sync_user_playlists(db, user)
@@ -337,18 +337,16 @@ def revert_youtube(
    once the in-session undo history is gone."""
    pl = _own_playlist(db, user, playlist_id)
    if not pl.yt_playlist_id:
-        raise HTTPException(status_code=400, detail="This playlist isn't linked to YouTube.")
+        raise _refused(400, "not_on_youtube")
    if not has_read_scope(user):
-        raise HTTPException(
+        raise _refused(403, "youtube_read_scope")
            status_code=403, detail="Connect YouTube (read access) to sync your playlists."
        )
    _check_pull_cooldown(user)
    try:
        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
            return repull_playlist(db, user, pl)
    except YouTubeError:
        db.rollback()
-        raise HTTPException(status_code=422, detail="Couldn't refresh from YouTube.")
+        raise _refused(422, "youtube_failed")
 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
@@ -356,9 +354,7 @@ def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
    Watch later and read-only YouTube mirrors are never pushable."""
    pl = _own_playlist(db, user, playlist_id)
    if pl.kind == "watch_later":
-        raise HTTPException(
+        raise _refused(400, "watch_later_not_pushable")
            status_code=400, detail="The Watch later list can't be sent to YouTube."
        )
    return pl
@@ -376,7 +372,7 @@ def push_plan(
        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
            plan = plan_merge(db, user, pl)
    except YouTubeError:
-        raise HTTPException(status_code=422, detail="Couldn't read the playlist on YouTube.")
+        raise _refused(422, "youtube_failed")
    plan["remaining_today"] = quota.remaining_today(db)
    plan["affordable"] = plan["units_estimate"] <= plan["remaining_today"]
    return plan
@@ -406,14 +402,11 @@ def push(
                    )
            plan = plan_merge(db, user, pl, live=live)
            if plan["units_estimate"] > quota.remaining_today(db):
-                raise HTTPException(
+                raise _refused(429, "quota_exceeded")
                    status_code=429,
                    detail="Not enough YouTube quota left today for this sync.",
                )
            return merge_playlist(db, user, pl, live=live)
    except YouTubeError:
        db.rollback()
-        raise HTTPException(status_code=422, detail="YouTube playlist sync failed.")
+        raise _refused(422, "youtube_failed")
@router.get("/{playlist_id}")
@@ -458,7 +451,7 @@ def rename_playlist(
    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")
+            raise _refused(400, "name_required")
        if name != pl.name:
            pl.name = name
            recompute_dirty(db, pl)
@@ -493,18 +486,18 @@ def delete_playlist(
 ) -> dict:
    pl = _own_playlist(db, user, playlist_id)
    if pl.kind == "watch_later":
-        raise HTTPException(status_code=400, detail="The Watch later list can't be deleted.")
+        raise _refused(400, "watch_later_undeletable")
    if on_youtube:
        if not pl.yt_playlist_id:
-            raise HTTPException(status_code=400, detail="This playlist isn't on YouTube.")
+            raise _refused(400, "not_on_youtube")
        if not has_write_scope(user):
-            raise HTTPException(status_code=403, detail="Enable YouTube editing in Settings first.")
+            raise _refused(403, "youtube_editing_off")
        try:
            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
                with YouTubeClient(db, user) as yt:
                    yt.delete_playlist(pl.yt_playlist_id)
        except YouTubeError:
-            raise HTTPException(status_code=422, detail="YouTube delete failed.")
+            raise _refused(422, "youtube_failed")
    db.delete(pl)  # items cascade
    db.commit()
    return {"deleted": playlist_id}
@@ -519,8 +512,7 @@ def add_item(
 ) -> dict:
    pl = _own_playlist(db, user, playlist_id)
    video_id = body.video_id
-    if db.get(Video, video_id) is None:
+    get_or_404(db, Video, video_id, what="video")
        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}
@@ -557,7 +549,9 @@ def move_item(
    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 = _own_playlist(db, user, playlist_id)
-    dst = _own_playlist(db, user, body.target_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:
        raise HTTPException(
            status_code=400, detail={"code": "playlist_move", "reason": "same_playlist"}
@@ -1,14 +1,13 @@
 """Shared helpers, serializers and constants for the plex route package."""
 import logging
 from fastapi import HTTPException
 from sqlalchemy.orm import Session
 from app import logs
 from app.models import PlexItem
 from app.plex.lookups import by_rating_key
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 def item_or_404(db: Session, rating_key: str) -> PlexItem:
@@ -54,6 +54,22 @@ from app.utils import to_tsquery_str
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 def sort_column(u, sort: str):
    """The browse grid's sort key -> orderable column on the union subquery. Module-level (not inline
    in the handler) so a test can pin its vocabulary to `PLEX_SORT_KEYS` — a key the Sort control
    offers but this cannot order would quietly fall back to `added_at` and look like a broken control.
    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback."""
    return {
        "added": u.c.added_at,
        "title": func.lower(u.c.title),
        "year": u.c.year,
        "rating": u.c.rating,
        "duration": u.c.duration_s,
        "release": u.c.rel,
        "lastwatched": u.c.last_watched,
    }.get(sort, u.c.added_at)
@router.get("/libraries")
 def list_libraries(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
    """The mirrored libraries the user can browse (drives the Plex scope selector). HU overlay
@@ -221,14 +237,7 @@ def unified_library(
        if tsq is not None:
            order = [u.c.rank.desc()]
        else:
-            col = {
+            col = sort_column(u, sort)
                "title": func.lower(u.c.title),
                "year": u.c.year,
                "rating": u.c.rating,
                "duration": u.c.duration_s,
                "release": u.c.rel,
                "lastwatched": u.c.last_watched,
            }.get(sort, u.c.added_at)
            order = [(col.asc() if sort_dir == "asc" else col.desc()).nullslast()]
        order.append(u.c.rk.desc())
        rows = db.execute(select(u).order_by(*order).offset(offset).limit(limit)).all()
@@ -1,5 +1,9 @@
 """Plex collections: browse mirrored collections + the admin manual-collection editor."""
 from collections.abc import Callable
 from datetime import date, datetime
 from typing import Any, NamedTuple
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select
@@ -12,6 +16,7 @@ from app.models import (
    PlexItem,
    PlexLibrary,
    PlexShow,
    PlexState,
    User,
 )
 from app.plex import rollup
@@ -83,13 +88,20 @@ def _collection_card(c: PlexCollection) -> dict:
 def collections(
    library: str | None = None,
    q: str | None = None,
    keys: str | None = None,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
    """Mirrored collections as cards (most-populated first), optionally name-filtered by `q`. With a
    `library` plex_key → that one library's collections (used by the collection editor). WITHOUT one →
    the UNION across all enabled libraries (the unified-scope sidebar picker, which has no single
-    library selected)."""
+    library selected).
    `keys` (CSV of rating_keys) narrows to just those. It exists because a Plex link carries the
    collection FILTER as bare rating_keys — nothing in the URL says what "17045" is called — so the
    sidebar token and the applied-filter chip had nothing to render but the raw id. Resolving them
    through this endpoint costs one small row each; pulling the whole list to find two titles is
    ~200 KB."""
    if library is not None:
        lib = (
            db.execute(select(PlexLibrary).where(PlexLibrary.plex_key == str(library)))
@@ -113,6 +125,13 @@ def collections(
    term = (q or "").strip()
    if term:
        query = query.where(PlexCollection.title.ilike(f"%{like_escape(term)}%"))
    if keys is not None:
        wanted = [k for k in (keys or "").split(",") if k]
        # An explicit but empty `keys=` asks for nothing — answer nothing, rather than falling through
        # to "every collection" (which is what an unguarded empty IN () would have to become).
        if not wanted:
            return {"collections": []}
        query = query.where(PlexCollection.rating_key.in_(wanted))
    rows = (
        db.execute(
            query.order_by(
@@ -149,14 +168,69 @@ def collections(
    }
 class Member(NamedTuple):
    """One collection member flattened to everything the Sort control can order by. The page's two
    legs are different tables (movies and shows), so there is no single query to ORDER BY — the
    ordering is a pure list sort over these, which is also what makes it unit-testable."""
    kind: str  # "movie" | "show"
    obj: Any  # PlexItem | PlexShow, carried through to the card serializer
    title: str  # lower-cased; never NULL (the column is not nullable)
    year: int | None
    rating: float | None
    added: datetime | None
    release: date | None
    duration: int | None  # movies only — a show has no single runtime
    last_watched: datetime | None
 # Sort key -> what to read off a Member. Pinned to `PLEX_SORT_KEYS` by a test: the collection page
 # shows the SAME Sort control as the browse grid, so a key this map is missing would be an option
 # that silently does nothing here.
 MEMBER_SORT_KEYS: dict[str, Callable[[Member], Any]] = {
    "added": lambda m: m.added,
    "lastwatched": lambda m: m.last_watched,
    "release": lambda m: m.release,
    "year": lambda m: m.year,
    "rating": lambda m: m.rating,
    "duration": lambda m: m.duration,
    "title": lambda m: m.title,
 }
 # What the page ordered by before it had a control, and still its default: a film series wants to be
 # read in release order, not by whenever Plex happened to ingest it.
 DEFAULT_MEMBER_SORT = "year"
 def sort_members(members: list[Member], sort: str, sort_dir: str) -> list[Member]:
    """Order a collection's members by one of `PLEX_SORT_KEYS`.
    Two properties worth stating because they are easy to get wrong with a plain `reverse=True`:
    members with no value for the key sink to the END in BOTH directions (matching the browse grid's
    `nullslast()` — a movie with no rating is not "the worst rated"), and ties always resolve
    title-ascending, so flipping the direction reverses the ranking rather than the alphabet inside
    it. An unknown key falls back to the page's default instead of returning an arbitrary order."""
    key = MEMBER_SORT_KEYS.get(sort, MEMBER_SORT_KEYS[DEFAULT_MEMBER_SORT])
    ordered = sorted(members, key=lambda m: m.title)  # stable secondary, applied first
    have = [m for m in ordered if key(m) is not None]
    missing = [m for m in ordered if key(m) is None]
    have.sort(key=key, reverse=sort_dir != "asc")
    return have + missing
@router.get("/collections/{rating_key}")
 def collection_detail(
    rating_key: str,
    sort: str = DEFAULT_MEMBER_SORT,
    sort_dir: str = "asc",
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    """One collection's hero data + its members (movies + shows), ordered by release year then title —
+    """One collection's hero data + its members (movies + shows) in the requested order — the
-    the Collection info page. Read-only here; edits go through the admin mutation endpoints below."""
+    Collection info page. The sort vocabulary is the browse grid's (`PLEX_SORT_KEYS`) so the same Sort
    control means the same thing on both surfaces; the default is release year ascending, which is
    what this page did before it had a control. Read-only here; edits go through the admin mutation
    endpoints below."""
    col = by_rating_key(db, PlexCollection, rating_key)
    if col is None:
        raise HTTPException(status_code=404, detail="Unknown collection")
@@ -179,19 +253,63 @@ def collection_detail(
        .all()
    )
    mstate = rollup.item_state_map(db, user.id, [m.id for m in movies])
-    sstate = rollup.state_map(db, user.id, [s.id for s in shows])
+    # ONE rollup pass over the show members, for both the aggregate badge status and `resumed_at` —
-    # Merge the two type-homogeneous lists into ONE member list ordered by (year, title).
+    # the browse grid's "last watched" for a show (the newest resume/watched across its episodes). The
-    tagged = [(m.year, (m.title or "").lower(), "movie", m) for m in movies] + [
+    # cheaper `rollup.state_map` gives only the status, which would leave `lastwatched` unorderable on
-        (s.year, (s.title or "").lower(), "show", s) for s in shows
+    # a show collection while the control still offered it.
    show_rows = (
        db.execute(
            rollup.agg_subquery(db, user.id, include_resumed=True).where(
                PlexItem.show_id.in_([s.id for s in shows])
            )
        ).all()
        if shows
        else []
    )
    sstate = {r.show_id: rollup.show_status(r.total, r.watched, r.inprog) for r in show_rows}
    sresumed = {r.show_id: r.resumed_at for r in show_rows}
    def _movie_last_watched(st: PlexState | None) -> datetime | None:
        # Same definition as the browse grid's: when it was last resumed, else when it was marked
        # watched (coalesce(progress_updated_at, watched_at)).
        return (st.progress_updated_at or st.watched_at) if st else None
    # Merge the two type-homogeneous lists into ONE member list, then order it.
    members = [
        Member(
            kind="movie",
            obj=m,
            title=(m.title or "").lower(),
            year=m.year,
            rating=m.rating,
            added=m.added_at,
            release=m.originally_available_at,
            duration=m.duration_s,
            last_watched=_movie_last_watched(mstate.get(m.id)),
        )
        for m in movies
    ] + [
        Member(
            kind="show",
            obj=sh,
            title=(sh.title or "").lower(),
            year=sh.year,
            rating=sh.rating,
            added=sh.added_at,
            release=sh.originally_available_at,
            duration=None,
            last_watched=sresumed.get(sh.id),
        )
        for sh in shows
    ]
-    tagged.sort(key=lambda t: (t[0] is None, t[0] or 0, t[1]))
+    members = sort_members(members, sort, sort_dir)
    items = [
-        movie_card(o, mstate.get(o.id))
+        movie_card(m.obj, mstate.get(m.obj.id))
-        if kind == "movie"
+        if m.kind == "movie"
-        else show_card(o, sstate.get(o.id, "new"))
+        else show_card(m.obj, sstate.get(m.obj.id, "new"))
-        for _, _, kind, o in tagged
+        for m in members
    ]
-    years = [y for y, _, _, _ in tagged if y is not None]
+    years = [m.year for m in members if m.year is not None]
    certs = [m.content_rating for m in movies] + [s.content_rating for s in shows]
    return {
        **_collection_card(col),
@@ -229,7 +347,9 @@ def _reject_duplicate_name(
        .first()
    )
    if dup is not None and dup.rating_key != exclude_rk:
-        raise HTTPException(status_code=409, detail="A collection with this name already exists")
+        # Structured, so the bilingual UI says it in the reader's language (it was toasted in
        # Hungarian beside an English error dialog saying the same thing).
        raise HTTPException(status_code=409, detail={"code": "collection", "reason": "name_taken"})
 def _write_or_pending_error(wrote: bool, e: Exception) -> HTTPException:
@@ -9,6 +9,7 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 from app import logs
 from app.auth import current_user
 from app.db import get_db
 from app.models import (
@@ -30,6 +31,8 @@ from app.plex.lookups import by_rating_key
 from app.routes.plex._shared import _norm_lang, item_or_404
 from app.routes.plex.collections import _collection_source
 log = logs.get_logger(__name__)
 router = APIRouter(prefix="/api/plex", tags=["plex"])
@@ -65,7 +68,21 @@ def _show_enrichment(db: Session, rating_key: str) -> tuple[dict, list]:
                related_f = ex.submit(plex.related, rating_key)  # swallows its own errors → []
                meta = meta_f.result() or {}
                related_raw = related_f.result()
-    except (PlexError, PlexNotConfigured):
+    except PlexNotConfigured:
        # silent-ok: not a failure but a state — this instance has no Plex server, and the page
        # is meant to render from the local rows alone.
        return {}, []
    except PlexError as exc:
        # The detail page still renders, from the rows the sync left behind: no cast, no related
        # strip, no rich detail. Indistinguishable on screen from a show that simply has none.
        log.warning(
            "live Plex enrichment failed for a show",
            extra=logs.event(
                "plex.detail.show_enrich_failed",
                rating_key=rating_key,
                reason=type(exc).__name__,
            ),
        )
        return {}, []
    # Don't cache an EMPTY related list: plex.related() swallows a transient failure as [] (same as a
    # genuinely no-related show), so caching it would serve an empty "related" section for the whole TTL
@@ -145,12 +162,26 @@ def show_detail(
            sh.people_enriched_at = datetime.now(timezone.utc)
            try:
                db.commit()
-            except Exception:
+            except Exception:  # noqa: BLE001 — a failed enrich must not fail the page
                # The rollback un-does the enrichment AND the `people_enriched_at` stamp, so the
                # next view tries again — but if the commit keeps failing nobody ever hears, and
                # the cast section stays empty for good.
                log.warning(
                    "the show enrichment could not be committed",
                    extra=logs.event(
                        "plex.detail.enrich_commit_failed", rating_key=sh.rating_key, kind="show"
                    ),
                )
                db.rollback()
-    except Exception:
+    except Exception:  # noqa: BLE001 — the local episode list must render whatever Plex does
        # Best-effort only — the local episode list is already assembled, so any live-Plex failure
-        # (not configured, HTTP/JSON shape) must degrade, not 500.
+        # (not configured, HTTP/JSON shape) must degrade, not 500. With the traceback, because what
-        pass
+        # is left in here after the Plex errors above are handled is our own shape bugs.
        log.warning(
            "the live part of a show page could not be built",
            extra=logs.event("plex.detail.show_extras_failed", rating_key=sh.rating_key),
            exc_info=True,
        )
    imdb_id = sh.imdb_id
    return {
@@ -295,6 +326,14 @@ def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
    try:
        i = keys.index(it.rating_key)
    except ValueError:
        # An episode missing from its own show's ordered list — the two came out of the same sync,
        # so this is a gap in it. The page loses its previous/next arrows and says nothing.
        log.info(
            "an episode is not in its show's episode list; no previous/next",
            extra=logs.event(
                "plex.detail.episode_nav_missing", rating_key=it.rating_key, show_id=it.show_id
            ),
        )
        return None, None
    return (keys[i - 1] if i > 0 else None), (keys[i + 1] if i < len(keys) - 1 else None)
@@ -366,8 +405,32 @@ def item_detail(
                        "text": codec not in subtitles.BITMAP_SUBS,
                    }
                )
-    except Exception:
+    # Best-effort, but not free: what either branch drops is the subtitle stream list and the intro
-        pass  # live extras (markers/streams) are best-effort; any live-Plex failure must degrade, not 500 — playback works without them
+    # markers, so the player offers no subtitles and no skip button — and looks like a file that has
    # neither.
    except PlexNotConfigured:
        # silent-ok: not a failure but a state — no Plex server, and nothing to play from anyway.
        pass
    except PlexError as exc:
        log.warning(
            "the live extras for an item could not be fetched",
            extra=logs.event(
                "plex.detail.extras_failed",
                rating_key=it.rating_key,
                kind=it.kind,
                reason=type(exc).__name__,
            ),
        )
    except Exception:  # noqa: BLE001 — playback works without the extras; never 500 here
        # Plex answered and WE could not read it — a shape our parsing does not expect. The same
        # split `show_detail` makes: the stack is the only thing that says where.
        log.warning(
            "the live extras for an item could not be read",
            extra=logs.event(
                "plex.detail.extras_unreadable", rating_key=it.rating_key, kind=it.kind
            ),
            exc_info=True,
        )
    # Lazy enrichment (movies only): the live fetch above carries the FULL cast + rich detail (the sync
    # only stored the listing's top ~3), so fill a not-yet-enriched movie — its cast becomes filterable
@@ -380,7 +443,15 @@ def item_detail(
        it.people_enriched_at = datetime.now(timezone.utc)
        try:
            db.commit()
-        except Exception:
+        except Exception:  # noqa: BLE001 — a failed enrich must not fail the page
            # Same as the show path above: the info page then serves the three names the listing
            # sync stored, and the full cast it just fetched is thrown away unreported.
            log.warning(
                "the movie enrichment could not be committed",
                extra=logs.event(
                    "plex.detail.enrich_commit_failed", rating_key=it.rating_key, kind="movie"
                ),
            )
            db.rollback()
    hu = lang == "hu"
@@ -1,6 +1,5 @@
 """Plex people: cast/crew filter-chip cards + a single person's filmography page."""
 import logging
 import threading
 import time
@@ -8,6 +7,7 @@ from fastapi import APIRouter, BackgroundTasks, Depends
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 from app import logs
 from app.auth import current_user
 from app.db import SessionLocal, get_db
 from app.models import (
@@ -22,7 +22,7 @@ from app.plex.cards import movie_card, show_card
 from app.plex.query import content_libs, split_csv
 router = APIRouter(prefix="/api/plex", tags=["plex"])
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 def _resolve_known_for(
@@ -1,8 +1,6 @@
 """Plex playback: image/subtitle proxies, HLS streaming, and watch-state writes."""
 import hashlib
 import os
 import tempfile
 import threading
 from datetime import datetime, timedelta, timezone
@@ -12,17 +10,20 @@ from fastapi import (
    BackgroundTasks,
    Depends,
    HTTPException,
    Path,
    Query,
    Request,
    Response,
 )
 from fastapi.responses import FileResponse
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from app.auth import current_user, resolved_user_id
 from app.db import SessionLocal, get_db
 from app.models import (
    POSITION_MAX_S,
    PlexItem,
    PlexSeason,
    PlexShow,
@@ -89,62 +90,70 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
    return imgcache.response(data, ct)
 # Both subtitle routes authenticate with the full `current_user`, not the cookie-only
 # `_require_session` the image proxies use. That lighter gate exists for bursts of low-sensitivity
 # poster fetches and skips the is_active / is_suspended / session-epoch checks — acceptable for a
 # poster, not for a route that starts reads of the media library: a suspended or "log out
 # everywhere"-revoked cookie kept scheduling them. They are not bursty (one poll a second, one fetch
 # per track), so the DB user-load costs nothing that matters.
 #
 # Both path parameters are bounded, the same way on both routes: they become a cache FILE name
 # (`sub_<rating_key>_<ord>`), and an absurd one — a 250-digit key or ordinal — outgrew the OS's name
 # limit and turned the status poll into a 500. A Plex rating_key is a short number; the bound only
 # has to be generous.
 _RatingKey = Path(max_length=32)
 _SubOrd = Path(ge=0, le=9999)
@router.get("/subtitle/{rating_key}/{sub_ord}/status")
 def subtitle_status(
    rating_key: str = _RatingKey,
    sub_ord: int = _SubOrd,
    user: User = Depends(current_user),
    # Bounded both ways: a non-finite position used to reach the scheduler's arithmetic and 500, and
    # an absurd one reached ffmpeg's `-ss`, which refused it.
    at: float = Query(0.0, ge=0.0, le=subtitles.MAX_POSITION_S, allow_inf_nan=False),
 ) -> dict:
    """Is this subtitle track showable yet — and if not, get it moving. Extraction runs in the
    background (see plex/subtitles.py for the measurements that forced it there), so the player polls
    this while it waits instead of hanging on a <track> that will not load for a minute or more.
    `at` is the viewer's absolute position: the extractor windows around it, so what gets read first
    is the part actually about to be watched."""
    return subtitles.ensure(rating_key, sub_ord, at)
@router.get("/subtitle/{rating_key}/{sub_ord}")
-def subtitle(rating_key: str, sub_ord: int, request: Request, offset: float = 0.0) -> Response:
+def subtitle(
    rating_key: str = _RatingKey,
    sub_ord: int = _SubOrd,
    user: User = Depends(current_user),
    # Finite, like every float this router takes: `-inf` crashed the shift (a 500), `nan` stacked
    # every cue at 0. It can legitimately be negative (a subtitle nudged later than the session start).
    offset: float = Query(0.0, allow_inf_nan=False),
 ) -> Response:
    """Serve the ord-th subtitle track as WebVTT for the browser's <track> — so choosing a subtitle
    overlays it directly (no HLS re-mux / session restart). Handles EXTERNAL sidecar subs (fetched
    from Plex via the stream `key` — the old `-map 0:s` broke on these since they're not in the file)
-    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached."""
+    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached.
-    _require_session(request)
+
-    # Cache the ABSOLUTE-time VTT once (per rk+ord); the per-session cue-shift is applied on the way
+    A pure READ: it serves whatever is cached and schedules nothing — the status poll owns that,
-    # out, so a resume/seek to any offset reuses the same cached track (no cache-per-offset explosion).
+    because only it knows where the viewer is (see `subtitles.cached_track`). The player mounts the
-    cache_key = f"sub_{rating_key}_{sub_ord}"
+    <track> only once /status says there is something to show, so in practice this is only ever hit
-    hit = subtitles.cache_read(cache_key)
+    warm; on a cache eviction race the 202 sends the player back to polling."""
-    if hit is not None:
+    # The cached VTT holds ABSOLUTE cue times (per rk+ord); the per-session cue-shift is applied on
-        return Response(subtitles.shift_vtt(hit, offset), media_type="text/vtt")
+    # the way out, so a resume/seek to any offset reuses the same track (no cache-per-offset explosion).
-    try:
+    hit, code = subtitles.cached_track(rating_key, sub_ord)
-        with SessionLocal() as db:
+    if hit is None and code:
-            it = item_or_404(db, rating_key)
+        raise HTTPException(
-            with PlexClient(db) as plex:
+            status_code=subtitles.UNAVAILABLE_STATUS.get(code, 422),
-                part = ((plex.metadata(it.rating_key) or {}).get("Media") or [{}])[0].get(
+            detail={"code": "subtitle", "reason": code},
-                    "Part"
+        )
-                ) or [{}]
+    if hit is None:
-                subs = [s for s in (part[0].get("Stream") or []) if s.get("streamType") == 3]
+        return Response(
-                if sub_ord < 0 or sub_ord >= len(subs):
+            status_code=202, media_type="application/json", content='{"state":"preparing"}'
-                    raise HTTPException(status_code=404, detail="No such subtitle")
+        )
-                s = subs[sub_ord]
+    return Response(subtitles.shift_vtt(hit, offset), media_type="text/vtt")
                codec = (s.get("codec") or s.get("format") or "").lower()
                if codec in subtitles.BITMAP_SUBS:
                    raise HTTPException(
                        status_code=415,
                        detail="Image-based subtitle can't be shown as text",
                    )
                if s.get("key"):  # external sidecar → fetch from Plex, convert to VTT
                    raw = plex.raw_get(s["key"])
                    if codec in ("srt", "subrip", ""):
                        vtt = subtitles.srt_to_vtt(raw.decode("utf-8", "replace"))
                    else:
                        fd, tmp = tempfile.mkstemp(suffix="." + (codec or "sub"))
                        try:
                            os.write(fd, raw)
                            os.close(fd)
                            vtt = subtitles.ffmpeg_to_vtt(tmp, None)
                        finally:
                            os.unlink(tmp)
                elif s.get("index") is not None:  # embedded → extract from the local file
                    src = plex_paths.local_media_path(db, it.file_path)
                    if src is None:
                        raise HTTPException(status_code=404, detail="Media file not found on disk")
                    emb_ord = sum(1 for x in subs[:sub_ord] if x.get("index") is not None)
                    vtt = subtitles.ffmpeg_to_vtt(str(src), emb_ord)
                else:
                    raise HTTPException(status_code=404, detail="Subtitle not fetchable")
    except PlexNotConfigured as e:
        raise HTTPException(status_code=400, detail=str(e))
    except PlexError as e:
        raise HTTPException(status_code=502, detail=f"Subtitle fetch failed: {e}")
    subtitles.cache_write(cache_key, vtt)
    return Response(subtitles.shift_vtt(vtt, offset), media_type="text/vtt")
 # Resume/watched thresholds. _PROGRESS_MIN_S matches the feed's PROGRESS_MIN_SECONDS (5), but
@@ -287,10 +296,15 @@ def _push_watch(
 class ItemProgressIn(BaseModel):
    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
    # one into a 500.
    model_config = ConfigDict(allow_inf_nan=False)
    # 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
+    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
-    duration_seconds: float = 0
+    position_seconds: float = Field(0, le=POSITION_MAX_S)
    duration_seconds: float = Field(0, le=POSITION_MAX_S)
    final: bool = False
@@ -309,6 +323,14 @@ def item_progress(
    `_should_push_resume`). `final` (sent on pause / seek / pagehide / unmount) pushes immediately and
    resets the throttle window, so Plex sees a settled position the instant the user pauses or seeks."""
    it = item_or_404(db, rating_key)
    # A player parked mid-item — playing or PAUSED — checkpoints every 10 s, so this is the signal
    # that such a viewer still wants their HLS session: the one thing `last_access` could not see,
    # since it moved only on a file fetch and a paused player fetches nothing (see
    # stream.reap_idle). It is NOT every open player: `usePlexProgress.flush` sends nothing once the
    # finish latch is up, or before the first position is known. Those are the states in which
    # reaping is the right answer anyway, and a viewer who scrubs back into a reaped session gets
    # the same 404 → reclaim the player already handles.
    plex_stream.touch_session(str(rating_key))
    position = max(0, int(body.position_seconds))
    duration = int(body.duration_seconds)
    final = body.final
@@ -406,10 +428,20 @@ def item_state(
    )
    prev_status = st.status if st is not None else "new"
    if status == "new":
        # Does Plex hold anything for this item that the un-mark has to clear? Two things qualify: a
        # view count, and a resume point. An IN-PROGRESS item carries status "new" WITH a position —
        # that is how the importer maps a bare `viewOffset` (`_plex_watch_to_state`) — so keying the
        # push on the status alone silently skipped the single case "Clear resume point" exists for:
        # the un-mark never reached Plex, the offset stayed, and the next pull imported it straight
        # back (Protector, cleared twice by the user and back at 92s both times). `hidden` is
        # Siftlode-only and still pushes nothing, exactly as this endpoint's docstring says.
        mirrored_on_plex = st is not None and (
            st.status == "watched" or (st.position_seconds or 0) > 0
        )
        if st is not None:
            db.delete(st)
            db.commit()
-        if prev_status != "new":  # something → unwatched: mirror the un-mark to Plex
+        if mirrored_on_plex:
            _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
        return {"status": "new"}
    if st is None:
@@ -524,9 +556,10 @@ def season_state(
@router.post("/stream/{rating_key}/session")
 def stream_session(
    rating_key: str,
-    start: float = 0.0,
+    # Finite: `start=inf` reached `int()` in the session builder and came back as a 500.
    start: float = Query(0.0, allow_inf_nan=False),
    audio: int | None = None,
-    aoff: float = 0.0,
+    aoff: float = Query(0.0, allow_inf_nan=False),
    multi: bool = False,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
@@ -536,7 +569,6 @@ def stream_session(
    HEVC/VP9/AV1/…) take the same HLS path but with the video re-encoded to H.264 (VAAPI or libx264).
    Selecting a non-default audio track (`audio` = stream ordinal) forces the HLS path so the chosen audio
    can be muxed in. Subtitles are independent WebVTT tracks (GET /subtitle) — no session restart."""
    plex_stream.reap_idle()  # opportunistic cleanup of idle sessions on each new playback
    it = item_or_404(db, rating_key)
    transcode = it.playable == "transcode"
    # `multi` (item has ≥2 audio tracks) forces the HLS path so ALL audio tracks ship as renditions and
@@ -560,7 +592,9 @@ def stream_session(
    return {
        "mode": "hls",
        "start_s": s.media_start_s,
-        "url": f"/api/plex/stream/{it.rating_key}/hls/{s.entry}",
+        # The session id is part of the path (not a query param) so the playlist's RELATIVE segment
        # names resolve back into the same session — see `stream_hls_file` for why it has to.
        "url": f"/api/plex/stream/{it.rating_key}/hls/{s.id}/{s.entry}",
        "transcode": s.transcode,
        "hw": s.hw,
        "tonemap": s.tonemap,
@@ -592,45 +626,82 @@ def stream_file(
    return FileResponse(str(src))  # Starlette honours the Range header (206)
 # What a session directory can contain, and nothing else. No `.vtt`: ffmpeg runs with `-sn` and
 # subtitles are independent tracks served by GET /subtitle, so a WebVTT name here could only ever be
 # a name that will not arrive — and accepting it cost a 20 s parked worker per request.
 _HLS_CT = {
    ".m3u8": "application/vnd.apple.mpegurl",
    ".ts": "video/mp2t",
    ".vtt": "text/vtt",
 }
 # A real artifact name is ~20 characters. The bound is what keeps an absurd one out of the parser:
 # `int()` on an unbounded digit run raises ValueError past 4300 digits (CPython's
 # `sys.get_int_max_str_digits`), which reached the client as a 500 — the same shape of bug the
 # subtitle routes were bounded for (`_RatingKey`, above).
 _HLS_NAME_MAX = 128
-@router.get("/stream/{rating_key}/hls/{filename}")
+@router.get("/stream/{rating_key}/hls/{session_id}/{filename}")
 def stream_hls_file(
    rating_key: str,
    session_id: str,
    filename: str,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> Response:
-    """Serve a file (playlist / segment / subtitle) from the current HLS session directory. The
+    """Serve a file (playlist / segment / subtitle) from ONE HLS session's directory. The playlist
-    playlist references its segments/subtitles by relative name, all resolving back here."""
+    references its segments/subtitles by relative name, all resolving back here.
    The session id in the path is what makes "back here" mean the same session. Sessions are keyed by
    rating_key alone and a seek-restart or a second viewer of the same item replaces the registered
    one, while the DIRECTORY is per (key, offset, tag) — so resolving by rating_key handed the old
    viewer the new session's `seg_12.ts`, produced from a different offset under `-copyts`: wrong
    bytes with a 200, which the player has no way to notice (deep-review round 5). A request for a
    session that is no longer the registered one is a 404, and the player reclaims at the playhead.
    That reclaim is also why a request with no live session is no longer auto-started here: the
    auto-start could only ever begin at 0, silently throwing away the viewer's position."""
    # Filename must be a plain hls artifact — no path separators, only the expected extensions.
    ext = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
-    if ext not in _HLS_CT or "/" in filename or "\\" in filename or ".." in filename:
+    if (
        len(filename) > _HLS_NAME_MAX
        or ext not in _HLS_CT
        or "/" in filename
        or "\\" in filename
        or ".." in filename
    ):
        raise HTTPException(status_code=404, detail="Not found")
    s = plex_stream.current_session(str(rating_key))
-    if s is None:
+    if s is None or s.id != session_id:
-        # No session yet (e.g. reaped): the ENTRY playlist may auto-start one at 0 — master.m3u8 for a
+        raise HTTPException(status_code=404, detail="No active playback session")
        # multi-audio item, index.m3u8 for a single-audio remux item.
        it = item_or_404(db, rating_key)
        if filename == "master.m3u8":
            s = plex_stream.start_session(db, it, 0.0, multi=True)
        elif filename == "index.m3u8" and it.playable == "remux":
            s = plex_stream.start_session(db, it, 0.0)
        else:
            raise HTTPException(status_code=404, detail="No active playback session")
        if s is None:
            raise HTTPException(status_code=404, detail="Media file not found on disk")
    path = s.dir / filename
-    timeout = 30 if ext == ".m3u8" else 20
+    # Only a name THIS session can actually produce is worth waiting for: its own playlists, and a
-    if not plex_stream.wait_for(path, timeout):
+    # segment of one of its own renditions whose predecessor is already on disk (ffmpeg writes them
    # in order, so if it is not there this one is not next). The session is passed, not just its
    # directory, because the single- and multi-audio argv branches spell their names differently and
    # neither can produce the other's. Answering now instead of waiting it out is what keeps a seek
    # past the produced region — or a deliberate flood of hopeless names — from parking threadpool
    # workers and their DB connections (see `artifact_may_arrive`).
    if not plex_stream.artifact_may_arrive(s, filename):
        raise HTTPException(status_code=404, detail="Not available yet")
    timeout = 30 if ext == ".m3u8" else 20
    # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
    # whole timeout: this is a SYNC route on the ~40-slot threadpool, holding a pooled DB connection
    # with it, so every such wait is a worker (and a connection) parked for 20 s — an ordinary seek
    # past the produced region was enough to do it (round 5).
    if not plex_stream.wait_for(path, timeout, proc=s.proc):
        raise HTTPException(status_code=404, detail="Not available yet")
    try:
        content = path.read_bytes()
    except OSError:
        # The session was torn down between the wait and the read — `_kill` rmtrees the whole
        # directory, and nothing holds `_lock` across those two steps. It has to present as the same
        # 404 a gone session does: the player's recovery is keyed on the STATUS (`code === 404`), so
        # a 500 here skipped the reclaim and ended playback with "couldn't play" instead of
        # restarting at the playhead. Ordinary trigger: `loadSession` awaits the new session — which
        # kills and rmtrees the old one — before destroying the old hls instance, so the outgoing
        # instance's in-flight segment request races the rmtree on every seek-restart.
        raise HTTPException(status_code=404, detail="No active playback session") from None
    return Response(
-        content=path.read_bytes(),
+        content=content,
        media_type=_HLS_CT[ext],
        headers={"Cache-Control": "no-store"},
    )
@@ -25,7 +25,7 @@ router = APIRouter(prefix="/api/plex", tags=["plex"])
 def _own_playlist_or_404(db: Session, pid: int, user: User) -> PlexPlaylist:
-    return owned_or_404(db, PlexPlaylist, pid, user, detail="Playlist not found")
+    return owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
 def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
@@ -6,7 +6,7 @@ the app or any account data. Password-protected links exchange the password once
 a short-lived signed grant that the media URL carries (a `<video src>` can't send a header).
 """
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -17,13 +17,21 @@ from app.db import get_db
 from app.downloads import links as linksmod
 from app.downloads import storage
 from app.models import DownloadJob, DownloadLink, MediaAsset
-from app.ratelimit import RateLimiter
+from app.ratelimit import RateLimiter, client_key
 from app.security import verify_password
 router = APIRouter(prefix="/api/public", tags=["public"])
-# Slow password guessing per link (the token itself is 192-bit, so it needs no throttle).
+# Slow password guessing on a link (the token itself is 192-bit, so it needs no throttle). Counted per
 # viewer — the link AND the client (`client_key`) — so a client guessing wrong shuts out only itself, and a
 # busy link's own unlocks don't count against its next viewer.
 _unlock_limit = RateLimiter(max_events=10, window_seconds=300)
 # ...under a ceiling on WRONG passwords for the link from every client together, so guessing spread over
 # many addresses stays slow too; unlocking with the password never adds to it. The price of the ceiling:
 # someone with the link but not its password, guessing from 50 / 10 = 5 networks, can keep the link shut
 # for everyone until the window passes. It is checked before the password and counted after it, so guesses
 # already running when it fills are still checked — as many as the route's threadpool runs at once.
 _unlock_failures = RateLimiter(max_events=50, window_seconds=300)
 def _link_or_404(db: Session, token: str) -> DownloadLink:
@@ -83,11 +91,16 @@ class WatchUnlockIn(BaseModel):
@router.post("/watch/{token}/unlock")
-def watch_unlock(token: str, body: WatchUnlockIn, db: Session = Depends(get_db)) -> dict:
+def watch_unlock(
    token: str, body: WatchUnlockIn, request: Request, 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):
+    # The link first: a token naming none must leave no limiter entry behind, or posting made-up tokens
-        raise HTTPException(status_code=429, detail="Too many attempts. Try again later.")
+    # would grow the limiter without bound.
    link = _link_or_404(db, token)
    viewer = f"{token}|{client_key(request)}"
    if _unlock_failures.exhausted(token) or not _unlock_limit.allow(viewer):
        raise HTTPException(status_code=429, detail="Too many attempts. Try again later.")
    if not link.password_hash:
        # Not a password link — nothing to unlock; just hand back the plain meta.
        job, asset = _ready_target(db, link)
@@ -96,6 +109,7 @@ def watch_unlock(token: str, body: WatchUnlockIn, db: Session = Depends(get_db))
            **linksmod.public_meta(link, job, asset, _file_url(token), _poster_url(token, asset)),
        }
    if not verify_password(body.password, link.password_hash):
        _unlock_failures.allow(token)
        raise HTTPException(status_code=403, detail="Wrong password.")
    job, asset = _ready_target(db, link)
    link.view_count += 1
@@ -91,7 +91,7 @@ def create_view(
 def _own_view(db: Session, user: User, view_id: int) -> SavedView:
-    return owned_or_404(db, SavedView, view_id, user, detail="Unknown view")
+    return owned_or_404(db, SavedView, view_id, user, what="view")
 class UpdateViewIn(BaseModel):
@@ -22,7 +22,9 @@ from app.scheduler import (
    trigger_all,
    trigger_job,
 )
 from app.sync.explore import followed_channel
 from app.sync.runner import estimate_deep_backfill
 from app.routes._common import not_found
 router = APIRouter(prefix="/api/admin/scheduler", tags=["admin"])
@@ -41,7 +43,7 @@ def set_job_interval(
    """Change how often a scheduler job runs (minutes). Persisted as an override and applied
    to the live scheduler immediately."""
    if job_id not in JOB_INTERVALS:
-        raise HTTPException(status_code=404, detail="Unknown job")
+        raise not_found("job")
    minutes = body.interval_minutes
    if not (MIN_INTERVAL <= minutes <= MAX_INTERVAL):
        raise HTTPException(
@@ -73,7 +75,7 @@ def run_job_now(
    try:
        result = trigger_job(job_id, actor_id=user.id)
    except KeyError:
-        raise HTTPException(status_code=404, detail="Unknown job")
+        raise not_found("job")
    if result == "already_running":
        raise HTTPException(status_code=409, detail="Job is already running")
    return {"id": job_id, "started": True}
@@ -136,9 +138,17 @@ def get_scheduler(_: User = Depends(admin_user), db: Session = Depends(get_db))
    queue = {
        "channels_recent_pending": db.scalar(
-            select(func.count()).select_from(Channel).where(Channel.recent_synced_at.is_(None))
+            # The same selection run_recent_backfill works through, or the card counts channels
            # the job will never touch and never reaches zero.
            select(func.count())
            .select_from(Channel)
            .where(Channel.recent_synced_at.is_(None), followed_channel())
        )
        or 0,
        # The whole opted-in BACKLOG, deliberately not `run_deep_backfill`'s next-pass selection
        # (which also wants `recent_synced_at`): the same figure /api/sync/my-status shows the user,
        # and a channel missing its recent pull is one the same job tick fetches first, not one the
        # job will never touch. Narrowing it here would under-report work that is genuinely queued.
        "channels_deep_pending": deep_eta["channels_pending"],
        "deep_eta_seconds": deep_eta["eta_seconds"],
        "videos_pending_enrich": db.scalar(
@@ -13,7 +13,6 @@ this search-discovered "noise" by default. Shorts and currently-live/upcoming vi
 ingested this way (Shorts are confirmed by the youtube.com/shorts probe; live/upcoming are
 dropped from the search response up front)."""
 import logging
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
@@ -23,7 +22,7 @@ from sqlalchemy import and_, delete, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session, aliased
-from app import quota, sysconfig
+from app import logs, quota, sysconfig
 from app.auth import require_human
 from app.db import get_db
 from app.models import (
@@ -45,8 +44,7 @@ from app.youtube import search_scrape
 from app.youtube.client import YouTubeClient, YouTubeError
 from app.youtube.shorts import make_client, probe_is_short
-log = logging.getLogger("siftlode.search")
+log = logs.get_logger(__name__)
 router = APIRouter(prefix="/api/search", tags=["search"])
 # search.list costs this many quota units per page.
@@ -132,6 +130,13 @@ def _ingest_candidates(
            apply_channel_details(db, details)
            db.commit()
        except YouTubeError:
            # The stubs remain and the details can be backfilled later — but until they are, those
            # channels sit in the results with no thumbnail and no subscriber count, looking like
            # channels that have neither.
            log.warning(
                "the channels found by a search could not be enriched",
                extra=logs.event("search.channel_enrich_failed", channels=len(new_channel_ids)),
            )
            db.rollback()  # details can be backfilled later; the stubs remain
    # 2) Video stubs, flagged via_search. Existing rows keep their flags (ON CONFLICT DO
@@ -161,6 +166,12 @@ def _ingest_candidates(
        with quota.attribute(user.id, quota.QuotaAction.VIDEOS_ENRICH):
            detail_by_id = {it["id"]: it for it in yt.get_videos(ids)}
    except YouTubeError:
        # Every candidate then stays unenriched, and an unenriched video cannot be judged live or
        # Short — so it is dropped. A working search returns nothing and reads as "no results".
        log.warning(
            "the videos found by a search could not be enriched",
            extra=logs.event("search.video_enrich_failed", candidates=len(ids)),
        )
        detail_by_id = {}
    enriched_at = datetime.now(
        timezone.utc
@@ -231,21 +242,29 @@ def search_youtube(
    limit = max(1, min(limit, 100))
    # Source: "scrape" (InnerTube, no API quota) or "api" (search.list, 100 units/page).
-    source = (sysconfig.get_str(db, "search_source") or "scrape").lower()
+    source = sysconfig.get_str(db, "search_source")
    if source != "scrape":
        source = "api"
    # Per-user daily cap applies to both sources (anti-abuse); with scrape it's the only guard
    # since the search itself spends no quota.
    daily_limit = sysconfig.get_int(db, "search_daily_limit_per_user")
    used = quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_SEARCH)
    if used >= daily_limit:
        # The 429 is in the request line either way; which of the two caps produced it is not, and
        # they are answered by different things — this one by tomorrow, the other by the admin.
        log.info(
            "a live search was refused: the per-user daily cap is spent",
            extra=logs.event("search.refused", reason="daily_cap", limit=daily_limit),
        )
        raise HTTPException(
            status_code=429,
            detail=f"You've reached today's YouTube search limit ({daily_limit}). Try again tomorrow.",
        )
    # The 100-unit budget pre-check only applies to the API source.
    if source == "api" and not quota.can_spend(db, SEARCH_COST):
        log.info(
            "a live search was refused: the shared YouTube budget is spent",
            extra=logs.event("search.refused", reason="shared_quota", cost=SEARCH_COST),
        )
        raise HTTPException(
            status_code=429,
            detail="The shared YouTube quota for today is used up. Try again tomorrow.",
@@ -293,7 +312,29 @@ def search_youtube(
                collected.extend(_ingest_candidates(db, yt, user, candidates))
            except Exception as exc:  # noqa: BLE001 — any ingest failure, not just YouTubeError
                db.rollback()
-                log.exception("live search ingest failed for %r", term)
+                # The term is NOT in this line. A search string is exactly what the privacy
                # policy keeps out of the log unless the user turned Teljes/TRACE on for
                # themselves, and `redact_text` does not cover it — it scrubs addresses and
                # credential params, not what someone typed into the search box. What the
                # ERROR line carries instead is the shape of the failure, which is what tells
                # an ingest bug from an upstream one; the term follows at TRACE, and only
                # under this user's own consent — not whenever the process runs at TRACE.
                log.exception(
                    "live search ingest failed",
                    extra=logs.event(
                        "search.live.ingest_failed",
                        source=source,
                        candidates=len(candidates),
                        collected=len(collected),
                    ),
                )
                if logs.consented_trace():
                    log.log(
                        logs.TRACE,
                        "the term the ingest failed on",
                        # log-pii-ok: only under this user's own Teljes consent
                        extra=logs.event("search.live.term", term=term),
                    )
                if collected:
                    break  # keep what earlier pages already gathered
                raise HTTPException(
@@ -80,7 +80,7 @@ def create_tag(
 def _own_tag(db: Session, user: User, tag_id: int) -> 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")
+    return owned_or_404(db, Tag, tag_id, user, what="tag")
 class TagUpdateIn(BaseModel):
@@ -2,7 +2,6 @@
 recent-first / deep backfill. Runs inside the API process (single worker)."""
 import contextvars
 import logging
 import threading
 from datetime import datetime, timezone
 from typing import Callable
@@ -10,7 +9,7 @@ from typing import Callable
 from apscheduler.schedulers.background import BackgroundScheduler
 from sqlalchemy import select
-from app import audit, progress, quota
+from app import audit, logs, logsink, progress, quota
 from app.audit import AuditAction
 from app.config import settings
 from app.db import SessionLocal
@@ -35,8 +34,7 @@ from app.sync.runner import (
    run_subscription_resync,
 )
-logger = logging.getLogger("siftlode.scheduler")
+log = logs.get_logger(__name__)
 _scheduler: BackgroundScheduler | None = None
 # Per-job run activity, kept in-memory for the admin Scheduler dashboard to read (the
@@ -72,6 +70,7 @@ JOB_INTERVALS: dict[str, int] = {
    "plex_watch_reconcile": settings.plex_watch_reconcile_interval_min,
    "tmdb_enrich": settings.tmdb_enrich_interval_min,
    "audit_gc": settings.audit_gc_minutes,
    "log_gc": settings.log_gc_minutes,
 }
 # Sane bounds for an admin-set interval (minutes).
@@ -103,7 +102,7 @@ def apply_interval(db, job_id: str, minutes: int) -> int:
    db.commit()
    if _scheduler is not None and _scheduler.get_job(job_id) is not None:
        _scheduler.reschedule_job(job_id, trigger="interval", minutes=minutes)
-        logger.info("rescheduled job %s to every %s min", job_id, minutes)
+        log.info("rescheduled job %s to every %s min", job_id, minutes)
    return minutes
@@ -130,7 +129,7 @@ def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | Non
        )
    except Exception:
        db.rollback()
-        logger.exception("failed to write completion notification for job %s", job_id)
+        log.exception("failed to write completion notification for job %s", job_id)
 def _run_changed(result) -> bool:
@@ -166,7 +165,7 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
        db.commit()
    except Exception:
        db.rollback()
-        logger.exception("failed to write audit row for job %s", job_id)
+        log.exception("failed to write audit row for job %s", job_id)
 def _job(name: str, fn) -> None:
@@ -174,7 +173,7 @@ def _job(name: str, fn) -> None:
    # HERE, atomically: whichever reaches this first wins, the other skips. This is the real
    # single-run guard — trigger_job's pre-check is only a fast best-effort answer for the UI.
    if not _claim_running(name):
-        logger.info("job %s already running — skipping this trigger", name)
+        log.info("job %s already running — skipping this trigger", name)
        return
    db = SessionLocal()
    actor_id = _manual_actor.get()  # set only for a manual "run now" trigger
@@ -187,7 +186,7 @@ def _job(name: str, fn) -> None:
    try:
        if is_sync_paused(db):
-            logger.info("job %s skipped (sync paused)", name)
+            log.info("job %s skipped (sync paused)", name)
            _record(
                name,
                status="skipped",
@@ -202,14 +201,14 @@ def _job(name: str, fn) -> None:
        with progress.bind(sink):
            result = fn(db)
        summary = _summarize(result)
-        logger.info("job %s -> %s", name, result)
+        log.info("job %s -> %s", name, result)
        _record(name, status="ok", last_finished=_now_iso(), last_result=summary, progress=None)
        if actor_id is not None:
            _notify_done(db, actor_id, name, "ok", summary)
        _audit_run(db, actor_id, name, "ok", summary, result)
    except Exception as exc:
        db.rollback()
-        logger.exception("job %s failed", name)
+        log.exception("job %s failed", name)
        err = str(exc) or exc.__class__.__name__
        _record(name, status="error", last_finished=_now_iso(), last_error=err, progress=None)
        if actor_id is not None:
@@ -381,6 +380,19 @@ def _audit_gc_job() -> None:
    _job("audit_gc", work)
 def _log_gc_job() -> None:
    # Prune log_events rows older than log_retention_days — the limit the privacy policy states, so
    # this runs hourly rather than daily. Pure DB, no quota.
    def work(db):
        from app import sysconfig
        reaped = logsink.gc(db, sysconfig.get_int(db, "log_retention_days"))
        db.commit()
        return {"reaped": reaped}
    _job("log_gc", work)
 # job_id -> wrapper. The single source of truth for which jobs exist and how to run one,
 # shared by start_scheduler (recurring registration) and trigger_job (manual "run now").
 JOB_FUNCS: dict[str, Callable[[], None]] = {
@@ -400,6 +412,7 @@ JOB_FUNCS: dict[str, Callable[[], None]] = {
    "plex_watch_reconcile": _plex_watch_reconcile_job,
    "tmdb_enrich": _tmdb_enrich_job,
    "audit_gc": _audit_gc_job,
    "log_gc": _log_gc_job,
 }
@@ -478,7 +491,7 @@ def start_scheduler() -> None:
        scheduler.add_job(fn, "interval", minutes=iv[job_id], id=job_id)
    scheduler.start()
    _scheduler = scheduler
-    logger.info("scheduler started")
+    log.info("scheduler started")
 def shutdown_scheduler() -> None:
@@ -1,10 +1,14 @@
 import hashlib
 from argon2 import PasswordHasher
 from argon2.exceptions import VerifyMismatchError
 from cryptography.fernet import Fernet
 from app import logs
 from app.config import settings
 log = logs.get_logger(__name__)
 # argon2id with the library defaults (sensible memory/time cost). One shared hasher instance.
 _ph = PasswordHasher()
@@ -24,8 +28,16 @@ def verify_password(password: str, hashed: str | None) -> bool:
        return False
    try:
        return _ph.verify(hashed, password)
-    except Exception:
+    except VerifyMismatchError:
-        # Any failure (mismatch, malformed hash) is a non-match — never raise to the caller.
+        return False  # silent-ok: a wrong password. The commonest path through this function.
    except Exception as exc:  # noqa: BLE001 — never raise to the caller, whatever went wrong
        # Everything else is a hash this process cannot USE — truncated in the column, written by
        # a different argon2 build. It is answered as "wrong password", so the owner of that
        # account is locked out by a bug and told they mistyped.
        log.warning(
            "a stored password hash could not be verified",
            extra=logs.event("auth.password.hash_unusable", reason=type(exc).__name__),
        )
        return False
@@ -60,5 +72,13 @@ def decrypt_optional(value: str | None) -> str | None:
        return None
    try:
        return _require_fernet().decrypt(value.encode()).decode()
-    except Exception:
+    except Exception as exc:  # noqa: BLE001 — callers fall back to a refresh, never to an error
        # Info rather than warning because the docstring's legacy-plaintext case comes through
        # here too and is harmless. What is NOT harmless looks identical: a rotated
        # TOKEN_ENCRYPTION_KEY turns every stored token unreadable at once, and every account
        # then reads as "not connected" with nothing saying the key is the reason.
        log.info(
            "a stored ciphertext could not be decrypted",
            extra=logs.event("security.decrypt.failed", reason=type(exc).__name__),
        )
        return None
@@ -1,15 +1,14 @@
 """Global admin-controlled app state (e.g. pausing background sync, first-run setup)."""
 import logging
 import secrets
 from sqlalchemy.orm import Session
 from app import logs
 from app.models import AppState
 from app.security import hash_token
-log = logging.getLogger("siftlode.state")
+log = logs.get_logger(__name__)
 # Once configuration completes in this process it never reverts, so cache it to skip the per-request
 # DB hit in the setup-mode gate (see main.setup_gate). Starts False; refreshed from the DB.
 _configured_cache = False
@@ -6,17 +6,16 @@ topicDetails categories and the channel's dominant video category. System tags a
 regenerated freely; user tags are never touched here.
 """
 import logging
 import re
 from sqlalchemy import and_, exists, func, select
 from sqlalchemy.orm import Session
-log = logging.getLogger("siftlode.autotag")
+from app import logs, progress, sysconfig
 from app import progress, sysconfig
 from app.models import Channel, ChannelTag, Tag, Video
 log = logs.get_logger(__name__)
 # --- language id (offline, deterministic, small) ---
 try:
    from py3langid.langid import MODEL_FILE, LanguageIdentifier
@@ -29,7 +28,13 @@ try:
    def _restrict(codes: list[str]) -> None:
        _identifier.set_languages(codes)
-except Exception:  # pragma: no cover - fallback to module-level API
+except Exception:  # noqa: BLE001 — pragma: no cover, fallback to the module-level API
    # The fallback classifies without the normalisation the identifier applies, so language tags
    # come out subtly different — and nothing else in the app would ever hint at which path ran.
    log.info(
        "the langid model could not be loaded; using the module-level classifier",
        extra=logs.event("autotag.langid.fallback"),
    )
    import py3langid as _langid
    def _classify(text: str):
@@ -8,13 +8,12 @@ stay private to users who explored (or subscribe to) the channel — the feed qu
 otherwise the cleanup job hard-deletes the channel and its untouched ephemeral videos after a
 grace period (mirrors the maintenance job's grace-then-delete safety)."""
 import logging
 from datetime import timedelta
-from sqlalchemy import delete, select
+from sqlalchemy import delete, or_, select
 from sqlalchemy.orm import Session
-from app import sysconfig
+from app import logs, sysconfig
 from app.models import (
    Channel,
    ExploredChannel,
@@ -28,7 +27,24 @@ from app.sync.videos import insert_stubs, stub_from_playlist_item, apply_video_d
 from app.utils import now_utc as _now
 from app.youtube.client import YouTubeClient
-log = logging.getLogger("siftlode.explore")
+log = logs.get_logger(__name__)
 def followed_channel():
    """WHERE clause: a channel somebody follows — a subscription, or an exploration still inside its
    grace window (`purge_unkept_explored` deletes the expired ExploredChannel rows first). ONE
    definition for both halves of the question: what the scheduled RSS poll and recent backfill cover
    (sync/runner.py) and what the explore purge may delete.
    The poll and backfill cover only these (owner decision, 2026-09-17). They used to cover EVERY
    channel row, but rows also come from search results, playlist sync and dropped subscriptions, and
    nothing deletes those: on prod 582 of 979 polled channels had no follower, three of them dead
    feeds answering 404 on every poll. The cost of narrowing is deliberate: the shared Library stops
    receiving new uploads from channels nobody follows."""
    return or_(
        select(Subscription.id).where(Subscription.channel_id == Channel.id).exists(),
        select(ExploredChannel.id).where(ExploredChannel.channel_id == Channel.id).exists(),
    )
 def _enrich_new(db: Session, yt: YouTubeClient, video_ids: list[str]) -> int:
@@ -98,12 +114,8 @@ def purge_unkept_explored(db: Session) -> dict:
    ).rowcount
    db.commit()
    sub_exists = select(Subscription.id).where(Subscription.channel_id == Channel.id).exists()
    exp_exists = select(ExploredChannel.id).where(ExploredChannel.channel_id == Channel.id).exists()
    orphan_ids = (
-        db.execute(
+        db.execute(select(Channel.id).where(Channel.from_explore.is_(True), ~followed_channel()))
            select(Channel.id).where(Channel.from_explore.is_(True), ~sub_exists, ~exp_exists)
        )
        .scalars()
        .all()
    )
@@ -20,13 +20,12 @@ Quota: phase 1 costs ~(flagged / 50) units, phase 2 ~(batch / 50). Both respect
 backfill reserve as the other jobs so interactive syncs never starve.
 """
 import logging
 from datetime import timedelta
 from sqlalchemy import select
 from sqlalchemy.orm import Session
-from app import progress, quota, sysconfig
+from app import logs, progress, quota, sysconfig
 from app.config import settings
 from app.models import Playlist, PlaylistItem, Video
 from app.notifications import create_notification
@@ -35,8 +34,7 @@ from app.sync.videos import apply_video_details, parse_dt
 from app.utils import now_utc as _now
 from app.youtube.client import YouTubeClient
-log = logging.getLogger("siftlode.maintenance")
+log = logs.get_logger(__name__)
 # Reasons recorded on Video.unavailable_reason. "removed" = absent from videos.list
 # (deleted or made private); "abandoned" = an upcoming premiere that never went live.
 GRACE_DAYS_BY_REASON = {
@@ -8,7 +8,6 @@ ingested (with a stub channel) so the mirror is faithful."""
 import hashlib
 import json
 import logging
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -17,15 +16,14 @@ from typing import TypeVar
 from sqlalchemy import delete, select
 from sqlalchemy.orm import Session
-from app import progress, quota
+from app import logs, progress, quota
 from app.auth import has_read_scope
 from app.models import Channel, Playlist, PlaylistItem, User, Video
 from app.sync.runner import token_users
 from app.sync.videos import apply_video_details, parse_dt
 from app.youtube.client import YouTubeClient, YouTubeError
-log = logging.getLogger("siftlode.sync")
+log = logs.get_logger(__name__)
 # Cost of a single YouTube write op (playlists/playlistItems insert/update/delete).
 WRITE_UNIT_COST = 50
@@ -59,7 +57,17 @@ def _load_baseline(pl: Playlist) -> tuple[list[str] | None, set[str]]:
        return None, set()
    try:
        val = json.loads(pl.synced_video_ids)
-    except (ValueError, TypeError):
+    except (ValueError, TypeError) as exc:
        # No baseline means the three-way merge has no "what we last agreed on" to subtract, so
        # it degrades to a union: nothing is lost, but a delete made on either side comes back.
        log.warning(
            "the sync baseline for a playlist could not be read; merging as a union",
            extra=logs.event(
                "sync.playlist.baseline_unreadable",
                playlist_id=pl.id,
                reason=type(exc).__name__,
            ),
        )
        return None, set()
    if isinstance(val, list):
        return [str(v) for v in val], set()
@@ -410,8 +418,11 @@ class _Breaker:
    write site can't accidentally implement two thirds of the protocol (forgetting to record a
    failure would silently disable the breaker for that operation)."""
-    def __init__(self, limit: int = _MAX_CONSECUTIVE_FAILURES) -> None:
+    def __init__(
        self, limit: int = _MAX_CONSECUTIVE_FAILURES, playlist_id: int | None = None
    ) -> None:
        self.limit = limit
        self.playlist_id = playlist_id  # for the failure line only
        self.streak = 0
        self.tripped = False
@@ -432,7 +443,9 @@ class _Breaker:
                self.limit,
            )
-    def run(self, op: Callable[[], T], on_fail: Callable[[], None]) -> T | _Failed:
+    def run(
        self, op: Callable[[], T], on_fail: Callable[[], None], action: str = "write"
    ) -> T | _Failed:
        """Attempt one YouTube write. Returns the op's result, or `FAILED` when the breaker is
        already tripped (op not called) or the op raised YouTubeError. `on_fail` records the item
        in the caller's failure list either way."""
@@ -441,7 +454,19 @@ class _Breaker:
            return FAILED
        try:
            out = op()
-        except YouTubeError:
+        except YouTubeError as exc:
            # The client logged the call, but not which playlist it was for or what kind of write
            # — and the caller's failure list only ever reaches the user as a count. Not the video:
            # what is in someone's playlist is a row of their history, the same as a download.
            log.debug(
                "a playlist write to YouTube failed",
                extra=logs.event(
                    "sync.playlist.item_push_failed",
                    playlist_id=self.playlist_id,
                    action=action,
                    reason=exc.reason,
                ),
            )
            on_fail()
            self.hit(False)
            return FAILED
@@ -460,7 +485,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
    local = _local_video_ids(db, pl)
    inserted = deleted = reordered = created = pulled = removed_local = 0
    failures: list[str] = []
-    breaker = _Breaker()
+    breaker = _Breaker(playlist_id=pl.id)
    with YouTubeClient(db, user) as yt:
        if not pl.yt_playlist_id:
            pl.yt_playlist_id = yt.create_playlist(pl.name)
@@ -471,6 +496,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                added = breaker.run(
                    lambda v=vid: yt.add_playlist_item(pl.yt_playlist_id, v),
                    lambda v=vid: failures.append(v),
                    "add",
                )
                if not isinstance(added, _Failed):
                    inserted += 1
@@ -533,7 +559,17 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
        if snippet is not None and (snippet.get("title") or "") != pl.name:
            try:
                yt.update_playlist_title(pl.yt_playlist_id, pl.name)
-            except YouTubeError:
+            except YouTubeError as exc:
                # All the caller passes on is the word "title", which says the rename did not
                # happen but not that YouTube refused it, or why.
                log.debug(
                    "a playlist rename did not reach YouTube",
                    extra=logs.event(
                        "sync.playlist.title_push_failed",
                        playlist_id=pl.id,
                        reason=exc.reason,
                    ),
                )
                failures.append("title")
        # Propagate genuine local deletes.
        for vid in mp.remove_from_yt:
@@ -543,6 +579,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
            dropped = breaker.run(
                lambda i=item_id: yt.delete_playlist_item(i),
                lambda v=vid: failures.append(v),
                "delete",
            )
            if not isinstance(dropped, _Failed):
                deleted += 1
@@ -552,6 +589,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
            item_id = breaker.run(
                lambda v=vid: yt.add_playlist_item(pl.yt_playlist_id, v),
                lambda v=vid: failures.append(v),
                "add",
            )
            if not isinstance(item_id, _Failed):
                item_id_by_vid[vid] = item_id
@@ -571,6 +609,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                    item_id_by_vid[w], pl.yt_playlist_id, w, pos
                ),
                lambda w=want: failures.append(w),
                "move",
            )
            if isinstance(moved, _Failed):
                continue
@@ -7,16 +7,18 @@ public reads.
 import logging
 import threading
 from collections import Counter
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from sqlalchemy import select
 from sqlalchemy.orm import Session
-from app import progress, quota, sysconfig
+from app import logs, progress, quota, sysconfig
-log = logging.getLogger("siftlode.sync")
+log = logs.get_logger(__name__)
 from app.db import SessionLocal
 from app.models import Channel, OAuthToken, Subscription, User
 from app.sync.explore import followed_channel
 from app.sync.subscriptions import import_subscriptions
 from app.sync.videos import (
    apply_rss_feed,
@@ -32,6 +34,8 @@ from app.youtube.rss import RssError, fetch_channel_feed
 # RSS feeds are free and network-bound, so fetch many at once; DB writes stay single-threaded.
 RSS_POLL_WORKERS = 16
 # Failed channels named in a poll's summary warning; the rest are counted by reason.
 RSS_FAILURE_EXAMPLES = 5
 def token_users(db: Session) -> list[User]:
@@ -52,7 +56,7 @@ def get_service_user(db: Session) -> User | None:
 def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str, int]:
-    """Poll every channel's free RSS feed. Returns `{"new": inserted, "failed": channels_that_did
+    """Poll the free RSS feed of every followed channel (`followed_channel`). Returns `{"new": inserted, "failed": channels_that_did
    _not_complete}` — the failure count is part of the RESULT, not just a log line, so the scheduler
    card and the audit summary can tell "no new uploads" apart from "nothing worked" (an egress
    outage, or a database that can't accept writes, otherwise renders identically to a quiet hour).
@@ -67,7 +71,7 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
    carries the FIRST underlying error, because on a small instance "all channels failed" is also
    what a single dead feed id looks like."""
    if channels is None:
-        channels = db.execute(select(Channel)).scalars().all()
+        channels = db.execute(select(Channel).where(followed_channel())).scalars().all()
    total = len(channels)
    new = 0
    done = 0
@@ -76,6 +80,27 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
    # outage from one permanently dead feed id — which is the whole difference on an instance with
    # a single subscription, where BOTH render as 100% failed.
    first_error: str | None = None
    # What failed, as counts per reason (`http_404`, `transport`, `apply`, …) plus a few examples —
    # the ONE warning a poll writes. One line per failed channel was what turned YouTube's RSS outage
    # of 2026-09-16 into 11k warnings in four hours; each channel's own line is DEBUG now.
    reasons: Counter[str] = Counter()
    examples: list[str] = []
    def fail(reason: str, detail: str, *, unexpected: str | None = None) -> None:
        """Count a channel that did not get polled. `unexpected` is the message for a failure that
        is a bug on our side: its FIRST occurrence per reason gets a traceback at ERROR, the rest
        DEBUG — a read-only database fails every channel the same way, and 979 identical tracebacks
        tell nobody anything the first one didn't. Call it from inside the `except` block."""
        nonlocal failed, first_error
        if unexpected is not None:
            level = logging.ERROR if reasons[reason] == 0 else logging.DEBUG
            log.log(level, unexpected, exc_info=True)
        failed += 1
        reasons[reason] += 1
        first_error = first_error or detail
        if len(examples) < RSS_FAILURE_EXAMPLES:
            examples.append(detail)
    # Fetch feeds concurrently (network-bound, no DB), then apply inserts on this thread as
    # each fetch returns — a SQLAlchemy session isn't thread-safe. Pass the channel id (a
    # plain str) to the workers; the ORM instance is touched only here on the main thread.
@@ -90,31 +115,47 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
            # A failed poll is NOT an empty feed: skip the apply so `last_rss_at` stays where it
            # was (stamping it made a permanently-broken feed look freshly polled). The shared
            # counter/progress tail lives after the statement, so the two outcomes can stay two
-            # clauses: an RssError is EXPECTED (404, timeout) and gets one warning line; anything
+            # clauses: an RssError is EXPECTED (404, timeout) and is only counted; anything else is a
-            # else is a bug on our side and earns a traceback.
+            # bug on our side and earns a traceback (the first of its kind per poll).
            except RssError as exc:
-                log.warning("RSS poll skipped for channel %s: %s", channel.id, exc)
+                log.debug("RSS poll skipped for channel %s: %s", channel.id, exc)
-                failed += 1
+                fail(exc.reason, f"{channel.id}: {exc}")
-                first_error = first_error or f"{channel.id}: {exc}"
+            # silent-ok: `fail(unexpected=…)` is the report — it logs at ERROR with the
-            except Exception as exc:
+            # traceback, once per reason per poll, which is the flood control this loop needs.
-                log.exception("RSS fetch failed for channel %s", channel.id)
+            except Exception as exc:  # noqa: BLE001 — one channel must not stop the poll
-                failed += 1
+                fail(
-                first_error = first_error or f"{channel.id}: {exc}"
+                    "error", f"{channel.id}: {exc}", unexpected=f"RSS fetch failed for {channel.id}"
                )
            else:
                try:
                    new += apply_rss_feed(db, channel, entries)
-                except Exception as exc:
+                # silent-ok: `fail(unexpected=…)` below is the report — ERROR with the traceback,
                # once per reason per poll.
                except Exception as exc:  # noqa: BLE001 — one channel must not stop the poll
                    # A write failure (read-only DB, failover) leaves the channel just as un-polled
                    # as an unreachable feed — count it, or a wholly broken run reports "failed=0".
                    db.rollback()
-                    failed += 1
+                    fail(
-                    first_error = first_error or f"{channel.id} (apply): {exc}"
+                        "apply",
-                    log.exception("RSS apply failed for channel %s", channel.id)
+                        f"{channel.id} (apply): {exc}",
                        unexpected=f"RSS apply failed for {channel.id}",
                    )
            # One place that advances the counter, whatever happened above.
            done += 1
            progress.report(done, total, "rss_poll")
    if failed:
-        log.warning("RSS poll: %d/%d channels could not be polled", failed, total)
+        log.warning(
            "RSS poll: %d/%d channels could not be polled",
            failed,
            total,
            extra=logs.event(
                "sync.rss.failed",
                failed=failed,
                total=total,
                reasons=dict(reasons),
                examples=examples,
            ),
        )
    if total and failed == total:
        # Nothing was polled at all — an egress outage (the tinyproxy-after-reboot incident), a
        # dead DNS, a read-only database. Returning normally would record the run as `ok` with the
@@ -174,7 +215,11 @@ def run_recent_backfill(
        return {"channels_processed": 0, "videos_added": 0, "reason": "no service user"}
    if channels is None:
        channels = (
-            db.execute(select(Channel).where(Channel.recent_synced_at.is_(None))).scalars().all()
+            db.execute(
                select(Channel).where(Channel.recent_synced_at.is_(None), followed_channel())
            )
            .scalars()
            .all()
        )
    if max_channels:
        channels = channels[:max_channels]
@@ -204,7 +249,8 @@ def run_deep_backfill(db: Session, max_channels: int = 10, max_pages: int = 5) -
    if user is None:
        return {"channels_processed": 0, "videos_added": 0, "reason": "no service user"}
    # Demand-driven: only deep-backfill channels at least one user has opted into
-    # (Subscription.deep_requested). Recent backfill stays unconditional (cheap).
+    # (Subscription.deep_requested). Recent backfill needs no opt-in: it covers every followed channel
    # (`followed_channel`).
    deep_requested = (
        select(Subscription.id)
        .where(
@@ -1,21 +1,23 @@
 """Import the authenticated user's YouTube subscriptions and channel metadata."""
 import logging
 from datetime import datetime, timezone
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from app import logs
 from app.models import Channel, Subscription, User
 from app.utils import normalize_description
 from app.youtube.client import YouTubeClient, best_thumbnail
-log = logging.getLogger("siftlode.sync")
+log = logs.get_logger(__name__)
 def _to_int(value) -> int | None:
    try:
        return int(value) if value is not None else None
    # silent-ok: an upstream count we cannot read is stored as no count, which the card renders as
    # absent rather than as zero. Per-channel over a whole subscription list, so it must stay quiet.
    except (TypeError, ValueError):
        return None
@@ -25,6 +27,8 @@ def _parse_dt(value: str | None) -> datetime | None:
        return None
    try:
        return datetime.fromisoformat(value.replace("Z", "+00:00"))
    # silent-ok: as `_to_int` above — an unreadable upstream date becomes NULL, and every caller
    # already treats a missing date as unknown.
    except ValueError:
        return None
@@ -39,6 +39,8 @@ def parse_dt(value: str | None) -> datetime | None:
        return None
    try:
        return datetime.fromisoformat(value.replace("Z", "+00:00"))
    # silent-ok: a pure parser with no video to name — the only thing it could put in a line is
    # the upstream string itself. None is stored, and absent is how the UI renders it.
    except ValueError:
        return None
@@ -8,26 +8,28 @@ stored Fernet-encrypted at rest (requires TOKEN_ENCRYPTION_KEY; without it, secr
 stored in the DB and stay env-only).
 """
 import logging
 from dataclasses import dataclass
 from sqlalchemy.orm import Session
-from app import security
+from app import logs, security
-from app.config import settings
+from app.config import Settings, canonical_choice, choices_of, settings
 from app.models import SystemConfig
-log = logging.getLogger("siftlode.config")
+log = logs.get_logger(__name__)
 # Config keys whose stored ciphertext failed to decrypt — tracked so the warning is logged once per
 # key, not once per request (bounded by the number of secret config keys).
 _decrypt_warned: set[str] = set()
 # The same for a stored value that no longer coerces (a choice list that shrank in a release): it
 # fails on EVERY read of a hot knob until someone saves it again. Keyed with the value, so saving a
 # different bad value is reported afresh (bounded by the keys times the values ever saved).
 _coerce_warned: set[tuple[str, str]] = set()
@dataclass(frozen=True)
 class ConfigSpec:
    key: str
-    type: str  # "int" | "str" | "bool"
+    type: str  # "int" | "str" | "bool" | "choice"
    group: str  # admin-UI grouping (logically related keys stay together)
    default_attr: str  # attribute on `settings` holding the env/config default
    secret: bool = False
@@ -35,16 +37,33 @@ class ConfigSpec:
    max: int | None = None
    allow_empty: bool = False  # str keys: a stored "" is an explicit empty value, not "unset"
    @property
    def choices(self) -> tuple[str, ...]:
        """A choice key's allowed values, read from its setting's Literal type in config.py — the one
        place the list is written. The admin page renders them as a picker."""
        return choices_of(Settings.model_fields[self.default_attr].annotation)
 # Registry of DB-overridable keys. Add a key here + wire its read through get_*() to move it
-# off env into the admin UI; the admin page renders it automatically from this list.
+# off env into the admin UI; the admin page renders it automatically from this list. The ORDER is the
 # admin page's tab order (first appearance of each group), so keep a group's keys together.
 SPECS: tuple[ConfigSpec, ...] = (
    # --- Access / registration ---
    ConfigSpec("allow_registration", "bool", "access", "allow_registration"),
    # --- Email / SMTP (one logical group; the password is the only secret) ---
    ConfigSpec("smtp_host", "str", "email", "smtp_host"),
    ConfigSpec("smtp_port", "int", "email", "smtp_port", min=1, max=65535),
    ConfigSpec("smtp_user", "str", "email", "smtp_user", allow_empty=True),
    ConfigSpec("smtp_from", "str", "email", "smtp_from"),
    ConfigSpec("smtp_password", "str", "email", "smtp_password", secret=True),
    # --- YouTube Data API key (secret; optional — public reads prefer it over OAuth) ---
    ConfigSpec("youtube_api_key", "str", "youtube", "youtube_api_key", secret=True),
    # Optional egress proxy for YouTube API calls (fixed-IP host for an IP-restricted key).
    ConfigSpec("youtube_api_proxy", "str", "youtube", "youtube_api_proxy", allow_empty=True),
    # --- Google OAuth client (Sign in with Google; both encrypted, env fallback). Set from the
    #     install wizard / Configuration page so no restart is needed when the creds change. ---
    ConfigSpec("google_client_id", "str", "google", "google_client_id", secret=True),
    ConfigSpec("google_client_secret", "str", "google", "google_client_secret", secret=True),
    # --- Quota (shared YouTube Data API daily budget) ---
    ConfigSpec("quota_daily_budget", "int", "quota", "quota_daily_budget", min=1, max=1_000_000),
    ConfigSpec(
@@ -59,7 +78,7 @@ SPECS: tuple[ConfigSpec, ...] = (
        max=100_000,
    ),
    # Live-search source: "scrape" (InnerTube, zero API quota) or "api" (search.list, 100u/page).
-    ConfigSpec("search_source", "str", "quota", "search_source"),
+    ConfigSpec("search_source", "choice", "quota", "search_source"),
    # --- Backfill (recent-first first pass per channel) ---
    ConfigSpec(
        "backfill_recent_max_videos",
@@ -96,16 +115,6 @@ SPECS: tuple[ConfigSpec, ...] = (
    ConfigSpec("explore_grace_days", "int", "explore", "explore_grace_days", min=0, max=3_650),
    # Days an un-kept live-search result video is kept before the cleanup job removes it.
    ConfigSpec("search_grace_days", "int", "explore", "search_grace_days", min=0, max=3_650),
    # --- YouTube Data API key (secret; optional — public reads prefer it over OAuth) ---
    ConfigSpec("youtube_api_key", "str", "youtube", "youtube_api_key", secret=True),
    # Optional egress proxy for YouTube API calls (fixed-IP host for an IP-restricted key).
    ConfigSpec("youtube_api_proxy", "str", "youtube", "youtube_api_proxy", allow_empty=True),
    # --- Google OAuth client (Sign in with Google; both encrypted, env fallback). Set from the
    #     install wizard / Configuration page so no restart is needed when the creds change. ---
    ConfigSpec("google_client_id", "str", "google", "google_client_id", secret=True),
    ConfigSpec("google_client_secret", "str", "google", "google_client_secret", secret=True),
    # --- Access / registration ---
    ConfigSpec("allow_registration", "bool", "access", "allow_registration"),
    # --- Download center (yt-dlp) — per-user defaults + retention/GC + layout ---
    ConfigSpec("download_total_max_bytes", "int", "downloads", "download_total_max_bytes", min=0),
    ConfigSpec(
@@ -137,7 +146,7 @@ SPECS: tuple[ConfigSpec, ...] = (
    ConfigSpec(
        "download_gc_grace_days", "int", "downloads", "download_gc_grace_days", min=0, max=3_650
    ),
-    ConfigSpec("download_layout", "str", "downloads", "download_layout"),
+    ConfigSpec("download_layout", "choice", "downloads", "download_layout"),
    ConfigSpec(
        "download_worker_concurrency",
        "int",
@@ -150,6 +159,13 @@ SPECS: tuple[ConfigSpec, ...] = (
    # --- Audit log ---
    # Days to keep admin audit-log rows before the audit_gc job prunes them (0 = keep forever).
    ConfigSpec("audit_retention_days", "int", "audit", "audit_retention_days", min=0, max=3650),
    # --- Diagnostics (E22) ---
    # Runtime log level for the API process. Applied without a restart — see routes/config.py and
    # main.py's lifespan.
    ConfigSpec("log_level", "choice", "diagnostics", "log_level"),
    # Days the log_events table keeps a row (the log_gc job prunes). No "0 = forever": stored logs
    # carry account-linked request history, and the privacy policy names a limit.
    ConfigSpec("log_retention_days", "int", "diagnostics", "log_retention_days", min=1, max=90),
    # --- Plex integration (optional; local-file playback + Plex metadata) ---
    ConfigSpec("plex_enabled", "bool", "plex", "plex_enabled"),
    ConfigSpec("plex_server_url", "str", "plex", "plex_server_url"),
@@ -159,14 +175,16 @@ SPECS: tuple[ConfigSpec, ...] = (
    ConfigSpec("plex_overlay_map", "str", "plex", "plex_overlay_map"),
    # (plex_sync_interval_min is tuned from the Scheduler dashboard, not here — it's a scheduler job.)
    ConfigSpec("plex_max_transcodes", "int", "plex", "plex_max_transcodes", min=0, max=16),
-    # Transcode re-encode tuning (E6 S1). hw = "auto"|"on"|"off" (free-text, like search_source); the
+    # Transcode re-encode tuning (E6 S1). The libx264 knobs apply only to the software fallback.
-    # libx264 knobs apply only to the software fallback. crf 0–51 (x264 range); max_height 0 = source.
+    # crf 0–51 (x264 range); max_height 0 = source.
-    ConfigSpec("plex_transcode_hw", "str", "plex", "plex_transcode_hw"),
+    ConfigSpec("plex_transcode_hw", "choice", "plex", "plex_transcode_hw"),
-    ConfigSpec("plex_transcode_preset", "str", "plex", "plex_transcode_preset"),
+    ConfigSpec("plex_transcode_preset", "choice", "plex", "plex_transcode_preset"),
    ConfigSpec("plex_transcode_crf", "int", "plex", "plex_transcode_crf", min=0, max=51),
    ConfigSpec(
        "plex_transcode_max_height", "int", "plex", "plex_transcode_max_height", min=0, max=4320
    ),
    # Audio loudness normalisation on the HLS path (remux + transcode alike, not direct play).
    ConfigSpec("plex_audio_loudnorm", "bool", "plex", "plex_audio_loudnorm"),
    # NOTE: plex_watch_sync_interval_min is a config.py default read by the watch-sync scheduler job
    # (scheduler.py); it is intentionally NOT a runtime admin knob, so it stays out of SPECS.
    # --- TMDB enrichment (E5 S2; optional) — the API key is the only secret ---
@@ -192,11 +210,23 @@ def _default(s: ConfigSpec):
    return getattr(settings, s.default_attr)
 def _choice(s: ConfigSpec, raw: object) -> str:
    """The canonical spelling of `raw` among the key's choices (any letter case), or ValueError."""
    option = canonical_choice(s.choices, raw)
    if option is None:
        raise ValueError(f"{s.key} must be one of: {', '.join(s.choices)}")
    return option
 def _coerce(s: ConfigSpec, raw: str):
    if s.type == "int":
        return int(raw)
    if s.type == "bool":
        return raw == "true"
    if s.type == "choice":
        # A stored value that is no longer a choice (the list shrank) reads as the default, like a
        # non-numeric int override does — see get().
        return _choice(s, raw)
    return raw
@@ -241,7 +271,17 @@ def get(db: Session, key: str):
        return _default(s)
    try:
        return _coerce(s, raw)
-    except (TypeError, ValueError):
+    except (TypeError, ValueError) as exc:
        # The admin set this in the UI and it is quietly not in force: the app runs on the env
        # default while the settings page goes on showing the value that was saved.
        if (s.key, raw) not in _coerce_warned:
            _coerce_warned.add((s.key, raw))
            log.warning(
                "a stored setting could not be coerced; the default is used instead",
                extra=logs.event(
                    "sysconfig.override_uncoercible", key=s.key, reason=type(exc).__name__
                ),
            )
        return _default(s)
@@ -272,6 +312,8 @@ def set_value(db: Session, key: str, value) -> None:
        raw = str(v)
    elif s.type == "bool":
        raw = "true" if value else "false"
    elif s.type == "choice":
        raw = _choice(s, value)
    else:
        raw = "" if value is None else str(value)
@@ -314,6 +356,7 @@ def describe(db: Session) -> dict:
            "max": s.max,
            "is_set": is_set,  # an override row exists
            "allow_empty": s.allow_empty,  # if true, the UI stores "" rather than deleting the row
            "choices": list(s.choices),  # the picker's options; [] for any other type
        }
        if s.secret:
            item["default_is_set"] = bool(_default(s))
@@ -16,7 +16,6 @@ Design:
  * Crash-safe: on startup, orphaned `running` jobs are requeued and `downloading` assets reset.
 """
 import logging
 import os
 import shutil
 import signal
@@ -24,27 +23,29 @@ import subprocess
 import sys
 import threading
 import time
 from collections.abc import Callable
 from datetime import datetime, timezone
 from sqlalchemy import text
 from app import logs
 from app import logsink
 from app import sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
-from app.downloads import quota, service
+from app.downloads import credentials, formats, quota, service
 from app.downloads import errors as dlerrors
 from app.downloads.jobdb import (
    _edit_staging_dir,
    _requeue_if_running,
    _reset_asset_pending,
    _set_job,
    _staging_dir,
 )
 from app.downloads.status import STOPPED_BY_ROUTE, JobStatus
 from app.models import DownloadJob, MediaAsset
-log = logging.getLogger("siftlode.worker")
+log = logs.get_logger(__name__)
 _stop = threading.Event()
@@ -71,13 +72,14 @@ def _wait_for_schema(timeout: float = 300.0) -> bool:
            with SessionLocal() as db:
                db.execute(text("SELECT 1 FROM download_jobs LIMIT 1"))
            return True
-        except Exception as exc:  # noqa: BLE001 — table not migrated yet / DB not up yet
+        except Exception:  # noqa: BLE001 — table not migrated yet / DB not up yet
            if time.monotonic() > deadline:
-                log.error(
+                # The traceback, not `str(exc)[:120]`: this is the last thing the worker says
-                    "download schema still absent after %ss — the API's migrations have not landed; "
+                # before it exits, and which driver call failed is the whole question.
-                    "exiting so the container restarts: %s",
+                log.exception(
                    "download schema still absent after %ss — the API's migrations have not "
                    "landed; exiting so the container restarts",
                    timeout,
                    str(exc)[:120],
                )
                return False
            log.info("waiting for the database schema (API migrations)…")
@@ -217,8 +219,17 @@ def _signal_group(proc: subprocess.Popen, pgid: int | None, sig: int) -> None:
            os.killpg(pgid, sig)
        else:
            proc.send_signal(sig)
-    except (ProcessLookupError, OSError):
+    except ProcessLookupError:
-        pass
+        pass  # silent-ok: the child already exited — the race this function is written around
    except OSError as exc:
        # Any OTHER refusal means the signal did not land and the child is still running, which
        # is how a "cancelled" download keeps writing to a staging tree nobody is watching.
        log.info(
            "a download child could not be signalled",
            extra=logs.event(
                "download.child.signal_failed", signal=int(sig), reason=type(exc).__name__
            ),
        )
 def _stop_child(proc: subprocess.Popen, grace_s: float) -> None:
@@ -228,6 +239,8 @@ def _stop_child(proc: subprocess.Popen, grace_s: float) -> None:
    child already exited, and `getpgid` yields None for a reaped pid, so no separate poll guard."""
    try:
        pgid: int | None = os.getpgid(proc.pid)
    # silent-ok: `getpgid` refuses for a reaped pid, which the docstring above already treats as
    # the ordinary case — the escalation then signals the child alone and no-ops if it is gone.
    except OSError:
        pgid = None
    editmod.escalate_kill(
@@ -248,12 +261,94 @@ def _stop_and_free(job_id: int, asset_id: int, proc: subprocess.Popen, grace_s:
 def _fail_after_kill(
-    job_id: int, asset_id: int, proc: subprocess.Popen, grace_s: float, error: str, error_code: str
+    job_id: int,
-) -> None:
+    asset_id: int,
    proc: subprocess.Popen,
    grace_s: float,
    error: str,
    error_code: str,
    cause: str | None = None,
 ) -> bool:
    """`_stop_and_free` + mark the job errored — for the watchdog's stall/timeout kills and the
-    supervisor-error fallback."""
+    supervisor-error fallback. Returns whether the job failed here (`_fail_running`)."""
    _stop_and_free(job_id, asset_id, proc, grace_s)
-    _set_job(job_id, status="error", error=error, error_code=error_code, phase=None)
+    return _fail_running(job_id, error=error, error_code=error_code, cause=cause)
 def _fail_running(
    job_id: int,
    *,
    error: str,
    error_code: str | None,
    error_detail: str | None = None,
    cause: str | None = None,
    exit_code: int | None = None,
 ) -> bool:
    """Fail a claimed job — only while it is still `running` (`service.finalize_if_running`), so a
    cancel/pause a route landed first is never turned back into `error`, which holds the asset the
    route already released. `error_detail` is written every time: a failure never shows an earlier
    failure's explanation.
    `cause` is the worker's half of `download.job.failed`: the failures the child never got to
    report because it was killed, never ran or died — a stall, the wall-clock cap, a non-zero exit
    (with its `exit_code`). Without it those left no line at all. A caller that logs its own line
    (a worker error, with its stack — `_report_worker_error`) passes none and uses the returned
    verdict. Logged only when the job actually failed here: a route's cancel that landed first is
    not a failure. Returns whether it failed here."""
    with SessionLocal() as db:
        failed = service.finalize_if_running(
            db,
            job_id,
            status=JobStatus.ERROR,
            error=error,
            error_code=error_code,
            error_detail=error_detail,
            phase=None,
        )
        db.commit()
    if cause is not None and failed:
        log.warning(
            "job %s failed in the worker: %s",
            job_id,
            cause,
            extra=logs.event(
                "download.job.failed",
                job_id=job_id,
                error_code=error_code,
                cause=cause,
                **({"exit_code": exit_code} if exit_code is not None else {}),
            ),
        )
    return failed
 def _report_worker_error(job_id: int, exc: Exception, cause: str, fail: Callable[[], bool]) -> None:
    """A worker error on a job (the supervisor loop, or processing the job, raised): fail the job,
    then ONE line with the stack. Its event says what the error did to the job —
    `download.job.failed` when the job failed with it, `download.worker.error` when a route had
    already stopped it (a cancel that landed first is not a failure, `_fail_running`).
    The line goes out even when failing the job raises (the database is down): as
    `download.worker.error`, since the job was not failed, and the raise goes on to the caller —
    without `exc` as its context, which this line has already carried with its stack."""
    failed = False
    try:
        failed = fail()
    except BaseException as write_error:
        write_error.__suppress_context__ = True
        raise
    finally:
        log.error(
            "job %s: worker error (%s)",
            job_id,
            cause,
            exc_info=exc,
            extra=logs.event(
                "download.job.failed" if failed else "download.worker.error",
                job_id=job_id,
                cause=cause,
            ),
        )
 def _run_supervised(job_id: int, asset_id: int) -> None:
@@ -284,6 +379,8 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
            try:
                proc.wait(timeout=poll_s)
                break  # child finished on its own
            # silent-ok: the timeout is the loop's clock, not a failure — it is what gives this
            # thread a turn to check whether a route cancelled the job.
            except subprocess.TimeoutExpired:
                pass
            status, stale = _job_liveness(job_id)
@@ -306,15 +403,20 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
            # else: a terminal status under the cap (done/error, or a re-queued contended asset) means
            # the child is exiting on its own — keep polling; NEVER kill a finishing child (that could
            # drop its completion notice).
-    except Exception:  # noqa: BLE001 — a watchdog error must NEVER leave the child running unsupervised
+    except Exception as exc:  # noqa: BLE001 — a watchdog error must NEVER leave the child running unsupervised
-        log.exception("supervisor loop failed for job %s; stopping the child", job_id)
+        # silent-ok: not silent — `_report_worker_error` is the report.
-        _fail_after_kill(
+        _report_worker_error(
            job_id,
-            asset_id,
+            exc,
-            proc,
+            "supervisor_error",
-            grace_s,
+            lambda: _fail_after_kill(
-            "The download was stopped after a worker error.",
+                job_id,
-            "unknown",
+                asset_id,
                proc,
                grace_s,
                "The download was stopped after a worker error.",
                "unknown",
            ),
        )
        return
@@ -329,15 +431,12 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
                status, _ = _job_liveness(job_id)
                if status == "running":
                    _cleanup_staging(asset_id)
-                    _set_job(
+                    _fail_running(
                        job_id,
                        status="error",
                        error_code="unknown",
                        phase=None,
                        error=f"The download process exited unexpectedly (code {proc.returncode}).",
-                    )
+                        error_code="unknown",
-                    log.warning(
+                        cause="child_exit",
-                        "job %s: child exited %s without finishing", job_id, proc.returncode
+                        exit_code=proc.returncode,
                    )
        except Exception:  # noqa: BLE001 — boot recovery is the backstop for a stuck 'running' job
            log.exception("post-exit reconciliation failed for job %s", job_id)
@@ -351,6 +450,7 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
            grace_s,
            f"The download stalled (no progress for {int(stall_s)}s) and was stopped.",
            "network",
            cause="stalled",
        )
        return
    if reason == "timeout":
@@ -361,6 +461,7 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
            grace_s,
            f"The download exceeded the {int(wall_s)}s time limit and was stopped.",
            "network",
            cause="timeout",
        )
        return
    # cancelled / abandon / shutdown: stop + free the asset, but leave the job's own DB status.
@@ -369,10 +470,19 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
        _requeue_if_running(job_id, None)  # resume on the next boot
    elif reason == "abandon":
        log.warning(
-            "job %s: killed a child wedged past the wall-clock; DB status left intact", job_id
+            "job %s: killed a child wedged past the wall-clock; DB status left intact",
            job_id,
            extra=logs.event("download.child.abandoned", job_id=job_id),
        )
    else:  # cancelled
-        log.info("job %s: child stopped (route pause/cancel)", job_id)
+        # Not `download.job.aborted`: that is the child's line, logged when it notices the pause
        # itself — and it often has, and is only tearing down when this poll comes round. This one
        # says the worker had to stop it.
        log.info(
            "job %s: child stopped (route pause/cancel)",
            job_id,
            extra=logs.event("download.child.stopped", job_id=job_id),
        )
 def _cleanup_staging(asset_id: int) -> None:
@@ -399,16 +509,33 @@ def _process_job(job_id: int) -> None:
        asset_id = asset.id if asset else None
        asset_status = asset.status if asset else None
        asset_error = asset.error if asset else None
        if asset_status == "error":
            # A job that meets an already-failed asset gets that failure's explanation — not a bare
            # "Download failed". Only the text is on the asset, so it is diagnosed again, for this
            # link, with whether a cookie goes with it asked of the same gate the download child
            # used (`credentials.usable_cookie`) — as it stands now, so the advice fits this job's Retry.
            url = service.source_url(job.source_kind, job.source_ref)
            cookie = credentials.usable_cookie(
                db, job.user_id, url, asset, formats.normalize(job.profile_snapshot)
            )
            diagnosis = dlerrors.diagnose(asset_error, url=url, cookie_attached=cookie is not None)
            del cookie  # only whether there is one matters here
    if asset is None:
-        _set_job(job_id, status="error", error="No media asset", phase=None)
+        _fail_running(job_id, error="No media asset", error_code=None, cause="no_asset")
        return
    if asset_status == "ready":
        _finish_from_cache(job_id, asset_id)
        return
    if asset_status == "error":
-        _set_job(job_id, status="error", error=asset_error or "Download failed", phase=None)
+        _fail_running(
            job_id,
            error=asset_error or "Download failed",
            error_code=diagnosis.code,
            error_detail=diagnosis.detail,
            cause="asset_failed",
        )
        return
    if asset_status == "downloading":
        # Another worker won this asset between our claim and here (a narrow race — the claim SQL
@@ -457,15 +584,34 @@ def _worker_loop(idx: int) -> None:
        if job_id is None:
            _stop.wait(settings.download_poll_seconds)
            continue
-        try:
+        # Tag every line this job produces (including the crash below) with the job id: a worker runs
-            _process_job(job_id)
+        # N jobs at once on N threads, so without it the interleaved output is unreadable. The bind
-        except Exception:  # noqa: BLE001
+        # wraps the handler too — bound inside the `try`, it was already reset by the time the crash
-            log.exception("processing job %s crashed", job_id)
+        # line was logged.
-            _set_job(job_id, status="error", error="Worker error", phase=None)
+        with logs.bind(job_id=job_id):
            try:
                _process_job(job_id)
            except Exception as exc:  # noqa: BLE001
                try:
                    _report_worker_error(
                        job_id,
                        exc,
                        "crash",
                        lambda: _fail_running(job_id, error="Worker error", error_code=None),
                    )
                # silent-ok: not silent — `_report_worker_error` logged the crash before this
                # re-raise. Failing the job hit the database, and letting that out would end this
                # worker thread for good; boot recovery settles a job left `running`.
                except Exception:  # noqa: BLE001
                    log.exception(
                        "could not fail job %s after its crash",
                        job_id,
                        extra=logs.event("download.worker.fail_write_failed", job_id=job_id),
                    )
 def main() -> None:
-    logging.basicConfig(level=logging.INFO)
+    logs.configure_logging("worker")
    signal.signal(signal.SIGTERM, _handle_signal)
    signal.signal(signal.SIGINT, _handle_signal)
@@ -481,6 +627,10 @@ def main() -> None:
        if _stop.is_set():
            return  # asked to shut down while waiting — that IS a clean exit
        raise SystemExit(1)
    # After the wait, not before: the DB is reachable now. The wait checks `download_jobs`, not
    # `log_events`, so on the deploy that first adds the table the worker may start before the API
    # has migrated — those few seconds of batches fail and say so on stderr; nothing else breaks.
    logsink.start()
    _recover_orphans()
    n = max(1, settings.download_worker_concurrency)
    log.info("Download worker started (concurrency=%d, root=%s).", n, settings.download_root)
@@ -6,24 +6,81 @@ so they don't depend on a specific user's token; subscriptions.list?mine=true al
 uses OAuth.
 """
 import logging
 from collections.abc import Iterator
 from datetime import datetime, timedelta, timezone
 import httpx
-from app import quota, sysconfig
+from app import logs, quota, sysconfig
 from app.models import User
 from app.security import decrypt, decrypt_optional, encrypt
-log = logging.getLogger("siftlode.youtube")
+log = logs.get_logger(__name__)
 GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
 API_BASE = "https://www.googleapis.com/youtube/v3"
 class YouTubeError(Exception):
-    pass
+    """An upstream YouTube Data API failure.
    `reason` is the API's own error reason code (`quotaExceeded`, `subscriptionDuplicate`,
    `videoNotFound`, …) when the body carried one. Branch on THAT, never on the message: the
    message is prose, it changes under us, and it is deliberately the poorer of the two here."""
    def __init__(self, message: str, *, reason: str = ""):
        super().__init__(message)
        self.reason = reason
 def _error_reason(resp: httpx.Response) -> str:
    """The `reason` YouTube puts on an API error. That is the whole diagnostic value of an error
    body; the `message` beside it is prose, and upstream prose can quote the request back — a
    search term, a playlist title."""
    try:
        error = resp.json().get("error")
        # The OAuth token endpoint's shape: `{"error": "invalid_grant", "error_description": …}`.
        if isinstance(error, str):
            return error or "<none>"
        errors = (error or {}).get("errors") or []
        reasons = ",".join(e.get("reason", "") for e in errors if e.get("reason"))
    # silent-ok: the sentinel it returns goes straight into the caller's warning line, which
    # is the report. (Any non-JSON body — an HTML error page from a proxy.)
    except Exception:  # noqa: BLE001
        return "<unparseable>"
    return reasons or "<none>"
 def _upstream_failure(method: str, path: str, resp: httpx.Response) -> YouTubeError:
    """Report one upstream failure and build the error to raise. Every YouTube response that is
    not a success goes through here — the Data API's reads, writes and deletes and the OAuth
    token refresh — so what may appear in a log line cannot drift apart between them, and the
    error a caller raises carries the reason code rather than the body, because callers put it in
    a log line (`routes/channels.py`) and in a 422 answered to the user. (A request that got no
    response at all is `_send`'s, with the reason `transport`.) The body is logged only under
    the requesting user's own Teljes consent: it is the request quoted back."""
    reason = _error_reason(resp)
    log.warning(
        "YouTube %s %s -> %s (%s)",
        method,
        path,
        resp.status_code,
        reason,
        extra=logs.event(
            "youtube.api.error",
            method=method,
            path=path,
            status=resp.status_code,
            reason=reason,
        ),
    )
    if logs.consented_trace():
        log.log(
            logs.TRACE,
            "the upstream body behind it",
            # log-pii-ok: only under this user's own Teljes consent, which is what it is for
            extra=logs.event("youtube.api.body", body=resp.text[:500]),
        )
    return YouTubeError(f"{method} {path} -> {resp.status_code}: {reason}", reason=reason)
 def _chunks(items: list, size: int) -> Iterator[list]:
@@ -62,13 +119,13 @@ class YouTubeClient:
        YouTubeError — degrade gracefully, log, and move on — so wrapping here keeps a
        transient network fault (e.g. the fixed-IP egress proxy being unreachable) from
        escaping as a raw httpx error and turning into an uncaught 500. HTTP status errors
-        are NOT touched here (we don't use raise_for_status): callers inspect resp.status_code
+        are NOT touched here (we don't use raise_for_status): each call site inspects
-        themselves and raise their own YouTubeError with the response body."""
+        resp.status_code itself and hands the response to `_upstream_failure`."""
        try:
            return self._http.request(method, url, **kwargs)
        except httpx.HTTPError as exc:
            raise YouTubeError(
-                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})"
+                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})", reason="transport"
            ) from exc
    # --- auth ---
@@ -99,7 +156,7 @@ class YouTubeClient:
            },
        )
        if resp.status_code != 200:
-            raise YouTubeError(f"Token refresh failed: {resp.status_code} {resp.text[:200]}")
+            raise _upstream_failure("POST", "oauth2/token", resp)
        data = resp.json()
        access = data["access_token"]
        tok.access_token = encrypt(access)
@@ -121,8 +178,7 @@ class YouTubeClient:
        resp = self._send("GET", f"{API_BASE}/{path}", params=p, headers=headers)
        quota.record_usage(cost)
        if resp.status_code != 200:
-            log.warning("YouTube API %s -> %s: %s", path, resp.status_code, resp.text[:200])
+            raise _upstream_failure("GET", path, resp)
            raise YouTubeError(f"GET {path} -> {resp.status_code}: {resp.text[:300]}")
        return resp.json()
    # --- endpoints ---
@@ -247,12 +303,7 @@ class YouTubeClient:
        )
        quota.record_usage(50)
        if resp.status_code not in (200, 204):
-            log.warning(
+            raise _upstream_failure("DELETE", "subscriptions", resp)
                "YouTube subscriptions.delete -> %s: %s",
                resp.status_code,
                resp.text[:200],
            )
            raise YouTubeError(f"DELETE subscriptions -> {resp.status_code}: {resp.text[:300]}")
    def insert_subscription(self, channel_id: str) -> str:
        """Subscribe to a channel on YouTube. Requires the write scope and the user's
@@ -282,8 +333,7 @@ class YouTubeClient:
        resp = self._send(method, f"{API_BASE}/{path}", params=params, json=json, headers=headers)
        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 _upstream_failure(method, path, resp)
            raise YouTubeError(f"{method} {path} -> {resp.status_code}: {resp.text[:300]}")
        return resp.json() if resp.content else {}
    def get_playlist_snippet(self, playlist_id: str) -> dict | None:
@@ -14,7 +14,14 @@ class RssError(Exception):
    Deliberately NOT the same as an empty feed: a failed poll used to return `[]`, which the
    caller stamped as a successful `last_rss_at` — so a channel whose feed 404s permanently
-    (deleted, renamed id) looked like it was being polled fine forever, and nothing surfaced it."""
+    (deleted, renamed id) looked like it was being polled fine forever, and nothing surfaced it.
    `reason` is a short stable code (`http_404`, `transport`) so a poll over many channels can report
    WHAT failed as counts instead of one line per channel."""
    def __init__(self, message: str, reason: str):
        super().__init__(message)
        self.reason = reason
 def fetch_channel_feed(channel_id: str) -> list[dict]:
@@ -24,9 +31,12 @@ def fetch_channel_feed(channel_id: str) -> list[dict]:
    try:
        resp = httpx.get(url, timeout=20.0, headers={"User-Agent": "Siftlode/1.0"})
    except httpx.HTTPError as exc:
-        raise RssError(f"RSS fetch failed for {channel_id}: {exc}") from exc
+        raise RssError(f"RSS fetch failed for {channel_id}: {exc}", "transport") from exc
    if resp.status_code != 200:
-        raise RssError(f"RSS fetch for {channel_id} returned HTTP {resp.status_code}")
+        raise RssError(
            f"RSS fetch for {channel_id} returned HTTP {resp.status_code}",
            f"http_{resp.status_code}",
        )
    parsed = feedparser.parse(resp.content)
    out: list[dict] = []
@@ -21,6 +21,10 @@ import re
 import httpx
 from app import logs
 log = logs.get_logger(__name__)
 _SEARCH_URL = "https://www.youtube.com/youtubei/v1/search"
 _RESULTS_URL = "https://www.youtube.com/results"
 # Public WEB InnerTube key + a recent client version. These are also embedded in every results
@@ -74,7 +78,14 @@ def _get_config(client: httpx.Client) -> tuple[str, str]:
            key.group(1) if key else _FALLBACK_KEY,
            ver.group(1) if ver else _FALLBACK_CLIENT_VERSION,
        )
-    except httpx.HTTPError:
+    except httpx.HTTPError as exc:
        # The fallback pair is CACHED in `_config` for the life of the process, so one failed
        # fetch at the wrong moment pins every later search to a hard-coded key and version —
        # and when those go stale, search returns nothing at all, with no error anywhere.
        log.warning(
            "the InnerTube config could not be fetched; falling back to the pinned key",
            extra=logs.event("youtube.scrape.config_fallback", reason=type(exc).__name__),
        )
        _config = (_FALLBACK_KEY, _FALLBACK_CLIENT_VERSION)
    return _config
@@ -18,6 +18,8 @@ def probe_is_short(client: httpx.Client, video_id: str) -> bool | None:
    """True if a Short, False if a regular video, None if undetermined (retry later)."""
    try:
        resp = client.get(SHORTS_URL.format(video_id=video_id), follow_redirects=False)
    # silent-ok: None is the documented third state — "undetermined, ask again later" — and the
    # scheduler retries it. It is not the same answer as False, so nothing is being hidden.
    except httpx.HTTPError:
        return None
    if resp.status_code == 200:
@@ -11,8 +11,12 @@ echo "Starting Siftlode API..."
 # on the next request -> 502. Non-idempotent POSTs (the player's progress/state writes,
 # fired every 5s) can't be auto-retried by the proxy, so those 502s reached the user.
 #
-# SECURITY: do NOT add --proxy-headers / --forwarded-allow-ips here. auth._client_ip trusts
+# SECURITY: do NOT add --proxy-headers / --forwarded-allow-ips here. ratelimit.client_key trusts
 # X-Forwarded-For only when the TRUE socket peer is a configured proxy (TRUSTED_PROXY_IPS); those
 # flags would make uvicorn overwrite request.client from the forgeable XFF, defeating that check and
 # reopening the rate-limit bypass (SA3).
-exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --log-config log_config.json --timeout-keep-alive 75
+#
 # No --log-config: app/logs.py configures logging for every Siftlode process (api, worker, download
 # child, alembic) in one place, and it silences uvicorn's access log in favour of our own
 # `http.request` line (route template, no query string, request id).
 exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --timeout-keep-alive 75
@@ -1,40 +0,0 @@
 {
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default": {
      "()": "uvicorn.logging.DefaultFormatter",
      "fmt": "%(asctime)s %(levelprefix)s [%(name)s] %(message)s"
    },
    "access": {
      "()": "uvicorn.logging.AccessFormatter",
      "fmt": "%(asctime)s %(levelprefix)s %(client_addr)s - \"%(request_line)s\" %(status_code)s"
    },
    "plain": {
      "format": "%(asctime)s %(levelname)-5s [%(name)s] %(message)s"
    }
  },
  "handlers": {
    "default": {
      "class": "logging.StreamHandler",
      "formatter": "default",
      "stream": "ext://sys.stdout"
    },
    "access": {
      "class": "logging.StreamHandler",
      "formatter": "access",
      "stream": "ext://sys.stdout"
    },
    "plain": {
      "class": "logging.StreamHandler",
      "formatter": "plain",
      "stream": "ext://sys.stdout"
    }
  },
  "loggers": {
    "uvicorn": { "handlers": ["default"], "level": "INFO", "propagate": false },
    "uvicorn.error": { "handlers": ["default"], "level": "INFO", "propagate": false },
    "uvicorn.access": { "handlers": ["access"], "level": "INFO", "propagate": false },
    "siftlode": { "handlers": ["plain"], "level": "INFO", "propagate": false }
  }
 }
@@ -1,7 +1,9 @@
 # Test + lint tooling — NEVER in the prod image. Installed only by backend/Dockerfile.test (the
 # throwaway test image), which the prod build (root Dockerfile) never references. Pinned so the
 # suite is reproducible: pytest for the pure-logic tests, and ruff at the SAME version the gate's
-# backend lint lane currently runs on the host (see the run_lint note in siftlode.sh). httpx is
+# backend lint lane runs on the host (the gate fails when the host's ruff is not this one). httpx2:
-# already an app dependency (requirements.txt), so its TestClient needs nothing extra here.
+# Starlette 1.x's TestClient is built on it (`import httpx2 as httpx`) and only falls back to the
 # app's own httpx with a deprecation warning on every run.
 pytest==8.4.2
 ruff==0.15.21
 httpx2==2.13.0
@@ -7,6 +7,7 @@ Authlib==1.7.2
 Mako==1.4.1
 MarkupSafe==3.0.3
 PyYAML==6.0.3
 Pygments==2.21.0
 SQLAlchemy==2.0.52
 alembic==1.19.1
 annotated-doc==0.0.5
@@ -21,6 +22,7 @@ cffi==2.1.1
 charset-normalizer==3.5.1
 click==8.4.2
 cryptography==50.0.0
 curl_cffi==0.15.0
 fastapi==0.141.1
 feedparser-sgmllib==2.1.0
 feedparser==6.0.14
@@ -32,6 +34,8 @@ httpx==0.28.1
 idna==3.18
 itsdangerous==2.2.0
 joserfc==1.7.4
 markdown-it-py==4.2.0
 mdurl==0.1.2
 mutagen==1.48.1
 numpy==2.5.2
 psycopg-binary==3.3.4
@@ -45,6 +49,7 @@ pydantic_core==2.46.4
 python-dotenv==1.2.3
 python-multipart==0.0.32
 requests==2.34.2
 rich==15.0.0
 starlette==1.6.0
 typing-inspection==0.4.4
 typing_extensions==4.16.0
@@ -21,6 +21,13 @@ argon2-cffi>=23.1,<26
 # scripts Deno runs for YouTube's n-signature). yt-dlp is release-often (YouTube changes), so
 # keep the floor loose and bump it when extraction breaks.
 yt-dlp[default]>=2025.5.22
 # Browser impersonation (`impersonate`) for Facebook downloads made with the user's cookie: some
 # links answer a signed-in plain request with "Cannot parse data" and only parse as Chrome (E11.5,
 # measured). The range is YT-DLP's, not ours — yt-dlp 2026.07.04 imports curl_cffi only in
 # 0.10.x–0.15.x and silently reports every target "unavailable" outside it. Move it when bumping
 # yt-dlp; `tests/test_facebook_impersonation.py::test_the_locked_curl_cffi_can_impersonate_chrome`
 # fails the gate if the locked pair can no longer impersonate.
 curl_cffi>=0.10,<0.16
 # PO Token provider plugin: talks to the bgutil sidecar (brainicism/bgutil-ytdlp-pot-provider)
 # to mint YouTube Proof-of-Origin tokens on demand, bypassing "confirm you're not a bot" and
 # unlocking high-quality formats. Pin to match the sidecar image tag (versions must align).
@@ -9,4 +9,21 @@
 line-length = 100
 [lint]
 # Beyond the default set, the rules that hold a LOG LINE to what E22.5 makes of it:
 #   LOG     — stdlib logging misuse (`.warn()`, a logger built by hand, `exc_info` on `.exception`)
 #   G       — the call's shape: %-style args, never an f-string the level filter cannot skip, and
 #             never `str(exc)` where `exc_info` would carry the traceback
 #   T20     — `print` instead of a log line. Two deliberate ones remain, each with its `# noqa`
 #             and a why: `downloads/runner.py`'s usage line is for whoever typed it, and
 #             `logsink.py` reports the SINK's own failure, which cannot be logged into the sink.
 #   TRY400  — `.error()` in an `except` where `.exception()` would keep the traceback
 #   TRY401  — the exception spelled into the message AND passed as `exc_info` (it is in both)
 #   S112    — `except: continue`, the silent swallow inside a loop
 #   S110    — `except: pass`, the same thing outside one
 #   BLE001  — a blind `except Exception`. Every one that remains carries `# noqa: BLE001 — <why>`,
 #             which is the point: catching everything is sometimes right (a worker thread with
 #             nobody to raise to, a best-effort backfill inside a sync) and always worth a sentence.
 # The wider rule these two enforce lives in tests/test_swallowed_exceptions.py: a handler that
 # neither logs nor re-raises says `# silent-ok: <why>`. Ruff sees only the two narrow shapes.
 extend-select = ["LOG", "G", "T20", "TRY400", "TRY401", "S110", "S112", "BLE001"]
 ignore = ["E402"]
@@ -49,7 +49,9 @@ def _db_reachable() -> bool:
        with probe.connect() as conn:
            conn.execute(text("SELECT 1"))
        return True
-    except Exception:
+    # silent-ok / noqa BLE001: the question is literally "can anything reach it", so every
    # failure is the same answer — and this runs at import, before logging is configured.
    except Exception:  # noqa: BLE001
        return False
    finally:
        probe.dispose()
@@ -57,6 +59,10 @@ def _db_reachable() -> bool:
 _DB_REACHABLE = _db_reachable()
 # No background log writer in tests: every TestClient would otherwise start one on app startup and
 # write into tables the fixtures truncate between tests. The sink's own tests drive it explicitly.
 settings.log_db_sink = False
@pytest.fixture(scope="session")
 def _schema():
@@ -210,3 +216,15 @@ def _reset_rate_limiters():
        for obj in vars(mod).values():
            if isinstance(obj, RateLimiter):
                obj.reset()
@pytest.fixture(autouse=True)
 def _reset_log_erasures():
    """`logs._erased` is module-level and remembers an erased account for an hour of monotonic time
    — longer than any suite run — while the `db` fixture hands serial ids back out from 1 via
    TRUNCATE … RESTART IDENTITY. So a test that purges user 1 would otherwise make a LATER test's
    rows for user 1 store with `user_id = None`, failing somewhere nowhere near the cause and only
    in some file orders. Same reasoning as the limiter sweep above, different global."""
    from app import logs
    logs._erased.clear()
@@ -0,0 +1,92 @@
 {
  "_comment": "One redaction contract for both logs: backend/app/logs.py redact() and frontend/src/lib/log.ts redact() must turn every `value` (under `key`) into `expected`. Both test suites run this file (backend tests/test_logs.py, frontend src/lib/log.contract.test.ts), so the two implementations cannot drift apart. Some cases prove a secret goes; others prove ordinary content (a search term, a Plex title, a chat line) is not mangled — what a LEVEL may carry is decided at the call site, not here.",
  "cases": [
    {
      "name": "a password field is dropped whole",
      "key": "",
      "value": {
        "email": "a@b.co",
        "password": "hunter2",
        "current_password": "x"
      },
      "expected": {
        "email": "[email]",
        "password": "[redacted]",
        "current_password": "[redacted]"
      }
    },
    {
      "name": "a token under any spelling of the key, nested and in lists",
      "key": "",
      "value": {
        "plex": { "plex_server_token": "abc", "Authorization": "Bearer z" },
        "items": [{ "access_token": "t1" }, { "id": 3 }]
      },
      "expected": {
        "plex": {
          "plex_server_token": "[redacted]",
          "Authorization": "[redacted]"
        },
        "items": [{ "access_token": "[redacted]" }, { "id": 3 }]
      }
    },
    {
      "name": "E2EE material and cookies",
      "key": "",
      "value": {
        "ciphertext": "AAAA",
        "passphrase": "p",
        "private_key": "k",
        "cookies": "SID=1"
      },
      "expected": {
        "ciphertext": "[redacted]",
        "passphrase": "[redacted]",
        "private_key": "[redacted]",
        "cookies": "[redacted]"
      }
    },
    {
      "name": "a reset link and a verify fragment",
      "key": "msg",
      "value": "open https://app.example/#reset=QWErty123 or /?verify=abc&lang=hu",
      "expected": "open https://app.example/#reset=[redacted] or /?verify=[redacted]&lang=hu"
    },
    {
      "name": "an OAuth callback URL",
      "key": "url",
      "value": "/auth/callback?code=4/0Ab-xyz&state=s3cr3t&scope=email",
      "expected": "/auth/callback?code=[redacted]&state=[redacted]&scope=email"
    },
    {
      "name": "an email address inside a sentence",
      "key": "message",
      "value": "Invitation sent to Some.One+tag@mail.example.org.",
      "expected": "Invitation sent to [email]."
    },
    {
      "name": "a search term is kept (TRACE decides whether it is logged at all)",
      "key": "q",
      "value": "lo-fi beats to relax",
      "expected": "lo-fi beats to relax"
    },
    {
      "name": "a Plex title with an at-sign is not an address",
      "key": "title",
      "value": "Live @ Wembley 1986",
      "expected": "Live @ Wembley 1986"
    },
    {
      "name": "a chat line is text like any other; its only secret part is scrubbed",
      "key": "body",
      "value": "see you at 8, my mail is me@home.example",
      "expected": "see you at 8, my mail is [email]"
    },
    {
      "name": "non-text values pass through",
      "key": "",
      "value": { "status": 404, "ok": false, "ratio": 0.5, "none": null },
      "expected": { "status": 404, "ok": false, "ratio": 0.5, "none": null }
    }
  ]
 }
@@ -1,6 +1,8 @@
 """Per-source adapter selection + the source-specific policy each one carries. These lock the
 behaviour that used to live inline in worker.build_uploader_url / backfill._should_refetch."""
 from app.config import settings
 from app.titles import normalize_title
 from app.downloads.adapters import (
    FacebookAdapter,
    RedditAdapter,
@@ -103,12 +105,74 @@ def test_generic_source_url_is_passthrough_youtube_reconstructs():
    )
-def test_client_sets_and_retriable_are_youtube_only():
+def test_client_sets_and_retriable_are_per_source():
    # Generic sources make a single attempt and never retry on the YouTube per-client markers.
    assert SourceAdapter().client_sets() == [None]
    assert SourceAdapter().client_sets(authed=True) == [None]
    assert SourceAdapter().retriable("Sign in to confirm you're not a bot") is False
    assert YouTubeAdapter().retriable("Sign in to confirm you're not a bot") is True
    assert YouTubeAdapter().retriable("some unrelated network blip") is False
    # A client list yt-dlp empties because none of its clients take cookies does NOT raise "No
    # player clients have been requested" (that raise sits earlier in yt-dlp, before the
    # cookie-capability removal). Measured with a real cookie: the emptied request fails with
    # "Requested format is not available", which is retriable here already — so the wasted attempt
    # is recoverable and `_COOKIE_CAPABLE` exists to avoid spending it at all.
    assert (
        YouTubeAdapter().retriable(
            "ERROR: [youtube] abc: Requested format is not available. Use --list-formats"
        )
        is True
    )
    # The media fetch refused after a successful extraction: the format URLs belong to the client
    # that minted them, so the next client set is a real second chance (it used to end the job).
    assert (
        YouTubeAdapter().retriable(
            "ERROR: unable to download video data: HTTP Error 403: Forbidden"
        )
        is True
    )
    assert (
        SourceAdapter().retriable("ERROR: unable to download video data: HTTP Error 403") is False
    )
    # Facebook: a second, Chrome-impersonating attempt only WITH the user's cookie, and only behind
    # the parse wall (without a cookie that wall is the login wall — no disguise gets past it).
    fb = FacebookAdapter()
    assert fb.client_sets() == [None]
    assert len(fb.client_sets(authed=True)) == 2
    assert fb.ydl_opts_extra(fb.client_sets(authed=True)[0]) == {}
    assert fb.retriable("ERROR: [facebook] 1: Cannot parse data; please report this issue") is True
    assert fb.retriable("ERROR: [facebook] 1: No video formats found!") is False
 def test_a_signed_in_youtube_download_only_runs_cookie_capable_clients(monkeypatch):
    yt = YouTubeAdapter()
    monkeypatch.setattr(settings, "download_player_clients", "android_vr")
    monkeypatch.setattr(settings, "download_player_clients_fallback", "web_safari,web,android")
    # Signed out: the admin's ladder exactly as configured.
    assert yt.client_sets() == [["android_vr"], ["web_safari", "web", "android"]]
    # Signed in: yt-dlp REMOVES every client that takes no cookies, and a set it empties that way
    # raises "No player clients have been requested" — which would fail the download on attempt 1,
    # before the POT-backed web fallback the cookie exists for. So the adapter never asks for one:
    # the android_vr-only set is gone and `android` is dropped out of the fallback.
    assert yt.client_sets(authed=True) == [["web_safari", "web"]]
 def test_a_signed_in_download_still_has_clients_when_the_admin_configured_none(monkeypatch):
    # Both knobs cookie-incapable: fall back to the POT-backed web pair rather than no attempt at all.
    monkeypatch.setattr(settings, "download_player_clients", "android_vr")
    monkeypatch.setattr(settings, "download_player_clients_fallback", "android,ios")
    assert YouTubeAdapter().client_sets(authed=True) == [["web_safari", "web"]]
 def test_the_cookie_capable_clients_match_the_installed_ytdlp():
    # The list is yt-dlp's, not ours (INNERTUBE_CLIENTS[...]["SUPPORTS_COOKIES"]). Pinned here so a
    # yt-dlp bump that renames or re-flags a client turns the gate red, instead of silently sending
    # a signed-in download to a client that drops the cookie.
    from yt_dlp.extractor.youtube._base import INNERTUBE_CLIENTS
    live = {k for k, v in INNERTUBE_CLIENTS.items() if v.get("SUPPORTS_COOKIES")}
    assert live == set(YouTubeAdapter._COOKIE_CAPABLE)
    assert set(YouTubeAdapter._AUTHED_DEFAULT) <= live
 def test_youtube_ydl_opts_extra_carries_player_client_and_pot():
@@ -130,3 +194,28 @@ def test_wants_metadata_backfill_matches_old_should_refetch():
 def test_nfo_uniqueid_type_is_the_adapter_key():
    assert YouTubeAdapter().nfo_uniqueid_type() == "youtube"
    assert SourceAdapter().nfo_uniqueid_type() == "generic"
 def test_title_is_yt_dlps_for_a_source_without_placeholders():
    assert SourceAdapter().title({"title": "Video", "description": "text"}) == "Video"
    assert SourceAdapter().title({}) is None
 def test_facebook_placeholder_title_takes_the_posts_text():
    # Measured: signed in, yt-dlp titles every reel "Video" (an 18+ reel read as Chrome: "Facebook"),
    # while the post's text is still in the description.
    a = FacebookAdapter()
    info = {"title": "Video", "description": "\n  Tune of The Day\nsecond line"}
    assert a.title(info) == "Tune of The Day"
    assert a.title({**info, "title": "Facebook"}) == "Tune of The Day"
    # A real title (signed out) is left for normalize_title, engagement prefix and all.
    assert a.title({**info, "title": "456K views | Tune"}) == "456K views | Tune"
    # Nothing better on the page: keep what yt-dlp gave.
    assert a.title({"title": "Facebook", "description": None}) == "Facebook"
 def test_facebook_title_from_a_long_description_is_the_whole_line_after_cleaning():
    # Dev UAT: a cut with "…" came out of normalize_title as "… live at." (NFKC "..." collapsed to "."),
    # a sentence that seemed to end. The whole first line survives the cleaning intact instead.
    line = 'Tune of The Day, Argy playing his version of the classic "Resurrection" with Paul Oakenfold live at Space'
    assert normalize_title(FacebookAdapter().title({"title": "Video", "description": line})) == line
--- a/Show More
+++ b/Show More