Add series/season/episode ingestion pipeline

Movie and person ingestion existed, but the series/season/episode API
endpoints had no way to actually populate them from TMDb -- the
biggest remaining gap in Core 0.1's television scope.

- normalize_series/normalize_season in the metadata normalizer,
  including two TMDb quirks that would otherwise silently produce
  empty data: /tv nests keywords and alternative_titles under
  "results" (not "keywords"/"titles" like /movie), and series-level
  creators come from a separate created_by array, not the credits
  cast/crew lists.
- ingest_series upserts the Series row plus season *stubs* (number,
  title, air date, poster -- everything TMDb inlines on /tv/{id});
  ingest_season fetches and upserts one season's full episode list,
  and requires the series to already exist (TMDb has no single
  endpoint for a whole series' episodes, so this has to be a separate
  per-season call).
- Wired through the same job-lifecycle path as movie/person ingestion
  (runner.py, arq tasks, admin endpoints), with the shared boilerplate
  between them factored into runner._run_ingestion and
  admin.py:_enqueue rather than copy-pasted a third and fourth time.
- Unit tests for both normalizers (runnable without a DB) and
  integration tests for the full ingest_series -> ingest_season flow,
  including the series-must-exist-first error and idempotency on
  re-ingestion.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

tests/integration/test_series_ingestion.py

@@ -0,0 +1,121 @@
+"""Integration tests for the series/season ingestion pipeline (section 15).
+A fake provider stands in for TMDb so these run without network access,
+while still exercising the real normalize -> match -> upsert -> provenance
+path against PostgreSQL."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.tv import Episode, Season, Series
+from app.providers.base import MetadataProvider, ProviderNotFoundError
+from app.services.ingestion.series_ingestion import ingest_season, ingest_series
+from tests.unit.test_normalizer import FAKE_SEASON, FAKE_SERIES
+
+
+class FakeTMDbSeriesProvider(MetadataProvider):
+    slug = "tmdb"
+    name = "The Movie Database (TMDb)"
+
+    def __init__(self, series_payload: dict[str, Any], season_payload: dict[str, Any]) -> None:
+        self._series_payload = series_payload
+        self._season_payload = season_payload
+
+    async def get_movie(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def get_series(self, external_id: str) -> dict[str, Any]:
+        return self._series_payload
+
+    async def get_season(self, series_external_id: str, season_number: int) -> dict[str, Any]:
+        return self._season_payload
+
+    async def get_person(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def search_movie(self, query: str) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
+
+@pytest.mark.asyncio
+async def test_ingest_series_creates_series_and_season_stubs(db_session: AsyncSession):
+    provider = FakeTMDbSeriesProvider(FAKE_SERIES, FAKE_SEASON)
+
+    series_id = await ingest_series(db_session, provider, "1396")
+    await db_session.commit()
+
+    series = await db_session.get(Series, series_id)
+    assert series is not None
+    assert series.title == "Ozymandias"
+    assert series.status.value == "ended"
+
+    seasons = (
+        (await db_session.execute(select(Season).where(Season.series_id == series_id)))
+        .scalars()
+        .all()
+    )
+    season_numbers = sorted(s.season_number for s in seasons)
+    assert season_numbers == [0, 1]
+    # Season stubs have no episodes yet — that's ingest_season's job.
+    assert all(
+        (await db_session.execute(select(Episode).where(Episode.season_id == s.id)))
+        .scalars()
+        .first()
+        is None
+        for s in seasons
+    )
+
+
+@pytest.mark.asyncio
+async def test_ingest_season_requires_series_ingested_first(db_session: AsyncSession):
+    provider = FakeTMDbSeriesProvider(FAKE_SERIES, FAKE_SEASON)
+
+    with pytest.raises(ProviderNotFoundError):
+        await ingest_season(db_session, provider, "1396", 1)
+
+
+@pytest.mark.asyncio
+async def test_ingest_season_creates_episodes_with_credits_and_stills(db_session: AsyncSession):
+    provider = FakeTMDbSeriesProvider(FAKE_SERIES, FAKE_SEASON)
+
+    await ingest_series(db_session, provider, "1396")
+    await db_session.flush()
+
+    season_id = await ingest_season(db_session, provider, "1396", 1)
+    await db_session.commit()
+
+    episodes = (
+        (await db_session.execute(select(Episode).where(Episode.season_id == season_id)))
+        .scalars()
+        .all()
+    )
+    assert len(episodes) == 2
+    pilot = next(e for e in episodes if e.episode_number == 1)
+    assert pilot.title == "Pilot"
+    assert pilot.runtime_minutes == 58
+
+
+@pytest.mark.asyncio
+async def test_ingest_season_is_idempotent(db_session: AsyncSession):
+    provider = FakeTMDbSeriesProvider(FAKE_SERIES, FAKE_SEASON)
+
+    await ingest_series(db_session, provider, "1396")
+    await db_session.flush()
+
+    first_season_id = await ingest_season(db_session, provider, "1396", 1)
+    await db_session.flush()
+    second_season_id = await ingest_season(db_session, provider, "1396", 1)
+    await db_session.commit()
+
+    assert first_season_id == second_season_id
+    episodes = (
+        (await db_session.execute(select(Episode).where(Episode.season_id == first_season_id)))
+        .scalars()
+        .all()
+    )
+    # Re-running must not duplicate episode rows.
+    assert len(episodes) == 2