US02-06: Deliver Workflow, Safety, Library, Analysis, and Stats Views

Ports the safety review and the Photo Analyzer Library/Analyze/Stats
experiences onto the shared API + service layer, and adds the Workflow
home, enforcing the pipeline gates and the one-mutating-job policy.

Backend
- migration 0005 + models: safety_reviews (append-only, latest row is the
  current decision) and analysis_results (donor photos schema re-keyed to
  asset_id).
- SafetyService: persist scores/decisions, review queue with filters, and
  the EXIF safety checkpoint (mutually-exclusive sfw/nsfw keyword written,
  read back, current_sha256 refreshed) that upload eligibility depends on.
- AnalysisService: the privacy gate — the vision provider is called ONLY for
  canonical, confirmed-SFW assets; nsfw/undecided are recorded skipped without
  a request. Provider is an injected adapter (real OpenAI-compatible Gemini
  call extracted from photo_analyzer.analyze_image; a fake in tests).
- LibraryService: Library search + Stats read model ported from webapp/query.py
  (LIKE search in place of FTS5; facets, top tags, years, albums, people).
- WorkflowService + GET /api/v1/workflow: per-stage readiness derived from the
  source tables — counts, blockers, last-run, action, and an active_job that
  drives read-only-during-jobs. Safety scoring and analysis run as durable jobs
  under the library_write lock via new domain handlers, so a second mutating
  job is refused.
- routes: workflow, safety (queue/counts/decisions/jobs), analysis
  (counts/results/jobs), library (assets/facets/stats).

Frontend
- five views (frontend/js/views.js) on the US02-05 shell: Workflow stepper
  (status text+icon, not colour alone; actions disabled with a reason while a
  job runs), Safety review (filter tabs, decide, persists across reload),
  Library (search + cards), Analyze (counts + live job log via the SSE
  adapter), Stats. Shared DOM helpers extracted to dom.js; Workflow is the home
  route.

Tests
- integration: provider-call privacy (nsfw never reaches the provider),
  sfw→nsfw flip drops analysis eligibility, decision persistence, one-mutating-
  job rejection, workflow counts, and the exiftool safety-keyword write/verify.
- e2e: Workflow cards, actions disabled+explained during a job, safety
  decide-persists-across-reload, Library search, Stats, Analyze counts.
- traceability map updated for US02-05 and US02-06.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

photo_pipeline/jobs/domain_handlers.py

@@ -0,0 +1,36 @@
+"""Domain job handlers: safety scoring and content analysis (US02-06).
+
+Importing this module registers the ``safety_score`` and ``analysis`` job types so
+the generic worker can run them per item (one item = one ``asset_id``). Each handler
+delegates to its service, which owns the real work and the privacy gate. Handlers
+are idempotent: re-scoring or re-analyzing one asset is safe after an interrupted
+attempt.
+
+Providers/models are the service defaults here (real NsfwModel / vision provider);
+tests exercise the services directly with injected fakes rather than the worker.
+"""
+
+from __future__ import annotations
+
+from photo_pipeline.jobs.handlers import JobContext, register
+
+SAFETY_SCORE = "safety_score"
+ANALYSIS = "analysis"
+# Both mutate the library's metadata/derived state; one at a time (concept §one job).
+LIBRARY_WRITE_LOCK = "library_write"
+
+
+def _safety_score_item(asset_id: str, ctx: JobContext) -> None:
+    from photo_pipeline.services.safety import SafetyService
+
+    SafetyService(ctx.session_factory).score_assets([asset_id])
+
+
+def _analysis_item(asset_id: str, ctx: JobContext) -> None:
+    from photo_pipeline.services.analysis import AnalysisService
+
+    AnalysisService(ctx.session_factory).run([asset_id])
+
+
+register(SAFETY_SCORE, _safety_score_item)
+register(ANALYSIS, _analysis_item)

photo_pipeline/jobs/handlers.py

@@ -26,12 +26,14 @@ class Cancelled(Exception):
 
 @dataclass
 class JobContext:
-    """What a handler needs from the coordinator: cancellation checks and heartbeats."""
+    """What a handler needs from the coordinator: cancellation checks, heartbeats,
+    and the session factory to build domain services against."""
 
     job_id: str
     worker_id: str
     fencing_token: int
     service: "JobService"
+    session_factory: object | None = None
 
     def cancelled(self) -> bool:
         from photo_pipeline.services.jobs import JobState

photo_pipeline/jobs/worker.py

@@ -51,7 +51,7 @@ class Worker:
 
     def _process(self, job_id: str, job_type: str, token: int) -> None:
         handler = self.handlers[job_type]
-        ctx = JobContext(job_id, self.worker_id, token, self.service)
+        ctx = JobContext(job_id, self.worker_id, token, self.service, self._session_factory)
         self._reset_interrupted_items(job_id, token)
 
         cancelled = False