@glw907/cairn-cms 0.58.0 → 0.59.0

package/src/lib/components/admin-icons.ts

@@ -29,3 +29,4 @@ export { default as RefreshCwIcon } from '@lucide/svelte/icons/refresh-cw';
 export { default as GitBranchIcon } from '@lucide/svelte/icons/git-branch';
 export { default as ArrowRightIcon } from '@lucide/svelte/icons/arrow-right';
 export { default as MegaphoneIcon } from '@lucide/svelte/icons/megaphone';
+export { default as DatabaseIcon } from '@lucide/svelte/icons/database';

package/src/lib/log/events.ts

@@ -23,6 +23,8 @@ export type CairnLogEvent =
   | 'media.resolve_missing'
   | 'media.deleted'
   | 'media.delete_blocked'
+  | 'media.bulk_deleted'
+  | 'media.orphans_purged'
   | 'media.replaced'
   | 'media.replace_blocked'
   | 'media.alt_propagated';

package/src/lib/media/bulk-delete-plan.ts

@@ -0,0 +1,54 @@
+// cairn-cms: the pure core of the bulk-delete safety floor. Given a STRICT usage index, the selected
+// hashes, and the media manifest, it partitions the selection into what is safe to delete and what is
+// skipped, with the reason. The gate is membership in the passed strict index, never a display count:
+// the caller builds the index with strict:true (see usage.ts) so a transient branch-read failure
+// fails the whole build rather than making a still-referenced asset look orphaned. This function
+// stays pure so the same verdict is testable without a repo round trip and so the destructive action
+// that consumes it can be reviewed against a fixed input.
+import type { UsageEntry, UsageIndex } from './usage.js';
+import type { MediaManifest } from './manifest.js';
+
+/** One selected hash that is not deleted, with why and (for the where-used) its usage rows. The rows
+ *  are present only for 'still-referenced'; an 'uncommitted' skip carries an empty list. */
+export interface BulkDeleteSkip {
+  hash: string;
+  reason: 'still-referenced' | 'uncommitted';
+  usage: UsageEntry[];
+}
+
+/** The partitioned selection: the hashes safe to purge and the hashes held back. Both arrays keep the
+ *  input order of `selected` so the screen reports them in the order the user picked. */
+export interface BulkDeletePlan {
+  deletable: string[];
+  skipped: BulkDeleteSkip[];
+}
+
+/**
+ * Partition `selected` against a strict usage index and the media manifest.
+ *
+ * A hash with one or more usage rows is skipped 'still-referenced', carrying those rows for the
+ * where-used. A hash with no usage row and no committed manifest row is skipped 'uncommitted', since
+ * there is nothing committed to delete. A hash with no usage row and a committed manifest row is
+ * deletable. The input order of `selected` is preserved in both output arrays.
+ */
+export function planBulkDelete(
+  selected: string[],
+  index: UsageIndex,
+  manifest: MediaManifest,
+): BulkDeletePlan {
+  const deletable: string[] = [];
+  const skipped: BulkDeleteSkip[] = [];
+
+  for (const hash of selected) {
+    const usage = index.get(hash);
+    if (usage && usage.length > 0) {
+      skipped.push({ hash, reason: 'still-referenced', usage });
+    } else if (manifest[hash]) {
+      deletable.push(hash);
+    } else {
+      skipped.push({ hash, reason: 'uncommitted', usage: [] });
+    }
+  }
+
+  return { deletable, skipped };
+}

package/src/lib/media/orphan-scan.ts

