Clarify the 'missing episode' definition and AniDB_GroupStatus refresh behavior

[harshithmohan]

Background

While investigating a user-facing inconsistency, I found two related questions worth settling as a team. Both revolve around what "missing episode" means and where the release-group data that one definition depends on comes from.

The divergence

/v3/Series → Sizes.Missing.Episodes and /v3/MissingEpisodes report different numbers for the same series.

Example: for a currently-airing series where a recent episode's AniDB air date has passed but no release group has actually produced it yet:

• Sizes.Missing.Episodes counts it (non-hidden, aired regular episode, no local file).
• /v3/MissingEpisodes does not list it (it additionally requires a release group to have reached that episode).

So a series can show "1 missing episode" in Sizes while the missing-episodes endpoint returns nothing (or fewer) for the same series.

Why they differ

The two features encode two different notions of "missing":

Endpoint	Definition	Basis
/v3/Series → Sizes	aired-but-absent	air date (no group-status check)
/v3/MissingEpisodes	released-but-absent	release-group progress (AniDB_GroupStatus)

Sizes.Missing.Episodes (ModelHelper.GenerateSeriesSizes) is computed in-memory: not hidden + EpisodeType == Episode + no local file + HasAired. It never reads AniDB_GroupStatus.

/v3/MissingEpisodes (AnimeEpisodeRepository.GetMissing) is a SQL query that adds a group-status gate: an episode counts only if it's aired/unknown and no file exists and (AniDB_GroupStatus has no rows or some group has CompletionState IN (3,5) or LastEpisodeNumber >= the episode).

Second part: AniDB_GroupStatus goes stale (this is a defect, not a decision)

The "released-but-absent" definition depends on AniDB_GroupStatus, which is only ever written by GetAniDBReleaseGroupStatusJob. That job is not part of the standard anime-refresh path — it's only triggered from the legacy v1 API (initial-load at ShokoServiceImplementation_Entities.cs:1784, "Get Updated" at :1823). There is no recurring job and no v3 trigger.

Consequences:

• With a v3-only install (v1 disabled by default), GS data stops updating after the initial pull.
• This makes the "released-but-absent" set under-count: episodes aired since the last GS refresh are treated as "not yet released," so the missing-episodes list lags reality. This is the root cause of the divergence above once GS data goes stale.

GetAniDBReleaseGroupStatusJob.ShouldSkip() already handles the ended-anime case (skips only when ended > 50 days ago, unless ForceRefresh), so there's no technical reason it can't run on a normal refresh.

Decision needed

Which definition of "missing" should be canonical?

• A. Aired-but-absent — simpler, more predictable, but flags episodes that no group has actually released (arguably "not yet out," not "missing").
• B. Released-but-absent — more accurate to "actually obtainable," but depends on GS data staying fresh (see defect below).
• C. Keep both, but document/label which each endpoint uses — preserve current behavior, just be explicit.

Whichever we pick, the Sizes counter and the MissingEpisodes endpoints should agree (or clearly communicate the distinction).

Proposed follow-up (actionable either way)

Run GetAniDBReleaseGroupStatusJob (force refresh) as part of the anime-refresh pipeline (e.g. GetUpdatedAniDBAnimeJob / the remote refresh path) so AniDB_GroupStatus stays current without depending on the legacy v1 API.

[da3dsoul]

So, it worked that way for an obvious reason. We had the data.
To determine missing episodes, we really only have a few ways to do it, in order of accuracy:

• From a group you are collecting (group status)
• From a group you aren't collecting (group status)
• An episode exists and has an air date in the past (anime info)
• A series has an end date and episode count that doesn't match the number of episodes you have (math, probably from bad data, needs an anime refresh)

[harshithmohan]

Should we change the /v3/Series/{SeriesID} endpoint to also match this logic so there is no divergence between them?

[da3dsoul]

They should use a shared helper, yes

[da3dsoul]

A problem with group status is that it can be stale, as mentioned. A problem with not using group status is that it's actually not uncommon for an episode to be added when it's announced, such as a special announcement, but then no one ever uploads it.

[harshithmohan]

The current issue with group status is not that it can be stale. It is always stale as it's never refreshed on any path. Shouldn't we refresh it when the anime info gets refreshed?

[da3dsoul]

Yes