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/version_pinning_scheduler.py

@@ -5,68 +5,39 @@ system promotes stable note versions before they get aged out of the
 rolling cap. Off-hours by design — the scan is cheap but not time-
 critical and doesn't need to interrupt regular activity.
 
-Mirrors the BackgroundScheduler + threadsafe-async-call pattern used by
-journal_scheduler.py.
+One ScheduledJob (services/scheduler.py), like the other *_scheduler modules.
 """
 from __future__ import annotations
 
 import asyncio
 import logging
 
-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger
 
+from scribe.services.scheduler import ScheduledJob
 from scribe.services.version_pinning import scan_all_users_for_auto_pins
 
 logger = logging.getLogger(__name__)
 
-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None
+
+async def _run_scan() -> None:
+    results = await scan_all_users_for_auto_pins()
+    total = sum(results.values())
+    if total > 0:
+        logger.info(
+            "auto-pin scan: pinned %d version(s) across %d user(s)",
+            total, len(results),
+        )
+    else:
+        logger.debug("auto-pin scan: no new pins")
 
 
-def _run_scan_threadsafe() -> None:
-    """APScheduler invokes this from a worker thread; bridge into the
-    asyncio loop so the scan can await its DB operations."""
-    if _loop is None:
-        logger.warning("version_pinning scheduler: no loop registered")
-        return
-
-    async def _runner():
-        try:
-            results = await scan_all_users_for_auto_pins()
-            total = sum(results.values())
-            if total > 0:
-                logger.info(
-                    "auto-pin scan: pinned %d version(s) across %d user(s)",
-                    total, len(results),
-                )
-            else:
-                logger.debug("auto-pin scan: no new pins")
-        except Exception:
-            logger.exception("auto-pin scan run failed")
-
-    asyncio.run_coroutine_threadsafe(_runner(), _loop)
+_JOB = ScheduledJob("version_pinning_auto_scan", _run_scan, label="Version pinning")
 
 
 def start_version_pinning_scheduler(loop: asyncio.AbstractEventLoop) -> None:
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
-    _scheduler = BackgroundScheduler()
-    _scheduler.add_job(
-        _run_scan_threadsafe,
-        trigger=CronTrigger(hour=3, minute=0, timezone="UTC"),
-        id="version_pinning_auto_scan",
-        replace_existing=True,
-    )
-    _scheduler.start()
-    logger.info("Version pinning scheduler started (daily 03:00 UTC)")
+    _JOB.start(loop, CronTrigger(hour=3, minute=0, timezone="UTC"), describe="daily 03:00 UTC")
 
 
 def stop_version_pinning_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("Version pinning scheduler stopped")
+    _JOB.stop()