@@ -0,0 +1,74 @@
+// cairn-cms: the orphan-scan projection, the pure model behind the admin Media Library's scan
+// surface. It folds reconcileMedia's two directions together with the usage index into the two rows
+// the screen renders: the purgeable byte-rows and the read-only broken-reference rows (manifest rows
+// whose bytes are gone). It only projects; no path here reads R2, the manifest, or git. The module
+// is engine-internal and on no public subpath.
+//
+// An orphaned byte is a stored R2 object whose hash has NO manifest row AND appears in NO usage row,
+// so it is referenced nowhere across main and every open branch. Reconcile only checks main's
+// manifest, so a branch-only upload (bytes in R2, manifest row only on the open cairn/* branch) gets
+// flagged as an orphaned object even though a colleague's in-progress draft references it. The byte
+// purge is irreversible, so we intersect reconcile's verdict with the strict cross-branch usage
+// index here: any hash the index references is in use and is dropped from orphanedBytes, which keeps
+// a live draft's bytes from ever reaching the purge surface.
+import { MEDIA_KEY_RE, type ReconcileResult } from './reconcile.js';
+import type { MediaManifest } from './manifest.js';
+import type { UsageEntry, UsageIndex } from './usage.js';
+
+/** A purgeable orphan: a stored R2 key with no manifest row, plus the 16-hex hash parsed from it. */
+export interface OrphanByteRow {
+  /** The full R2 object key, e.g. "media/ff/ffffffffffffffff.webp". */
+  key: string;
+  /** The 16-hex content hash parsed from the key. */
+  hash: string;
+}
+
+/** A broken reference: a manifest row whose bytes are gone. Read-only, since purging it would drop a
+ *  still-referenced asset's record; the screen shows where it is used so an operator can re-ingest. */
+export interface BrokenRefRow {
+  /** The 16-hex content hash of the manifest row whose bytes are missing. */
+  hash: string;
+  /** The manifest row's display slug, or '' when the row is somehow absent. */
+  slug: string;
+  /** Where the asset is referenced, from the usage index. Empty when no reference was found. */
+  usage: UsageEntry[];
+}
+
+/** The scan surface model: the two row sets the Library renders. */
+export interface OrphanScan {
+  orphanedBytes: OrphanByteRow[];
+  brokenRefs: BrokenRefRow[];
+}
+
+/**
+ * Project a reconcile read plus the usage index into the scan surface model.
+ *
+ * `orphanedBytes` come from `reconcile.orphanedObjects`: each key is parsed to its hash via the
+ * shared media-key grammar, and a key that does not match (so it is not a content-addressed media
+ * object) is skipped. A key whose hash the usage index references is also skipped: it is referenced
+ * on main or some open branch, so its bytes are in use, not orphaned. `brokenRefs` come from
+ * `reconcile.missingObjects`: each hash carries its
+ * manifest slug (falling back to '' when the row is absent) and its where-used rows from the index
+ * (an empty list when no reference was found). Both directions keep their input order.
+ */
+export function buildOrphanScan(
+  reconcile: ReconcileResult,
+  manifest: MediaManifest,
+  index: UsageIndex,
+): OrphanScan {
+  const orphanedBytes: OrphanByteRow[] = [];
+  for (const key of reconcile.orphanedObjects) {
+    const hash = MEDIA_KEY_RE.exec(key)?.[1];
+    if (hash === undefined) continue;
+    if (index.has(hash)) continue;
+    orphanedBytes.push({ key, hash });
+  }
+
+  const brokenRefs: BrokenRefRow[] = reconcile.missingObjects.map((hash) => ({
+    hash,
+    slug: manifest[hash]?.slug ?? '',
+    usage: index.get(hash) ?? [],
+  }));
+
+  return { orphanedBytes, brokenRefs };
+}

package/src/lib/media/reconcile.ts

@@ -8,8 +8,9 @@
 import type { MediaManifest } from './manifest.js';
 import { log } from '../log/index.js';
 
-/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. */
-const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
+ *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar. */
+export const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
 
 /** What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
  *  has no manifest row; `missingObjects` are manifest hashes with no stored object. */

package/src/lib/sveltekit/cairn-admin.ts

@@ -186,6 +186,12 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
     mediaReplace: viewAction(['media'], (event) => content.mediaReplaceApply(contentEvent(event, {}))),
     mediaAltPreview: viewAction(['media'], (event) => content.mediaAltPreview(contentEvent(event, {}))),
     mediaAltPropagate: viewAction(['media'], (event) => content.mediaAltApply(contentEvent(event, {}))),
+    // Pass C library actions: a multi-select bulk delete, the on-demand orphan scan, and the
+    // irreversible byte purge. The component posts to `?/mediaBulkDelete`, `?/mediaOrphanScan`, and
+    // `?/mediaPurge` (the purge key is short of its content method name). All gate on the media view.
+    mediaBulkDelete: viewAction(['media'], (event) => content.mediaBulkDelete(contentEvent(event, {}))),
+    mediaOrphanScan: viewAction(['media'], (event) => content.mediaOrphanScan(contentEvent(event, {}))),
+    mediaPurge: viewAction(['media'], (event) => content.mediaPurgeOrphans(contentEvent(event, {}))),
     publishAll: viewAction(authedViews, (event) => content.publishAllAction(contentEvent(event, {}))),
     addEditor: viewAction(['editors'], (event) => editors.addEditorAction(event)),
     removeEditor: viewAction(['editors'], (event) => editors.removeEditorAction(event)),

