fix(xtream): preserve favorites across catalog refreshes

libs/shared/database/README.md

@@ -46,13 +46,30 @@ root is resolved in this order:
 Users may skip releases. The application must apply every required migration in
 dependency order when opening an older database, preserving user data without
 requiring intermediate application installations or a database reset. This is
-the repository policy mirrored in `AGENTS.md` and `CLAUDE.md`.
+the repository policy in `AGENTS.md`, which `CLAUDE.md` imports.
 
 `src/lib/connection.ts` owns initialization: `createTables()` creates missing
 schema objects, then `runMigrations()` applies column/index migrations and
 dedicated schema/data upgrades. One-off data migrations can record completion
 in `app_state`. Keep existing migration paths when adding new ones.
 
+Xtream favorites are migrated by `src/lib/favorites-table.ts` before legacy
+content/category deduplication. The transactional table rebuild backfills typed
+provider identity and saved display metadata while retaining favorite IDs,
+dates and positions. Duplicate favorites of the same playlist/type/provider ID
+collapse to the earliest favorite record. `content_id` becomes nullable with
+`ON DELETE SET NULL`; owning playlist deletion still cascades. The legacy
+content deduplicator updates references without replacing favorite IDs.
+Favorites whose owning playlist was already missing remain stored. The rebuild
+temporarily disables foreign-key enforcement outside its transaction, permits
+only those pre-existing playlist violations by favorite ID, and rolls back if
+it introduces another violation. The original enforcement setting is restored
+on both success and failure.
+Historical upgrade tests include tagged 0.19–0.24 schemas, duplicate categories,
+orphaned favorites, repeated startup and forced rollbacks. Keep snapshot
+migration before content deduplication so the originally favorited row's
+metadata survives.
+
 When changing initialization:
 
 - Create required tables before migrating them. `CREATE TABLE IF NOT EXISTS`
@@ -102,7 +119,7 @@ playlists) are guarded in `runMigrations()`:
 The #1580 index-ordering fix is included in 0.24 through PR #1550.
 `src/lib/connection-upgrades.spec.ts` exercises `initDatabase()` with real
 SQLite under the Electron runtime, using fresh-install schema snapshots from
-tags 0.19–0.23 and a fresh current database. The `epg_channel_id` column is absent
+tags 0.19–0.24 and a fresh current database. The `epg_channel_id` column is absent
 in 0.19, present from 0.20, and indexed from 0.23. Each case checks current Drizzle
 tables, columns/types, and named indexes/uniqueness, as well as preserved user
 rows, foreign keys, database integrity, index availability, and repeated startup;
@@ -115,3 +132,6 @@ the index ahead of its column migration makes the 0.19 case fail again.
 Run this coverage with `pnpm nx test database --runInBand`. The Electron UI and
 worker upgrade flow is also covered by
 `pnpm nx run electron-backend-e2e:e2e-ci--src/legacy-playlist-migration.e2e.ts`.
+For an orphaned 0.24 favorites table, initial startup and restart through the
+real Electron UI and worker are covered by
+`pnpm nx run electron-backend-e2e:e2e-ci--src/favorites-legacy.e2e.ts`.