refactor(e5): deferred review-tail (backend) — enrich off request path, reuse, tests

Address the deep-review's deferred backend items so E5 is review-complete:

- person-enrich OFF the request path (ABUSE finding): person_detail no longer makes
  the TMDB call inline (even bounded to 8s it sat on the serve thread, un-throttled,
  demo-reachable — it violated the module's "no live TMDB call at serve time"
  invariant). It now schedules a FastAPI BackgroundTask (people._enrich_person_bg,
  fresh session, best-effort) after the response; the first open serves the row as-is
  and the bio lands by the next open. The inline try/rollback recovery is gone with it.

- reuse: a shared tmdb.resolve_library_guids owns the collision-safe guid→library
  bucketing (movie vs tv ids are independent sequences) that resolve_recs and
  people._resolve_known_for each hand-duplicated; a new rollup.item_state_map dedups
  the "PlexState-by-item_id" fetch across the person + discover paths.

- test gaps: enrich_batch transient TmdbError leaves the watermark NULL to retry;
  guid_to_tmdb_id resolves a tvdb source + tv media_type via /find's tv_results;
  _continue_watching includes a NULL-status started movie and excludes a hidden one;
  /api/search/youtube returns 422 (not 5xx) when ingest fails (route-level, B-core-1).

Backend lane 403 → 413, ruff clean. No migration; serve contracts unchanged.

backend/tests/test_plex_discover.py

@@ -113,6 +113,33 @@ def test_continue_watching_movies_and_shows(db, monkeypatch):
     assert "m1" not in ids
 
 
+def test_continue_watching_null_status_in_hidden_out(db, monkeypatch):
+    # A started movie whose PlexState.status is NULL is still "in progress": `NULL NOT IN (...)` is NULL
+    # (not TRUE), so a bare notin_ would wrongly drop it — the or_(is_(None), notin_) branch keeps it.
+    # A hidden started movie must be excluded.
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    m_null = PlexItem(rating_key="mn", library_id=lib.id, kind="movie", title="Null Status", guid="tmdb:1")
+    m_hidden = PlexItem(rating_key="mh", library_id=lib.id, kind="movie", title="Hidden", guid="tmdb:2")
+    db.add_all([m_null, m_hidden])
+    db.flush()
+    user = User(email="cw-null@example.com")
+    db.add(user)
+    db.flush()
+    db.add_all([
+        PlexState(user_id=user.id, item_id=m_null.id, status=None, position_seconds=500,
+                  progress_updated_at=NOW),
+        PlexState(user_id=user.id, item_id=m_hidden.id, status="hidden", position_seconds=500,
+                  progress_updated_at=NOW - timedelta(hours=1)),
+    ])
+    db.commit()
+
+    ids = _ids(_get(db, user, monkeypatch, "/api/plex/discover?scope=movie").json()["continue_watching"])
+    assert "mn" in ids  # NULL-status started movie IS in progress
+    assert "mh" not in ids  # hidden is excluded
+
+
 def test_because_you_watched_resolves_in_library_recs(db, monkeypatch):
     user = _seed(db)
     d = _get(db, user, monkeypatch, "/api/plex/discover?scope=both").json()

backend/tests/test_plex_person_bio.py

@@ -100,34 +100,51 @@ def _get(db, user, monkeypatch, path):
         app.dependency_overrides.clear()
 
 
-def test_person_detail_survives_poisoned_enrich(db, monkeypatch):
-    # If the lazy enrich_person leaves the session in a failed-transaction state (e.g. a commit-time
-    # flush error), person_detail's except must roll it back so the following SELECTs still run — the
-    # page renders despite the enrich failure ("never fail the page"). Without the db.rollback() fix the
-    # poisoned session would raise PendingRollbackError on the next query and 500.
-    from sqlalchemy import text
+def test_person_detail_schedules_enrich_off_request_path(db, monkeypatch):
+    # The bio fetch runs OFF the request path (a background task after the response), so the serve never
+    # makes a live TMDB call. An un-enriched person (tmdb_person_id set + tmdb_enriched_at None) schedules
+    # the enrich and the page still renders immediately with whatever's in the row (bio still null).
+    from app.routes.plex import people
 
     lib = PlexLibrary(plex_key="9", title="Movies", kind="movie", enabled=True)
     db.add(lib)
     db.flush()