package/src/lib/sveltekit/content-routes.ts

@@ -29,10 +29,14 @@ import { mediaLibraryEntry } from '../media/library-entry.js';
 import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js';
 import { buildUsageIndex } from '../media/usage.js';
 import type { UsageEntry } from '../media/usage.js';
+import { runReconcile, MEDIA_KEY_RE, type ReconcileBucket } from '../media/reconcile.js';
+import { buildOrphanScan, type OrphanScan } from '../media/orphan-scan.js';
 import { repointMediaRef, fillAltForHash } from '../content/media-rewrite.js';
 import type { RepointPlacement, AltPlacement } from '../content/media-rewrite.js';
 import { planMediaRewrite } from '../media/rewrite-plan.js';
 import type { BranchRef } from '../media/rewrite-plan.js';
+import { planBulkDelete } from '../media/bulk-delete-plan.js';
+import type { BulkDeleteSkip } from '../media/bulk-delete-plan.js';
 import type { CookieJar, EventBase } from './types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField, PreviewConfig, ResolvedPreview } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
@@ -161,9 +165,10 @@ export interface MediaLibraryData {
    *  redirected commit conflict never overwrite each other. */
   error: string | null;
   /** The success flash a redirected action carries: `deleted` from `?deleted=1`, `updated` from
-   *  `?updated=1`, `replaced` from `?replaced=1`, `altPropagated` from `?altPropagated=1`, null
-   *  otherwise. The component renders a polite success strip for each. */
-  flash: 'deleted' | 'updated' | 'replaced' | 'altPropagated' | null;
+   *  `?updated=1`, `replaced` from `?replaced=1`, `altPropagated` from `?altPropagated=1`,
+   *  `bulkDeleted` from `?bulkDeleted=1`, `orphansPurged` from `?orphansPurged=1`, null otherwise.
+   *  The component renders a polite success strip for each. */
+  flash: 'deleted' | 'updated' | 'replaced' | 'altPropagated' | 'bulkDeleted' | 'orphansPurged' | null;
   /** A redirected action's conflict error read from `?error=` (a commit-conflict bounce). Kept in
    *  its own slot rather than the degraded-load `error` above, so the two never collide. */
   flashError: string | null;
@@ -248,6 +253,30 @@ export interface MediaAltPropagateFailure {
   error: string;
 }
 
+/** A refused media bulk delete or orphan purge: `fail(503)` for the fail-closed strict-usage refusal
+ *  (the whole batch refuses) or media-off / a missing bucket binding. The per-item outcomes ride the
+ *  returned summary, not a fail. */
+export interface MediaBulkFailure {
+  error: string;
+}
+
+/** The bulk-delete outcome the component renders: the deleted hashes, the skipped rows from the
+ *  partition (with their reason and where-used), and any per-object R2 delete failure. Admin-internal,
+ *  not on the package subpath, so no reference page. */
+export interface MediaBulkDeleteResult {
+  deleted: string[];
+  skipped: BulkDeleteSkip[];
+  failed: { hash: string; error: string }[];
+}
+
+/** The orphan-purge outcome: the purged R2 keys, the keys skipped because their hash was claimed by a
+ *  manifest row since the scan, and any per-object delete failure. Admin-internal, no reference page. */
+export interface MediaOrphanPurgeResult {
+  purged: string[];
+  skippedClaimed: string[];
+  failed: { key: string; error: string }[];
+}
+
 /** One entry the replace preview will rewrite, enriched with its display title and permalink from the
  *  content manifest (the planner's PlannedEntry carries neither). The screen lists these as the
  *  confirm dialog's where-touched preview, and the apply re-derives its own plan rather than trusting
@@ -312,7 +341,7 @@ export interface MediaAltPreviewPlan {
  *  `form` prop carries a `?/mediaDelete`, `?/mediaUpdate`, `?/mediaReplace`, or `?/mediaAltPropagate`
  *  refusal without a second type. */
 export type ContentFormFailure = Partial<
-  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure
+  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure & MediaBulkFailure
 >;
 
 /** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
@@ -546,6 +575,8 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     else if (event.url.searchParams.get('updated') === '1') flash = 'updated';
     else if (event.url.searchParams.get('replaced') === '1') flash = 'replaced';
     else if (event.url.searchParams.get('altPropagated') === '1') flash = 'altPropagated';
+    else if (event.url.searchParams.get('bulkDeleted') === '1') flash = 'bulkDeleted';
+    else if (event.url.searchParams.get('orphansPurged') === '1') flash = 'orphansPurged';
     const flashError = event.url.searchParams.get('error');
     let token: string;
     try {
@@ -1493,6 +1524,263 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     throw redirect(303, '/admin/media?deleted=1');
   }
 
+  /** Bulk safe-delete a multi-select of committed media assets. This is mediaDeleteAction extended to
+   *  many items, with the same safety primitives and one rule that defines the batch: the gate is ONE
+   *  shared strict cross-branch usage index built per batch, never N per-item reads (N strict reads
+   *  would blow the workerd connection budget at many open branches). The fail-closed posture is for
+   *  the WHOLE batch: if that single strict index cannot complete, the action refuses everything and
+   *  commits nothing, rather than risk deleting bytes a branch still references.
+   *
+   *  Skip-and-report, never force: the pure planBulkDelete partitions the selection against the strict
+   *  index into deletable (no usage row, a committed manifest row exists), skipped-still-referenced (a
+   *  usage row, carried for the where-used), and skipped-uncommitted (no manifest row). An in-use item
+   *  is skipped and reported, never bulk-force-deleted; forced in-use deletion stays the single-item
+   *  typed-slug path.
+   *
+   *  The order is load-bearing, mirroring single delete: ONE atomic commit removes every deletable row
+   *  FIRST, then the R2 objects are deleted (commit-row-then-delete-R2). A failure after the commit
+   *  leaves bytes with no row (a benign orphan) rather than a row pointing at deleted bytes. Each R2
+   *  delete is best-effort and batch-resilient: a per-object error is reported in `failed` and never
+   *  aborts the rest of the batch. The result is an itemized 207-style summary the component renders
+   *  (deleted / skipped with reasons / failed); there is no success redirect. */
+  async function mediaBulkDelete(event: ContentEvent): Promise<ReturnType<typeof fail> | MediaBulkDeleteResult> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Read the selected hashes from the form. Accept the repeated `hash` field, falling back to a JSON
+    // `hashes` array. Each value must match the 16-hex content-hash grammar; a malformed value is
+    // dropped silently rather than surfaced as a skip (it was never a real selection).
+    const form = await event.request.formData();
+    let raw = form.getAll('hash').map(String);
+    if (raw.length === 0) {
+      const json = form.get('hashes');
+      if (typeof json === 'string') {
+        try {
+          const parsed: unknown = JSON.parse(json);
+          if (Array.isArray(parsed)) raw = parsed.map(String);
+        } catch {
+          raw = [];
+        }
+      }
+    }
+    const selected = raw.filter((h) => MEDIA_HASH_RE.test(h));
+
+    // Read the fresh media manifest (the deletable rows come from here, by hash).
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // Resolve the R2 bucket before any write, so a media-off site or a missing binding refuses before
+    // the commit, exactly like single delete.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+    const store = r2Store(rawBucket as R2Bucket);
+
+    // THE fail-closed gate for the whole batch: one shared strict usage index. STRICT mode rethrows a
+    // branch-read failure, so a transient branch read failing refuses the whole batch rather than
+    // mistaking a still-referenced asset for an orphan. Build exactly one index, never one per item.
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not verify where these assets are used. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    // The pure partition: membership in the fresh strict index is the gate, never the display count.
+    const plan = planBulkDelete(selected, index, manifest);
+    // An all-skipped or empty batch is a no-op success: nothing committed, nothing deleted.
+    if (plan.deletable.length === 0) {
+      return { deleted: [], skipped: plan.skipped, failed: [] } satisfies MediaBulkDeleteResult;
+    }
+
+    // ONE atomic commit removing EVERY deletable row, folded over removeMediaEntry.
+    let next = manifest;
+    for (const hash of plan.deletable) next = removeMediaEntry(next, hash);
+    const commitFields = { concept: 'media', id: 'bulk', editor: editor.email };
+    try {
+      await commitFiles(
+        runtime.backend,
+        [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(next) }],
+        { message: `Delete ${plan.deletable.length} media assets`, author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+      log.info('commit.succeeded', commitFields);
+    } catch (err) {
+      commitFailure(commitFields, err, '/admin/media',
+        'The media manifest changed since you opened it. Reload and try again.');
+    }
+
+    // THEN delete each deletable hash's R2 object (the load-bearing order, see the docstring). Best
+    // effort and batch-resilient: a thrown key derivation or a delete error is reported in `failed`
+    // and the loop continues. An absent object is a no-op (the R2 contract).
+    const deleted: string[] = [];
+    const failed: { hash: string; error: string }[] = [];
+    for (const hash of plan.deletable) {
+      try {
+        const row = manifest[hash];
+        await store.delete(r2Key(row.hash, row.ext));
+        deleted.push(hash);
+      } catch (err) {
+        failed.push({ hash, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+
+    log.info('media.bulk_deleted', { editor: editor.email, deleted: deleted.length, skipped: plan.skipped.length });
+    return { deleted, skipped: plan.skipped, failed } satisfies MediaBulkDeleteResult;
+  }
+
+  /** The on-demand orphan scan: a read-only reconcile of stored R2 bytes against the manifest, joined
+   *  with one strict cross-branch usage index for the broken-reference where-used. It runs only when
+   *  requested, never on the loaded index, because it is heavier than the load path: a full R2 list
+   *  plus a reconcile pass on top of the strict usage build.
+   *
+   *  Detection-time fail-closed: BOTH the reconcile and the strict usage build run inside one
+   *  try/catch, and any throw refuses the whole scan with fail(503) rather than returning a partial
+   *  result. The reconcile must not run on a half-listed bucket: a truncated R2 list would call
+   *  still-stored bytes orphaned. The strict usage build must not run on a half-read branch set: an
+   *  unread branch would make a branch-referenced asset look orphaned. A wrong orphan verdict here
+   *  feeds the irreversible purge, so the scan refuses rather than risk it.
+   *
+   *  The result is the OrphanScan projection: orphanedBytes (stored keys with no manifest row, the
+   *  purge surface) and brokenRefs (manifest rows whose bytes are gone, read-only, shown with their
+   *  where-used so an operator can re-ingest rather than purge a still-referenced record). */
+  async function mediaOrphanScan(event: ContentEvent): Promise<ReturnType<typeof fail> | OrphanScan> {
+    requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Resolve the R2 binding. The reconcile lists the raw bucket directly, so keep the raw binding;
+    // the MediaStore seam carries no list. A media-off site or a missing binding refuses the scan.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+
+    // Read the fresh media manifest for the reconcile's manifest side.
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // THE detection-time fail-closed surface. The reconcile (an R2 list that must complete in full)
+    // and the strict usage build (a branch read that must complete in full) are both unsafe to use
+    // partially, so either throwing refuses the scan. A wrong orphan verdict from a partial read here
+    // would feed the irreversible purge.
+    let reconcile: Awaited<ReturnType<typeof runReconcile>>;
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      reconcile = await runReconcile(rawBucket as unknown as ReconcileBucket, manifest);
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not check where files are used, so the scan was not run. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    return buildOrphanScan(reconcile, manifest, index);
+  }
+
+  /** Purge orphaned R2 bytes: the one IRREVERSIBLE media action. Raw object bytes live only in R2, not
+   *  in git, so a purged orphan cannot be recovered the way a deleted manifest row can be reverted in
+   *  history. The whole action is built around that fact.
+   *
+   *  The typed-count confirm is the never-bypassable gate, the analogue of single delete's typed-slug
+   *  check. The form's `confirm` must equal the count of selected keys (the approved rev.2 mockup's
+   *  "Type N to purge these files for good"); an empty selection or a mismatched count deletes nothing.
+   *
+   *  Re-derive fresh is the safety crux. The selection came from an earlier scan, so the action does
+   *  NOT trust it: the purge keys are client-posted, so the server cannot assume they came from a fresh
+   *  scan. It reads the current media manifest AND rebuilds ONE strict cross-branch usage index, then
+   *  for each selected key parses the hash from the key grammar. A key that does not match the grammar
+   *  was never a real orphan key and is dropped silently. A key whose hash now has a manifest row OR is
+   *  referenced on any open cairn/* branch survived the scan window (it was claimed by a row, or a
+   *  draft started referencing those bytes), so it is skipped into skippedClaimed and its bytes survive.
+   *  Only a key whose hash is STILL absent from both is purged. This closes the TOCTOU between scan and
+   *  purge that could otherwise irreversibly delete a live draft's bytes.
+   *
+   *  Like the scan and the bulk delete, the strict index build is the fail-closed gate: a branch read
+   *  that throws refuses the whole batch with fail(503) rather than mistaking an unverifiable reference
+   *  for an absent one. The index is built exactly once for the batch, never once per key.
+   *
+   *  There is no commit. An orphan by definition has no manifest row to remove, so the purge deletes
+   *  the R2 object directly. Each delete is best-effort and batch-resilient: a per-object error is
+   *  reported in `failed` and the loop continues; an absent object is a no-op (the R2 contract). */
+  async function mediaPurgeOrphans(event: ContentEvent): Promise<ReturnType<typeof fail> | MediaOrphanPurgeResult> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Resolve the R2 binding, the same media-off / missing-binding refusals as the scan. The purge
+    // deletes through the MediaStore seam, so wrap the raw binding.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+    const store = r2Store(rawBucket as R2Bucket);
+
+    // Read the selected R2 keys and the typed confirm.
+    const form = await event.request.formData();
+    const keys = form.getAll('key').map(String);
+    const confirm = String(form.get('confirm') ?? '');
+
+    // The irreversible gate: the confirm must equal the selected count, and the set must be non-empty.
+    // A mismatch or an empty set refuses and deletes NOTHING.
+    if (keys.length === 0 || confirm !== String(keys.length)) {
+      return fail(400, { error: 'Type the number of files to confirm the purge.' } satisfies MediaBulkFailure);
+    }
+
+    // Re-derive fresh against the current manifest, so a key claimed since the scan is never purged.
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // THE fail-closed gate for the whole batch: one shared strict cross-branch usage index, symmetric
+    // with the scan and the bulk delete. STRICT mode rethrows a branch-read failure, so a transient
+    // branch read refuses the irreversible purge rather than letting a possibly-referenced byte be
+    // treated as a true orphan. Build exactly one index, never one per key.
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not verify where these files are used. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    const purged: string[] = [];
+    const skippedClaimed: string[] = [];
+    const failed: { key: string; error: string }[] = [];
+    for (const key of keys) {
+      const hash = MEDIA_KEY_RE.exec(key)?.[1];
+      // A key that does not match the grammar was never a real orphan key: drop it silently.
+      if (hash === undefined) continue;
+      // A hash that now has a manifest row was claimed since the scan: its bytes are a live asset now.
+      if (manifest[hash]) {
+        skippedClaimed.push(key);
+        continue;
+      }
+      // A hash referenced on any open cairn/* branch backs an in-progress draft: skip it claimed too.
+      if (index.has(hash)) {
+        skippedClaimed.push(key);
+        continue;
+      }
+      // Still orphaned: delete the object directly. No commit, there is no manifest row.
+      try {
+        await store.delete(key);
+        purged.push(key);
+      } catch (err) {
+        failed.push({ key, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+
+    log.info('media.orphans_purged', { editor: editor.email, purged: purged.length });
+    return { purged, skippedClaimed, failed } satisfies MediaOrphanPurgeResult;
+  }
+
   /** Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
    *  row commit, with NO reference rewrite: the resolver and the delivery route key on the hash, so a
    *  rename never breaks an existing `media:` reference. The default alt is the asset's value for the
@@ -1881,7 +2169,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     throw redirect(303, '/admin/media?altPropagated=1');
   }
 
-  return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, mintToken };
+  return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, mintToken };
 }
 
 /** The cap, in characters, on the stored alt text. The human fields are display copy, not content,

package/src/lib/sveltekit/index.ts

@@ -22,6 +22,7 @@ export type {
   MediaUpdateFailure,
   MediaReplaceFailure,
   MediaAltPropagateFailure,
+  MediaBulkFailure,
   ContentFormFailure,
   UploadResult,
 } from './content-routes.js';