@jant/core 0.6.8 → 0.6.9

package/src/services/__tests__/media.test.ts

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion -- Test assertions use ! for readability */
 import { describe, it, expect, beforeEach, vi } from "vitest";
+import { eq } from "drizzle-orm";
 import {
   createTestDatabase,
   DEFAULT_TEST_SITE_ID,
@@ -7,6 +8,7 @@ import {
 import { createMediaService } from "../media.js";
 import { createPostService } from "../post.js";
 import type { Database } from "../../db/index.js";
+import { storagePurge } from "../../db/schema.js";
 import { MediaQuotaExceededError } from "../../lib/errors.js";
 import { now } from "../../lib/time.js";
 
@@ -55,9 +57,21 @@ function createMockStorage() {
     async delete(key: string) {
       files.delete(key);
     },
+    async copy(sourceKey: string, destKey: string) {
+      const file = files.get(sourceKey);
+      if (file) files.set(destKey, { ...file });
+    },
   };
 }
 
+/** Storage mock without server-side copy (e.g. R2 Workers binding). */
+function createNoCopyStorage() {
+  const full = createMockStorage();
+  const { copy: _copy, ...rest } = full;
+  void _copy;
+  return rest;
+}
+
 describe("MediaService", () => {
   let db: Database;
   let mediaService: ReturnType<typeof createMediaService>;
@@ -504,7 +518,7 @@ describe("MediaService", () => {
   });
 
   describe("delete for text attachments", () => {
-    it("removes the single .md storage object", async () => {
+    it("moves the .md object to trash and frees the original key", async () => {
       const storage = createMockStorage();
       const media = await mediaService.createTextAttachment(
         {
@@ -522,13 +536,18 @@ describe("MediaService", () => {
 
       await mediaService.delete(media.id, storage);
 
-      expect(storage.files.size).toBe(0);
+      // Row gone and the original (public) key freed immediately; the bytes
+      // live on under a trash/ key, recoverable until purge.
+      expect(await mediaService.getById(media.id)).toBeNull();
       expect(storage.files.has(media.storageKey)).toBe(false);
+      expect(
+        [...storage.files.keys()].some((k) => k.startsWith("trash/")),
+      ).toBe(true);
     });
   });
 
   describe("deleteByIds for text attachments", () => {
-    it("removes the .md file for every text attachment in the batch", async () => {
+    it("moves every .md object in the batch to trash", async () => {
       const storage = createMockStorage();
       const a = await mediaService.createTextAttachment(
         { contentFormat: "markdown", content: "first" },
@@ -543,7 +562,14 @@ describe("MediaService", () => {
 
       await mediaService.deleteByIds([a.id, b.id], storage);
 
-      expect(storage.files.size).toBe(0);
+      expect(await mediaService.getById(a.id)).toBeNull();
+      expect(await mediaService.getById(b.id)).toBeNull();
+      // Originals freed; two trash copies remain until the purge sweep.
+      expect(storage.files.has(a.storageKey)).toBe(false);
+      expect(storage.files.has(b.storageKey)).toBe(false);
+      expect(
+        [...storage.files.keys()].filter((k) => k.startsWith("trash/")).length,
+      ).toBe(2);
     });
   });
 
@@ -1006,6 +1032,30 @@ describe("MediaService", () => {
       expect(ids).toEqual([orphan.id]);
     });
 
+    it("excludes site asset media (avatars, favicons) referenced by settings", async () => {
+      const orphan = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/site/files/orphan.jpg",
+      });
+      const avatar = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/site/assets/avatar/avatar.png",
+      });
+      const favicon = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/site/assets/favicon/apple-touch-icon.png",
+      });
+
+      const ids = await mediaService.listOrphanedMediaIds({
+        before: now() + 1,
+        limit: 10,
+      });
+
+      expect(ids).toEqual([orphan.id]);
+      expect(ids).not.toContain(avatar.id);
+      expect(ids).not.toContain(favicon.id);
+    });
+
     it("excludes media created at or after the cutoff", async () => {
       await mediaService.create({
         ...sampleMedia,
@@ -1305,25 +1355,24 @@ describe("MediaService", () => {
       expect(result).toBe(false);
     });
 
-    it("deletes poster from storage when posterKey exists", async () => {
+    it("moves storage objects to trash and frees the original keys", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/vid.mp4", new Uint8Array([1]));
+      await storage.put("media/vid.poster.webp", new Uint8Array([2]));
       const media = await mediaService.create({
         ...sampleMedia,
         storageKey: "media/vid.mp4",
         posterKey: "media/vid.poster.webp",
       });
 
-      const deletedKeys: string[] = [];
-      const mockStorage = {
-        delete: async (key: string) => {
-          deletedKeys.push(key);
-        },
-        put: async () => {},
-        get: async () => null,
-      };
+      await mediaService.delete(media.id, storage);
 
-      await mediaService.delete(media.id, mockStorage as never);
-      expect(deletedKeys).toContain("media/vid.mp4");
-      expect(deletedKeys).toContain("media/vid.poster.webp");
+      // Originals freed immediately; both objects moved under trash/.
+      expect(storage.files.has("media/vid.mp4")).toBe(false);
+      expect(storage.files.has("media/vid.poster.webp")).toBe(false);
+      expect(
+        [...storage.files.keys()].filter((k) => k.startsWith("trash/")).length,
+      ).toBe(2);
     });
   });
 
@@ -1357,7 +1406,11 @@ describe("MediaService", () => {
       expect(await mediaService.getById(m1.id)).not.toBeNull();
     });
 
-    it("deletes poster keys from storage", async () => {
+    it("moves storage objects to trash and frees the original keys", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/a.mp4", new Uint8Array([1]));
+      await storage.put("media/a-poster.webp", new Uint8Array([2]));
+      await storage.put("media/b.jpg", new Uint8Array([3]));
       const m1 = await mediaService.create({
         ...sampleMedia,
         storageKey: "media/a.mp4",
@@ -1368,20 +1421,128 @@ describe("MediaService", () => {
         storageKey: "media/b.jpg",
       });
 
-      const deletedKeys: string[] = [];
-      const mockStorage = {
-        delete: async (key: string) => {
-          deletedKeys.push(key);
-        },
-        put: async () => {},
-        get: async () => null,
-      };
+      await mediaService.deleteByIds([m1.id, m2.id], storage);
+
+      // Three originals freed, three trash copies remain.
+      expect(storage.files.has("media/a.mp4")).toBe(false);
+      expect(storage.files.has("media/a-poster.webp")).toBe(false);
+      expect(storage.files.has("media/b.jpg")).toBe(false);
+      expect(
+        [...storage.files.keys()].filter((k) => k.startsWith("trash/")).length,
+      ).toBe(3);
+    });
+  });
+
+  describe("storage purge (recycle window)", () => {
+    const FAR_FUTURE = () => now() + 365 * 24 * 60 * 60;
+
+    it("moves a deleted object to trash with a recorded original_key", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/x.jpg", new Uint8Array([1]));
+      const m = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/x.jpg",
+      });
+
+      await mediaService.delete(m.id, storage);
+
+      const rows = await db
+        .select()
+        .from(storagePurge)
+        .where(eq(storagePurge.siteId, DEFAULT_TEST_SITE_ID));
+      expect(rows).toHaveLength(1);
+      expect(rows[0]!.originalKey).toBe("media/x.jpg");
+      expect(rows[0]!.storageKey.startsWith("trash/")).toBe(true);
+      expect(storage.files.has(rows[0]!.storageKey)).toBe(true);
+      expect(storage.files.has("media/x.jpg")).toBe(false);
+    });
+
+    it("purges trashed objects once due (storageKey + posterKey)", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/v.mp4", new Uint8Array([1]));
+      await storage.put("media/v-poster.webp", new Uint8Array([2]));
+      const m = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/v.mp4",
+        posterKey: "media/v-poster.webp",
+      });
+      await mediaService.delete(m.id, storage);
+
+      const purged = await mediaService.purgeDueStorageObjects(
+        { before: FAR_FUTURE(), limit: 50, provider: "r2" },
+        storage,
+      );
+
+      expect(purged).toBe(2);
+      expect(storage.files.size).toBe(0);
+    });
+
+    it("retains trash whose recycle window has not elapsed", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/keep.jpg", new Uint8Array([1]));
+      const m = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/keep.jpg",
+      });
+      await mediaService.delete(m.id, storage);
+
+      // before = now → the 30-day-out purge_after is not yet due.
+      const purged = await mediaService.purgeDueStorageObjects(
+        { before: now(), limit: 50, provider: "r2" },
+        storage,
+      );
+
+      expect(purged).toBe(0);
+      // Original freed, but the trash copy is retained.
+      expect(storage.files.has("media/keep.jpg")).toBe(false);
+      expect(
+        [...storage.files.keys()].some((k) => k.startsWith("trash/")),
+      ).toBe(true);
+    });
+
+    it("deletes immediately with no recycle when the driver lacks copy", async () => {
+      const storage = createNoCopyStorage();
+      await storage.put("media/nocopy.jpg", new Uint8Array([1]));
+      const m = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/nocopy.jpg",
+      });
+
+      await mediaService.delete(m.id, storage);
+
+      // Deleted outright; nothing in trash, nothing queued.
+      expect(storage.files.size).toBe(0);
+      const rows = await db
+        .select()
+        .from(storagePurge)
+        .where(eq(storagePurge.siteId, DEFAULT_TEST_SITE_ID));
+      expect(rows).toHaveLength(0);
+    });
+
+    it("respects the batch limit", async () => {
+      const storage = createMockStorage();
+      await storage.put("media/p1.jpg", new Uint8Array([1]));
+      await storage.put("media/p2.jpg", new Uint8Array([2]));
+      const m1 = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/p1.jpg",
+      });
+      const m2 = await mediaService.create({
+        ...sampleMedia,
+        storageKey: "media/p2.jpg",
+      });
+      await mediaService.deleteByIds([m1.id, m2.id], storage);
+
+      const purged = await mediaService.purgeDueStorageObjects(
+        { before: FAR_FUTURE(), limit: 1, provider: "r2" },
+        storage,
+      );
 
-      await mediaService.deleteByIds([m1.id, m2.id], mockStorage as never);
-      expect(deletedKeys).toContain("media/a.mp4");
-      expect(deletedKeys).toContain("media/a-poster.webp");
-      expect(deletedKeys).toContain("media/b.jpg");
-      expect(deletedKeys).toHaveLength(3);
+      expect(purged).toBe(1);
+      // One trash object purged, one remains.
+      expect(
+        [...storage.files.keys()].filter((k) => k.startsWith("trash/")).length,
+      ).toBe(1);
     });
   });
 });

