ersatztv/docs/decisions/archive/scan.md

Archive — library scanning / media-server reconciliation

Superseded/retired records for the media-server library scanners and their reconciliation strategies. See docs/decisions/archive/README.md for the archive's general rules (rationale kept verbatim, never in the active read-path). Active successor for music-video reconciliation: scan.musicvideo-server-identity in docs/decisions.md.

---

2026-07-20 — JellyfinMusicVideoLibraryScanner reconciles by library-scoped path diff + hard delete, not server itemId soft-trash (#494)

key: scan.musicvideo-reconciliation · status: superseded · since: 2026-07-20 · supersedes: none · superseded-by: scan.musicvideo-server-identity@2026-07-25 Rule: (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. Signals: 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 Mechanics: 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.