TV identity and season corrections
Implementation contracts and behavior for tv identity and season corrections.
One server resolver owns TV requests, approvals, retries, live status, history and sibling-library badges. Precedence is local admin correction or pause → reviewed bundled correction → verified TMDB/Trakt bridge (30-day SQLite cache) → strict title fallback. Title fallback requires exactly one canonical/original-title match with known premiere years within one year; search position or year alone never identifies a show. Provider failures remain unknown, not permission to guess. Client TVDB IDs are hints only. The additive migration clears the old unverified bridge cache once; ordinary expiry continues afterward.
The bundled data in internal/request/tv_matches.v1.json maps these TMDB titles to Monster (2022), TVDB 389492:
| TMDB title | TMDB ID | Source season | Sonarr season |
|---|---|---|---|
| Dahmer | 113988 | 1 | 1 |
| Menendez | 225634 | 1 | 2 |
| Ed Gein | 286801 | 1 | 3 |
| Lizzie Borden | 299939 | 1 | 4 |
Submitted seasons and returned season statuses always use TMDB numbering. All/first/latest are expanded over that title’s source seasons; specials and unmapped seasons are refused. One title maps to one target series, with one distinct target season per source season. Custom mappings must cover current TMDB seasons and pass live Sonarr validation.
TV intake resolves and persists a target snapshot before mutation, alongside the original TMDB identity and source scope. The durable dispatcher retains approval, pinned instances, leases, retries and restart recovery. It rechecks the requester’s current grants/content policy and the mapping revision before mutations. A changed or paused mapping needs admin review. New parents receive explicit season flags and monitorNewItems: none; existing parents receive additive monitoring without changing unrelated seasons, episodes, files, profiles or settings. Pilot-only targets episode 1 of the first mapped source season. A new pilot parent is added without monitoring/search; the saved job waits until Sonarr clears its initial addOptions before enabling/searching that one episode. It never sends the parent-series pilot monitor option.
Admins manage corrections through the routes below and the capability-gated app editor. Local overrides survive bundled-data upgrades. Pause and restore retain revision tombstones to reject stale edits. Saving changes no Sonarr monitoring. Repair previews name the original and intended targets, library, season/episode scope and approval requirement; legacy target uncertainty is explicit. A repair creates one auditable, idempotent corrective request linked to the original. It never deletes files, unmonitors the previous target, revives a denied request, or erases history. Pending requests keep approval requirements. Upgrades do not re-request old content.
Movies skip bridging entirely: Radarr natively supports term=tmdb:{id}. Books have no TMDB id at all; they’re keyed by the Chaptarr/Readarr foreignBookId plus a strict book_format (ebook, audiobook, or both). Book request bodies may include instance_id; status and library endpoints accept the same field as a query parameter. The server authorizes that selection and persists it with new pending/history rows, so approval always targets the instance the requester was viewing. Omitted IDs on new requests resolve through the requester’s effective grant (or the admin fallback). Legacy rows are deliberately left unscoped because today’s default cannot prove their original library; a legacy pending book row must be resubmitted instead of being approved against a guessed instance.
Library selection (movies/TV). The same instance_id field routes requests to a specific authorized Radarr/Sonarr library, with per-library status badges and duplicate protection. New requests persist and echo that selection; unknown or forbidden IDs never fall back to another library. TV delivery and repair recheck the original requester’s current access and content policy even after approval. Admin TV badges expose all configured Sonarr libraries, matching the request options. Legacy TV approvals resolve and snapshot their current intended target only on explicit approval; legacy history is not proof of the old library or target, and repairs refuse an unrecorded library. Movies retain their existing approval and legacy-default behavior.
Adding a new native book requires a fresh lookup of the selected ID; editions are round-tripped into Chaptarr’s add body. The worker tries the original successful search term first, then ID/title fallbacks, accepting only the exact native ID. A similarly titled summary or another author’s book can never become the target. Open Library translation and match confirmation are retired. See book setup for saved-state and recovery behavior.