fix(core,meta,app,android,cli): number episodes the way releases do

AniList's per-season lookup searched for "<title> 2nd Season" and the
scorer picked the base entry again, so Attack on Titan seasons 2-4 and
Jigokuraku season 2 were captioned with season one's names. Episode
names came from streamingEpisodes, which is partial and numbered however
a streaming site counted. Bleach S17 and Mushishi S02/S03 had none.

AniList now walks SEQUEL relations from the match and takes each
entry's episodes from ani.zip, which carries TVDB's season, number and
absolute number. An episode row keeps all three plus its place in the
AniList entry. EpisodeGuide::get matches whichever numbering a file
uses and never answers from another season.

Episodes and fanart are stored as one enrichment. The episode list is
replaced even when empty, and the enrichment is recorded as asked, so a
film is not re-asked every run. Storing a different match drops the old
entry's episode rows. AniList's 4.75:1 bannerImage is no longer stored
as the 16:9 backdrop; ani.zip's 1920x1080 fanart is used instead.

Schema v9 adds the columns and deletes the AniList episode rows and
banners. Matches are kept. Desktop, Android and the CLI now share
service::plan and MetadataService::work. The settings text names
ani.zip. Audit and roadmap in docs/METADATA.md; bug entry B61.

crates/pstr-core/src/catalog.rs

@@ -17,11 +17,13 @@ use rusqlite::{Connection, OptionalExtension, params};
 
 use crate::error::Result;
 use crate::library::TitleKind;
-use crate::metadata::{EpisodeGuide, EpisodeMetadata, MetadataRecord, ProviderId, TitleMetadata};
+use crate::metadata::{
+    Enrichment, EpisodeGuide, EpisodeMetadata, MetadataRecord, ProviderId, TitleMetadata,
+};
 use crate::naming::{self, ParsedName};
 
 /// Bump when adding a migration.
