fix(quota): prune quota history past a retention window

quota_events had no retention: one row per API spend plus a zero-unit row per live search, kept
forever. The daily history cleanup (audit_gc) now also prunes it past quota_retention_days (a new
Quota setting, default 365 so the admin usage view's longest window stays whole; 0 = forever). The
floor of two days keeps today's rows, which the per-user search cap counts.

backend/app/config.py

@@ -260,6 +260,9 @@ class Settings(BaseSettings):
     # Admin audit log: how long to keep rows (days; 0 = keep forever) + how often the GC runs.
     audit_retention_days: int = 180
     audit_gc_minutes: int = 1440
+    # YouTube quota history (quota_events): days kept (0 = forever). A year, so the admin usage view's
+    # longest window (365 days) stays whole; the same daily cleanup job prunes it.
+    quota_retention_days: int = 365
     # On-disk layout: "plex" (Channel/Season YYYY/… [id].ext + .nfo/poster) or "flat".
     download_layout: DownloadLayout = "plex"
     # Default SponsorBlock (skip sponsor segments) for new custom profiles.

backend/app/quota.py

@@ -7,11 +7,13 @@ always be allowed; expensive backfill must yield to the remaining budget.
 
 import contextlib
 import contextvars
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
+from typing import Any, cast
 from zoneinfo import ZoneInfo
 
-from sqlalchemy import func, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
 from app import sysconfig
@@ -96,6 +98,20 @@ def pacific_today():
     return datetime.now(_PACIFIC).date()
 
 
+def gc(db: Session, retention_days: int) -> int:
+    """Delete quota-history rows older than `retention_days` (<= 0 keeps them forever) and return how
+    many went. Flushes only; the cleanup job commits. Today's rows are never in reach: the per-user
+    search cap counts them, and the floor of two days outlasts any Pacific day (25 h at most)."""
+    if retention_days <= 0:
+        return 0
+    cutoff = datetime.now(timezone.utc) - timedelta(days=max(2, retention_days))
+    # A DELETE answers with a CursorResult; `execute` is typed as the general Result, without rowcount.
+    result = cast(
+        CursorResult[Any], db.execute(delete(QuotaEvent).where(QuotaEvent.created_at < cutoff))
+    )
+    return result.rowcount or 0
+
+
 def pacific_day_start_utc() -> datetime:
     """UTC instant of the current Pacific day's midnight — aligns 'today' with the budget reset."""
     start = datetime.now(_PACIFIC).replace(hour=0, minute=0, second=0, microsecond=0)

backend/app/scheduler.py

@@ -425,12 +425,15 @@ def _people_enrich_job() -> None:
 
 
 def _audit_gc_job() -> None:
-    # Prune audit-log rows older than the admin-set retention (audit_retention_days; 0 = keep
-    # forever). Pure DB, no quota.
+    # The history cleanup: audit-log rows past audit_retention_days and YouTube quota history past
+    # quota_retention_days (0 = keep forever, each). Pure DB, no quota.
     def work(db):
         from app import sysconfig
 
-        return {"reaped": audit.gc(db, sysconfig.get_int(db, "audit_retention_days"))}
+        reaped = audit.gc(db, sysconfig.get_int(db, "audit_retention_days"))
+        quota_reaped = quota.gc(db, sysconfig.get_int(db, "quota_retention_days"))
+        db.commit()
+        return {"reaped": reaped, "quota_reaped": quota_reaped}
 
     _job("audit_gc", work)
 

backend/app/sysconfig.py

@@ -80,6 +80,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ),
     # Live-search source: "scrape" (InnerTube, zero API quota) or "api" (search.list, 100u/page).
     ConfigSpec("search_source", "choice", "quota", "search_source"),
+    ConfigSpec("quota_retention_days", "int", "quota", "quota_retention_days", min=0, max=3650),
     # --- Backfill (recent-first first pass per channel) ---
     ConfigSpec(
         "backfill_recent_max_videos",