ersatztv/docs/decisions/archive/scan/musicvideo-reconciliation.md

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

key	title	status	since	supersedes	superseded-by	rule	signals	mechanics
scan.musicvideo-reconciliation	2026-07-20 — `JellyfinMusicVideoLibraryScanner` reconciles by library-scoped path diff + hard delete, not server itemId soft-trash (#494)	superseded	2026-07-20	none	scan.musicvideo-server-identity@2026-07-25	(superseded) `JellyfinMusicVideoLibraryScanner` reconciles removed music videos by a library-scoped local-path diff plus hard delete (`TrashMissingMusicVideos`), not the server-itemId soft-trash pattern the other media-server scanners use, because music videos carry no server identity.	music-video trash sweep, path-based identity, cross-kind safety, path-keyed identity, empty-fetch guard reuse, remove-stale+add-new dedup · paths: `JellyfinMusicVideoLibraryScanner.TrashMissingMusicVideos`, `FindMusicVideoPaths`/`DeleteByPath`, `IMusicVideoRepository`, `MediaServerReconciliationGuard` · issues: #494, #477, #488, #496, #500	`ScanLibrary_Should_Not_CrossDelete_Movie_Or_Show_Sharing_The_LibraryPath`; `ScanLibrary_Should_Not_Sweep_When_Jellyfin_Returns_Zero_Items`; integration tests extending the #488 harness. #500 — when mirroring the remove-stale + add-new idiom, dedup the incoming set on **the same key its add filter compares** (the filter is materialized before the loop mutates `existing`, so duplicates both pass): `Name`, `Guid` for guids, and for Plex `Actors` an artwork-preferring dedup shared with the remove filter (whose key is `(Name, artwork-presence)`). Remaining un-deduped copies of the idiom: #600. Superseded by `scan.musicvideo-server-identity` (ersatztv#496): music videos gained a `JellyfinMusicVideo` ItemId/Etag identity, so the path diff + hard delete became an itemId diff + soft `FileNotFound` trash.

The Jellyfin music-video scanner did add/update only — a music video removed on the Jellyfin side lingered in ErsatzTV forever and could still be scheduled. It now runs a trash sweep at the end of ScanLibrary (TrashMissingMusicVideos), mirroring the MediaServer{Movie,Television,OtherVideo}LibraryScanner "gone upstream ⇒ remove" pattern but with a deliberately different identity function, because music videos lack the media-server identity those base scanners rely on.

• Identity is (LibraryPathId, path), not server itemId. The base scanners diff GetExisting* (keyed by MediaServerItemId) against the incoming server item ids, then soft-trash via FlagFileNotFound. Music videos have no JellyfinMusicVideo entity and no ItemId/Etag — the scanner is a standalone IJellyfinMusicVideoLibraryScanner that injects the local IMusicVideoRepository, which offers no itemId-keyed existing-set or flag seam. So the sweep diffs the local path set instead: existing = FindMusicVideoPaths(libraryPath) .Except the incoming items' replaced local paths, then hard-deletes the remainder with DeleteByPath + IScannerProxy.RemoveMediaItems, and cleans now-empty artists with IArtistRepository.DeleteEmptyArtists. Hard delete (not soft FileNotFound trash) because there is no per-item FileNotFound seam on this path and the issue's Done-when is "removed".
• Cross-kind safety is a property of the queries, not the media kind. MediaItem is TPT with LibraryPathId on the abstract base, so a Movie, Show and MusicVideo can share one LibraryPath (a mixed Jellyfin library). Both FindMusicVideoPaths and DeleteByPath filter LibraryPathId and join the concrete MusicVideo table, so the sweep can only ever see/delete music videos — a Movie/Show under the same LibraryPath is invisible to it. Pinned by ScanLibrary_Should_Not_CrossDelete_Movie_Or_Show_Sharing_The_LibraryPath.
• Reuses the #477 empty-fetch guard. The sweep is gated by MediaServerReconciliationGuard.ShouldFlagMissing — a successful fetch that returns zero items (server mid-restore / transient) is indistinguishable from a real emptying, so the whole-library wipe is refused and logged. Pinned as a negative control by ScanLibrary_Should_Not_Sweep_When_Jellyfin_Returns_Zero_Items (removing the guard flips it red).
• Known limitation (deferred to per-library identity). MusicVideoRepository.GetOrAdd dedups a path globally (no LibraryPathId predicate), so a file served by two libraries with overlapping local paths is a single row owned by whichever library scanned it first. If that owner later stops reporting the file while another library still serves it, this sweep removes the shared row. A proper fix needs per-library music-video identity (a JellyfinMusicVideo etag entity + migration) — the issue's "option 2 / fold into the base scanner" refactor — tracked as #496.
• Tests. Integration tests (real ArtistRepository/MusicVideoRepository/LibraryRepository over in-memory SQLite, extending the #488 harness) pin removal, empty-artist cleanup, cross-kind safety, and the empty-fetch guard. Proven non-vacuous: all four fail against the pre-fix scanner except the guard control, which only earns its keep once the sweep exists.