diff --git a/ErsatzTV.Tests/Application/Paging/MediaCardsCountMatchesPageTests.cs b/ErsatzTV.Tests/Application/Paging/MediaCardsCountMatchesPageTests.cs index a71b5fc76..096184579 100644 --- a/ErsatzTV.Tests/Application/Paging/MediaCardsCountMatchesPageTests.cs +++ b/ErsatzTV.Tests/Application/Paging/MediaCardsCountMatchesPageTests.cs @@ -88,9 +88,11 @@ public class MediaCardsCountMatchesPageTests // pages EpisodeMetadata, so only 2 are reachable and the count must say 2. await using (TvContext context = _db.CreateContext()) { - // the full graph: GetPagedEpisodes's include chain walks Episode -> Season -> Show -> - // ShowMetadata, and a missing Show drops every row, so a partial seed would make the - // page 0 for a reason that has nothing to do with the count under test + // GetPagedEpisodes's include chain reaches Episode -> Season -> Show through REQUIRED + // reference navs, which EF emits as INNER JOINs, so a missing Season or Show row drops + // every row and would make the page 0 for a reason unrelated to the count under test. + // The ShowMetadata leg is a COLLECTION nav (LEFT JOIN) and drops nothing — the row below + // is incidental, seeded only to keep the graph realistic. context.Shows.Add(new Show { Id = 1 }); context.ShowMetadata.Add(new ShowMetadata { Id = 201, ShowId = 1, Title = "Show", Year = 2000 }); context.Seasons.Add(new Season { Id = 11, ShowId = 1, SeasonNumber = 1 }); diff --git a/docs/decisions/records/api/paged-count-matches-page-query.md b/docs/decisions/records/api/paged-count-matches-page-query.md index 842fb1fd5..8a7415da7 100644 --- a/docs/decisions/records/api/paged-count-matches-page-query.md +++ b/docs/decisions/records/api/paged-count-matches-page-query.md @@ -6,8 +6,8 @@ since: '2026-08-26' supersedes: none superseded-by: none rule: 'A handler that returns a page plus a total count builds ONE `IQueryable`, applies every filter to it, and then derives BOTH the count and the page from that single object — `int count = await query.CountAsync(ct)` followed by `query.Include(...).OrderBy(...).Skip(...).Take(...)`. Counting the `DbSet` directly, or re-stating the predicate in a second `CountAsync(pred, ct)`, is the defect: the two expressions are then free to drift and nothing reports it. This is not a style preference — the drifted state is SILENT and shaped like working software. The page is correct, the count is wrong, and the client trusts the count: the SPA paginates on `TotalCount`, so 40 rows with 3 matching a search renders 4 pages of which 3 are permanently empty (#690), and an MCP agent paging to a completeness target reads a `totalCount` its own page can never reach (#758). Scope that harm honestly — of the six, only `GetPagedRerunCollections`, `GetPagedMultiCollections` and `GetPagedPlayouts` reach a controller today; `GetPagedCollections`, `GetPagedSmartCollections` and `GetPagedProgramSchedules` have no production caller (their REST routes use unpaged `GetAll*` queries), so they were latent, not live. Both named issues were ONE mechanism at six sites, of which the issues named two: `GetPagedCollections`, `GetPagedMultiCollections`, `GetPagedRerunCollections`, `GetPagedSmartCollections`, `GetPagedPlayouts`, `GetPagedProgramSchedules`. THE FILTER IS NOT ONLY THE SEARCH STRING — `GetPagedPlayouts` also applies `Filter(p => p.Channel != null)` to the page, and counting the DbSet missed that too; that clause is DEFENSIVE rather than a live defect, because `Playout.ChannelId` is non-nullable with `DeleteBehavior.Cascade` and both production connection strings set `foreign keys=true`, so the orphan state is unreachable while the FK holds. Two corollaries. (1) INCLUDES BELONG TO THE PAGE CHAIN, not to the shared filtered query: a COUNT does not materialize the graph, so `.Include(...)`/`IncludeSelectionDetails()` are appended after the count is taken, which keeps `api.selection-projection-include-chain` intact while leaving one predicate source. (2) A HANDLER WITH NO FILTER STILL TAKES THE SHAPE — `GetPagedFillerPresets` and `GetPagedTraktLists` take no `Query` parameter, so their `DbSet` counts were not WRONG, but leaving them counting one expression while paging another preserves exactly the drift this record is about for whoever adds the first filter. They derive both from one query too. (3) THE POPULATION IS DERIVED FROM THE SHAPE, NOT FROM THE `GetPaged*` NAME — three further count+page producers in `ErsatzTV.Application/MediaCards` (`GetTelevisionSeasonCards`, `GetTelevisionEpisodeCards`, `GetMusicVideoCards`) carry the same drift across a REPOSITORY boundary, where the count and the page are two interface methods rather than two expressions, so the structural fix cannot apply and they are pinned by a test instead (`MediaCardsCountMatchesPageTests`). `GetSeasonCount` now expands to the same Title+Year show set `GetPagedSeasons` pages; `GetEpisodeCount` and `GetMusicVideoCount` now count the METADATA table their pages are taken from, so a media item whose metadata row is missing no longer inflates the total. Their 1-based `pageNumber` is a separate defect against `api.paging-zero-based` and stays open in #832.' -signals: 'TotalCount ignores the search query · filtered page reports the unfiltered total · SPA renders empty pages after a search · agent pages to a completeness target it can never reach · count the same query you page · one predicate applied to both so they cannot drift · CountAsync on the DbSet · Channel != null missing from the count · includes belong to the page chain not the counted query · an unfiltered paged handler takes the shape too · a repository count and its page are two methods that must be pinned by a test · paths: `ErsatzTV.Application/MediaCollections/Queries/GetPagedCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedMultiCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedRerunCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedSmartCollectionsHandler.cs`, `ErsatzTV.Application/Playouts/Queries/GetPagedPlayoutsHandler.cs`, `ErsatzTV.Application/ProgramSchedules/Queries/GetPagedProgramSchedulesHandler.cs`, `ErsatzTV.Tests/Application/Paging/PagedQueryTotalCountTests.cs` · issues: #758, #690, #671, #757' -mechanics: 'Pinned per-handler by `PagedQueryTotalCountTests`, one test per filtering paged handler, each asserting a LITERAL expected count and the expected page contents. No repo-wide detector is proposed — see the record body for why the obvious one is not reliable.' +signals: 'TotalCount ignores the search query · filtered page reports the unfiltered total · SPA renders empty pages after a search · agent pages to a completeness target it can never reach · count the same query you page · one predicate applied to both so they cannot drift · CountAsync on the DbSet · Channel != null missing from the count · includes belong to the page chain not the counted query · an unfiltered paged handler takes the shape too · a repository count and its page are two methods that must be pinned by a test · paths: `ErsatzTV.Application/MediaCollections/Queries/GetPagedCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedMultiCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedRerunCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedSmartCollectionsHandler.cs`, `ErsatzTV.Application/Playouts/Queries/GetPagedPlayoutsHandler.cs`, `ErsatzTV.Application/ProgramSchedules/Queries/GetPagedProgramSchedulesHandler.cs`, `ErsatzTV.Application/Filler/Queries/GetPagedFillerPresetsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedTraktListsHandler.cs`, `ErsatzTV.Infrastructure/Data/Repositories/TelevisionRepository.cs`, `ErsatzTV.Infrastructure/Data/Repositories/MusicVideoRepository.cs`, `ErsatzTV.Tests/Application/Paging/PagedQueryTotalCountTests.cs`, `ErsatzTV.Tests/Application/Paging/MediaCardsCountMatchesPageTests.cs` · issues: #758, #690, #671, #757' +mechanics: 'TWO enforcement modes, because the rule has two shapes. Where the count and the page are expressions in one handler, the STRUCTURE carries it (one `IQueryable`) and `PagedQueryTotalCountTests` pins one test per filtering paged handler. Where they are separate repository methods (`MediaCards`), nothing structural is available and `MediaCardsCountMatchesPageTests` pins their agreement instead. Both assert LITERAL expected counts and expected page contents. No repo-wide detector is proposed — see the record body for why the obvious one is not reliable.' --- **The two issues were filed as separate bugs on separate entities, and they are one mechanism.** @@ -40,12 +40,17 @@ constructs each divergence and asserts `count == pageable rows`. The seasons count has a THIRD answer nobody would guess from the count alone — with no `ShowMetadata` row there is nothing to expand from, so `GetPagedSeasons` returns nothing and the count must be 0 rather than the show's season total; that case is pinned separately. And an include chain can filter more narrowly than -the count: `GetPagedEpisodes` walks `Episode -> Season -> Show -> ShowMetadata`, and a missing `Show` -row drops every row, so count 1 / page 0 is reachable. Scope that honestly, the same way the -`Channel != null` clause above is scoped — `Season.ShowId` is non-nullable with `DeleteBehavior.Cascade` -and production enforces the FK, so this is a corruption-only state, not something a user can reach. It -is stated because "count the table the page reads" is then necessary and NOT sufficient as a general -rule, not because a live defect is being left open; #832 carries it. +the count, in ALL THREE pairs rather than the one it was first noticed in: a REQUIRED reference +`Include` is emitted as an INNER JOIN, so `GetPagedEpisodes` (`Episode -> Season -> Show`), +`GetPagedSeasons` (`Include(s => s.Show)`) and `GetPagedMusicVideos` (`ThenInclude(mv => mv.Artist)`) +each return nothing when the principal row is absent, while the corrected count still counts. A +COLLECTION `Include` such as `Show.ShowMetadata` is a LEFT JOIN and drops nothing — the distinction +is the whole mechanism, so do not read "an include filters" as a blanket claim. Scope the consequence +honestly, the same way the `Channel != null` clause above is scoped: `Season.ShowId` and +`MusicVideo.ArtistId` are non-nullable with `DeleteBehavior.Cascade` and production enforces the FK, +so count-N / page-0 is a corruption-only state no user can reach. It is stated because it makes +"count the table the page reads" necessary and NOT sufficient as a general rule, not because a live +defect is being left open; #832 carries it. **`GetBlockPlayoutHistory`, `GetFuturePlayoutItemsById` and `GetLibraryBrowseItems` already did this** — they build the filtered query, count it, then page it. The idiom was in the repo; the six