refactor(services): one periodic-task shape, one APScheduler job shape, one token hash, one summary rule — the services pass of the shape audit (#2830, milestone 296)

- background.start_periodic(interval, work, label=) replaces the three hand-rolled
  while-True/sleep/try loops in logging, auth and notifications.
- services/scheduler.ScheduledJob replaces the four private BackgroundScheduler
  copies in recurrence/version_pinning/trash/db_maintenance schedulers; public
  start_/stop_/reschedule_ surfaces unchanged.
- api_keys.hash_token is the one sha256 helper; auth.py used to inline it 5x.
- auth.is_registration_open reads via settings.get_admin_setting; notification
  prefs read via settings.get_setting; _fire_share_email uses _get_user_email.
- projects.get_project_summary / milestones.get_project_milestone_summary are
  now the one-id view of their batch siblings instead of a second copy of the
  queries; sharing.best_permission_by (was _deduplicate_by_permission) is the
  one rank-dedup, now also used by list_projects_for_user.
- backup: the row builders for every section both exporters carry are named
  functions, so a column added to one export cannot silently miss the other.
- iso() from models.base replaces the attr.isoformat()-if-attr-else-None idiom
  and db_maintenance._iso across services; backup keeps its explicit shape.
- trash.py hoists the sql_delete/timedelta imports it re-imported per function.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/scribe/services/trash_scheduler.py

@@ -1,80 +1,50 @@
 """Daily APScheduler cron that purges expired trash.
 
-Mirrors version_pinning_scheduler.py: a single global BackgroundScheduler job
-at 03:30 UTC bridges into the asyncio loop to run the async purge. Iterates
-every user and applies that user's own `trash_retention_days` setting; 0
-disables auto-purge for that user.
+A single job at 03:30 UTC (services/scheduler.py). Iterates every user and
+applies that user's own `trash_retention_days` setting; 0 disables auto-purge
+for that user.
 """
 from __future__ import annotations
 
 import asyncio
 import logging
 
-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger
+from sqlalchemy import select
 
+from scribe.models import async_session
+from scribe.models.user import User
 from scribe.services import trash as trash_svc
+from scribe.services.scheduler import ScheduledJob
 from scribe.services.settings import get_setting
 
 logger = logging.getLogger(__name__)
 
-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None
 
+async def _run_purge() -> None:
+    async with async_session() as session:
+        user_ids = (await session.execute(select(User.id))).scalars().all()
 
-def _run_purge_threadsafe() -> None:
-    """APScheduler invokes this from a worker thread; bridge into the loop."""
-    if _loop is None:
-        logger.warning("trash scheduler: no loop registered")
-        return
-
-    async def _runner():
+    purged = 0
+    for uid in user_ids:
+        raw = await get_setting(uid, "trash_retention_days", "90")
         try:
-            from sqlalchemy import select
+            days = int(raw)
+        except (TypeError, ValueError):
+            days = 90
+        purged += await trash_svc.purge_expired(uid, days)
+    if purged:
+        logger.info("trash purge: removed %d expired row(s)", purged)
+    else:
+        logger.debug("trash purge: nothing expired")
 
-            from scribe.models import async_session
-            from scribe.models.user import User
 
-            async with async_session() as session:
-                user_ids = (await session.execute(select(User.id))).scalars().all()
-
-            purged = 0
-            for uid in user_ids:
-                raw = await get_setting(uid, "trash_retention_days", "90")
-                try:
-                    days = int(raw)
-                except (TypeError, ValueError):
-                    days = 90
-                purged += await trash_svc.purge_expired(uid, days)
-            if purged:
-                logger.info("trash purge: removed %d expired row(s)", purged)
-            else:
-                logger.debug("trash purge: nothing expired")
-        except Exception:
-            logger.exception("trash purge run failed")
-
-    asyncio.run_coroutine_threadsafe(_runner(), _loop)
+_JOB = ScheduledJob("trash_retention_purge", _run_purge, label="Trash retention")
 
 
 def start_trash_scheduler(loop: asyncio.AbstractEventLoop) -> None:
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
-    _scheduler = BackgroundScheduler()
-    _scheduler.add_job(
-        _run_purge_threadsafe,
-        trigger=CronTrigger(hour=3, minute=30, timezone="UTC"),
-        id="trash_retention_purge",
-        replace_existing=True,
-    )
-    _scheduler.start()
-    logger.info("Trash retention scheduler started (daily 03:30 UTC)")
+    _JOB.start(loop, CronTrigger(hour=3, minute=30, timezone="UTC"), describe="daily 03:30 UTC")
 
 
 def stop_trash_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("Trash retention scheduler stopped")
+    _JOB.stop()