-pub const SCHEMA_VERSION: i64 = 8;
+pub const SCHEMA_VERSION: i64 = 9;
 
 const MIGRATION_V1: &str = r#"
 CREATE TABLE nodes (
@@ -153,6 +155,30 @@ ALTER TABLE title_track_prefs ADD COLUMN audio_title TEXT;
 ALTER TABLE title_track_prefs ADD COLUMN subtitle_title TEXT;
 "#;
 
+/// Episodes numbered three ways, and a record of which titles were enriched.
+///
+/// A release numbers its files by TVDB season, by absolute number inside a
+/// season folder, or by AniList entry; an episode row now carries all three so
+/// `EpisodeGuide::get` can meet whichever the filename used. `enriched_at` is
+/// set once a matched title's episodes and art were asked for — empty answers
+/// included, which is what stops a film being re-asked on every run.
+///
+/// The deletes are a repair, not a reset. Every AniList episode row came from
+/// `streamingEpisodes` — partial, numbered however a streaming site numbered
+/// it, and in places a later season captioned with season one's names — and
+/// every AniList backdrop was a 4.75:1 banner drawn into a 16:9 tile. Both are
+/// wrong rather than stale, so they go; the matches stay, hand-picked ones
+/// included, and the next match run enriches them again. See
+/// `docs/METADATA.md`.
+const MIGRATION_V9: &str = r#"
+ALTER TABLE episode_metadata ADD COLUMN absolute INTEGER;
+ALTER TABLE episode_metadata ADD COLUMN entry_season INTEGER;
+ALTER TABLE episode_metadata ADD COLUMN entry_number INTEGER;
+ALTER TABLE title_metadata ADD COLUMN enriched_at INTEGER;
+DELETE FROM episode_metadata WHERE provider = 'anilist';
+UPDATE title_metadata SET backdrop_url = NULL WHERE provider = 'anilist';
+"#;
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OfflineFile {
     pub revision_id: String,
@@ -332,6 +358,12 @@ impl Catalog {
             tx.pragma_update(None, "user_version", 8)?;
             tx.commit()?;
         }
+        if version < 9 {
+            let tx = self.conn.transaction()?;
+            tx.execute_batch(MIGRATION_V9)?;
+            tx.pragma_update(None, "user_version", 9)?;
+            tx.commit()?;
+        }
 
         Ok(())
     }
@@ -699,8 +731,25 @@ impl Catalog {
     ///
     /// A miss is stored too — see [`MetadataRecord::metadata`]. Storing only
     /// matches would leave every unmatched title asking again on every render.
+    ///
+    /// Clears the title's enrichment record, so the answer is enriched again;
+    /// see [`Catalog::set_enrichment`]. And when the answer is a different
+    /// entry from the one stored — or none — the old entry's episode rows go
+    /// at once: they are not about this one, and a front end that pins a match
+    /// without enriching it must not show them in the meantime.
     pub fn set_metadata(&self, record: &MetadataRecord) -> Result<()> {
         let data = record.metadata.as_ref();
+        self.conn.execute(
+            "DELETE FROM episode_metadata WHERE title_key = ?1 AND NOT EXISTS (
+                 SELECT 1 FROM title_metadata
+                 WHERE title_key = ?1 AND provider = ?2 AND remote_id IS ?3
+             )",
+            params![
+                record.title_key,
+                record.provider.as_str(),
+                data.map(|data| data.remote_id.as_str()),
+            ],
+        )?;
         self.conn.execute(
             "INSERT INTO title_metadata (
                  title_key, provider, matched, fetched_at, remote_id, name, original_name,
@@ -723,7 +772,8 @@ impl Catalog {
                  genres        = excluded.genres,
                  episodes      = excluded.episodes,
                  url           = excluded.url,
-                 manual        = excluded.manual",
+                 manual        = excluded.manual,
+                 enriched_at   = NULL",
             params![
                 record.title_key,
                 record.provider.as_str(),
@@ -776,12 +826,7 @@ impl Catalog {
         Ok(())
     }
 
-    /// Replace everything stored about one title's episodes.
-    ///
-    /// A replace rather than an upsert per row: a provider that has *dropped*
-    /// an episode — a special that was recounted, a season renumbered — should
-    /// leave nothing behind, and an episode list is small enough that the
-    /// difference is a few hundred microseconds.
+    /// Replace everything stored about one title's episodes, and nothing else.
     pub fn set_episode_metadata(
         &mut self,
         title_key: &str,
@@ -790,31 +835,39 @@ impl Catalog {
         episodes: &[EpisodeMetadata],
     ) -> Result<()> {
         let tx = self.conn.transaction()?;
+        replace_episodes(&tx, title_key, provider, fetched_at, episodes)?;
+        tx.commit()?;
+        Ok(())
+    }
+
+    /// Store what enriching a matched title found, and that it was asked.
+    ///
+    /// The episode list is replaced even when the new one is empty — a title
+    /// re-pinned from a series to its film must not keep the series' episode
+    /// names. The backdrop only changes when one was found. And the title is
+    /// marked enriched either way, so a film with no episodes is not asked
+    /// about again on every run; [`Catalog::set_metadata`] clears the mark when
+    /// the match itself changes.
+    pub fn set_enrichment(
+        &mut self,
+        title_key: &str,
+        provider: ProviderId,
+        fetched_at: i64,
+        enrichment: &Enrichment,
+    ) -> Result<()> {
+        let tx = self.conn.transaction()?;
+        replace_episodes(&tx, title_key, provider, fetched_at, &enrichment.episodes)?;
         tx.execute(
-            "DELETE FROM episode_metadata WHERE title_key = ?1",
-            params![title_key],
+            "UPDATE title_metadata
+             SET enriched_at = ?3, backdrop_url = COALESCE(?4, backdrop_url)
+             WHERE title_key = ?1 AND provider = ?2",
+            params![
+                title_key,
+                provider.as_str(),
+                fetched_at,
+                enrichment.backdrop_url.as_deref(),
+            ],
         )?;
-        {
-            let mut insert = tx.prepare(
-                "INSERT INTO episode_metadata (
-                     title_key, season, number, provider, fetched_at,
-                     name, overview, still_url, air_date
-                 ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
-            )?;
-            for episode in episodes {
-                insert.execute(params![
-                    title_key,
-                    episode.season.map_or(ABSOLUTE_SEASON, i64::from),
-                    episode.number,
-                    provider.as_str(),
-                    fetched_at,
-                    episode.name.as_deref(),
-                    episode.overview.as_deref(),
-                    episode.still_url.as_deref(),
-                    episode.air_date.as_deref(),
-                ])?;
-            }
-        }
         tx.commit()?;
         Ok(())
     }
@@ -825,7 +878,8 @@ impl Catalog {
     /// season drawn a row at a time must not be a SQLite round-trip per row.
     pub fn all_episode_metadata(&self) -> Result<HashMap<String, EpisodeGuide>> {
         let mut statement = self.conn.prepare(
-            "SELECT title_key, season, number, name, overview, still_url, air_date
+            "SELECT title_key, season, number, name, overview, still_url, air_date,
+                    absolute, entry_season, entry_number
              FROM episode_metadata",
         )?;
         let rows = statement.query_map([], |row| {
@@ -836,6 +890,9 @@ impl Catalog {
                 EpisodeMetadata {
                     season: (season != ABSOLUTE_SEASON).then_some(season as u32),
                     number: row.get::<_, i64>(2)? as u32,
+                    absolute: row.get(7)?,
+                    entry_season: row.get(8)?,
+                    entry_number: row.get(9)?,
                     name: row.get(3)?,
                     overview: row.get(4)?,
                     still_url: row.get(5)?,
@@ -855,13 +912,13 @@ impl Catalog {
             .collect())
     }
 
-    /// Which titles already have an episode list stored, and how fresh.
-    ///
-    /// Enough to decide whether to ask again without reading every row: the
-    /// answer is only ever compared against a TTL.
-    pub fn episode_metadata_ages(&self) -> Result<HashMap<String, (ProviderId, i64)>> {
+    /// When each matched title was last enriched, for the provider it is
+    /// matched against. A title missing here has never been, or its match has
+    /// changed since.
+    pub fn enrichment_ages(&self) -> Result<HashMap<String, (ProviderId, i64)>> {
         let mut statement = self.conn.prepare(
-            "SELECT title_key, provider, MIN(fetched_at) FROM episode_metadata GROUP BY title_key",
+            "SELECT title_key, provider, enriched_at FROM title_metadata
+             WHERE enriched_at IS NOT NULL",
         )?;
         let rows = statement.query_map([], |row| {
             Ok((
@@ -873,15 +930,58 @@ impl Catalog {
 
         let mut ages = HashMap::new();
         for row in rows {
-            let (title_key, provider, fetched_at) = row?;
+            let (title_key, provider, enriched_at) = row?;
             if let Some(provider) = ProviderId::parse(&provider) {
-                ages.insert(title_key, (provider, fetched_at));
+                ages.insert(title_key, (provider, enriched_at));
             }
         }
         Ok(ages)
     }
 }
 
+/// Replace every episode row of one title with `episodes`, inside `tx`.
+///
+/// A replace rather than an upsert per row: a provider that has *dropped* an
+/// episode — a special that was recounted, a season renumbered — should leave
+/// nothing behind, and an episode list is small enough that the difference is a
+/// few hundred microseconds.
+fn replace_episodes(
+    tx: &rusqlite::Transaction<'_>,
+    title_key: &str,
+    provider: ProviderId,
+    fetched_at: i64,
+    episodes: &[EpisodeMetadata],
+) -> Result<()> {
+    tx.execute(
+        "DELETE FROM episode_metadata WHERE title_key = ?1",
+        params![title_key],
+    )?;
+    let mut insert = tx.prepare(
+        "INSERT OR REPLACE INTO episode_metadata (
+             title_key, season, number, provider, fetched_at,
+             name, overview, still_url, air_date,
+             absolute, entry_season, entry_number
+         ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)",
+    )?;
+    for episode in episodes {
+        insert.execute(params![
+            title_key,
+            episode.season.map_or(ABSOLUTE_SEASON, i64::from),
+            episode.number,
+            provider.as_str(),
+            fetched_at,
+            episode.name.as_deref(),
+            episode.overview.as_deref(),
+            episode.still_url.as_deref(),
+            episode.air_date.as_deref(),
+            episode.absolute,
+            episode.entry_season,
+            episode.entry_number,
+        ])?;
+    }
+    Ok(())
+}
+
 /// `None` for a row whose provider column this build does not recognise.
 fn row_to_metadata(row: &rusqlite::Row<'_>) -> rusqlite::Result<Option<MetadataRecord>> {
     let title_key: String = row.get(0)?;
@@ -1281,6 +1381,9 @@ mod tests {
                 &[EpisodeMetadata {
                     season: None,
                     number: 1,
+                    absolute: None,
+                    entry_season: None,
+                    entry_number: None,
                     name: Some("To You, in 2000 Years".into()),
                     overview: None,
                     still_url: None,
@@ -1370,6 +1473,9 @@ mod tests {
             EpisodeMetadata {
                 season: None,
                 number: 57,
+                absolute: None,
+                entry_season: None,
+                entry_number: None,
                 name: Some("The Immortal Legion".into()),
                 overview: Some("Ed and Al…".into()),
                 still_url: None,
@@ -1378,6 +1484,9 @@ mod tests {
             EpisodeMetadata {
                 season: Some(1),
                 number: 1,
+                absolute: None,
+                entry_season: None,
+                entry_number: None,
                 name: Some("Fullmetal Alchemist".into()),
                 overview: None,
                 still_url: Some("still.jpg".into()),
@@ -1407,9 +1516,235 @@ mod tests {
             .expect("store again");
         let stored = catalog.all_episode_metadata().expect("read");
         assert_eq!(stored["fma"].len(), 1);
+    }
 
-        let ages = catalog.episode_metadata_ages().expect("ages");
-        assert_eq!(ages["fma"], (ProviderId::AniList, 200));
+    /// The three numberings a release might use have to survive a restart, or
+    /// an absolutely-numbered season folder stops finding its names.
+    #[test]
+    fn every_numbering_of_an_episode_round_trips() {
+        let mut catalog = Catalog::in_memory().expect("open");
+        let episode = EpisodeMetadata {
+            season: Some(2),
+            number: 11,
+            absolute: Some(39),
+            entry_season: Some(3),
+            entry_number: Some(1),
+            name: Some("Lightning's End".into()),
+            overview: None,
+            still_url: None,
+            air_date: None,
+        };
+        catalog
+            .set_episode_metadata(
+                "mushishi",
+                ProviderId::AniList,
+                1,
+                std::slice::from_ref(&episode),
+            )
+            .expect("store");
+        let stored = catalog.all_episode_metadata().expect("read");
+        assert_eq!(stored["mushishi"].get(Some(2), 11), Some(&episode));
+        assert_eq!(stored["mushishi"].get(Some(3), 1), Some(&episode));
+    }
+
+    /// **What left Jujutsu Kaisen 0 with the TV series' episode names.** The
+    /// title was re-pinned to the film, the film had no episodes, and an empty
+    /// list was never written — so the series' list stayed.
+    #[test]
+    fn an_empty_enrichment_clears_the_episodes_the_last_match_left() {
+        let mut catalog = Catalog::in_memory().expect("open");
+        let record = MetadataRecord {
+            title_key: "jujutsu kaisen 0 movie".into(),
+            provider: ProviderId::AniList,
+            metadata: Some(found()),
+            fetched_at: 1,
+            manual: true,
+        };
+        catalog.set_metadata(&record).expect("store");
+        catalog
+            .set_episode_metadata(
+                &record.title_key,
+                ProviderId::AniList,
+                1,
+                &[EpisodeMetadata {
+                    season: Some(1),
+                    number: 1,
+                    absolute: None,
+                    entry_season: None,
+                    entry_number: None,
+                    name: Some("Ryomen Sukuna".into()),
+                    overview: None,
+                    still_url: None,
+                    air_date: None,
+                }],
+            )
+            .expect("store episodes");
+
+        // Storing the same entry again keeps them; it is the same entry.
+        catalog.set_metadata(&record).expect("store again");
+        assert_eq!(catalog.all_episode_metadata().expect("read").len(), 1);
+
+        catalog
+            .set_enrichment(
+                &record.title_key,
+                ProviderId::AniList,
+                5,
+                &Enrichment::default(),
+            )
+            .expect("enrich");
+        assert!(catalog.all_episode_metadata().expect("read").is_empty());
+        // Asked, and the answer was nothing: that is recorded, or a film is
+        // asked again on every run.
+        assert_eq!(
+            catalog
+                .enrichment_ages()
+                .expect("ages")
+                .get(&record.title_key),
+            Some(&(ProviderId::AniList, 5))
+        );
+    }
+
+    /// Android pins a match without enriching it; until the next match run,
+    /// the title must show no episode names rather than the old entry's.
+    #[test]
+    fn pinning_a_different_entry_drops_the_old_entrys_episodes_at_once() {
+        let mut catalog = Catalog::in_memory().expect("open");
+        let series = MetadataRecord {
+            title_key: "jujutsu kaisen 0 movie".into(),
+            provider: ProviderId::AniList,
+            metadata: Some(found()),
+            fetched_at: 1,
+            manual: false,
+        };
+        catalog.set_metadata(&series).expect("store");
+        catalog
+            .set_episode_metadata(
+                &series.title_key,
+                ProviderId::AniList,
+                1,
+                &[EpisodeMetadata {
+                    season: Some(1),
+                    number: 1,
+                    absolute: None,
+                    entry_season: None,
+                    entry_number: None,
+                    name: Some("Ryomen Sukuna".into()),
+                    overview: None,
+                    still_url: None,
+                    air_date: None,
+                }],
+            )
+            .expect("store episodes");
+
+        let film = MetadataRecord {
+            metadata: Some(TitleMetadata {
+                remote_id: "131573".into(),
+                ..found()
+            }),
+            manual: true,
+            ..series
+        };
+        catalog.set_metadata(&film).expect("pin");
+        assert!(catalog.all_episode_metadata().expect("read").is_empty());
+    }
+
+    /// Enrichment adds a backdrop when it found one and otherwise leaves the
+    /// match's own alone; a new match makes the title un-enriched again.
+    #[test]
+    fn enrichment_keeps_the_backdrop_it_did_not_replace_and_a_new_match_resets_it() {
+        let mut catalog = Catalog::in_memory().expect("open");
+        let record = MetadataRecord {
+            title_key: "attack on titan".into(),
+            provider: ProviderId::AniList,
+            metadata: Some(TitleMetadata {
+                backdrop_url: Some("old.jpg".into()),
+                ..found()
+            }),
+            fetched_at: 1,
+            manual: false,
+        };
+        catalog.set_metadata(&record).expect("store");
+        let backdrop = |catalog: &Catalog| {
+            catalog
+                .metadata("attack on titan")
+                .expect("read")
+                .and_then(|record| record.metadata)
+                .and_then(|found| found.backdrop_url)
+        };
+
+        catalog
+            .set_enrichment(
+                "attack on titan",
+                ProviderId::AniList,
+                2,
+                &Enrichment::default(),
+            )
+            .expect("enrich");
+        assert_eq!(backdrop(&catalog).as_deref(), Some("old.jpg"));
+
+        let enrichment = Enrichment {
+            backdrop_url: Some("fanart.jpg".into()),
+            ..Enrichment::default()
+        };
+        catalog
+            .set_enrichment("attack on titan", ProviderId::AniList, 3, &enrichment)
+            .expect("enrich again");
+        assert_eq!(backdrop(&catalog).as_deref(), Some("fanart.jpg"));
+
+        catalog.set_metadata(&record).expect("match again");
+        assert!(catalog.enrichment_ages().expect("ages").is_empty());
+    }
+
+    /// Schema v9 repairs what AniList's first episode source wrote: its
+    /// episode rows and its banners go, and the matches — hand-picked ones
+    /// included — stay.
+    #[test]
+    fn upgrading_drops_anilists_episode_rows_and_banners_but_keeps_its_matches() {
+        let conn = Connection::open_in_memory().expect("open");
+        for migration in [
+            MIGRATION_V1,
+            MIGRATION_V2,
+            MIGRATION_V3,
+            MIGRATION_V4,
+            MIGRATION_V5,
+            MIGRATION_V6,
+            MIGRATION_V7,
+            MIGRATION_V8,
+        ] {
+            conn.execute_batch(migration).expect("migrate");
+        }
+        conn.pragma_update(None, "user_version", 8)
+            .expect("set version");
+        conn.execute_batch(
+            "INSERT INTO title_metadata (title_key, provider, matched, fetched_at, remote_id,
+                                         name, kind, backdrop_url, manual)
+             VALUES ('aot', 'anilist', 1, 1, '16498', 'Attack on Titan', 'series',
+                     'banner.jpg', 1),
+                    ('got', 'tmdb', 1, 1, '1399', 'Game of Thrones', 'series',
+                     'backdrop.jpg', 0);
+             INSERT INTO episode_metadata (title_key, season, number, provider, fetched_at, name)
+             VALUES ('aot', 2, 1, 'anilist', 1, 'Season one''s first, wrongly'),
+                    ('got', 1, 1, 'tmdb', 1, 'Winter Is Coming');",
+        )
+        .expect("seed");
+
+        let catalog = Catalog::from_connection(conn).expect("upgrade");
+        let records = catalog.all_metadata().expect("read");
+        let aot = records["aot"].metadata.as_ref().expect("still matched");
+        assert!(records["aot"].manual);
+        assert_eq!(aot.backdrop_url, None);
+        assert_eq!(
+            records["got"]
+                .metadata
+                .as_ref()
+                .and_then(|got| got.backdrop_url.as_deref()),
+            Some("backdrop.jpg")
+        );
+
+        let episodes = catalog.all_episode_metadata().expect("read");
+        assert!(!episodes.contains_key("aot"));
+        assert_eq!(episodes["got"].len(), 1);
+        assert!(catalog.enrichment_ages().expect("ages").is_empty());
     }
 
     #[test]
@@ -1423,6 +1758,9 @@ mod tests {
                 &[EpisodeMetadata {
                     season: None,
                     number: 1,
+                    absolute: None,
+                    entry_season: None,
+                    entry_number: None,
                     name: Some("Fullmetal Alchemist".into()),
                     overview: None,
                     still_url: None,

crates/pstr-core/src/metadata.rs

@@ -20,7 +20,7 @@
 //! thumbnails at upload time and that client attaches none. See
 //! `docs/DEVELOPMENT.md`.
 
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 
 use serde::{Deserialize, Serialize};
 
@@ -62,7 +62,10 @@ impl ProviderId {
     /// One line on what it covers and what it costs to use.
     pub fn description(self) -> &'static str {
         match self {
-            Self::AniList => "Anime, with no API key and no account.",
+            Self::AniList => {
+                "Anime, with no API key and no account. Episode names and wide art come from \
+                 ani.zip, which is sent the matched ids."
+            }
             Self::Tmdb => "Film and television. Needs a free API key from themoviedb.org.",
         }
     }
@@ -139,6 +142,23 @@ pub struct EpisodeMetadata {
     /// anime releases name their files.
     pub season: Option<u32>,
     pub number: u32,
+    /// Its place counting straight through every season, when the provider
+    /// knows it. What an absolutely-numbered file inside a season folder —
+    /// `Attack on Titan/Season 2/… - 26.mkv` — is matched on.
+    #[serde(default)]
+    pub absolute: Option<u32>,
+    /// Its season and number counting each provider *entry* as a season: the
+    /// position of the entry it belongs to among the franchise's series
+    /// entries, and its number within that entry.
+    ///
+    /// Not TVDB's season. A release that follows AniList rather than TVDB
+    /// names Mushishi's *Zoku Shou 2* `S03`, where TVDB files it as the second
+    /// half of season two; this is what that file is answered from. See
+    /// [`EpisodeGuide::get`] for when it is allowed to be.
+    #[serde(default)]
+    pub entry_season: Option<u32>,
+    #[serde(default)]
+    pub entry_number: Option<u32>,
     pub name: Option<String>,
     pub overview: Option<String>,
     /// A frame from the episode, around 16:9.
@@ -149,6 +169,20 @@ pub struct EpisodeMetadata {
     pub air_date: Option<String>,
 }
 
+/// What enriching a matched title found: its episodes, and art the search
+/// answer did not carry.
+///
+/// Stored as one unit by `Catalog::set_enrichment`, and recorded as asked even
+/// when both are empty — a film has no episode list, and without the record it
+/// would be asked again on every match run.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Enrichment {
+    pub episodes: Vec<EpisodeMetadata>,
+    /// A 16:9 picture of the whole title, when one was found. `None` leaves
+    /// whatever backdrop the match already had.
+    pub backdrop_url: Option<String>,
+}
+
 /// Every episode a provider listed for one title, ready to look up.
 ///
 /// The lookup is the whole reason this is a type rather than a `Vec`: a file
@@ -160,16 +194,33 @@ pub struct EpisodeGuide {
     /// Keyed `(season, number)`, where `None` is the provider's own absolute
     /// numbering.
     entries: HashMap<(Option<u32>, u32), EpisodeMetadata>,
+    /// [`EpisodeMetadata::absolute`] to the key of the entry holding it.
+    absolute: HashMap<u32, (Option<u32>, u32)>,
+    /// [`EpisodeMetadata::entry_season`] and `entry_number` to the key of the
+    /// entry holding them.
+    by_entry: HashMap<(u32, u32), (Option<u32>, u32)>,
+    /// Every season some entry is filed under, for deciding when the entry
+    /// numbering may answer.
+    stated: HashSet<u32>,
 }
 
 impl EpisodeGuide {
     pub fn new(episodes: Vec<EpisodeMetadata>) -> Self {
-        Self {
-            entries: episodes
-                .into_iter()
-                .map(|episode| ((episode.season, episode.number), episode))
-                .collect(),
+        let mut guide = Self::default();
+        for episode in episodes {
+            let key = (episode.season, episode.number);
+            if let Some(absolute) = episode.absolute {
+                guide.absolute.insert(absolute, key);
+            }
+            if let (Some(season), Some(number)) = (episode.entry_season, episode.entry_number) {
+                guide.by_entry.insert((season, number), key);
+            }
+            if let Some(season) = episode.season {
+                guide.stated.insert(season);
+            }
+            guide.entries.insert(key, episode);
         }
+        guide
     }
 
     pub fn is_empty(&self) -> bool {
@@ -182,20 +233,25 @@ impl EpisodeGuide {
 
     /// What the provider says about the file numbered like this.
     ///
-    /// Tried in order: the season and number the filename states; the
-    /// provider's absolute numbering; and, for a file with no season at all,
-    /// season one. That second fallback is what makes an absolutely-numbered
-    /// release line up with a provider that files everything under a single
-    /// season — the common case for anime on TMDB.
+    /// Tried in order:
     ///
-    /// **The absolute fallback stops at season one.** A provider that numbers
-    /// straight through is one that split nothing, so its episode seven is the
-    /// seventh of the show — which is season one's, not season two's. Answering
-    /// `S02E07` with it captions every episode of every later season with the
-    /// wrong name, and a wrong caption does not look like a bug: it looks like
-    /// the library is wrong. Season two upwards is answered from an entry that
-    /// states that season or not at all — see
-    /// `Provider::seasons_are_separate_entries`.
+    /// 1. the season and number the filename states;
+    /// 2. for a file in no season or in season one, the provider's own absolute
+    ///    list, and for a file in no season, season one — what makes `#057`
+    ///    line up with TMDB filing a 64-episode anime under one season;
+    /// 3. the absolute number, into the season the file states — what makes
+    ///    `Season 2/… - 26.mkv` the second season's first episode;
+    /// 4. the entry numbering, for a season the provider files nothing under.
+    ///
+    /// **No fallback crosses into another season.** Step 2 stops at season one
+    /// and step 3 only answers inside the season the file named, because
+    /// answering `S02E07` with season one's seventh episode captions every
+    /// episode of every later season with the wrong name — and a wrong caption
+    /// does not look like a bug, it looks like the library is wrong. Step 4
+    /// only answers a season the provider has nothing filed under, so a release
+    /// numbered the provider's way is never re-read the other way: Mushoku
+    /// Tensei's second *entry* is the second half of season one, and its
+    /// `S02E01` is season two's.
     pub fn get(&self, season: Option<u32>, number: u32) -> Option<&EpisodeMetadata> {
         if let Some(found) = self.entries.get(&(season, number)) {
             return Some(found);
@@ -205,14 +261,31 @@ impl EpisodeGuide {
         {
             return Some(found);
         }
-        season
-            .is_none()
-            .then(|| self.entries.get(&(Some(1), number)))?
+        if season.is_none()
+            && let Some(found) = self.entries.get(&(Some(1), number))
+        {
+            return Some(found);
+        }
+        if let Some(found) = self
+            .absolute
+            .get(&number)
+            .and_then(|key| self.entries.get(key))
+            && (season.is_none() || found.season == season)
+        {
+            return Some(found);
+        }
+        let season = season?;
+        if self.stated.contains(&season) {
+            return None;
+        }
+        self.by_entry
+            .get(&(season, number))
+            .and_then(|key| self.entries.get(key))
     }
 
     /// Which seasons this guide actually has answers for. `None` is the
     /// provider's own absolute numbering.
-    pub fn seasons(&self) -> std::collections::HashSet<Option<u32>> {
+    pub fn seasons(&self) -> HashSet<Option<u32>> {
         self.entries
             .values()
             .map(|episode| episode.season)
@@ -335,6 +408,9 @@ mod tests {
         EpisodeMetadata {
             season,
             number,
+            absolute: None,
+            entry_season: None,
+            entry_number: None,
             name: Some(name.into()),
             overview: None,
             still_url: None,
@@ -342,6 +418,89 @@ mod tests {
         }
     }
 
+    /// An episode as ani.zip describes one: TVDB's season and number, TVDB's
+    /// absolute number, and its place in the AniList entry it came from.
+    fn numbered(
+        (season, number): (u32, u32),
+        absolute: u32,
+        (entry_season, entry_number): (u32, u32),
+        name: &str,
+    ) -> EpisodeMetadata {
+        EpisodeMetadata {
+            absolute: Some(absolute),
+            entry_season: Some(entry_season),
+            entry_number: Some(entry_number),
+            ..episode(Some(season), number, name)
+        }
+    }
+
+    fn name_of(guide: &EpisodeGuide, season: Option<u32>, number: u32) -> Option<String> {
+        guide.get(season, number).and_then(|e| e.name.clone())
+    }
+
+    /// `Attack on Titan/Season 2/[Anime Time] Attack On Titan - 26.mkv`: a
+    /// season folder full of absolutely-numbered files.
+    #[test]
+    fn an_absolute_number_in_a_season_folder_finds_that_seasons_episode() {
+        let guide = EpisodeGuide::new(vec![
+            numbered((1, 1), 1, (1, 1), "To You, in 2000 Years"),
+            numbered((2, 1), 26, (2, 1), "Beast Titan"),
+        ]);
+        assert_eq!(name_of(&guide, Some(2), 26).as_deref(), Some("Beast Titan"));
+        // And with no season at all, the absolute number is the whole answer.
+        assert_eq!(name_of(&guide, None, 26).as_deref(), Some("Beast Titan"));
+    }
+
+    /// The absolute fallback must not carry a file into a season it did not
+    /// name: `S03E13` of a show whose 13th episode is in season one is not that
+    /// episode.
+    #[test]
+    fn an_absolute_number_never_answers_for_another_season() {
+        let guide = EpisodeGuide::new(vec![
+            numbered((1, 13), 13, (1, 13), "Season one's thirteenth"),
+            numbered((3, 1), 38, (3, 1), "Smoke Signal"),
+        ]);
+        assert_eq!(guide.get(Some(3), 13), None);
+    }
+
+    /// Mushishi: TVDB files both halves of *Zoku Shou* as season two, and the
+    /// release calls the second half `S03`. Season three exists nowhere at the
+    /// provider, so the entry numbering answers it.
+    #[test]
+    fn a_season_the_provider_does_not_have_is_answered_by_entry() {
+        let guide = EpisodeGuide::new(vec![
+            numbered((1, 1), 1, (1, 1), "The Green Seat"),
+            numbered((2, 1), 28, (2, 1), "The Hand That Caresses the Night"),
+            numbered((2, 11), 39, (3, 1), "Lightning's End"),
+        ]);
+        assert_eq!(
+            name_of(&guide, Some(3), 1).as_deref(),
+            Some("Lightning's End")
+        );
+        assert_eq!(
+            name_of(&guide, Some(2), 1).as_deref(),
+            Some("The Hand That Caresses the Night")
+        );
+    }
+
+    /// Mushoku Tensei: AniList's second entry is the second half of TVDB's
+    /// season one. A release numbered TVDB's way names season two `S02`, and
+    /// the entry numbering must not answer it with that second half.
+    #[test]
+    fn the_entry_numbering_never_overrides_a_season_the_provider_has() {
+        let guide = EpisodeGuide::new(vec![
+            numbered((1, 12), 12, (2, 1), "Cour two's first"),
+            numbered((2, 1), 26, (3, 1), "Season two's first"),
+        ]);
+        assert_eq!(
+            name_of(&guide, Some(2), 1).as_deref(),
+            Some("Season two's first")
+        );
+        // A second-season episode the provider does not list is unanswered,
+        // not answered from the entry numbering.
+        assert_eq!(guide.get(Some(2), 2), None);
+    }
+
     #[test]
     fn a_file_that_states_its_season_is_answered_from_that_season() {
         let guide = EpisodeGuide::new(vec![