package/src/services/__tests__/settings.test.ts

@@ -446,6 +446,61 @@ describe("SettingsService", () => {
       expect(await settingsService.get("SITE_LANGUAGE")).toBe("en");
     });
 
+    it("stores a valid dashboard language and reports the change", async () => {
+      const result = await settingsService.updateLocaleSettings(
+        {
+          siteLanguage: "fr",
+          dashboardLanguage: "zh-Hant",
+          cjkSerifFont: "off",
+          timeZone: "UTC",
+        },
+        { oldLanguage: "fr", oldDashboardLanguage: "" },
+      );
+
+      expect(result.languageChanged).toBe(true);
+      expect(await settingsService.get("SITE_LANGUAGE")).toBe("fr");
+      expect(await settingsService.get("DASHBOARD_LANGUAGE")).toBe("zh-Hant");
+    });
+
+    it("clears DASHBOARD_LANGUAGE when dashboard language is blank", async () => {
+      await settingsService.set("DASHBOARD_LANGUAGE", "zh-Hans");
+      await settingsService.updateLocaleSettings(
+        {
+          siteLanguage: "en",
+          dashboardLanguage: "",
+          cjkSerifFont: "off",
+          timeZone: "UTC",
+        },
+        { oldLanguage: "en", oldDashboardLanguage: "zh-Hans" },
+      );
+
+      expect(await settingsService.get("DASHBOARD_LANGUAGE")).toBeNull();
+    });
+
+    it("leaves DASHBOARD_LANGUAGE untouched when not provided", async () => {
+      await settingsService.set("DASHBOARD_LANGUAGE", "zh-Hans");
+      await settingsService.updateLocaleSettings(
+        { siteLanguage: "en", cjkSerifFont: "off", timeZone: "UTC" },
+        { oldLanguage: "en" },
+      );
+
+      expect(await settingsService.get("DASHBOARD_LANGUAGE")).toBe("zh-Hans");
+    });
+
+    it("rejects a dashboard language Jant is not translated into", async () => {
+      await expect(
+        settingsService.updateLocaleSettings(
+          {
+            siteLanguage: "en",
+            dashboardLanguage: "fr",
+            cjkSerifFont: "off",
+            timeZone: "UTC",
+          },
+          { oldLanguage: "en" },
+        ),
+      ).rejects.toThrow();
+    });
+
     it("updates grouped feed, home, and search settings independently", async () => {
       await settingsService.updateFeedSettings({ mainRssFeed: "latest" });
       await settingsService.updateHomeBranding(true);

package/src/services/bootstrap.ts

@@ -13,6 +13,7 @@ import {
   baseLocale,
   isValidContentLanguage,
   normalizeContentLanguage,
+  resolveCatalogLocale,
 } from "../i18n/locales.js";
 import { createNavItemService } from "./navigation.js";
 import { createSettingsService } from "./settings.js";
@@ -65,6 +66,12 @@ export function createBootstrapService(
           ? normalizeContentLanguage(data.siteLanguage)
           : baseLocale;
       await settings.set("SITE_LANGUAGE", siteLanguage);
+      // Pin the dashboard UI locale to the detected catalog language so it stays
+      // stable if the operator later changes the public content language.
+      await settings.set(
+        "DASHBOARD_LANGUAGE",
+        resolveCatalogLocale(siteLanguage),
+      );
       if (data.cjkSerifFont && data.cjkSerifFont !== "off") {
         await settings.set("CJK_SERIF_FONT", data.cjkSerifFont);
       }

package/src/services/export-theme/layouts/_default/baseof.html

@@ -1,7 +1,8 @@
 <!doctype html>
 {{- $lang := .Site.LanguageCode | default "en" -}}
 {{- $themeMode := .Site.Params.theme_mode | default "auto" -}}
-<html lang="{{ $lang }}"{{ if ne $themeMode "auto" }} data-theme-mode="{{ $themeMode }}"{{ end }}>
+{{- $themeId := .Site.Params.theme_id -}}
+<html lang="{{ $lang }}"{{ with $themeId }} data-theme="{{ . }}"{{ end }}{{ if ne $themeMode "auto" }} data-theme-mode="{{ $themeMode }}"{{ end }}>
   <head>
     {{ partial "head.html" . }}
   </head>

package/src/services/media.ts

@@ -4,7 +4,18 @@
  * Handles media upload and management with pluggable storage backends.
  */
 
-import { eq, desc, inArray, asc, sql, and, or, isNull, lt } from "drizzle-orm";
+import {
+  eq,
+  desc,
+  inArray,
+  asc,
+  sql,
+  and,
+  or,
+  isNull,
+  lt,
+  lte,
+} from "drizzle-orm";
 import { generateKeyBetween } from "fractional-indexing";
 import { type Database, supportsDrizzleTransaction } from "../db/index.js";
 import type { DatabaseDialect } from "../db/dialect.js";
@@ -16,11 +27,12 @@ import { createEntityId } from "../lib/ids.js";
 import { markdownToTiptapJson } from "../lib/markdown-to-tiptap.js";
 import { extractBodyText } from "../lib/summary.js";
 import { now } from "../lib/time.js";
-import type { StorageDriver } from "../lib/storage.js";
+import { supportsCopy, type StorageDriver } from "../lib/storage.js";
 import { renderTiptapJson } from "../lib/tiptap-render.js";
 import { tiptapJsonToMarkdown } from "../lib/tiptap-to-markdown.js";
 import {
   generateStorageKey,
+  SITE_ASSET_STORAGE_KEY_LIKE_PATTERN,
   toMediaKind,
   validateUploadFileMetadata,
 } from "../lib/upload.js";
@@ -45,6 +57,15 @@ import type { HostedControlPlaneClient } from "../lib/hosted-control-plane.js";
 
 const DEFAULT_MEDIA_POSITION = "a0";
 
+/**
+ * Recycle-window length for deleted media storage objects. On delete we
+ * hard-remove the DB row but defer deleting the underlying storage object
+ * until this long afterwards (recorded in `storage_purge`), so an accidental
+ * delete is recoverable. R2 has no versioning/undelete, so this is our only
+ * safety net for the bytes.
+ */
+const STORAGE_PURGE_RETENTION_SECONDS = 30 * 24 * 60 * 60;
+
 /**
  * MIME type stored on disk and on the `media` row for a Jant-composed text
  * attachment. Markdown is the canonical source — HTML is rendered on read,
@@ -183,20 +204,38 @@ export interface MediaService {
    */
   validateIds(ids: string[]): Promise<void>;
   /**
-   * Delete a media record and its storage file.
+   * Delete a media record. The DB row is removed immediately. When `storage` is
+   * provided and supports server-side copy, the object is moved to a `trash/`
+   * key and its original key is deleted now (original URL 404s immediately,
+   * bytes recoverable until purge); otherwise the object is deleted immediately.
    *
    * @param id - Media record ID
-   * @param storage - Optional storage driver; when provided the file is deleted from storage
+   * @param storage - Storage driver used to retire the object
    * @returns true if the record existed and was deleted
    */
   delete(id: string, storage?: StorageDriver | null): Promise<boolean>;
   /**
-   * Delete multiple media records and their storage files.
+   * Delete multiple media records. Rows are removed immediately; their storage
+   * objects are retired (moved to trash, or deleted) via `storage`.
    *
    * @param ids - Media record IDs
-   * @param storage - Optional storage driver; when provided the files are deleted from storage
+   * @param storage - Storage driver used to retire the objects
    */
   deleteByIds(ids: string[], storage?: StorageDriver | null): Promise<void>;
+  /**
+   * Physically delete trashed storage objects whose recycle window has elapsed.
+   * Called by the upload cleanup sweep; removes the queue entry for each.
+   *
+   * @param input.before - Unix-seconds cutoff; only entries with `purgeAfter <= before` are processed
+   * @param input.limit - Maximum number of queue entries to process (batch bound)
+   * @param input.provider - Only process entries for this storage provider (the active driver)
+   * @param storage - Storage driver used to delete the objects
+   * @returns Number of storage objects actually deleted
+   */
+  purgeDueStorageObjects(
+    input: { before: number; limit: number; provider: string },
+    storage: StorageDriver,
+  ): Promise<number>;
   getByStorageKey(storageKey: string, provider: string): Promise<Media | null>;
   /**
    * Return IDs of orphaned media — rows never attached to a post
@@ -291,7 +330,91 @@ export function createMediaService(
     hostedControlPlane?: HostedControlPlaneClient | null;
   },
 ): MediaService {
-  const { media } = databaseSchema;
+  const { media, storagePurge } = databaseSchema;
+
+  /**
+   * Build the recycle-bin key for a deleted object. Each retired object gets a
+   * unique `trash/<siteId>/<id>/<basename>` key so trash entries never collide
+   * and the original (public) key can be freed immediately.
+   */
+  function trashStorageKey(id: string, originalKey: string): string {
+    const basename = originalKey.split("/").pop() || "object";
+    return `trash/${siteId}/${id}/${basename}`;
+  }
+
+  /**
+   * Retire the storage object(s) backing the given media rows. When the driver
+   * supports server-side copy, each object is moved to a `trash/` key (recorded
+   * in `storage_purge`) and its original key is deleted immediately — so the
+   * original public URL 404s right away while the bytes stay recoverable until
+   * `purge_after`. Drivers without server-side copy (e.g. the R2 Workers
+   * binding) fall back to immediate deletion with no recycle window. All
+   * storage ops are best-effort so a backend hiccup never blocks the row delete.
+   */
+  async function retireStorageObjects(
+    records: Media[],
+    storage: StorageDriver | null | undefined,
+    reason: string,
+  ): Promise<void> {
+    if (!storage || records.length === 0) return;
+
+    const objects = records.flatMap((record) => {
+      const keys = [record.storageKey];
+      if (record.posterKey) keys.push(record.posterKey);
+      return keys.map((key) => ({ provider: record.provider, key }));
+    });
+
+    if (!supportsCopy(storage)) {
+      // No server-side copy: delete immediately (no recycle window).
+      await Promise.all(
+        objects.map((o) =>
+          storage.delete(o.key).catch((err) => {
+            // eslint-disable-next-line no-console -- Error logging is intentional
+            console.error("Storage delete error:", err);
+          }),
+        ),
+      );
+      return;
+    }
+
+    const purgeAfter = now() + STORAGE_PURGE_RETENTION_SECONDS;
+    const createdAt = now();
+    const entries: Array<typeof storagePurge.$inferInsert> = [];
+    for (const o of objects) {
+      const id = createEntityId("storagePurge");
+      const trashKey = trashStorageKey(id, o.key);
+      try {
+        await storage.copy(o.key, trashKey);
+      } catch (err) {
+        // Copy failed: delete the original anyway rather than leave it stranded
+        // at its public URL. No recycle entry for this object.
+        // eslint-disable-next-line no-console -- Error logging is intentional
+        console.error("Storage trash copy error:", err);
+        await storage.delete(o.key).catch((e) => {
+          // eslint-disable-next-line no-console -- Error logging is intentional
+          console.error("Storage delete error:", e);
+        });
+        continue;
+      }
+      await storage.delete(o.key).catch((err) => {
+        // eslint-disable-next-line no-console -- Error logging is intentional
+        console.error("Storage delete error:", err);
+      });
+      entries.push({
+        id,
+        siteId,
+        provider: o.provider,
+        storageKey: trashKey,
+        originalKey: o.key,
+        reason,
+        purgeAfter,
+        createdAt,
+      });
+    }
+    if (entries.length > 0) {
+      await db.insert(storagePurge).values(entries);
+    }
+  }
 
   async function getLastPosition(postId: string): Promise<string | null> {
     const rows = await db
@@ -524,6 +647,10 @@ export function createMediaService(
             eq(media.siteId, siteId),
             isNull(media.postId),
             lt(media.createdAt, before),
+            // Site assets (avatars, favicons) are stored with postId = null and
+            // referenced from site settings, not posts. Exclude them so the
+            // reaper never deletes them as abandoned compose uploads.
+            sql`${media.storageKey} NOT LIKE ${SITE_ASSET_STORAGE_KEY_LIKE_PATTERN}`,
           ),
         )
         .orderBy(asc(media.createdAt), asc(media.id))
@@ -920,22 +1047,9 @@ export function createMediaService(
       const record = await this.getById(id);
       if (!record) return false;
 
-      if (storage) {
-        // Text attachments have a single `.md` object — same shape as any
-        // other media — so no sibling cleanup is needed. Only video/image
-        // rows carry a companion poster.
-        await storage.delete(record.storageKey).catch((err) => {
-          // eslint-disable-next-line no-console -- Error logging is intentional
-          console.error("Storage delete error:", err);
-        });
-        if (record.posterKey) {
-          await storage.delete(record.posterKey).catch((err) => {
-            // eslint-disable-next-line no-console -- Error logging is intentional
-            console.error("Storage delete poster error:", err);
-          });
-        }
-      }
-
+      // Move the bytes to trash (recoverable) and free the original key now, so
+      // the original public URL 404s immediately. Then remove the row.
+      await retireStorageObjects([record], storage, "media-delete");
       await db
         .delete(media)
         .where(and(eq(media.siteId, siteId), eq(media.id, id)));
@@ -945,28 +1059,41 @@ export function createMediaService(
     async deleteByIds(ids, storage) {
       if (ids.length === 0) return;
 
-      if (storage) {
-        const records = await this.getByIds(ids);
-        const keys: string[] = [];
-        for (const record of records) {
-          keys.push(record.storageKey);
-          if (record.posterKey) {
-            keys.push(record.posterKey);
-          }
-        }
-        await Promise.all(
-          keys.map((key) =>
-            storage.delete(key).catch((err) => {
-              // eslint-disable-next-line no-console -- Error logging is intentional
-              console.error("Storage delete error:", err);
-            }),
-          ),
-        );
-      }
-
+      const records = await this.getByIds(ids);
+      await retireStorageObjects(records, storage, "media-delete");
       await db
         .delete(media)
         .where(and(eq(media.siteId, siteId), inArray(media.id, ids)));
     },
+
+    async purgeDueStorageObjects({ before, limit, provider }, storage) {
+      if (limit <= 0) return 0;
+      const dueRows = await db
+        .select()
+        .from(storagePurge)
+        .where(
+          and(
+            eq(storagePurge.siteId, siteId),
+            eq(storagePurge.provider, provider),
+            lte(storagePurge.purgeAfter, before),
+          ),
+        )
+        .orderBy(asc(storagePurge.purgeAfter), asc(storagePurge.id))
+        .limit(limit);
+
+      let purged = 0;
+      for (const row of dueRows) {
+        // `storageKey` is the trash key; it is never referenced by a live media
+        // row, so no liveness check is needed — just delete it and drop the entry.
+        await storage.delete(row.storageKey).catch((err) => {
+          // eslint-disable-next-line no-console -- Error logging is intentional
+          console.error("Storage purge delete error:", err);
+        });
+        await db.delete(storagePurge).where(eq(storagePurge.id, row.id));
+        purged += 1;
+      }
+
+      return purged;
+    },
   };
 }