--- key: api.selection-projection-include-chain title: '2026-07-28 — A tagged-union selection is projected through one shared include chain, and its flattening switch never falls through to null (#671)' status: active since: '2026-07-28' supersedes: none superseded-by: none rule: 'Every handler that projects an aggregate carrying a tagged-union selection loads it through ONE shared `QueryExtensions` include chain — `RerunCollectionQueryExtensions.IncludeSelectionDetails()`, joining the existing `ProgramScheduleItemQueryExtensions.IncludeScheduleItemDetails()` — called by the paged-list handler and the by-id handler alike, so the two cannot drift. The media-item flattening switch is likewise ONE shared helper, `MediaCollections.Mapper.ProjectMediaItemToViewModel`, covering all ten selectable media types including `RemoteStream`, whose named projection is `MediaItems.Mapper.ProjectToNamedViewModel` (it cannot be an overload of `ProjectToViewModel(RemoteStream)`, which already exists returning the unrelated `RemoteStreamViewModel`; C# will not overload on return type). That switch NEVER ends in `_ => null`: a null MediaItem is the legitimate not-a-media-item case, while an unrecognized non-null subtype keeps its id and takes a conspicuous `[unsupported media type: X]` name. Fail-soft is deliberate — throwing would fail an entire paged GET over one unreadable row. Finally, every metadata navigation inside `MediaItems.Mapper` is read through `Optional(...).Flatten()` and degrades to the `"???"` placeholder, because those projections are reached from handlers whose include chains differ and a bare `x.Season.Show.ShowMetadata` is a latent 500 on some other caller GET.' signals: 'rerun collection null selection, selectedId null for every row, list badge renders Collection with no name, detail GET 500 on Episode, detail GET 500 on MusicVideo, RemoteStream dropped by the mapper, underscore arrow null fallthrough, AsNoTracking suppresses navigation fixup, eager load missing on paged list, Include after Skip Take, EpisodeTitle NullReferenceException, MusicVideoTitle bare Artist deref, ShowTitle bare Show deref, id only as available as the name, editor silently clears stored selection, ArgumentNullException value cannot be null parameter values, string.Join on null sequence, SongMetadata Artists is null, nullable primitive collection not a navigation, untagged song fallback metadata, playout guide 500 on a song, song artist prefix bare dash, chaptered song renders ErsatzTV.Core.Domain.Song, GetDisplayTitle interpolates the entity not the title · paths: `ErsatzTV.Application/MediaCollections/RerunCollectionQueryExtensions.cs`, `ErsatzTV.Application/MediaCollections/Mapper.cs`, `ErsatzTV.Application/MediaItems/Mapper.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetPagedRerunCollectionsHandler.cs`, `ErsatzTV.Application/MediaCollections/Queries/GetRerunCollectionByIdHandler.cs`, `docs/api-conventions.md` §2a · issues: #671, #651, #229' mechanics: '`RerunCollectionQueryExtensions.IncludeSelectionDetails`; `Mapper.ProjectMediaItemToViewModel`; `MediaItems.Mapper.ProjectToNamedViewModel`; `SelectionSeedData` (`SupportedSelectionTypes`, `ExpectedName`, `SeedSelection`, `ApplySelection`); `RerunCollectionQueryHandlerTests` (`GetById_Should_Resolve_The_Selection`, `GetPaged_Should_Resolve_The_Selection`, `Supported_Selection_Types_Should_Be_The_Full_Documented_Set`, `GetById_Should_Tolerate_Song_Artists`); `GetPlaylistItemsHandlerTests`; `Playouts.Mapper.GetDisplayTitle` + `PlayoutMapperDisplayTitleTests`; `RerunCollectionRequestMapping.IsSupportedSelectionType`' --- Applies the `#229` shared-include-chain remedy to the READ path — that record framed it as a write-path concern; this is its mirror image, where the GET itself under-loaded. ## The coupling that hid the bug The id and the display name are read off the SAME navigation, so the id is only ever as available as the name — the API never knows WHICH item is selected but not what it is called. Hence the symptom looked like a naming problem (an unlabelled badge) when the real harm is one level down: the selected id is null too, and an editor that round-trips it clears the stored selection. #651's client-side merge-instead-of-replace guard made this survivable and stays, but patched a server defect from the client. The rule: never let the id and the name share a single point of failure — hence the `_ => null` ban, where an unrecognized subtype surrenders its NAME, never its ID. Fail-soft, not a throw, which would fail a whole paged GET over one bad row. (`ProgramSchedules.Mapper`'s switch does throw, correctly — it dispatches on the ITEM type, an internal closed set.) ## Scope deliberately not widened Nine further media-item switches (`ProgramSchedules.Mapper` ×4, `Scheduling.Mapper` ×5) handle only Show/Season/Artist — not the same oversight, since those call sites genuinely restrict selection to those three and load a matching chain. Only RerunCollection and PlaylistItem span the full set, so exactly those two were merged. A THIRD consumer, `ReplacePlaylistItemsHandler`, projects items whose navigations are never loaded — inert only because the controller discards the result and re-queries. **Widening a shared switch incurs a debt in every caller loading for it**, discharged by a TEST, not by inspection — inspection is the method that produced this bug. `GetPlaylistItemsHandler` had no handler-level test at all (its controller tests stub the mediator), so it gained the same 13-type matrix via the shared `SelectionSeedData`. ## `Artists` is a nullable PRIMITIVE COLLECTION, and the sweep must follow the field `SongMetadata.Artists` is a nullable EF primitive collection — a JSON array in one column, **not a navigation** — left unassigned by `FallbackMetadataProvider` when a song's tags fail to read, and `string.Join` throws `ArgumentNullException`, not `NullReferenceException`. So a "null navigation" audit misses it and so does a grep for `NullReferenceException`. The guard is `Optional(sm.Artists).Flatten()`, empty filtered too so an artist-less song loses its bare `" - "`. Two corrections, because a wrong explanation outlives a wrong line. It was **not** introduced here: `GetPlaylistItemsHandler` already included `SongMetadata` on `origin/main` and already routed `Song`, so `GET /api/v1/playlists/{id}/items` was ALREADY a live 500 — this branch only made the same throw reachable on a second path. And fixing the rerun site alone left the mirror standing: `Playouts/Mapper` had the identical unguarded join on a path that also eager-loads `SongMetadata`, likewise live, swept here. `LibraryBrowseItemMapper` already wrote `Artists ?? []`, so the codebase knew. Filed separately: `SongVideoGenerator` dereferences `Artists.Count`/`.Contains` on the playback path. Sweep by FIELD. Adjacent, same review, fixed here: that Song arm interpolated the `case Song s` ENTITY into its chapter branch, rendering a chaptered song as the literal `ErsatzTV.Core.Domain.Song (Chapter 3)`. ## Verification worth repeating Every mechanism was removed in turn and quoted red before restoring it: stripping the list include chain failed all 13 types on "lost its selected id"; the original four-type by-id chain failed exactly the six the issue named; reverting the bare dereferences reproduced `NullReferenceException` for Episode and MusicVideo; reverting either `Artists` guard reproduced `ArgumentNullException`; and reverting the chapter fix rendered the type name. A green test proves little until shown to fail. The per-type assertion pins the WHOLE expected string, not merely "is not a placeholder", because the looser form cannot see a missing NESTED leg: drop Episode → Season → Show and the projection still reads `s00e04 - Selected episode`, placeholder-free, and passes. Relatedly an absent Season renders `s??`, never `s00`, which means Specials and would fabricate plausible-looking real data.