feat(cleanup): reclaim orphaned attachments — rows and store blobs (#3068)

PostAttachment's two FKs are both ON DELETE SET NULL, so a deleted post or
artist left the row behind rather than taking it. Nothing ever pruned those
rows, and nothing in the repo had ever unlinked a file under the attachment
store — so both rows and bytes accumulated permanently, invisible to every
existing diagnostic.

Why a disk->DB reconciliation rather than a row sweep: the store is
sha-addressed and idempotent, so ONE blob backs MANY rows. Deleting a row
does not free its blob, and since the artist cascade (#3066) now deletes
its attachment rows outright, a freed blob has no DB pointer left to find
it by. Walking the store and asking "does any row still reference this
sha?" catches orphans from every cause, including ones no future delete
path will think to report.

Preview and apply share `_orphan_attachment_conditions` (rule 93). The
dry-run derives its surviving-sha set by NEGATING that same predicate, so
it is honest about blobs the delete would free rather than counting them as
still-referenced — the one place this was easy to get backwards, so it has
its own parity test.

Guards, each with a reason:
- A blob is written before its row commits, so a just-stored file legitimately
  has no referencing row. Files under 6h are never judged — same guard and
  reasoning as ORPHAN_TEMP_MIN_AGE_HOURS.
- `.partial` staging files belong to cleanup_orphaned_temp_files; skipped
  rather than raced.
- The sha is parsed as the first 64 chars, not via Path.stem: store() takes
  the extension from the source filename, and a URL-encoded basename yields a
  multi-dot suffix that would make stem eat part of the sha.
- A 900s walk budget reports partial=True instead of running to the task's
  hard limit (rule 89).
- TASK_STUCK_THRESHOLD_MINUTES override at 30 (= time_limit 25 + 5). Without
  it a healthy 20-minute walk is phantom-flagged 'RecoverySweep' at the bare
  5-min default — the #883 failure class; its invariant test is mirrored here.

Defaults to the safe preview at both the task and the route, unlike the other
maintenance triggers: this apply unlinks files. Operator-triggered only,
never on a beat.

Ships with its UI (rule 27): AttachmentReclaimCard in Cleanup → Duplicates &
leftovers, built on the existing useMaintenanceTask/MaintenanceTile shapes, so
a run survives navigating away. Surfaces files_failed and partial explicitly,
since both change what the numbers mean.

Also promotes humanBytes to utils/bytes.js — it was byte-identical in
VideoDedupCard and GatedPurgeCard and this card would have been the third
copy. The three divergent `formatBytes` helpers are deliberately left alone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

backend/app/services/cleanup_service.py

@@ -1592,3 +1592,155 @@ def purge_gated_previews(
         "ledger_cleared": ledger_cleared,
         "posts_deleted": posts_deleted,
     }
+
+
+# -- orphaned attachment reclamation ---------------------------------------
+# PostAttachment's two FKs are both ON DELETE SET NULL, so a deleted post or
+# artist leaves the row behind rather than taking it. Nothing ever pruned those
+# rows, and nothing has ever unlinked a file under the attachment store — so
+# both rows and bytes accumulated permanently and were invisible to every
+# existing diagnostic.
+#
+# Why this is a DISK->DB reconciliation rather than a row sweep: the store is
+# sha-addressed and idempotent (attachment_store.store), so ONE blob backs MANY
+# rows. Deleting a row therefore does not free its blob, and — since the artist
+# cascade now deletes its attachment rows outright — a freed blob has no DB
+# pointer left to find it by. Walking the store and asking "does any row still
+# reference this sha?" catches orphans from every cause, including ones no
+# future delete path will think to report.
+
+# A blob is written by attachment_store.store BEFORE its row is inserted and
+# committed, so a just-stored file legitimately has no referencing row for a
+# moment. Same guard, same reasoning as ORPHAN_TEMP_MIN_AGE_HOURS in
+# tasks/maintenance.py: never judge a file younger than this.
+_ATTACHMENT_ORPHAN_MIN_AGE_HOURS = 6
+
+# Wall-clock budget for the store walk (rule 89). A library with a large
+# attachment store shouldn't be able to run this past its soft time limit; on
+# exhaustion it reports partial=True and the operator re-runs to finish.
+_ATTACHMENT_RECLAIM_BUDGET_SECONDS = 900
+
+# The store names files `<sha256><ext>`. Parse the sha as the first 64 chars
+# rather than via Path.stem: store() takes the extension straight from the
+# source filename, and a URL-encoded basename yields a multi-dot "suffix"
+# (see [[reference_url_encoded_basename_suffix]]) that would make stem eat part
+# of the sha. Validating the 64 chars as hex also skips anything else in the
+# tree that isn't a stored blob.
+_SHA256_HEX_LEN = 64
+
+
+def _orphan_attachment_conditions() -> list:
+    """PostAttachment rows belonging to nothing: both FKs nulled by a deleted
+    post AND a deleted artist. A row with post_id NULL but an artist_id is the
+    deliberate filesystem-import case (importer._capture_attachment writes it
+    that way) and is NOT an orphan — it is still attributed."""
+    return [
+        PostAttachment.post_id.is_(None),
+        PostAttachment.artist_id.is_(None),
+    ]
+
+
+def _is_sha_named(name: str) -> bool:
+    """True when `name` starts with a 64-char lowercase-hex sha256."""
+    if len(name) < _SHA256_HEX_LEN:
+        return False
+    head = name[:_SHA256_HEX_LEN]
+    return all(c in "0123456789abcdef" for c in head)
+
+
+def reclaim_orphaned_attachments(
+    session: Session, *, images_root: Path, dry_run: bool = False,
+) -> dict:
+    """Prune unattributed PostAttachment rows, then unlink store blobs that no
+    surviving row references.
+
+    Returns (same discovery keys either way, so the UI renders one shape):
+        {"rows": int,            # orphan rows found / deleted
+         "files": int,           # unreferenced blobs found / unlinked
+         "bytes": int,           # their total size
+         "scanned": int,         # blobs examined
+         "skipped_recent": int,  # blobs under the min-age guard
+         "files_failed": int,    # unlink raised (apply only)
+         "partial": bool}        # walk hit the time budget
+
+    dry_run computes exactly what the apply would do and mutates nothing — the
+    surviving-sha set is derived by NEGATING the same orphan predicate the
+    delete uses, so the preview cannot disagree with the apply (rule 93).
+    """
+    started = time.monotonic()
+    orphan_conds = _orphan_attachment_conditions()
+
+    if dry_run:
+        rows = session.execute(
+            select(func.count(PostAttachment.id)).where(*orphan_conds)
+        ).scalar_one()
+    else:
+        rows = session.execute(
+            delete(PostAttachment).where(*orphan_conds)
+        ).rowcount or 0
+        session.commit()
+
+    # Shas that still have a home. In the apply path the orphan rows are already
+    # gone, so `NOT orphan` is redundant but harmless; in the dry-run path it is
+    # what makes the projection honest about blobs the delete would free. One
+    # predicate, one query, both modes.
+    surviving_shas = set(session.execute(
+        select(PostAttachment.sha256).where(~and_(*orphan_conds)).distinct()
+    ).scalars())
+
+    root = Path(images_root) / "attachments"
+    cutoff = (
+        datetime.now(UTC).timestamp()
+        - _ATTACHMENT_ORPHAN_MIN_AGE_HOURS * 3600
+    )
+    files = 0
+    freed_bytes = 0
+    scanned = 0
+    skipped_recent = 0
+    files_failed = 0
+    partial = False
+
+    if root.is_dir():
+        for path in root.rglob("*"):
+            if time.monotonic() - started >= _ATTACHMENT_RECLAIM_BUDGET_SECONDS:
+                partial = True
+                break
+            # .partial staging files belong to cleanup_orphaned_temp_files —
+            # leave them alone rather than racing an in-flight store().
+            if path.suffix in (".part", ".partial") or not path.is_file():
+                continue
+            if not _is_sha_named(path.name):
+                continue
+            scanned += 1
+            sha = path.name[:_SHA256_HEX_LEN]
+            if sha in surviving_shas:
+                continue
+            try:
+                st = path.stat()
+                if st.st_mtime >= cutoff:
+                    skipped_recent += 1
+                    continue
+                size = st.st_size
+                if not dry_run:
+                    path.unlink()
+                files += 1
+                freed_bytes += size
+            except OSError as exc:
+                files_failed += 1
+                log.warning("reclaim_orphaned_attachments: %s: %s", path, exc)
+
+    if not dry_run and (rows or files):
+        log.info(
+            "attachment reclaim: %d orphan row(s) deleted, %d blob(s) unlinked "
+            "(%d bytes), %d failed, partial=%s",
+            rows, files, freed_bytes, files_failed, partial,
+        )
+    return {
+        "rows": rows,
+        "files": files,
+        "bytes": freed_bytes,
+        "scanned": scanned,
+        "skipped_recent": skipped_recent,
+        "files_failed": files_failed,
+        "partial": partial,
+    }