B1-5..B1-20: distill remaining code behaviors into specs (rendering.allium, post/media/task/generation/editor specs)

specs/media.allium

@@ -11,6 +11,7 @@ surface MediaControlSurface {
     provides:
         ImportMediaRequested(source_path, project, metadata)
         UpdateMediaRequested(media, changes)
+        ReplaceMediaFileRequested(media, new_source_path)
         DeleteMediaRequested(media)
         UpsertMediaTranslationRequested(media, language, title, alt, caption)
         RebuildMediaFromFilesRequested(project)
@@ -158,6 +159,28 @@ rule UpdateMedia {
     ensures: SearchIndexUpdated(media)
 }
 
+rule ReplaceMediaFile {
+    when: ReplaceMediaFileRequested(media, new_source_path)
+    -- Replaces the binary at media.file_path with the new source file,
+    -- keeping the same path/id. Sidecar metadata (title/alt/etc.) is preserved.
+    let checksum = md5(read(new_source_path))
+    -- Identical content (checksum = media.checksum): no-op, nothing rewritten.
+    -- Otherwise the old file is backed up to {path}.bak (restored on failure,
+    --   removed on success) and the row is updated from the new file:
+    if checksum != media.checksum:
+        ensures: media.checksum = checksum
+        ensures: media.size = file_size(new_source_path)
+        ensures: media.updated_at = now
+        ensures: MediaDimensionsUpdated(media)
+            -- width/height re-read from the new image
+        ensures: SidecarWritten(media)
+        if media.is_image:
+            ensures: ThumbnailsRegenerated(media)
+                -- Synchronous (awaited), not fire-and-forget
+        ensures: SearchIndexUpdated(media)
+        -- See engine_side_effects.allium ReplaceMediaFileSideEffects
+}
+
 rule DeleteMedia {
     when: DeleteMediaRequested(media)
     ensures: not exists media