-    # Un-enriched person (tmdb_person_id set + tmdb_enriched_at None) → triggers the lazy enrich path.
-    db.add(PlexPerson(name="Poison P", tmdb_person_id=777))
-    user = User(email="poison@example.com")
+    db.add(PlexPerson(name="Lazy P", tmdb_person_id=777))
+    user = User(email="lazybg@example.com")
     db.add(user)
     db.commit()
 
-    def _poison_then_raise(db_, person_):
-        try:
-            db_.execute(text("SELECT 1 / 0"))  # aborts the transaction (like a failed enrich commit)
-        except Exception:  # noqa: BLE001 — swallow so the tx stays poisoned, then raise like the real path
-            pass
-        raise RuntimeError("enrich commit blew up")
+    scheduled: list[int] = []
+    monkeypatch.setattr(people, "_enrich_person_bg", lambda pid: scheduled.append(pid))
 
-    monkeypatch.setattr(plex_tmdb, "enrich_person", _poison_then_raise)
+    resp = _get(db, user, monkeypatch, "/api/plex/person/Lazy P")
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["biography"] is None  # not enriched yet — the bio lands by the next open
+    assert len(scheduled) == 1  # the enrich was scheduled off the request path
 
-    resp = _get(db, user, monkeypatch, "/api/plex/person/Poison P")
-    assert resp.status_code == 200, resp.text  # page still renders (session was rolled back)
-    assert resp.json()["biography"] is None  # enrich failed, so no bio
+
+def test_person_detail_no_enrich_when_already_enriched(db, monkeypatch):
+    # An already-enriched person (tmdb_enriched_at set) must NOT schedule another background fetch.
+    from datetime import datetime, timezone
+
+    from app.routes.plex import people
+
+    lib = PlexLibrary(plex_key="8", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add(PlexPerson(name="Done P", tmdb_person_id=888,
+                      tmdb_enriched_at=datetime(2024, 1, 1, tzinfo=timezone.utc), biography="Bio."))
+    user = User(email="donebg@example.com")
+    db.add(user)
+    db.commit()
+
+    scheduled: list[int] = []
+    monkeypatch.setattr(people, "_enrich_person_bg", lambda pid: scheduled.append(pid))
+
+    resp = _get(db, user, monkeypatch, "/api/plex/person/Done P")
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["biography"] == "Bio."
+    assert scheduled == []  # already enriched → no background work
 
 
 def test_person_detail_serves_bio_and_resolves_known_for(db, monkeypatch):

backend/tests/test_plex_tmdb.py

@@ -142,6 +142,19 @@ def test_guid_to_tmdb_id_direct_find_and_bad():
     assert tmdb.guid_to_tmdb_id("local://abc", "movie", fake) is None
 
 
+def test_guid_to_tmdb_id_tvdb_source_and_tv_media_type():
+    # A tvdb guid for a TV item goes through /find and must pick the tv_results list (not movie_results),
+    # and a tvdb source maps to the tvdb_id external_source. The media_type branch is the whole point.
+    fake = FakeTmdb(find_map={"81189": {"movie_results": [], "tv_results": [{"id": 1396}]}})
+    assert tmdb.guid_to_tmdb_id("tvdb:81189", "tv", fake) == 1396
+    # The SAME /find result, asked for a movie, reads the (empty) movie_results → None.
+    assert tmdb.guid_to_tmdb_id("tvdb:81189", "movie", fake) is None
+    # A direct tmdb guid for a tv item is just the int (no /find).
+    assert tmdb.guid_to_tmdb_id("tmdb:1396", "tv", fake) == 1396
+    # An unknown provider (only imdb/tvdb are /find sources) is unresolvable.
+    assert tmdb.guid_to_tmdb_id("plex:abc", "tv", fake) is None
+
+
 # ---- DB-lane: batch enrich + serve --------------------------------------------------------------
 
 def _lib(db, key="1", kind="movie"):
@@ -245,6 +258,31 @@ def test_run_enrich_noops_without_key(db):
     assert out["enriched"] == 0 and "skipped" in out
 
 
+class _RaisingTmdb:
+    """A client whose fetch raises a transient TmdbError (e.g. a 429), to exercise the retry path."""
+
+    def find(self, external_id, source):
+        return None
+
+    def fetch(self, tmdb_id, media_type):
+        raise tmdb.TmdbError("429 rate limited")
+
+
+def test_enrich_batch_transient_error_leaves_watermark_null(db):
+    # A transient TmdbError mid-batch must leave the row's tmdb_enriched_at NULL so the next run retries
+    # it (unlike a definitive no-match, which stamps the watermark). The row is NOT counted as processed.
+    lib = _lib(db)
+    mv = PlexItem(rating_key="m1", library_id=lib.id, kind="movie", title="Godfather", guid="tmdb:238")
+    db.add(mv)
+    db.commit()
+
+    n = tmdb.enrich_batch(db, _RaisingTmdb(), 50)
+    assert n == 0  # the transient failure is skipped, not processed
+    db.refresh(mv)
+    assert mv.tmdb_enriched_at is None  # left NULL → retried next run
+    assert mv.tmdb_id is None
+
+
 def test_enrich_batch_skips_shows_without_guid(db):
     lib = _lib(db, key="2", kind="show")
     sh = PlexShow(rating_key="s1", library_id=lib.id, title="No Guid Show")  # guid None → not selected

backend/tests/test_search_scrape_ingest.py

@@ -93,3 +93,63 @@ def test_scrape_ingest_enrich_miss_keeps_nonnull_placeholder(db):
     c = db.get(Video, "vid_ccccccc")
     assert c.published_at is not None  # placeholder wrote a real value → no crash
     assert c.enriched_at is None
+
+
+def test_search_youtube_route_returns_422_when_ingest_fails(db, monkeypatch):
+    # Route-level guard (B-core-1): an ingest failure with nothing yet collected must surface as a 422
+    # + message on this JSON endpoint (the FE hides 5xx behind a generic "connection lost" + auto-retry,
+    # burning a second quota-costed search), and the session is rolled back. Here the page fetch succeeds
+    # (one candidate) and _ingest_candidates raises → the endpoint returns 422.
+    from fastapi.testclient import TestClient
+
+    import app.state as state
+    from app.auth import require_human
+    from app.db import get_db
+    from app.main import app
+    from app.routes import search as search_mod
+
+    user = User(email="route422@example.com")
+    db.add(user)
+    db.commit()
+
+    monkeypatch.setattr(state, "_configured_cache", True)
+    monkeypatch.setattr(
+        search_mod.sysconfig, "get_str", lambda d, k: "scrape" if k == "search_source" else ""
+    )
+    monkeypatch.setattr(search_mod.sysconfig, "get_int", lambda d, k: 100)  # daily cap not reached
+    monkeypatch.setattr(search_mod.quota, "actions_today", lambda d, uid, action: 0)
+
+    class _FakeYTCM:
+        def __init__(self, *a, **k):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    monkeypatch.setattr(search_mod, "YouTubeClient", _FakeYTCM)
+    monkeypatch.setattr(
+        search_mod.search_scrape,
+        "search",
+        lambda term, continuation=None: {
+            "items": [_candidate("vid_route12", "UC_route_a")],
+            "next_page_token": None,
+        },
+    )
+
+    def _boom(db_, yt, user_, candidates):
+        raise RuntimeError("ingest exploded")
+
+    monkeypatch.setattr(search_mod, "_ingest_candidates", _boom)
+
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[require_human] = lambda: user
+    try:
+        resp = TestClient(app).get("/api/search/youtube?q=test+term")
+    finally:
+        app.dependency_overrides.clear()
+
+    assert resp.status_code == 422, resp.text
+    assert "YouTube search failed" in resp.json()["detail"]