9.9 KiB
Phase 3: the library becomes the truth, the old Hero tables and the switches go
Status (2026-11-18): steps 3a and 3b are BUILT on feature/media-library-phase2 (3b behind a switch that is off by default); step 3c (dropping the old table and the switches) is NOT built and NOT run. Rules from Bryan, relayed by SLS-Main: build it only after phase 2 is verified on test; dropping the old tables only on TEST, with a back-up and rollback plan and a notice to SLS-Main first; never on production without a separate go from Bryan; no PR for the phase-2/3 branch before #22 is merged.
Where phase 2 leaves us
- The Hero tables (
HeroImages,HeroSlides) are the truth. The library tables (MediaAssets,MediaUses) mirror them (write-through,DualWrite) and the library screen can read them (ReadFromLibrary). - The library tables do not hold what the Hero needs to publish: the variants of a set (
Variants), the set hash of the photo, and the slide crops and sets as columns. So the Hero admin and the public hero still read the Hero tables.
What phase 3 does
| Step | What | Reversible? |
|---|---|---|
| 3a Expand | Add to the library tables what the Hero needs: MediaAssets.SetHash, MediaAssets.Variants (JSON), the photo's crops as columns (not only the default focus), MediaUses.Variants (the use's own set) and its crop columns (today only the JSON in Crops). Additive migration of the Media module. The write-through fills them; a verified backfill copies existing rows. |
Yes: drop the new columns; nothing reads them yet. |
| 3b Switch | The Hero reads and writes its photos and slides through a library store (IMediaLibraryStore, Core interface, implemented by the Media module) instead of HeroImages/HeroSlides: upload, crops, renderer, trash, restore, purge, public mapping, clean-up. Behind a setting (Media:Library:HeroUsesLibrary, default off) with the old code path kept for one release; compare mode first (both paths run, differences are logged). |
Yes: switch off; the old tables are still complete as long as the write-through to them (the reverse mirror) is on. |
| 3c Contract | A separate migration drops HeroImages, the photo columns of HeroSlides and HeroRetiredFiles (or moves it), and the code removes the three switches (CopyOnStartup, DualWrite, ReadFromLibrary), the copier and the mirror. |
Only from a back-up. TEST only until Bryan gives a separate go. |
Public addresses (/media/hero/<setHash>/...), ids and hashes stay as they are in every step; the golden files must not change.
Prerequisites (the gate before 3b and 3c)
- Phase 2 verified on test by Bryan:
GET media-library/read-checksaysmatches: true, the library screen withReadFromLibrary=onlooks the same, crops per slide work (assumptions 47-50). - A restore point of the test sites taken right before each step (the script of Pi-Main,
test-herstelpunt.sh; path recorded inphase2-design.md), plus the row counts and a sample of ten public addresses before and after. - SLS-Main is told before every deploy of 3a, 3b and 3c.
Tests to write before building 3b (can be written now against the current code)
- The Hero service tests run through an
IHeroPhotoStoreabstraction twice, once on the Hero tables and once on an in-memory library store, and must give the same answers (upload, same photo twice, crop per slide, trash, restore, purge, clean-up, public mapping, golden files). - A migration test on MariaDB for 3a (additive, backfill verified, rollback with
Down). - A contract test for 3c on MariaDB: after the drop, every Hero endpoint still answers the same (smoke test of the public hero and the admin).
Rollback per step
| Step | Rollback |
|---|---|
| 3a | Down of the Media migration (drops the new columns). |
| 3b | HeroUsesLibrary=off; the old tables are complete because the old path was kept in sync. |
| 3c | Restore the database dump of the restore point, then deploy the previous release; the media directory is never changed destructively (retired sets stay for the retention time). |
Open points for Bryan (assumed until he says otherwise)
- 3c is a separate release after a quiet period on test (assumption: at least a week), not part of the first rollout of phase 2.
- The clean-up job of the Hero (
HeroMediaCleanup) moves to the library in 3b, so other modules can use the same retention rules.
As built: 3a and 3b (2026-11-18)
3a, expand (Media migration AddHeroPhotoColumns, additive): MediaAssets gets SetHash, Variants (the hero's own JSON), WideFocusX/Y/Zoom, TallFocusX/Y/Zoom; MediaUses gets Variants. The verified copy, the write-through and the read check fill and compare them (a difference in the set or variants shows in the library check).
3b, the switch (Hero migration DropSlideImageForeignKey + switch Media__Library__HeroPhotosInLibrary, default off):
- The migration drops only the foreign key
FK_HeroSlides_HeroImages_ImageId(a slide may point at a photo that is only inMediaAssets). It has aDownthat puts it back. The model snapshot is deliberately unchanged. The service layer already checks that a photo exists and is not removed while a slide uses it. - With the switch on, the Hero's photo entity is mapped to the library table: rows of
MediaAssetswith modulehero(columnsDefaultFocusX/Y/Zoom, aModulecolumn set tohero, a query filter on it). Everything else in the hero (services, renderer, public mapping, clean-up) is unchanged and runs on those rows. The library owns that table and its migrations; the hero's context excludes it from its own. HeroImagesstays a complete copy while the switch is on (HeroLegacyImageMirrorafter every saved change), so switching back loses nothing.- Start-up guard: with the switch on, the application refuses to start (clear message in the log) unless the library holds every photo of
HeroImageswith the same hash, set and variants. So the order is fixed: copy first, library check, then the switch. - Public addresses, ids and hashes are unchanged; the golden files are untouched.
Order on test (each step a deploy, SLS-Main tells Bryan):
- Deploy with
media_library_copy=on(andmedia_library_dual_write=on): the migrations run and the copy fills the new columns for the existing photos. Open "Controle bibliotheek": it must say that the library matches the hero (it now also compares set and variants). - Deploy with
media_library_hero_photos=on. If the guard refuses to start, the log says why; set the switch back to off. - Check the hero admin (upload, crop a slide, save, trash and restore) and the public site; the library check still matches.
- Rollback at any time:
media_library_hero_photos=off(the application readsHeroImagesagain, a complete copy). To undo the foreign-key migration too: theDownofDropSlideImageForeignKey. Last resort: the restore point of the test sites.
Step 3c (not built): drop HeroImages and the legacy mirror, remove the three media switches and the copier, make the library table the only home. Needs: Bryan's verification of 3b on test, a notice to SLS-Main with the exact migration, a fresh restore point; test only.
Step 3c as built (2026-11-18) - on its own branch, NOT deployed
Branch feature/media-library-phase3c (from feature/media-library-phase2). It is a separate branch on purpose: dispatching phase2 can never carry the destructive migration by accident. It is code, docs and tests only; nothing has been run on a test host.
What it removes
- The three migration switches and everything behind them:
Media__Library__CopyOnStartupand the copier,DualWriteand the write-through (IMediaLibrarySync),ReadFromLibraryand the reader/compare mode (IMediaLibraryReader),HeroPhotosInLibraryand the legacy mirror, the start-up guard and the storage switch (HeroStorage, model cache key). - The "Controle bibliotheek" panel, the
read-checkendpoint and the migration source (IMediaMigrationSource,HeroMediaMigrationSource). Bryan: keep the panel until 3b is verified on test, then remove it together with the other migration aids (so: in this step). - The four workflow inputs (
media_library_copy,_dual_write,_read,_hero_photos) and their deploy steps.
What it makes permanent: the hero's photos are rows of the library's MediaAssets (module hero, filter and Module column in the hero's model; the table and its migrations belong to the Media module). MediaUses is no longer written or read (it stays in the database, empty of meaning; dropping it is a later clean-up).
The destructive migration: Hero DropHeroImagesTable (DROP TABLE HeroImages). Protected twice:
HeroImagesDropGuardruns before the migrations at start-up: when that migration is pending andHeroImagesholds rows, it throws (the application does not start, nothing is dropped) unless every row is inMediaAssets(module hero) with the same hash, set and variants, or whenMediaAssetsdoes not exist. A new database (nothing inHeroImages) passes.- The restore point of the test sites, taken right before the deploy.
Downbrings back the EMPTY table (data comes from the restore point). Tested on MariaDB: refused with a missing photo, refused with a different set, dropped when the library holds everything, Down recreates the empty table.
Order on test (needs Bryan's OK on 3b and a notice to SLS-Main with this exact migration): (1) 3b verified: copy done, library check matches, HeroPhotosInLibrary=on verified by Bryan and live for a quiet period; (2) fresh restore point (Pi-Main script); (3) deploy feature/media-library-phase3c (the switches no longer exist; the variable Media__Library__HeroPhotosInLibrary in shared/env can stay, it is ignored); (4) check the hero admin, the public site and the library screen. Rollback: restore the restore point and deploy the previous release; Down only gives the empty table.
Not tested here: the deploy itself, the media directory on the Pi, the production database (never).