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

@@ -0,0 +1,78 @@
+"""One APScheduler job bridged into the asyncio loop — the shape the four
+*_scheduler modules (recurrence spawn, auto-pin scan, trash purge, DB
+maintenance) each used to carry a private copy of.
+
+APScheduler's BackgroundScheduler fires from a worker thread; the work is
+async and must run on the app's loop, so the fire is bridged with
+``run_coroutine_threadsafe``. Each job is a module-level singleton: start is
+idempotent, stop shuts the scheduler down, and a job whose trigger the
+operator can change (the maintenance hour) reschedules the live job instead
+of restarting.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+from apscheduler.schedulers.background import BackgroundScheduler
+
+logger = logging.getLogger(__name__)
+
+
+class ScheduledJob:
+    """A named APScheduler job that awaits ``work()`` on the asyncio loop.
+
+    ``work`` is an async callable; exceptions it raises are logged under
+    ``label`` and never propagate into APScheduler's thread.
+    """
+
+    def __init__(self, job_id: str, work: Callable[[], Awaitable[None]], *, label: str) -> None:
+        self.job_id = job_id
+        self._work = work
+        self.label = label
+        self._scheduler: BackgroundScheduler | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._scheduler is not None
+
+    def _fire(self) -> None:
+        """APScheduler invokes this from its worker thread; bridge into the loop."""
+        if self._loop is None:
+            logger.warning("%s scheduler: no loop registered", self.label)
+            return
+
+        async def _runner() -> None:
+            try:
+                await self._work()
+            except Exception:
+                logger.exception("%s run failed", self.label)
+
+        asyncio.run_coroutine_threadsafe(_runner(), self._loop)
+
+    def start(self, loop: asyncio.AbstractEventLoop, trigger, *, describe: str = "") -> None:
+        """Start the job on ``trigger``. Idempotent — a second start is a no-op."""
+        if self._scheduler is not None:
+            return
+        self._loop = loop
+        self._scheduler = BackgroundScheduler()
+        self._scheduler.add_job(
+            self._fire, trigger=trigger, id=self.job_id, replace_existing=True,
+        )
+        self._scheduler.start()
+        logger.info("%s scheduler started%s", self.label, f" ({describe})" if describe else "")
+
+    def reschedule(self, trigger, *, describe: str = "") -> None:
+        """Move the live job to a new trigger; a no-op when not running."""
+        if self._scheduler is None:
+            return
+        self._scheduler.reschedule_job(self.job_id, trigger=trigger)
+        logger.info("%s scheduler rescheduled%s", self.label, f" to {describe}" if describe else "")
+
+    def stop(self) -> None:
+        if self._scheduler is not None:
+            self._scheduler.shutdown(wait=False)
+            self._scheduler = None
+            logger.info("%s scheduler stopped", self.label)