ersatztv/docs/decisions/records/api/selection-projection-include-chain.md

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics

key	title	status	since	supersedes	superseded-by	rule	signals	mechanics
api.selection-projection-include-chain	2026-07-28 — A tagged-union selection is projected through one shared include chain, and its flattening switch never falls through to null (#671)	active	2026-07-28	none	none	Every handler that projects an aggregate carrying a tagged-union selection loads it through ONE shared `<Aggregate>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.	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	`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.