US06-02: Transfer, Verify, and Remove Active Sources

2026-08-16 18:45:52 +02:00
138 changed files with 381 additions and 15792 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,22 +0,0 @@
 # Deny-by-default build context (US08-02): the image must contain no secrets, no
 # photos, no database, no logs, and no .git. An allow list is the only version of this
 # rule that stays true when a new file appears in the working copy.
 *
 !pyproject.toml
 !alembic.ini
 !README.md
 !photo_pipeline
 !migrations
 !frontend
 !docker
 # Nothing generated, even under an allowed directory.
 **/__pycache__
 **/*.py[cod]
 **/.DS_Store
 **/*.env
 **/*.log
 **/*.db
 **/*.db-*
 **/*.sqlite*
--- a/.gitignore
+++ b/.gitignore
@@ -17,15 +17,3 @@ _todo/
 pictures/
 photos/
 _IGNORE/
 # Test failure evidence (US07-04)
 .artifacts/
 # Any dotenv, not only the default name.
 *.env
 # Local virtualenv for running the app.
 .venv/
 # setuptools editable-install metadata.
 *.egg-info/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,8 +80,7 @@ are the authoritative backlog.
   uncertain. Work only on the claimed story and its generated feature branch.
 4. Read the entire issue, linked specification, dependencies, and acceptance criteria.
   Reconcile them with the concept before designing or changing code.
-5. Inspect the legacy CLI donors — frozen in `legacy_cli_archive/` since US07-01,
+5. Inspect the legacy CLI donors before replacing applicable behavior. Update the donor
   with their ledger — before replacing applicable behavior. Update the donor
   ledger and characterization tests required by the story.
 6. Implement every acceptance criterion and its automated tests.
 7. Run story-specific tests and the accumulated regression suite required by the epic.
--- a/115
+++ b/115
@@ -1,115 +0,0 @@
 # One image, two roles (US08-02).
 #
 # The application is not self-contained Python: it shells out to `exiftool` for every
 # EXIF checkpoint and to `immich-go` for every upload, and it serves the static
 # frontend from `frontend/`. All three are installed here at pinned versions, because
 # an image whose external tools drift is an image whose metadata checkpoints and
 # upload reports drift with them (concept §15, "External integration risks").
 #
 # Everything is pinned:
 #   * the base image by tag *and* digest, so a moved tag cannot change the runtime;
 #   * exiftool by its Debian package version, verified against `exiftool -ver`;
 #   * immich-go by release version and per-architecture SHA-256 of the release asset.
 # The verified versions become image labels and /etc/photo-pipeline/versions.json,
 # which `python -m photo_pipeline diagnostics` reports — so a running container can
 # prove what it contains instead of being trusted about it.
 #
 # The project is installed editable on purpose: `photo_pipeline.db` resolves
 # `alembic.ini` and `migrations/`, and the API resolves `frontend/`, relative to the
 # repository root. An editable install keeps that one layout instead of scattering the
 # same files across site-packages and a source tree.
 ARG PYTHON_IMAGE=python:3.12.14-slim-trixie@sha256:2c941e860699f878900b0edc2403613c234d4b32eda3cc9fa7036991a2a63c4a
 # ── the uploader, fetched and verified outside the final layer ────────────────
 FROM ${PYTHON_IMAGE} AS uploader
 ARG IMMICH_GO_VERSION=0.32.0
 ARG IMMICH_GO_SHA256_AMD64=6e2ad86bafdadb9466d6515de7cb882726c0aea1a21d51164dff361d7d480a97
 ARG IMMICH_GO_SHA256_ARM64=2c35d9284baae407ef9540bdac5f488971b0bdc7be758a4d7c05ab270af09fdb
 COPY docker/fetch-immich-go.py /tmp/fetch-immich-go.py
 RUN python /tmp/fetch-immich-go.py \
        --version "${IMMICH_GO_VERSION}" \
        --sha256-amd64 "${IMMICH_GO_SHA256_AMD64}" \
        --sha256-arm64 "${IMMICH_GO_SHA256_ARM64}" \
        --into /usr/local/bin \
    && /usr/local/bin/immich-go version
 # ── the application ──────────────────────────────────────────────────────────
 FROM ${PYTHON_IMAGE} AS runtime
 ARG EXIFTOOL_VERSION=13.25+dfsg-1
 ARG IMMICH_GO_VERSION=0.32.0
 # The library is mounted from the host, so the container's identity must match the
 # ownership that library already has: everything this application renames, writes
 # EXIF into, or archives has to stay owned by the host user afterwards.
 ARG UID=1000
 ARG GID=1000
 LABEL org.opencontainers.image.title="photo_pipeline" \
      org.opencontainers.image.source="https://github.com/domverse/photoanalyzer" \
      io.photoanalyzer.exiftool.version="${EXIFTOOL_VERSION}" \
      io.photoanalyzer.immich-go.version="${IMMICH_GO_VERSION}"
 ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PATH=/opt/venv/bin:$PATH \
    PHOTO_PIPELINE_DATA_DIR=/data
 RUN set -eu; \
    apt-get update; \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        "libimage-exiftool-perl=${EXIFTOOL_VERSION}"; \
    rm -rf /var/lib/apt/lists/*
 COPY --from=uploader /usr/local/bin/immich-go /usr/local/bin/immich-go
 WORKDIR /app
 COPY pyproject.toml alembic.ini README.md ./
 COPY photo_pipeline ./photo_pipeline
 COPY migrations ./migrations
 COPY frontend ./frontend
 COPY docker/entrypoint.sh docker/healthcheck.sh /usr/local/bin/
 # Runtime dependencies only: the `test` extra (pytest, playwright) and the `vision`
 # extra stay out, and pip's build isolation leaves no build tooling behind.
 RUN set -eu; \
    python -m venv /opt/venv; \
    /opt/venv/bin/pip install --no-cache-dir -e .
 # What is installed must be what was pinned, or the labels and the version record
 # would be a claim rather than a fact.
 RUN set -eu; \
    mkdir -p /etc/photo-pipeline; \
    exiftool_version="$(exiftool -ver)"; \
    immich_go_version="$(immich-go version | head -n 1 | tr -d '\r')"; \
    expected_exiftool="$(printf '%s' "${EXIFTOOL_VERSION}" | cut -d+ -f1 | cut -d- -f1)"; \
    [ "${exiftool_version}" = "${expected_exiftool}" ] \
      || { echo "exiftool ${exiftool_version} is not the pinned ${expected_exiftool}" >&2; exit 1; }; \
    case "${immich_go_version}" in \
      *"${IMMICH_GO_VERSION}"*) ;; \
      *) echo "immich-go '${immich_go_version}' is not pinned ${IMMICH_GO_VERSION}" >&2; exit 1 ;; \
    esac; \
    printf '{\n  "exiftool": "%s",\n  "immich-go": "%s"\n}\n' \
        "${exiftool_version}" "${IMMICH_GO_VERSION}" > /etc/photo-pipeline/versions.json
 # Non-root, with the host library's ownership. /data is the persistent volume; the
 # photo library itself is mounted by the deployment (US08-03), never baked in.
 RUN set -eu; \
    groupadd --gid "${GID}" --non-unique app; \
    useradd --uid "${UID}" --gid "${GID}" --non-unique --no-create-home --home-dir /app app; \
    mkdir -p /data; \
    chown "${UID}:${GID}" /data
 USER ${UID}:${GID}
 EXPOSE 8000
 # Readiness, not liveness: an unmigrated or misconfigured database answers
 # /api/v1/health/ready with 503, and a container that cannot serve must not be
 # reported healthy. The worker role has no endpoint, so its check is a no-op here.
 HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD ["/usr/local/bin/healthcheck.sh"]
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["serve"]
--- a/README.md
+++ b/README.md
@@ -7,145 +7,16 @@ archive workflow. Planning lives in `INTEGRATED_PIPELINE_CONCEPT.md` and
 ## Application (`photo_pipeline`)
 The target application lives in `photo_pipeline/` (FastAPI + SQLAlchemy + Alembic).
-Install it into a virtualenv once:
+Run it with:
 ```bash
-python3.12 -m venv .venv
+python -m photo_pipeline migrate   # apply database migrations
-.venv/bin/pip install -e ".[vision]"   # drop [vision] for a review-only install
+python -m photo_pipeline serve     # start the API + static review UI (127.0.0.1:8000)
 ```
 Then run the two processes:
 ```bash
 .venv/bin/python -m photo_pipeline migrate   # apply database migrations
 .venv/bin/python -m photo_pipeline serve     # API + review UI at 127.0.0.1:8000/app/
 .venv/bin/python -m photo_pipeline worker    # second terminal: runs the jobs
 ```
 The server enqueues work and serves the UI; nothing actually scans, scores,
 analyses, uploads, or archives without a worker. `work_item/scripts/python` is the
 *helper's* launcher — it prefers Conda base and falls back to a bare system
 interpreter, so it is not how the application is run.
 Configuration comes from `PHOTO_PIPELINE_*` environment variables (see
 `photo_pipeline/config.py`); secrets are referenced, never logged.
 ### Configuration file
 `.env` in the working directory is read at startup, or any path named by
 `PHOTO_PIPELINE_ENV_FILE`. It is parsed, never executed: `KEY=value` lines,
 `#` comments, optional quotes — no interpolation and no `export`. **Anything already
 exported wins**, so the file is the standing configuration and the shell is the
 override for one run.
 The archived CLI's variable names still work, so an existing `photo_analyzer.env`
 can be used as-is:
 | in the file | applied as |
 |---|---|
 | `LLM_API_KEY` / `GEMINI_API_KEY` | `OPENAI_API_KEY` |
 | `LLM_BASE_URL` | `OPENAI_BASE_URL` |
 | `LIBRARY` | `PHOTO_PIPELINE_LIBRARY_ROOTS` |
 `.env` and `*.env` are gitignored and denied by the work-item safety checks: the
 file holds a real key and must never be committed.
 ### API access (US07-02)
 The app listens on loopback, so its attacker is another page in the same browser.
 Every `/api/v1` route except `health/live`, `health/ready`, and `session` requires
 the application session, and every mutation requires its CSRF token as well:
 ```bash
 BASE=http://127.0.0.1:8000
 TOKEN=$(curl -sc /tmp/pp.jar $BASE/api/v1/session | python -c 'import json,sys; print(json.load(sys.stdin)["csrf_token"])')
 curl -sb /tmp/pp.jar -H "X-CSRF-Token: $TOKEN" -X POST $BASE/api/v1/albums/proposals -d '{}' -H 'Content-Type: application/json'
 ```
 The session is per server process — restarting `serve` invalidates it, and the
 browser client re-bootstraps by itself. Requests are also refused when the `Host` is
 not a loopback name (DNS rebinding), when `Origin` is any other origin, when
 `Sec-Fetch-Site` says the request came from another site (an `<img>` pointed at a
 thumbnail), or when the body exceeds `PHOTO_PIPELINE_MAX_REQUEST_BYTES`. There is no
 CORS middleware at all, so no other origin can read a response.
 ### Reaching it through a hostname or proxy (US08-01)
 | variable | meaning |
 |---|---|
 | `PHOTO_PIPELINE_ALLOWED_HOSTS` | comma-separated extra names the app answers to; empty means loopback only |
 | `PHOTO_PIPELINE_ACCESS_SECRET` | traded for the session cookie at `GET /api/v1/session` via `X-Access-Secret` |
 | `PHOTO_PIPELINE_TRUSTED_PROXIES` | comma-separated peer addresses whose `X-Forwarded-Proto`/`X-Forwarded-Host` are believed |
 Being reachable *was* the authentication: whoever could open `127.0.0.1:8000` owned
 the library. So naming any non-loopback host — or binding to one, `0.0.0.0` included
 — makes the access secret mandatory, and `serve` refuses to start without it rather
 than publishing the library. Loopback-only deployments need no secret and behave
 exactly as before.
 ```bash
 curl -sc /tmp/pp.jar -H "X-Access-Secret: $PHOTO_PIPELINE_ACCESS_SECRET" \
  https://photos.example.com/api/v1/session
 ```
 The browser asks for the secret once per tab and keeps it in `sessionStorage`.
 Wrong secrets are rate-limited (5 per minute) and logged with the caller's address
 only. `Host` and `Origin` are judged against the configured names; the *external*
 scheme and host come from the forwarded headers only when the request arrived from a
 `PHOTO_PIPELINE_TRUSTED_PROXIES` address, so a client cannot declare its own origin,
 and the session cookie is marked `Secure` when that external scheme is HTTPS. Health
 endpoints stay reachable without the secret so an orchestrator can restart the
 container; nothing else does.
 ## Container image (US08-02)
 One image runs either role. It is built from a clean checkout with no arguments:
 ```bash
 docker build -t photo-pipeline:dev .
 ```
 Everything external is pinned, and the build fails rather than drifting: the Python
 base image by tag *and* digest, `exiftool` by its Debian package version (verified
 against `exiftool -ver`), and `immich-go` by release version and per-architecture
 SHA-256 of the release asset. The verified versions become image labels and
 `/etc/photo-pipeline/versions.json`, which `diagnostics` reports as `tools[].pinned`
 beside the version actually installed — so a replaced binary shows up as a
 `tool_version_drift` warning instead of as a misparsed upload report.
 | build argument | default | why change it |
 |---|---|---|
 | `UID` / `GID` | `1000` | must match the owner of the mounted photo library |
 | `PYTHON_IMAGE` | pinned digest | upgrading the base image |
 | `EXIFTOOL_VERSION` | Debian package version | upgrading exiftool |
 | `IMMICH_GO_VERSION` + `IMMICH_GO_SHA256_AMD64`/`_ARM64` | pinned release | upgrading the uploader (take the digests from that release's `checksums.txt`) |
 The first argument is the role, and every other management command still works:
 ```bash
 docker run --rm -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev migrate
 docker run -d -p 127.0.0.1:8000:8000 -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_HOST=0.0.0.0 -e PHOTO_PIPELINE_ACCESS_SECRET=... \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev serve
 docker run -d -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev worker
 ```
 One role per container: `serve` and `worker` each take the library process lock for
 their role (US07-05), so no supervisor starts both. The container refuses to run as
 UID 0 — files it renames or writes must keep the ownership the host library expects —
 and `/data` is the persistent volume holding the database, journals, backups, and
 thumbnail cache. Binding to `0.0.0.0` makes the access secret mandatory
 ([above](#reaching-it-through-a-hostname-or-proxy-us08-01)); `serve` refuses to start
 without it. The declared `HEALTHCHECK` polls `/api/v1/health/ready`, so a container
 whose database is unmigrated or misconfigured is never reported healthy.
 Composing the runtime and mounting the library is US08-03; publishing and deploying
 the image is US08-04.
 ## Testing
 One offline command runs the whole suite (unit, integration, and browser
@@ -298,306 +169,3 @@ work_item/scripts/python -m pytest -m phase_e -q
  bytes, and recovery after a restart).
 Phases A–D remain green in the full run above.
 ### Phase F acceptance gate
 Phase F (Epic E06: archive lifecycle) is the only stage that *removes* originals
 from the library, and the only one whose storage can walk away in someone's bag.
 One command runs the archive fault-injection suites, the black-box archive and
 restore API journeys, and the browser suite:
 ```bash
 work_item/scripts/python -m pytest -m phase_f -q
 ```
 - `tests/integration/test_archive_*.py` and `tests/integration/test_restore.py`
  drive real files on real filesystems: preflight against a mounted, missing,
  swapped, read-only, or full medium; copy-verify-remove and the same-filesystem
  move path; and a crash at **every** persisted journal transition in both transfer
  modes, asserting that no source is ever removed without a durable, byte-identical
  archive copy.
 - `tests/e2e/test_phase_f_pipeline.py` drives a real server and a real durable
  worker over HTTP: preflight blockers (offline medium, wrong volume, insufficient
  capacity, bytes changed after upload), a verified archive whose manifest, hashes,
  and path history are checked on the medium itself, a worker killed at each of
  `transferring`, `verified`, `removing`, `source_removed`, and `complete`, the
  evidence-based recovery that follows, offline deduplication of an exact and a
  fuzzy copy while the medium is away, mount return, restore, and a collision that
  restores beside its occupant.
 - **Archived is not missing.** An unmounted medium leaves its photos
  `archived_offline` — still hashed, still in the duplicate indexes, still
  previewable through their protected thumbnails — and a rescan neither prunes nor
  flags them.
 - **Ambiguity is never guessed.** A journal state the medium contradicts stays
  `manual`, offers no automatic action, and keeps blocking further archiving until
  a human decides.
 - `tests/e2e/test_archive_ui.py` covers the browser journeys (preview with
  destination identity and reclaimable bytes, blockers and mount instructions,
  progress split into transfer/verification/removal, interruption and recovery,
  offline browsing, restore, collision, keyboard confirmation, and reload).
 Phases A–E remain green in the full run above.
 ## Media and metadata hardening (US07-03)
 Every pixel the application reads goes through `photo_pipeline/imaging.py`: the
 declared dimensions are checked before anything is decoded, Pillow's
 decompression-bomb warning is treated as a refusal, JPEG decodes near the requested
 size, and each decoder failure becomes one of two typed errors. A damaged file is a
 per-item error with a persisted code, never a failed scan or a dead worker.
 Every metadata stage ends with an EXIF checkpoint (`services/exif_checkpoint.py`):
 snapshot, write the owned keywords, read back, prove the owned fields landed and that
 nothing else moved, refresh the file hash. A field the stage does not own that
 changed anyway makes the checkpoint `divergent` — recorded in `exif_projections`,
 shown in the review queue, never repaired behind the user's back, and not counted as
 verified, so upload stays blocked.
 The golden corpus that proves all of it is generated, not committed:
 `tests/fixtures/media_corpus.py` declares every format, orientation, profile,
 damage, and metadata case with its expected outcome, and the suite regenerates it
 twice to prove it does not drift.
 ```bash
 work_item/scripts/python -m pytest tests/integration/test_media_hardening.py tests/integration/test_exif_checkpoints.py -q
 ```
 ## Concurrency and crash recovery (US07-04)
 Crash safety is proven by crashing. `photo_pipeline/faults.py` defines the control
 points — the persisted transitions of the rename, archive, EXIF, upload, and job
 lanes — and arms one only when `PHOTO_PIPELINE_FAULT_AFTER` names it, at which
 point the process dies the way a `SIGKILL` does. There is no endpoint and no
 configuration field that can reach a barrier; a deployment that never sets the
 variable can never hit one.
 The race suite runs each scenario several times with a seed recorded on the test
 result (`race_seed`) and asserts invariants rather than schedules: work is never
 claimed or executed twice, a stale fencing token never commits, no file body is
 lost or overwritten, and the database still passes `PRAGMA integrity_check`.
 ```bash
 work_item/scripts/python -m pytest tests/integration/test_concurrency_races.py \
    tests/integration/test_fault_matrix.py tests/e2e/test_crash_recovery.py -q
 # replay a failure, or soak for new interleavings
 PHOTO_PIPELINE_RACE_SEED=1234 PHOTO_PIPELINE_RACE_REPEATS=50 \
    work_item/scripts/python -m pytest tests/integration/test_concurrency_races.py -q
 ```
 Any failing test keeps its evidence: the temporary database (with its write-ahead
 log), the journals, the logs, the recorded seed, and a SHA-256 manifest of every
 file in the temporary library are copied to `.artifacts/<test id>/` before pytest
 deletes the directory. Point `PHOTO_PIPELINE_TEST_ARTIFACTS` elsewhere to collect
 them from CI.
 ## Release gate (US07-07)
 One command runs every suite in an isolated stack and keeps the evidence:
 ```bash
 work_item/scripts/python -m photo_pipeline release-gate --output data/release/$(date -u +%Y%m%dT%H%M%SZ)
 ```
 It fails — and exits non-zero — when any stage fails, when a suite skips a test for
 a reason that is not a documented environment limit (`exiftool not installed`,
 `root ignores directory permissions`), or when the story matrix has a hole. The
 evidence directory holds `release-report.json` (revision, per-stage result, timings,
 summaries), `logs/<stage>.log`, and `CHECKSUMS.sha256` over both.
 **The story matrix** lives in `tests/story_traceability.json`: every story under
 `delivery_backlog/stories/` is either mapped to test files that exist, or listed in
 `planned` as an accepted but unimplemented story. A story that is neither, or a
 mapping to a file that has been deleted, fails the gate.
 **The journey** (`tests/e2e/test_release_journey.py`) takes one fresh library through
 discovery, duplicate review, safety, analysis, EXIF verification, album proposal,
 guarded rename, rescan, upload with server-side verification, archive, offline
 deduplication, and restore — over HTTP against real server and worker processes,
 with a full restart in the middle and at the end.
 ### Real-library dry run and approval
 Before the application is pointed at photos that cannot be replaced:
 ```bash
 work_item/scripts/python -m photo_pipeline dry-run --output dry-run.json
 work_item/scripts/python -m photo_pipeline approve-dry-run dry-run.json --approver "$(whoami)"
 ```
 The dry run is strictly read-only: it opens no file for writing, writes no database
 row, and reports what it found — file counts by extension, folders, bytes, unreadable
 files, excluded directories, and a reconciliation against what the database already
 knows (already registered, new, recorded but absent). Set
 `PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL=1` and **every mutating API request is
 refused with `403 dry_run_not_approved`** until a report for exactly those library
 roots has been approved. Reading stays open — you have to be able to see what was
 found in order to approve it — and so does taking a backup. Change the library roots
 and the approval no longer applies: it approves that reconciliation, not the idea of
 mutating.
 ## Performance budgets (US07-06)
 Budgets are measured, not asserted in prose. `python -m photo_pipeline benchmark`
 builds a synthetic library of a stated size, runs the same scenarios every time,
 writes a machine-readable report, and **exits non-zero when a budget is breached**.
 ```bash
 work_item/scripts/python -m photo_pipeline benchmark --profile smoke    # ~2 s, runs in CI
 work_item/scripts/python -m photo_pipeline benchmark --profile short    # 25k assets
 work_item/scripts/python -m photo_pipeline benchmark --profile full \
    --output data/benchmarks/full.json                                  # 25k + 100k
 work_item/scripts/python -m photo_pipeline benchmark --profile huge \
    --soak-seconds 3600 --output data/benchmarks/soak.json              # 500k + soak
 ```
 | Metric | Budget | Why |
 |---|---|---|
 | `latency_p95_ms` | 250 ms | a list or search page must feel immediate |
 | `latency_max_ms` | 2 000 ms | no single page may stall the review flow |
 | `rss_growth_bytes` | 400 MB | a run must not leak the library |
 | `open_files` | 256 | file descriptors are a hard operating-system limit |
 | `wal_bytes` | 200 MB | a growing write-ahead log means checkpoints are starving |
 | `queue_depth` | 1 000 | an unbounded queue is an out-of-memory in waiting |
 | `cache_over_quota_bytes` | 0 | the thumbnail cache has to respect its quota |
 Measured on the reference machine (Apple Silicon, SQLite WAL), p95 per scenario:
 | Scenario | 25k | 100k |
 |---|---|---|
 | `inventory_page` | 0.5 ms | 0.6 ms |
 | `library_search` | 4.8 ms | 17.1 ms |
 | `library_stats` | 56.8 ms | 197.4 ms |
 | `workflow_readiness` | 52.6 ms | 235.4 ms |
 | `duplicate_cluster_list` | 0.6 ms | 0.5 ms |
 | `duplicate_cluster_page` | 1.7 ms | 1.7 ms |
 CI runs the `smoke` profile through `tests/integration/test_performance_budgets.py`;
 the 25k/100k/500k matrix and the multi-hour soak belong to scheduled infrastructure,
 because minutes of build time do not belong in the suite that runs on every change.
 **Exceptions.** A budget that cannot be met is not a warning to ignore: it goes into
 `APPROVED_EXCEPTIONS` in `photo_pipeline/services/benchmarks.py` with its raised
 limit, who approved it, why, and a review date. Every report lists the exceptions it
 applied, so a release review sees them.
 Approved today, both for the 500k `huge` profile only, review by 2027-02-17:
 | Scenario | Measured at 500k | Raised limit |
 |---|---|---|
 | `library_stats` | 1.08 s p95 · 3.2 s max | 1.5 s p95 · 4 s max |
 | `workflow_readiness` | 1.40 s p95 · 3.3 s max | 1.8 s p95 · 4 s max |
 Both are library-wide aggregates — the current safety decision of every asset, and
 the album/tag/year breakdown of every analysis row — and both meet the 250 ms budget
 at the 100k rows the concept sets it for. Beyond that they are linear against one
 SQLite writer; the fix is denormalized totals or the planned PostgreSQL transition,
 not a query tweak. Everything else at 500k is inside budget, and a soak at that size
 grows neither resident memory nor the job queue.
 ## Backup and recovery (US07-05)
 Backups go through SQLite's online backup API, never a file copy: with WAL enabled
 the `.db` file alone is missing every committed page still in the write-ahead log.
 Each backup is a directory under `data/backups/` holding the snapshot and a
 `manifest.json` describing it — schema revision, SHA-256, row counts, the archive
 media the library depends on, and which configuration was set. Secrets are recorded
 as `configured`, never as values, so a manifest is safe to attach to a bug report.
 ```bash
 work_item/scripts/python -m photo_pipeline backup --reason before-upgrade --keep 7
 work_item/scripts/python -m photo_pipeline verify-backup data/backups/<name>
 work_item/scripts/python -m photo_pipeline diagnostics
 ```
 The same is available at `GET /api/v1/diagnostics`, `GET|POST /api/v1/backups`,
 `GET /api/v1/backups/{name}/verify`, and `POST /api/v1/backups/prune`. **Restore is
 not an endpoint** — it replaces the state of an installation, so it belongs to a
 stopped one and a person at a terminal.
 ### Integrity check
 `verify-backup` runs `PRAGMA integrity_check` (structure) *and*
 `PRAGMA foreign_key_check` (references), compares the snapshot's SHA-256 with the
 manifest, and re-counts every table the manifest recorded. Any mismatch — bit rot, a
 truncated copy, a "repaired" snapshot — fails the check, and `restore` refuses a
 backup that does not verify.
 ### Restore drill
 1. Stop the server and the worker.
 2. `python -m photo_pipeline verify-backup data/backups/<name>` — never restore an
   unverified snapshot.
 3. `python -m photo_pipeline restore data/backups/<name> --into /path/to/fresh-data`
   (a target that already holds a database is refused; recovering in place means
   moving the old data directory aside first).
 4. Point `PHOTO_PIPELINE_DATA_DIR` at the restored directory and run
   `python -m photo_pipeline migrate`.
 5. Run an inventory scan so paths are reconciled against the real library.
 6. Mount every archive location named in the manifest before archiving again — the
   database records where archived originals are, but it does not contain them.
 Practise this against a copy before you need it; the drill is exercised
 automatically by `tests/integration/test_backup_recovery.py`.
 ### Failed migration
 A pending schema upgrade is snapshotted first (`reason: pre-migration`), by both the
 API startup and `python -m photo_pipeline migrate`. If a migration fails, the error
 log names the backup directory: stop everything and run the restore drill against
 it. An up-to-date database is not backed up again on every start.
 ### Archive media
 Archived originals live on their medium, not in the backup. The manifest lists every
 archive location with its `media_id` and whether it was mounted when the backup was
 taken. Keep one copy of each medium off-site, and remount a location before
 restoring assets from it.
 ### Retention and disk
 `--keep N` (default 7) prunes the oldest backups and never the newest.
 `diagnostics` reports the database, write-ahead log, thumbnail cache, uploader
 reports, backups, and logs separately, with free space and warnings for low disk
 (`disk_low`, `disk_critical`), a cache over its quota, a write-ahead log outgrowing
 its database, and a legacy CLI writing the library.
 ### Process locking
 `serve` and `worker` take a JSON lock in the data directory (`api.lock.json`,
 `worker.lock.json`). A second worker exits `2` and names the holder; a lock whose
 process is gone is taken over. If the frozen CLI's state files are being written,
 both refuse with exit `3` — `--allow-legacy` overrides, and you own the outcome.
 ## Legacy CLI archive
 The command-line tools this application was extracted from are frozen in
 `legacy_cli_archive/` (US07-01): the original sources, their docs, the dependency
 lock they were last verified against, schema notes, a redacted sample
 configuration, the donor ledger, and a checksum for every file.
 ```bash
 cd legacy_cli_archive && shasum -a 256 -c CHECKSUMS.sha256   # verify the archive
 work_item/scripts/python -m pytest tests/unit/test_legacy_archive.py -q   # lint it
 ```
 They are reference material and rollback evidence only. No module under
 `photo_pipeline/` imports or executes them, the archive is not on the application's
 import path, and `tests/unit/test_legacy_archive.py` enforces that along with the
 checksums and the redaction. Only the two suites that compare *against* the donors —
 `tests/characterization/` and `tests/integration/test_safety_parity.py` — put the
 archived sources on `sys.path`.
 The last path-keyed state they owned, `nsfw_scores.csv`, is imported once and then
 left alone:
 ```bash
 work_item/scripts/python -m photo_pipeline import-legacy-scores /path/to/nsfw_scores.csv --dry-run
 ```
 The import writes scored-but-unreviewed `safety_reviews` rows onto stable asset ids,
 never invents an asset for an unknown path, never overwrites a human decision, and
 writes a reconciliation report to the data directory saying exactly what it did.
 `legacy_cli_archive/donor_ledger.yaml` records every migrated behavior with its
 target, the tests that pin the donor, the tests that prove the replacement, and each
 intentional delta; rows still marked `pending` name the story that will resolve them.
--- a/legacy_cli_archive/src/compare_models.py
+++ b/legacy_cli_archive/src/compare_models.py
--- a/delivery_backlog/E08-container-deployment.md
+++ b/delivery_backlog/E08-container-deployment.md
@@ -1,32 +0,0 @@
 # E08 — Container Deployment
 Concept phase: none. This epic is a delivery-format addition on top of the concept:
 the same application, same safety invariants, packaged as a Docker image and deployed
 continuously from Gitea Actions instead of being started by hand from a working copy.
 It does not change the product scope in
 [`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md). SQLite stays the
 store, one worker stays the writer, the library process lock stays authoritative, and
 no path outside the configured library roots becomes reachable because the process now
 runs in a container.
 One decision does extend the concept and is made here explicitly: the application may
 be reached through a reverse proxy under a real hostname, not only over loopback. That
 requires a configurable trust boundary and an authentication gate, because the
 loopback-only checks of US07-02 are what currently stand in for authentication.
 ## Stories
 1. [US08-01 — Make the trust boundary configurable and authenticated](stories/US08-01-trusted-hosts-auth.md)
 2. [US08-02 — Build a reproducible application image](stories/US08-02-container-image.md)
 3. [US08-03 — Compose the runtime and mount the library safely](stories/US08-03-compose-runtime.md)
 4. [US08-04 — Publish and deploy from Gitea Actions](stories/US08-04-gitea-cicd.md)
 5. [US08-05 — Automate container deployment acceptance](stories/US08-05-container-e2e.md)
 ## Epic outcome
 A tagged image built from `main` runs the API and the worker as separate containers
 against a mounted library and a persistent data volume, is published to the Gitea
 registry, is redeployed by webhook, survives restart and upgrade with its database and
 journals intact, and refuses every request that a loopback deployment would have
 refused.
--- a/delivery_backlog/README.md
+++ b/delivery_backlog/README.md
@@ -2,13 +2,11 @@
 This backlog decomposes the phases in
 [`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md) into seven
-epics and small, independently verifiable user stories, plus one delivery-format
+epics and small, independently verifiable user stories.
 epic (E08) that packages the released application as a deployable container.
 ## Numbering and file naming
- Epics: `E01` through `E07`, matching concept Phases A through G; `E08` has no
+- Epics: `E01` through `E07`, matching concept Phases A through G.
  concept phase and must not change product scope.
 - Stories: `US<epic>-<sequence>`, for example `US03-02`.
 - Epic files: `E01-<slug>.md`.
 - Story files: `stories/US01-01-<slug>.md`.
@@ -38,7 +36,6 @@ epic (E08) that packages the released application as a deployable container.
 5. [E05 — Immich upload](E05-immich-upload.md)
 6. [E06 — Archive lifecycle](E06-archive-lifecycle.md)
 7. [E07 — Hardening and release](E07-hardening-release.md)
 8. [E08 — Container deployment](E08-container-deployment.md)
 ## Shared definition of done
--- a/delivery_backlog/stories/US08-01-trusted-hosts-auth.md
+++ b/delivery_backlog/stories/US08-01-trusted-hosts-auth.md
@@ -1,42 +0,0 @@
 # US08-01 — Make the Trust Boundary Configurable and Authenticated
 Epic: [E08](../E08-container-deployment.md)
 As an operator, I want to reach the application through my own hostname without
 weakening it, so a container behind a reverse proxy is as safe as the loopback
 deployment it replaces.
 ## Context
 `photo_pipeline/api/security.py` refuses any request whose `Host` or `Origin` is not
 loopback. That check is the current stand-in for authentication: whoever can reach
 `127.0.0.1:8000` is the owner. Behind a proxy the hostname is no longer loopback, so
 relaxing the check without adding an authentication gate would publish the library.
 ## Acceptance criteria
 - Allowed hosts and origins come from configuration (`PHOTO_PIPELINE_*`), default to
  the current loopback set, and an unset configuration behaves exactly as today.
 - Whenever a non-loopback host is configured, startup requires an access secret and
  refuses to serve without one; loopback-only deployments keep working with no secret.
 - The secret is exchanged for the existing session cookie and CSRF token through the
  bootstrap endpoint; every protected route keeps its current session and CSRF
  requirements unchanged.
 - Forwarded headers (`X-Forwarded-Proto`, `X-Forwarded-Host`) are honored only from a
  configured trusted proxy and ignored otherwise, so a client cannot forge its origin.
 - Cookies are marked `Secure` when the effective external scheme is HTTPS.
 - Failed authentication is rate-limited and logged without the secret, the session id,
  or any request body.
 - Health endpoints stay reachable without the secret; nothing else does.
 ## Automated tests
 - Unit tests for host/origin evaluation across loopback default, configured host,
  unconfigured host, forged forwarded headers, and trusted-proxy forwarded headers.
 - Integration tests: startup refusal without a secret, successful exchange, wrong
  secret, replay of an old session, cross-site request, and unauthenticated access to
  every route class.
 ## Dependencies
 - US07-02
--- a/delivery_backlog/stories/US08-02-container-image.md
+++ b/delivery_backlog/stories/US08-02-container-image.md
@@ -1,41 +0,0 @@
 # US08-02 — Build a Reproducible Application Image
 Epic: [E08](../E08-container-deployment.md)
 As an operator, I want one image that can run either application role, so deployment is
 a pull instead of a Python environment I have to reproduce by hand.
 ## Context
 The application shells out to `exiftool` and `immich-go`, writes into the library as a
 normal filesystem user, and serves a static frontend from `frontend/`. All three have to
 be true inside the image, or the container starts and then fails on the first real
 operation.
 ## Acceptance criteria
 - A `Dockerfile` builds from a pinned Python base, installs the project and its runtime
  dependencies, and contains no test, playwright, or build-only tooling in the final
  layer.
 - `exiftool` and `immich-go` are present at pinned versions, and their versions are
  recorded in the image and reported by `python -m photo_pipeline diagnostics`.
 - The image runs as a non-root user whose UID/GID are build-time arguments, so files
  the application renames or writes keep the ownership the host library expects.
 - One entrypoint selects the role: `serve` or `worker`, passing through the existing
  CLI arguments; no supervisor runs two roles in one container.
 - `serve` containers declare a `HEALTHCHECK` against `/api/v1/health/ready`, so an
  unmigrated or misconfigured database is not reported healthy.
 - The image contains no secrets, no library data, no database, and no `.git`; the build
  context is constrained by `.dockerignore`.
 - Image build is reproducible from a clean checkout and documented in `README.md`.
 ## Automated tests
 - A build-and-run test asserts the image starts, reports ready, serves the frontend
  index, and returns the pinned `exiftool` and `immich-go` versions.
 - A test asserts the container refuses to run as UID 0 and that a file created by the
  container is owned by the configured UID/GID.
 ## Dependencies
 - US07-05
--- a/delivery_backlog/stories/US08-03-compose-runtime.md
+++ b/delivery_backlog/stories/US08-03-compose-runtime.md
@@ -1,47 +0,0 @@
 # US08-03 — Compose the Runtime and Mount the Library Safely
 Epic: [E08](../E08-container-deployment.md)
 As an operator, I want a single compose file that runs the API and the worker against my
 real library, so a deployment is one command and the safety invariants survive it.
 ## Context
 The library process lock (US07-05) assumes both roles see the same lock file, and SQLite
 in WAL mode assumes a real local filesystem. Container path policy is the same problem
 as host path policy with a new failure mode: the configured library roots must name the
 in-container mount paths, not the host paths.
 ## Acceptance criteria
 - `docker-compose.yml` runs exactly one `serve` and one `worker` container from the same
  image and the same data volume, and a second worker is refused by the existing lock
  rather than by convention.
 - The library is a bind mount; `PHOTO_PIPELINE_LIBRARY_ROOTS` names the container-side
  paths, and a mismatch between mounted and configured roots fails at startup with a
  clear message instead of at the first write.
 - The data volume holds the database, WAL, thumbnail cache, and backups on a local
  filesystem; the composition documents that a network mount is unsupported for it.
 - Migrations run before `serve` and `worker` accept work, using the existing backup-then-
  migrate path, and an upgrade that fails leaves the previous database intact.
 - Configuration and secrets come from the environment, never from the image or a
  committed file; a `.env.example` lists every `PHOTO_PIPELINE_*` variable with safe
  defaults and no values.
 - The API port is published to host loopback by default; exposing it publicly requires
  the configured hostname and access secret from US08-01.
 - Containers restart automatically, and a restart mid-job resumes exactly as a host
  restart does today.
 - Backup, verify-backup, restore, and diagnostics are documented as container commands
  and work against the mounted volumes.
 ## Automated tests
 - An integration test brings the composition up against a temporary fixture library,
  runs a job, restarts both containers, and asserts the job resumes and the database is
  intact.
 - Tests for: second worker refused, library-root mismatch refused at startup, failed
  migration leaving the previous database restorable.
 ## Dependencies
 - US08-01, US08-02
--- a/delivery_backlog/stories/US08-04-gitea-cicd.md
+++ b/delivery_backlog/stories/US08-04-gitea-cicd.md
@@ -1,40 +0,0 @@
 # US08-04 — Publish and Deploy from Gitea Actions
 Epic: [E08](../E08-container-deployment.md)
 As a release owner, I want `main` to build, publish, and redeploy the image
 automatically, so deployment is the same reproducible path every time.
 ## Context
 The workflow is adapted from the `crowdsec-admin` deployment workflow
 (`.gitea/workflows/deploy.yml` in that repository): build, log in to the Gitea registry,
 push, trigger a Portainer webhook, prune. This project needs the same shape plus a test
 gate, because unlike that project it has a required suite that must not be skipped.
 ## Acceptance criteria
 - `.gitea/workflows/` contains a test workflow that runs on pull requests and on `main`,
  executing the configured required suites, and a deploy workflow that runs only after
  the tests pass on `main` and on manual dispatch.
 - The deploy workflow publishes to `git.domverse-berlin.eu` under this project's own
  image path, tagged `latest` and the commit SHA, so a rollback is a tag change.
 - Registry credentials and the Portainer webhook come from repository secrets; runtime
  secrets (vision key, Immich key, access secret) stay in the Portainer stack and never
  enter the repository or the image.
 - Redeploy is triggered by webhook and the workflow fails when the webhook call fails.
 - Dangling images are pruned; published tags are not.
 - A concurrency guard prevents two deploys of different commits overlapping.
 - `README.md` documents the required secrets, the image path, the rollback procedure,
  and that the stack is managed by Portainer from git.
 ## Automated tests
 - Workflow files are validated (syntax and required job/step names) by a repository test
  so a rename cannot silently disable the test gate.
 - A dry-run job builds and pushes to a scratch tag on manual dispatch without touching
  `latest` or triggering a redeploy.
 ## Dependencies
 - US08-02, US08-03
--- a/delivery_backlog/stories/US08-05-container-e2e.md
+++ b/delivery_backlog/stories/US08-05-container-e2e.md
@@ -1,30 +0,0 @@
 # US08-05 — Automate Container Deployment Acceptance
 Epic: [E08](../E08-container-deployment.md)
 As a release owner, I want one automated gate that proves the deployed container, so the
 packaged application is verified the same way the host application is.
 ## Acceptance criteria
 - One documented command provisions the composition from the built image against a
  temporary fixture library and an isolated data volume, and destroys it afterwards.
 - A browser journey against the containerized application covers discovery, duplicate
  review, analysis, album proposal, rename, upload preflight, and archive views.
 - An upgrade journey runs the previous published image, then the new one, and asserts
  migrations, journals, jobs, and the thumbnail cache survive.
 - A restart journey kills both containers mid-job and asserts resume without duplicate
  side effects.
 - Security gates run against the deployed instance: unauthenticated access refused,
  forged forwarded headers refused, paths outside the mounted library roots refused, and
  no secret in container logs.
 - Evidence is retained per run and the gate fails on any skipped required check.
 ## Automated tests
 - The container acceptance suite runs on a `phase_h` marker in CI on `main` and before a
  published deploy; earlier epic suites keep running unchanged.
 ## Dependencies
 - US08-01 through US08-04
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -1,22 +0,0 @@
 #!/bin/sh
 # One entrypoint, one role per container (US08-02).
 #
 # The first argument is the management command the image runs — `serve` and `worker`
 # are the two roles, and every other `python -m photo_pipeline` command (migrate,
 # diagnostics, backup, restore, dry-run) is passed through unchanged so operating the
 # container is operating the same CLI. No supervisor: two roles in one container would
 # share a process lock they are each meant to hold alone (US07-05).
 set -eu
 if [ "$(id -u)" = "0" ]; then
    echo "refusing to run as root: start this image with a non-root UID/GID so files" \
         "it renames or writes keep the ownership the mounted library expects" >&2
    exit 1
 fi
 role="${1:-serve}"
 # The health check has to know which role it is checking, and only the API has an
 # endpoint to check. /tmp is writable for the unprivileged user; /run may not be.
 printf '%s' "${role}" > "${PHOTO_PIPELINE_ROLE_FILE:-/tmp/photo-pipeline-role}" 2>/dev/null || true
 exec python -m photo_pipeline "$@"
--- a/docker/fetch-immich-go.py
+++ b/docker/fetch-immich-go.py
@@ -1,72 +0,0 @@
 """Download one pinned immich-go release and verify it before unpacking (US08-02).
 Run at image build time by the `uploader` stage, with the interpreter that is already
 in the base image: no curl, no wget, and no download tooling in the layer that ships.
 The checksum is not advisory — a release asset that does not match the pinned digest
 is a failed build, not a warning, because the uploader's flags and report format are
 what the upload parser is written against (concept §15).
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import platform
 import tarfile
 import tempfile
 import urllib.request
 from pathlib import Path
 RELEASE_URL = "https://github.com/simulot/immich-go/releases/download/v{version}/{asset}"
 # Debian/BuildKit architecture as the interpreter sees it → release asset name.
 ASSETS = {
    "x86_64": ("immich-go_Linux_x86_64.tar.gz", "amd64"),
    "amd64": ("immich-go_Linux_x86_64.tar.gz", "amd64"),
    "aarch64": ("immich-go_Linux_arm64.tar.gz", "arm64"),
    "arm64": ("immich-go_Linux_arm64.tar.gz", "arm64"),
 }
 TIMEOUT_SECONDS = 300
 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--version", required=True, help="immich-go release, without the v")
    parser.add_argument("--sha256-amd64", required=True)
    parser.add_argument("--sha256-arm64", required=True)
    parser.add_argument("--into", default="/usr/local/bin")
    args = parser.parse_args()
    machine = platform.machine().lower()
    if machine not in ASSETS:
        raise SystemExit(f"unsupported architecture: {machine}")
    asset, arch = ASSETS[machine]
    expected = {"amd64": args.sha256_amd64, "arm64": args.sha256_arm64}[arch]
    url = RELEASE_URL.format(version=args.version, asset=asset)
    with urllib.request.urlopen(url, timeout=TIMEOUT_SECONDS) as response:  # noqa: S310
        payload = response.read()
    digest = hashlib.sha256(payload).hexdigest()
    if digest != expected:
        raise SystemExit(f"checksum mismatch for {url}: {digest} != {expected}")
    target = Path(args.into)
    target.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory() as work:
        archive = Path(work) / asset
        archive.write_bytes(payload)
        with tarfile.open(archive) as tar:
            member = tar.getmember("immich-go")
            # Extract exactly the one file this pin is about, by name, so nothing
            # else in the archive can decide where it lands.
            extracted = tar.extractfile(member)
            if extracted is None:
                raise SystemExit("release archive contains no immich-go binary")
            binary = target / "immich-go"
            binary.write_bytes(extracted.read())
            binary.chmod(0o755)
    print(f"immich-go {args.version} ({arch}) verified {digest}")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
--- a/docker/healthcheck.sh
+++ b/docker/healthcheck.sh
@@ -1,34 +0,0 @@
 #!/bin/sh
 # Container health for the `serve` role: readiness, not liveness (US08-02).
 #
 # /api/v1/health/ready is 503 until the database is reachable, migrated, and in WAL
 # mode with foreign keys on, so an unmigrated or misconfigured container never reports
 # healthy. Health endpoints need no session and no access secret, which is what lets an
 # orchestrator restart a container it holds no credentials for (US08-01).
 set -eu
 role="$(cat "${PHOTO_PIPELINE_ROLE_FILE:-/tmp/photo-pipeline-role}" 2>/dev/null || echo unknown)"
 if [ "${role}" != "serve" ]; then
    # ponytail: the worker has no endpoint to probe; its liveness is its lease and job
    # heartbeat in the database. Add a `worker --health` command if a restart policy
    # ever needs to act on it.
    exit 0
 fi
 port="${PHOTO_PIPELINE_PORT:-8000}"
 exec python - "${port}" <<'PY'
 import sys
 import urllib.error
 import urllib.request
 url = f"http://127.0.0.1:{sys.argv[1]}/api/v1/health/ready"
 try:
    with urllib.request.urlopen(url, timeout=5) as response:  # noqa: S310 — loopback
        sys.exit(0 if response.status == 200 else 1)
 except urllib.error.HTTPError as error:
    print(f"not ready: HTTP {error.code}", file=sys.stderr)
    sys.exit(1)
 except OSError as error:
    print(f"not ready: {error}", file=sys.stderr)
    sys.exit(1)
 PY
--- a/legacy_cli_archive/donor_ledger.yaml
+++ b/legacy_cli_archive/donor_ledger.yaml
@@ -12,15 +12,7 @@
 #                            (if anything) carries over
 # Every row needs either `tests` (existing test IDs, module::function) or
 # `pending_story` (the backlog story that will characterize/deliver it).
-# status: characterized — donor behavior pinned by characterization tests
+# status: characterized | pending
 #         resolved      — replacement shipped; `parity` names the tests that prove
 #                         it, and `delta` states every intentional difference
 #         pending       — not migrated yet; `pending_story` says which story will
 # parity: test ids (path::function) in any suite, proving the replacement
 # delta:  what the replacement deliberately does differently, or not at all
 #
 # Archived by US07-01: the sources referenced below now live beside this file in
 # src/ and are frozen (see README.md). Nothing in photo_pipeline imports them.
 rows:
  # ── photo_analyzer.py ──────────────────────────────────────────────────────
@@ -88,12 +80,8 @@ rows:
      Copying a primary's analysis into variant rows survives, but keyed by
      asset_id and recorded as stage state instead of raw row copies.
    target: photo_pipeline/services/duplicates.py
-    parity:
+    pending_story: US01-04
-      - tests/integration/test_duplicate_engine.py::test_exact_copies_form_auto_decided_cluster
+    status: pending
      - tests/integration/test_duplicate_engine.py::test_perceptual_variant_is_review_only
    delta: >
      The donor propagated variant links implicitly while writing rows; the replacement makes the canonical link a reviewable, reversible cluster decision, so a propagated link can always be undone.
    status: resolved
  - id: pa-hashing
    area: hashing
@@ -153,12 +141,8 @@ rows:
    classification: replace
    rationale: Console report; superseded by the duplicate-review API/UI (US01-06).
    target: photo_pipeline/api/routes + frontend duplicate review
-    parity:
+    pending_story: US01-06
-      - tests/integration/test_review_api.py::test_clusters_list_and_detail
+    status: pending
      - tests/e2e/test_review_ui.py::test_fuzzy_decision_requires_confirmation
    delta: >
      The text listing became the paged cluster API and the comparison UI; no textual report is produced.
    status: resolved
  - id: pa-reconcile
    area: database
@@ -218,7 +202,7 @@ rows:
      RGB-normalize (drops alpha, converts HEIC), LANCZOS resize to 2048px
      long-edge, JPEG q85 base64 — the provider-input contract. Truncated-image
      tolerance (ImageFile.LOAD_TRUNCATED_IMAGES) carries with it.
-    target: photo_pipeline/services/analysis.py
+    target: photo_pipeline/integrations/vision.py
    tests:
      - test_pa_imaging::test_prepare_image_small_passthrough_jpeg
      - test_pa_imaging::test_prepare_image_resizes_to_max_long_edge
@@ -246,12 +230,9 @@ rows:
      response validation, 429/503 retry with exponential backoff. Prompt and
      model/config version must be persisted per analysis_runs. Characterized
      against a deterministic fake provider when the analysis service is ported.
-    target: photo_pipeline/services/analysis.py
+    target: photo_pipeline/integrations/vision.py
-    parity:
+    pending_story: US02-06
-      - tests/integration/test_safety_analysis.py::test_provider_called_only_for_confirmed_sfw
+    status: pending
    delta: >
      The prompt and response schema carry over; the provider is an injected adapter so the privacy gate is testable, and results are keyed to asset ids rather than paths.
    status: resolved
  - id: pa-throttle
    area: logging
@@ -260,8 +241,8 @@ rows:
    rationale: >
      Rolling throttle window + persistent throttle_events.jsonl + RPD day
      counter become job metrics/events on the durable job model.
-    target: photo_pipeline/services/jobs.py + photo_pipeline/services/analysis.py
+    target: photo_pipeline/jobs/coordinator.py
-    pending_story: US07-04
+    pending_story: US02-02
    status: pending
  - id: pa-nsfw-filter
@@ -331,12 +312,8 @@ rows:
      checked between items, double-SIGINT force quit — becomes the durable
      JobRunner worker loop with the same drain-and-resume semantics.
    target: photo_pipeline/jobs/worker.py
-    parity:
+    pending_story: US02-02
-      - tests/integration/test_worker.py::test_worker_processes_all_items
+    status: pending
      - tests/integration/test_worker.py::test_cooperative_cancellation_leaves_items_resumable
    delta: >
      The in-process folder loop with SIGINT handling became durable jobs claimed by a worker: cancellation is a persisted request, not a signal, and an interrupted run resumes from the database instead of restarting.
    status: resolved
  - id: pa-ui-terminal
    area: ui
@@ -394,12 +371,8 @@ rows:
      the JSONL history logger become structured JSON logging with job_id/
      asset_id and job_events rows; per-photo history maps to job events.
    target: photo_pipeline structured logging + jobs/job_events
-    parity:
+    pending_story: US02-02
-      - tests/integration/test_jobs.py::test_enqueue_persists_items_and_event
+    status: pending
      - tests/integration/test_jobs_sse.py::test_sse_streams_all_events_then_closes
    delta: >
      The JSONL history file and rich console handler are replaced by structured JSON logs plus durable job_events; the browser reads events over SSE rather than tailing a file.
    status: resolved
  - id: pa-balance
    area: vision
@@ -409,11 +382,8 @@ rows:
      Provider balance/quota probes (report 'unsupported' on providers without
      the endpoint). Network-bound; characterized against the fake provider.
    target: photo_pipeline/services/analysis.py
-    parity:
+    pending_story: US02-06
-      - tests/integration/test_safety_analysis.py::test_provider_called_only_for_confirmed_sfw
+    status: pending
    delta: >
      Not carried over: balance/quota polling was provider-specific (Gemini/OpenAI billing endpoints) and key-scoped. Cost reporting, when a story asks for it, comes from the per-run usage recorded with each analysis result rather than from a vendor endpoint.
    status: resolved
  - id: pa-cli
    area: configuration
@@ -423,13 +393,9 @@ rows:
      argparse surface is superseded by the API; flags map to job configs
      (documented in WEBAPP_CONCEPT.md §8 parity table). Transitional CLI calls
      the shared services until archival (E07).
-    target: photo_pipeline/__main__.py (serve | worker | migrate | import-legacy-scores) + /api/v1
+    target: photo_pipeline/api + transitional CLI
-    parity:
+    pending_story: US07-01
-      - tests/integration/test_app_lifecycle.py::test_restart_preserves_data_and_reruns_migrations
+    status: pending
      - tests/unit/test_legacy_archive.py::test_production_code_never_imports_an_archived_module
    delta: >
      The argparse surface is not reproduced. Every flag that drove work became an API command or a job configuration; the CLI keeps only what an application needs to be operated (serve, worker, migrate) plus the one-off legacy CSV import.
    status: resolved
  # ── nsfwtag/ ───────────────────────────────────────────────────────────────
  - id: nt-discovery
@@ -456,17 +422,9 @@ rows:
      nsfw_scores.csv stops being the source of truth (concept: DB state).
      Format characterized (4-decimal scores, bad rows dropped) because the
      existing CSV must migrate into assets.safety_score.
-    target: photo_pipeline/services/legacy_import.py (one-off import into safety_reviews)
+    target: photo_pipeline/repositories (safety), CSV import in US01-02 migration
    tests: [test_nsfwtag::test_score_cache_roundtrip_and_tolerance]
-    parity:
+    status: characterized
      - tests/integration/test_legacy_import.py::test_scores_are_imported_onto_asset_identity
      - tests/integration/test_legacy_import.py::test_a_reviewed_asset_is_never_overwritten_by_the_csv
    delta: >
      The CSV is no longer read at runtime at all: it is imported once into
      scored-but-unreviewed safety_reviews rows and left on disk untouched. A path
      that matches nothing is reported, never turned into an asset, and a human
      decision always outranks an imported score.
    status: resolved
  - id: nt-score-model
    area: nsfw
@@ -480,13 +438,6 @@ rows:
      inference path needs the local model + deterministic fake.
    target: photo_pipeline/integrations/nsfw_model.py
    tests: [test_nsfwtag::test_score_images_cache_hit_skips_model]
    delta: >
      The donor set Pillow's process-global ImageFile.LOAD_TRUNCATED_IMAGES so a
      partially downloaded file still scored. Here the same process also hashes
      files and renders previews, and those must keep refusing a truncated file
      rather than silently working on half of one; scoring opens images through
      the bounded photo_pipeline.imaging door instead and skips the ones it cannot
      read, leaving them unscored and visibly undecided (US07-03).
    status: characterized
  - id: nt-exif-keyword
@@ -534,11 +485,8 @@ rows:
      Newline-list bulk tagging (nsfw_confirmed.txt flow) is superseded by DB
      review decisions; the existing list is a one-time migration input.
    target: photo_pipeline/services/safety.py (decision import in US01-02)
-    parity:
+    pending_story: US01-02
-      - tests/integration/test_safety_parity.py::test_extracted_marks_and_partition_match_donor
+    status: pending
    delta: >
      Bulk keyword application from a file list is replaced by decisions against asset ids; the EXIF write itself is the extracted, read-back-verified one.
    status: resolved
  - id: nt-ui
    area: ui
@@ -550,11 +498,8 @@ rows:
      threshold/score review flow, lightbox and keyboard model are the frontend
      donor for the Safety view (preserved per concept §10; ported in US02-01).
    target: photo_pipeline/api + frontend Safety view
-    parity:
+    pending_story: US02-01
-      - tests/e2e/test_workflow_views.py::test_safety_review_decide_persists_across_reload
+    status: pending
    delta: >
      The stdlib review server is replaced by the API plus the Safety view; the donor's layout, thresholds, and keyboard flow carry over, its embedded HTML generation does not.
    status: resolved
  - id: nt-bench
    area: nsfw
@@ -564,11 +509,8 @@ rows:
      Dev-only model benchmark; archived without webapp replacement (recorded
      basis of the AdamCodd model choice). No production caller.
    target: none (archive as reference)
-    parity:
+    pending_story: US07-01
-      - tests/unit/test_legacy_archive.py::test_every_archived_source_matches_its_checksum
+    status: pending
    delta: >
      No replacement: a dev-only benchmark whose result (the AdamCodd model choice) is already recorded. Kept in the archive as the basis of that choice.
    status: resolved
  # ── webapp/ ────────────────────────────────────────────────────────────────
  - id: wa-query-search
@@ -637,13 +579,9 @@ rows:
      Subprocess-driving-the-CLI job control is superseded by durable DB jobs
      with a worker process. Two ideas carry over: progress derived from DB
      counts (not job-private state) and single-mutating-job enforcement.
-    target: photo_pipeline/services/jobs.py + photo_pipeline/jobs/worker.py
+    target: photo_pipeline/jobs/coordinator.py
-    parity:
+    pending_story: US02-02
-      - tests/integration/test_jobs.py::test_idempotency_key_returns_same_job
+    status: pending
      - tests/integration/test_worker.py::test_handler_failure_fails_the_job
    delta: >
      Subprocess supervision of a CLI is replaced by durable jobs in the same process family: there is no subprocess to supervise, and progress is persisted rather than scraped from stdout.
    status: resolved
  - id: wa-server
    area: ui
@@ -655,9 +593,5 @@ rows:
      browser. analyzer.html + page.py design (dark OLED tokens, Library/
      Analyze/Stats views) is frontend donor material per concept §10.
    target: photo_pipeline/api/app.py + frontend
-    parity:
+    pending_story: US02-05
-      - tests/e2e/test_frontend_shell.py::test_shell_loads_assets_without_console_or_network_errors
+    status: pending
      - tests/e2e/test_frontend_shell.py::test_deep_link_and_reload_restore_view_and_filters
    delta: >
      The stdlib HTTP routes become the versioned FastAPI API and the static frontend shell; Python no longer interpolates HTML.
    status: resolved
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -19,7 +19,6 @@
        <a href="#/albums" data-nav="albums">Albums</a>
        <a href="#/renames" data-nav="renames">Renames</a>
        <a href="#/uploads" data-nav="uploads">Upload</a>
        <a href="#/archive" data-nav="archive">Archive</a>
        <a href="#/stats" data-nav="stats">Stats</a>
      </nav>
    </header>
--- a/frontend/js/api.js
+++ b/frontend/js/api.js
@@ -2,62 +2,14 @@
 // cancellation. Every method accepts an optional { signal } from cancellable().
 export const BASE = "/api/v1";
 // The API refuses every request without the session cookie, and every mutation
 // without this token echoed back. The token is readable only same-origin, which is
 // what makes it proof that the caller is this app and not another page.
 let csrfToken = null;
 // A deployment reachable through a proxy trades an operator secret for that cookie.
 // Kept per tab: sessionStorage dies with the tab, and the secret never enters a URL.
 const SECRET_KEY = "pp_access_secret";
 async function bootstrap(secret) {
  return fetch(BASE + "/session", {
    credentials: "same-origin",
    headers: secret ? { "X-Access-Secret": secret } : {},
  });
 }
 async function session() {
  if (csrfToken === null) {
    let response = await bootstrap(sessionStorage.getItem(SECRET_KEY));
    if (response.status === 401) {
      sessionStorage.removeItem(SECRET_KEY);
      const secret = prompt("Access secret");
      if (secret) {
        response = await bootstrap(secret);
        if (response.ok) sessionStorage.setItem(SECRET_KEY, secret);
      }
    }
    const body = await response.json().catch(() => null);
    csrfToken = (body && body.csrf_token) || null;
  }
  return csrfToken || "";
 }
 async function send(path, { signal, ...options }) {
  return fetch(BASE + path, {
    credentials: "same-origin",
    signal,
    ...options,
    headers: {
      "Content-Type": "application/json",
      "X-CSRF-Token": await session(),
      ...(options.headers || {}),
    },
  });
 }
 async function request(path, { signal, ...options } = {}) {
  let response;
  try {
-    response = await send(path, { signal, ...options });
+    response = await fetch(BASE + path, {
-    // A restarted server issues a new session; re-bootstrap once rather than
+      headers: { "Content-Type": "application/json" },
-    // stranding an open tab on 401.
+      signal,
-    if (response.status === 401) {
+      ...options,
-      csrfToken = null;
+    });
      response = await send(path, { signal, ...options });
    }
  } catch (error) {
    // A caller-cancelled fetch is not a failure; tag it so views can ignore it.
    if (error.name === "AbortError") {
@@ -93,10 +45,8 @@ export const api = {
    request("/inventory/assets?" + new URLSearchParams(params).toString(), opts),
  listClusters: (params = {}, opts = {}) =>
    request("/duplicates/clusters?" + new URLSearchParams(params).toString(), opts),
-  getCluster: (id, params = {}, opts = {}) => {
+  getCluster: (id, opts = {}) =>
-    const query = new URLSearchParams(params).toString();
+    request(`/duplicates/clusters/${encodeURIComponent(id)}`, opts),
    return request(`/duplicates/clusters/${encodeURIComponent(id)}${query ? `?${query}` : ""}`, opts);
  },
  decide: (id, payload, opts = {}) =>
    request(`/duplicates/clusters/${encodeURIComponent(id)}/decision`, {
      method: "POST",
@@ -188,31 +138,4 @@ export const api = {
    }),
  uploadVerifications: (id, opts = {}) =>
    request(`/upload-batches/${encodeURIComponent(id)}/verifications`, opts),
  // ── Archive and restore: destinations, preflight, plans, recovery ────────
  archiveLocations: (opts = {}) => request("/archive-locations", opts),
  registerArchiveLocation: (payload, opts = {}) =>
    request("/archive-locations", { method: "POST", body: JSON.stringify(payload), ...opts }),
  archivePreflight: (payload, opts = {}) =>
    request("/archive-preflight", { method: "POST", body: JSON.stringify(payload), ...opts }),
  createArchivePlan: (payload, opts = {}) =>
    request("/archive-plans", { method: "POST", body: JSON.stringify(payload), ...opts }),
  listArchivePlans: (opts = {}) => request("/archive-plans", opts),
  getArchivePlan: (id, opts = {}) => request(`/archive-plans/${encodeURIComponent(id)}`, opts),
  applyArchivePlan: (id, opts = {}) =>
    request(`/archive-plans/${encodeURIComponent(id)}/apply`, { method: "POST", ...opts }),
  archiveRecovery: (opts = {}) => request("/archive-recovery", opts),
  resolveArchiveRecovery: (opts = {}) =>
    request("/archive-recovery/resolve", { method: "POST", ...opts }),
  restorePreflight: (payload, opts = {}) =>
    request("/restore-preflight", { method: "POST", body: JSON.stringify(payload), ...opts }),
  createRestorePlan: (payload, opts = {}) =>
    request("/restore-plans", { method: "POST", body: JSON.stringify(payload), ...opts }),
  listRestorePlans: (opts = {}) => request("/restore-plans", opts),
  getRestorePlan: (id, opts = {}) => request(`/restore-plans/${encodeURIComponent(id)}`, opts),
  applyRestorePlan: (id, opts = {}) =>
    request(`/restore-plans/${encodeURIComponent(id)}/apply`, { method: "POST", ...opts }),
  restoreRecovery: (opts = {}) => request("/restore-recovery", opts),
  resolveRestoreRecovery: (opts = {}) =>
    request("/restore-recovery/resolve", { method: "POST", ...opts }),
 };
--- a/frontend/js/app.js
+++ b/frontend/js/app.js
@@ -1,5 +1,4 @@
 import { api } from "./api.js";
 import { renderArchive, setArchiveRender } from "./archive.js";
 import { navigate, onRouteChange, parseHash } from "./router.js";
 import { renderRenames, setRenamesRender } from "./renames.js";
 import { renderUploads, setUploadsRender } from "./uploads.js";
@@ -193,7 +192,7 @@ async function renderClusters(params) {
        " ",
        el("span", { class: `badge ${cluster.state}` }, cluster.state)
      ),
-      el("div", { class: "muted" }, `${cluster.member_total ?? cluster.members.length} members · confidence ${cluster.confidence}`)
+      el("div", { class: "muted" }, `${cluster.members.length} members · confidence ${cluster.confidence}`)
    )
  );
@@ -207,11 +206,8 @@ async function renderClusters(params) {
 async function renderClusterDetail(id, extra = {}) {
  setActiveNav("duplicates");
  let cluster;
  // A cluster can hold thousands of members, so the server pages them; the page
  // asks for as many as it is currently showing (US07-06).
  const shown = extra.shown || 0;
  try {
-    cluster = await api.getCluster(id, shown ? { limit: shown } : {});
+    cluster = await api.getCluster(id);
  } catch (error) {
    show(errorBanner(`Failed to load cluster: ${error.message}`));
    return;
@@ -301,19 +297,6 @@ async function renderClusterDetail(id, extra = {}) {
  nodes.push(decisionBar);
  if (extra.pending) nodes.push(confirmPanel(cluster, extra.pending));
  nodes.push(el("div", { class: "cluster-grid" }, ...members));
  const total = cluster.member_total ?? cluster.members.length;
  if (cluster.members.length < total) {
    nodes.push(
      el(
        "button",
        {
          "data-testid": "show-more-members",
          onclick: () => renderClusterDetail(id, { ...extra, shown: cluster.members.length + 100 }),
        },
        `Show more (${cluster.members.length} of ${total})`
      )
    );
  }
  show(...nodes);
 }
@@ -383,7 +366,6 @@ function render() {
  else if (path === "/albums") renderAlbums(root, params);
  else if (path === "/renames") renderRenames(root, params);
  else if (path === "/uploads") renderUploads(root, params);
  else if (path === "/archive") renderArchive(root, params);
  else if (path === "/stats") renderStats(root, params);
  else show(errorBanner("Unknown view"));
 }
@@ -392,6 +374,5 @@ function render() {
 setRender(render);
 setRenamesRender(render);
 setUploadsRender(render);
 setArchiveRender(render);
 onRouteChange(render);
 render();
--- a/frontend/js/archive.js
+++ b/frontend/js/archive.js
@@ -1,870 +0,0 @@
 // Archive view (US06-05): preview what would leave active storage, confirm it
 // exactly, watch the transfer, recover an interrupted one, browse what is already
 // archived, and bring it back.
 //
 // Archiving is the only stage that removes originals, so this view never decides
 // anything itself: the destination's identity, every blocker, the confirmation
 // token, and what recovery may do all come from the server, and an action the
 // server would refuse is not offered. Two things follow from that. A medium that
 // is not mounted produces an instruction naming it rather than a disabled mystery,
 // and an operation whose evidence is ambiguous offers no button at all.
 import { api } from "./api.js";
 import { el, errorBanner, setActiveNav } from "./dom.js";
 import { subscribeJob } from "./events.js";
 import { navigate } from "./router.js";
 let outcome = null;
 let activity = [];
 let render = () => {};
 export function setArchiveRender(fn) {
  render = fn;
 }
 // The per-file journal states, split into the three things an operator actually
 // wants told apart: bytes moving, bytes proven, original removed (concept §9).
 const PHASES = [
  ["planned", "planned", "waiting"],
  ["transferring", "transfer", "copying to the medium"],
  ["verified", "verified", "archive copy hashed and manifested"],
  ["removing", "removing", "removing the active original"],
  ["complete", "complete", "archived and removed"],
  ["failed", "failed", "left alone for a decision"],
 ];
 const AVAILABILITY_LABEL = {
  active: "in the library",
  archived_online: "archived · medium mounted",
  archived_offline: "archived · medium away",
  missing_unexpected: "missing — unexplained",
 };
 export async function renderArchive(root, params = {}) {
  setActiveNav("archive");
  let locations;
  try {
    locations = (await api.archiveLocations()).locations;
  } catch (error) {
    root.replaceChildren(errorBanner(`Failed to load archive locations: ${error.message}`));
    return;
  }
  const location = locations.find((l) => l.id === params.location) || locations[0] || null;
  const nodes = [el("h1", {}, "Archive"), locationsCard(locations, location, params)];
  if (!location) {
    nodes.push(
      el(
        "p",
        { class: "muted", "data-testid": "no-locations" },
        "Register the disk, NAS share, or removable medium that will hold archived originals."
      ),
      outcomeBanner()
    );
    root.replaceChildren(...nodes.filter(Boolean));
    return;
  }
  const [preflight, archivePlans, restorePlans, recovery, restoreRecovery, archived, restore] =
    await Promise.all([
      load(() => api.archivePreflight({ location_id: location.id })),
      load(() => api.listArchivePlans()),
      load(() => api.listRestorePlans()),
      load(() => api.archiveRecovery()),
      load(() => api.restoreRecovery()),
      load(() => api.listAssets({ limit: 200 })),
      load(() => api.restorePreflight({ location_id: location.id })),
    ]);
  // Both directions share the runs table: one lane moves these originals, so one
  // history is what an operator has to reason about.
  const runs = [...plans(archivePlans), ...plans(restorePlans)].sort((a, b) =>
    (a.created_at || "").localeCompare(b.created_at || "")
  );
  const chosen = runs.find((run) => run.id === params.plan) || runs[runs.length - 1] || null;
  const selectedPlan = chosen ? await load(() => planDetailOf(chosen)) : null;
  nodes.push(
    preflight ? previewSection(preflight, location) : null,
    preflight ? confirmBlock(preflight, location) : null,
    outcomeBanner(),
    activityLog(),
    recoverySection(mergeRecovery(recovery, restoreRecovery)),
    planList(runs, chosen && chosen.id),
    selectedPlan ? planDetail(selectedPlan) : null,
    archived ? archivedSection(archived.items, locations) : null,
    restore ? restoreSection(restore, location) : null
  );
  root.replaceChildren(...nodes.filter(Boolean));
 }
 function plans(listed) {
  return listed ? listed.plans : [];
 }
 function planDetailOf(run) {
  return run.direction === "restore" ? api.getRestorePlan(run.id) : api.getArchivePlan(run.id);
 }
 // Archive and restore recovery answer the same question about the same lane, so
 // they are one list; an unresolved item of either kind blocks the other.
 function mergeRecovery(archive, restore) {
  if (!archive && !restore) return null;
  return {
    operations: [...((archive || {}).operations || []), ...((restore || {}).operations || [])],
    manual: [...((archive || {}).manual || []), ...((restore || {}).manual || [])],
  };
 }
 // A section whose data failed to load must not take the rest of the view with it:
 // the medium being away is exactly when the archived-asset list matters most.
 async function load(call) {
  try {
    return await call();
  } catch (_) {
    return null;
  }
 }
 // ── locations ────────────────────────────────────────────────────────────────
 // A location is a medium, not a path: the marker's ``media_id`` is what proves the
 // right disk is mounted, so it is shown next to the state it produced.
 function locationsCard(locations, selected, params) {
  const name = el("input", {
    type: "text",
    "data-testid": "location-name",
    "aria-label": "Archive location name",
    placeholder: "External disk",
  });
  const root = el("input", {
    type: "text",
    "data-testid": "location-root",
    "aria-label": "Archive location path",
    placeholder: "/Volumes/archive",
  });
  return el(
    "div",
    { class: "card", "data-testid": "archive-locations" },
    el("h2", {}, "Destinations"),
    locations.length
      ? el(
          "table",
          { class: "grid", "data-testid": "locations" },
          el(
            "thead",
            {},
            el(
              "tr",
              {},
              ...["", "Name", "Root", "Medium", "State", "Last seen"].map((label) =>
                el("th", { scope: "col" }, label)
              )
            )
          ),
          el(
            "tbody",
            {},
            ...locations.map((location) =>
              el(
                "tr",
                {
                  "data-testid": "location-row",
                  "data-name": location.name,
                  "aria-current": selected && location.id === selected.id ? "true" : false,
                },
                el(
                  "td",
                  {},
                  el("input", {
                    type: "radio",
                    name: "archive-location",
                    "data-testid": "select-location",
                    "aria-label": `Use ${location.name}`,
                    checked: selected && location.id === selected.id ? "checked" : false,
                    onchange: () => navigate("/archive", { ...params, location: location.id }),
                  })
                ),
                el("td", { "data-testid": "location-label" }, location.name),
                el("td", { class: "path", "data-testid": "location-path" }, location.root),
                el("td", { class: "path", "data-testid": "location-media" }, location.media_id),
                el(
                  "td",
                  {},
                  el(
                    "span",
                    {
                      class: `badge ${location.state === "online" ? "complete" : "attention"}`,
                      "data-testid": "location-state",
                    },
                    location.state
                  )
                ),
                el("td", { class: "muted" }, location.last_seen_at || "never")
              )
            )
          )
        )
      : null,
    selected && selected.state !== "online" ? mountInstruction(selected) : null,
    el(
      "div",
      { class: "toolbar" },
      name,
      root,
      el(
        "button",
        {
          "data-testid": "register-location",
          onclick: () =>
            run(() => api.registerArchiveLocation({ name: name.value, root: root.value })),
        },
        "Register destination"
      )
    )
  );
 }
 // The one thing the app cannot do for the user: name the medium to connect.
 function mountInstruction(location) {
  const detail =
    location.state === "wrong_volume"
      ? `A different medium is mounted at ${location.root}.`
      : `Nothing is mounted at ${location.root}.`;
  return el(
    "div",
    { class: "confirm", role: "status", "data-testid": "mount-instruction" },
    `${detail} Connect “${location.name}” (medium ${location.media_id}) and mount it there, ` +
      "then reload this view. Archived photos stay listed and searchable meanwhile."
  );
 }
 // ── preview ──────────────────────────────────────────────────────────────────
 function previewSection(preflight, location) {
  const totals = preflight.totals;
  const capacity = preflight.capacity;
  const rows = preflight.albums.map((album) =>
    el(
      "tr",
      { "data-testid": "archive-album-row", "data-album": album.album },
      el("td", { "data-testid": "album-name" }, album.album),
      el("td", { class: "path", "data-testid": "album-folder" }, album.folder),
      el("td", { class: "path", "data-testid": "album-destination" }, album.destination),
      el(
        "td",
        { "data-testid": "album-method" },
        album.transfer_method === "move" ? "move (same filesystem)" : "copy · verify · remove"
      ),
      el("td", { "data-testid": "album-assets" }, String(album.asset_count)),
      el("td", { "data-testid": "album-reclaim" }, bytes(album.reclaimable_bytes)),
      el(
        "td",
        {},
        el("span", { class: `badge ${album.state}`, "data-testid": "album-state" }, album.state),
        ...album.blockers.map((blocker) =>
          el(
            "div",
            { class: "blocker", "data-testid": "album-blocker", "data-code": blocker.code },
            blocker.message
          )
        )
      )
    )
  );
  return el(
    "div",
    { "data-testid": "archive-preview" },
    el("h2", {}, "Preview"),
    el(
      "div",
      { class: "decision-bar" },
      el(
        "span",
        { class: "badge", "data-testid": "destination-identity" },
        `${location.name} · ${location.media_id}`
      ),
      el("span", { class: "badge", "data-testid": "total-albums" }, `${totals.albums} album(s)`),
      el("span", { class: "badge", "data-testid": "total-assets" }, `${totals.assets} photo(s)`),
      el(
        "span",
        { class: "badge", "data-testid": "total-reclaim" },
        `${bytes(totals.bytes)} reclaimable`
      ),
      el(
        "span",
        {
          class: `badge ${capacity.sufficient ? "complete" : "blocked"}`,
          "data-testid": "capacity",
        },
        `free ${bytes(capacity.free_bytes)} · reserve ${bytes(capacity.reserve_bytes)}`
      )
    ),
    blockerList(preflight.blockers, "preflight-blockers", "preflight-blocker", "This scope cannot be archived yet"),
    rows.length
      ? el(
          "table",
          { class: "grid", "data-testid": "archive-albums" },
          el(
            "thead",
            {},
            el(
              "tr",
              {},
              ...["Album", "Folder", "Destination", "Transfer", "Photos", "Reclaims", "State"].map(
                (label) => el("th", { scope: "col" }, label)
              )
            )
          ),
          el("tbody", {}, ...rows)
        )
      : el(
          "p",
          { class: "muted", "data-testid": "no-albums" },
          "No album has a verified upload whose bytes are still unchanged, so nothing may be archived."
        )
  );
 }
 function blockerList(blockers, containerId, itemId, title) {
  if (!blockers || !blockers.length) return null;
  return el(
    "div",
    { class: "alert", role: "alert", "data-testid": containerId },
    el("strong", {}, title),
    el(
      "ul",
      {},
      ...blockers.map((blocker) =>
        el("li", { "data-testid": itemId, "data-code": blocker.code }, `${blocker.code}: ${blocker.message}`)
      )
    )
  );
 }
 // ── confirmation ─────────────────────────────────────────────────────────────
 function confirmBlock(preflight, location) {
  const ready = preflight.state === "ready";
  const totals = preflight.totals;
  return el(
    "div",
    { class: "card", "data-testid": "confirm" },
    el("h2", {}, "Confirm"),
    el(
      "p",
      { class: "muted", "data-testid": "confirm-token" },
      `Preflight ${preflight.token.slice(0, 20)}… · ${location.name}`
    ),
    el(
      "p",
      { "data-testid": "archive-note" },
      "Archiving removes each original from the library — but only after its copy on " +
        "the medium has been written, hashed, and recorded in the manifest. The photos " +
        "stay searchable and deduplicable while the medium is away, and can be restored " +
        "from this view."
    ),
    el(
      "div",
      { class: "toolbar" },
      el(
        "button",
        {
          class: "primary",
          "data-testid": "start-archive",
          disabled: ready ? false : "disabled",
          title: ready ? false : "resolve the blockers above first",
          onclick: () =>
            run(async () => {
              const plan = await api.createArchivePlan({
                location_id: location.id,
                token: preflight.token,
              });
              const started = await api.applyArchivePlan(plan.id);
              watch(started.job.id, plan.id, "archive");
              return { archiving: plan.asset_count };
            }),
        },
        `Archive ${totals.ready_albums} album(s) · reclaim ${bytes(totals.bytes)}`
      )
    )
  );
 }
 // ── plans and progress ───────────────────────────────────────────────────────
 function planList(runs, selectedId) {
  if (!runs.length) {
    return el("p", { class: "muted", "data-testid": "no-plans" }, "Nothing has been archived yet.");
  }
  return el(
    "div",
    { "data-testid": "archive-plans" },
    el("h2", {}, "Runs"),
    el(
      "table",
      { class: "grid", "data-testid": "plans" },
      el(
        "thead",
        {},
        el(
          "tr",
          {},
          ...["Created", "Direction", "State", "Photos", "Bytes"].map((l) =>
            el("th", { scope: "col" }, l)
          )
        )
      ),
      el(
        "tbody",
        {},
        ...runs.map((plan) =>
          el(
            "tr",
            {
              "data-testid": "plan-row",
              "data-plan": plan.id,
              "data-direction": plan.direction,
              "aria-current": plan.id === selectedId ? "true" : false,
            },
            el(
              "td",
              {},
              el("a", { class: "link", href: `#/archive?plan=${encodeURIComponent(plan.id)}` }, plan.created_at || plan.id)
            ),
            el("td", { "data-testid": "plan-direction" }, plan.direction),
            el("td", {}, el("span", { class: `badge ${plan.state}`, "data-testid": "plan-state" }, plan.state)),
            el("td", {}, String(plan.asset_count)),
            el("td", {}, bytes(plan.byte_size))
          )
        )
      )
    )
  );
 }
 function planDetail(plan) {
  const operations = plan.operations || [];
  const counts = {};
  for (const operation of operations) {
    counts[operation.journal_state] = (counts[operation.journal_state] || 0) + 1;
  }
  return el(
    "div",
    { class: "card", "data-testid": "plan-detail", "data-plan": plan.id },
    el("h2", {}, `${plan.direction === "restore" ? "Restore" : "Archive"} run ${plan.created_at || plan.id}`),
    // Transfer, verification, and removal are separate answers to separate
    // questions: what has moved, what is proven, and what is already gone.
    el(
      "div",
      { class: "decision-bar", "data-testid": "plan-progress" },
      el("span", { class: `badge ${plan.state}`, "data-testid": "detail-state" }, plan.state),
      ...PHASES.map(([key, label, title]) =>
        el(
          "span",
          { class: `badge ${key}`, "data-testid": `count-${label}`, title },
          `${label}: ${counts[key] ?? 0}`
        )
      )
    ),
    el(
      "table",
      { class: "grid", "data-testid": "operations" },
      el(
        "thead",
        {},
        el(
          "tr",
          {},
          ...["Photo", "Destination", "Phase", "Attempts", "Problem"].map((l) =>
            el("th", { scope: "col" }, l)
          )
        )
      ),
      el(
        "tbody",
        {},
        ...operations.map((operation) =>
          el(
            "tr",
            { "data-testid": "operation-row", "data-asset-id": operation.asset_id },
            el("td", { class: "path", "data-testid": "operation-source" }, operation.source_path),
            el("td", { class: "path", "data-testid": "operation-destination" }, operation.destination_path),
            el(
              "td",
              {},
              el(
                "span",
                { class: `badge ${operation.journal_state}`, "data-testid": "operation-phase" },
                phaseLabel(operation.journal_state)
              )
            ),
            el("td", {}, String(operation.attempt_count)),
            el(
              "td",
              { class: "muted", "data-testid": "operation-error", "data-code": operation.error_code || "" },
              operation.error_code ? `${operation.error_code}: ${operation.error_message || ""}` : "—"
            )
          )
        )
      )
    )
  );
 }
 function phaseLabel(state) {
  const found = PHASES.find(([key]) => key === state);
  return found ? found[1] : state;
 }
 // ── recovery ─────────────────────────────────────────────────────────────────
 // What an interrupted run left behind, straight from the journal plus the files on
 // disk. Only the operations the server itself classified as resolvable get an
 // action; ambiguous ones are shown with their evidence and no button.
 function recoverySection(recovery) {
  const operations = recovery ? recovery.operations : [];
  if (!operations.length) return null;
  const manual = recovery.manual || [];
  const resolvable = operations.length - manual.length;
  return el(
    "div",
    { class: "card", "data-testid": "archive-recovery" },
    el("h2", {}, "Interrupted work"),
    el(
      "p",
      { "data-testid": "recovery-summary" },
      `${operations.length} operation(s) did not finish · ${resolvable} resolvable · ` +
        `${manual.length} need a decision`
    ),
    el(
      "table",
      { class: "grid", "data-testid": "recovery-operations" },
      el(
        "thead",
        {},
        el(
          "tr",
          {},
          ...["Photo", "Phase", "Verdict", "Evidence"].map((l) => el("th", { scope: "col" }, l))
        )
      ),
      el(
        "tbody",
        {},
        ...operations.map((verdict) =>
          el(
            "tr",
            {
              "data-testid": "recovery-row",
              "data-classification": verdict.classification,
              "data-direction": verdict.direction,
            },
            el("td", { class: "path", "data-testid": "recovery-source" }, verdict.source_path),
            el("td", {}, el("span", { class: "badge" }, phaseLabel(verdict.journal_state))),
            el(
              "td",
              {},
              el(
                "span",
                {
                  class: `badge ${verdict.classification === "manual" ? "blocked" : "attention"}`,
                  "data-testid": "recovery-verdict",
                },
                verdict.classification
              )
            ),
            el(
              "td",
              { class: "muted", "data-testid": "recovery-reason" },
              `${verdict.reason} (source ${verdict.source_exists ? "present" : "absent"}, ` +
                `archive copy ${verdict.destination_matches ? "verified" : verdict.destination_exists ? "different bytes" : "absent"})`
            )
          )
        )
      )
    ),
    manual.length
      ? el(
          "div",
          { class: "alert", role: "alert", "data-testid": "recovery-manual" },
          `${manual.length} operation(s) cannot be resolved from the evidence. Nothing will be ` +
            "removed or retried for them here: inspect the medium and the library, then decide."
        )
      : null,
    el(
      "div",
      { class: "toolbar" },
      resolvable
        ? el(
            "button",
            {
              class: "primary",
              "data-testid": "resolve-recovery",
              onclick: () => run(() => api.resolveArchiveRecovery()),
            },
            `Finish ${resolvable} recoverable operation(s)`
          )
        : el(
            "span",
            { class: "muted", "data-testid": "no-safe-recovery" },
            "No operation can be finished safely from here."
          )
    )
  );
 }
 // ── archived assets ──────────────────────────────────────────────────────────
 // Browsing what is already archived, including while the medium is away: the
 // retained protected preview and the recorded hashes are the evidence, so the row
 // stays complete and honest instead of turning into a missing file.
 function archivedSection(assets, locations) {
  const archived = assets.filter((asset) => asset.availability_state !== "active");
  if (!archived.length) return null;
  const names = Object.fromEntries(locations.map((location) => [location.id, location.name]));
  return el(
    "div",
    { "data-testid": "archived-assets" },
    el("h2", {}, "Archived photos"),
    el(
      "table",
      { class: "grid", "data-testid": "archived" },
      el(
        "thead",
        {},
        el(
          "tr",
          {},
          ...["Preview", "Archived as", "Medium", "Availability", "Size"].map((l) =>
            el("th", { scope: "col" }, l)
          )
        )
      ),
      el(
        "tbody",
        {},
        ...archived.map((asset) =>
          el(
            "tr",
            { "data-testid": "archived-row", "data-asset-id": asset.id },
            el(
              "td",
              {},
              el("img", {
                "data-testid": "archived-preview",
                width: 96,
                loading: "lazy",
                src: api.thumbnailUrl(asset.id, 256),
                alt: `Preview of ${asset.archive_path || asset.id}`,
              })
            ),
            el("td", { class: "path", "data-testid": "archived-path" }, asset.archive_path || "—"),
            el(
              "td",
              { "data-testid": "archived-medium" },
              names[asset.archive_location_id] || asset.archive_location_id || "—"
            ),
            el(
              "td",
              {},
              el(
                "span",
                {
                  class: `badge ${asset.availability_state === "archived_online" ? "complete" : "attention"}`,
                  "data-testid": "archived-availability",
                },
                AVAILABILITY_LABEL[asset.availability_state] || asset.availability_state
              )
            ),
            el("td", {}, bytes(asset.byte_size))
          )
        )
      )
    )
  );
 }
 // ── restore ──────────────────────────────────────────────────────────────────
 function restoreSection(restore, location) {
  const ready = restore.state === "ready";
  const items = restore.items || [];
  if (!items.length && !restore.blockers.length) return null;
  return el(
    "div",
    { class: "card", "data-testid": "restore" },
    el("h2", {}, "Restore"),
    el(
      "p",
      { "data-testid": "restore-note" },
      "Restoring copies the archived bytes back into the library and leaves the archive " +
        "copy where it is. A name that is already taken is never overwritten: the photo " +
        "comes back beside it under a visibly different name."
    ),
    blockerList(restore.blockers, "restore-blockers", "restore-blocker", "This restore cannot run yet"),
    items.length
      ? el(
          "table",
          { class: "grid", "data-testid": "restore-items" },
          el(
            "thead",
            {},
            el(
              "tr",
              {},
              ...["Archived as", "Comes back as", "Size", "State"].map((l) =>
                el("th", { scope: "col" }, l)
              )
            )
          ),
          el(
            "tbody",
            {},
            ...items.map((item) =>
              el(
                "tr",
                { "data-testid": "restore-row", "data-asset-id": item.asset_id },
                el("td", { class: "path", "data-testid": "restore-source" }, item.archive_path),
                el("td", { class: "path", "data-testid": "restore-destination" }, item.destination_path || "—"),
                el("td", {}, bytes(item.byte_size)),
                el(
                  "td",
                  {},
                  item.blockers.length
                    ? el(
                        "span",
                        {
                          class: "badge blocked",
                          "data-testid": "restore-item-blocker",
                          "data-code": item.blockers[0].code,
                        },
                        item.blockers[0].code
                      )
                    : el("span", { class: "badge ready", "data-testid": "restore-item-state" }, "ready")
                )
              )
            )
          )
        )
      : null,
    el(
      "div",
      { class: "toolbar" },
      el(
        "button",
        {
          class: "primary",
          "data-testid": "start-restore",
          disabled: ready ? false : "disabled",
          title: ready ? false : "the medium and every archived copy must check out first",
          onclick: () =>
            run(async () => {
              const plan = await api.createRestorePlan({
                location_id: location.id,
                token: restore.token,
              });
              const started = await api.applyRestorePlan(plan.id);
              watch(started.job.id, plan.id, "restore");
              return { restoring: plan.asset_count };
            }),
        },
        `Restore ${items.length} photo(s) from ${location.name}`
      )
    )
  );
 }
 // ── running commands ─────────────────────────────────────────────────────────
 async function run(action) {
  try {
    outcome = { kind: "ok", result: await action() };
  } catch (error) {
    outcome = error.status === 409 ? { kind: "conflict", error } : { kind: "error", error };
  }
  render();
 }
 // Live job activity. The plan panel is refreshed on its own tick because the
 // journal advances per file, not per job event; a full re-render would re-run
 // preflight (which re-hashes the library), so that happens once when the job ends.
 const REFRESH_MS = 500;
 function watch(jobId, planId, kind) {
  activity = [`Started ${kind} job ${jobId}`];
  const tick = setInterval(() => refreshPlan(planId, kind), REFRESH_MS);
  subscribeJob(jobId, {
    onEvent: (event) => {
      activity.push(`${event.type}${event.message ? ": " + event.message : ""}`);
      const log = document.querySelector('[data-testid="archive-activity"]');
      if (log) log.textContent = activity.join("\n");
    },
    onDone: () => {
      clearInterval(tick);
      activity.push("done");
      render();
    },
  });
 }
 async function refreshPlan(planId, kind) {
  const node = document.querySelector(`[data-testid="plan-detail"][data-plan="${planId}"]`);
  if (!node) return; // the user navigated away from the running plan
  try {
    const plan = await (kind === "restore" ? api.getRestorePlan(planId) : api.getArchivePlan(planId));
    node.replaceWith(planDetail(plan));
  } catch (_) {
    // Transient; the next tick tries again and the job's end re-renders anyway.
  }
 }
 function activityLog() {
  return el(
    "pre",
    {
      class: "activity-log",
      role: "status",
      "aria-live": "polite",
      "data-testid": "archive-activity",
    },
    activity.join("\n")
  );
 }
 function outcomeBanner() {
  if (!outcome) return null;
  if (outcome.kind === "conflict") {
    return el(
      "div",
      { class: "alert", role: "alert", "data-testid": "conflict" },
      `The server refused this: ${outcome.error.message}. Nothing was moved or removed; ` +
        "the state below is the server's current one — review it and decide again."
    );
  }
  if (outcome.kind === "error") {
    return el(
      "div",
      { class: "alert", role: "alert", "data-testid": "archive-error" },
      `Failed: ${outcome.error.message}`
    );
  }
  const result = outcome.result || {};
  const message =
    result.archiving !== undefined
      ? `Archiving ${result.archiving} photo(s). Originals are removed only after their copies verify.`
      : result.restoring !== undefined
        ? `Restoring ${result.restoring} photo(s) into the library.`
        : "Done — the state below is the server's.";
  return el("div", { class: "alert", role: "status", "data-testid": "archive-result" }, message);
 }
 // ── formatting ───────────────────────────────────────────────────────────────
 function bytes(value) {
  if (value == null) return "unknown";
  const units = ["B", "kB", "MB", "GB", "TB"];
  let size = value;
  let unit = 0;
  while (size >= 1000 && unit < units.length - 1) {
    size /= 1000;
    unit += 1;
  }
  return `${unit === 0 ? size : size.toFixed(1)} ${units[unit]}`;
 }
--- a/frontend/js/tests/unit.js
+++ b/frontend/js/tests/unit.js
@@ -29,10 +29,6 @@ function jsonResponse(status, body) {
 const tick = (ms = 0) => new Promise((r) => setTimeout(r, ms));
 async function run() {
  // The client fetches its CSRF token once, lazily (US07-02). Do that against the
  // real server first, so the stubbed fetch below only ever sees the call under test.
  await api.workflow().catch(() => {});
  // ── store ────────────────────────────────────────────────────────────────
  {
    const store = createStore({ n: 0 });
--- a/legacy_cli_archive/CHECKSUMS.sha256
+++ b/legacy_cli_archive/CHECKSUMS.sha256
@@ -1,22 +0,0 @@
 d098bbde13d2ebc872ca781e244cc1e48b97cc551fedaca3251d6a5278a15234  src/compare_models.py
 7d0f68cb95fbd6603e4c558620098b46929ebdb6fd91a598bbf84f26eea35e6c  src/nsfw_tag.py
 35329c53570e215cef15f59429c1a5251a0448b90522b0910ab9d68efe1bc307  src/nsfwtag/__init__.py
 7f52b55e4f3b77eda3657d7cd2272c7cca8422100e241671de495603c1126ee2  src/nsfwtag/__main__.py
 6f5a97114e0d87d272ce22d065dc31fa0dd72ff8590d11ad14cb1c1f486d339c  src/nsfwtag/bench.py
 29498fac1d73ba2b7420ffe1ffe49a87f684ec299e2c3b9c6e14e63e95643ba4  src/nsfwtag/exif.py
 934e82c402813ebf503e5a20eb03d5103f84df13117bc4dd1fd95deaa01ab263  src/nsfwtag/README.md
 68125e6184c7e4d2a5b0153f2155675753ab0b1329d1dbc4933d4769492ec4be  src/nsfwtag/review.html
 a597eab74803dd31452b5d70abf7d6d6320eb17a61596c891b009da15d624e98  src/nsfwtag/scoring.py
 674969a18e58ee511a2abf574a875db92f2f524769b1b614d0d3662ab879a709  src/nsfwtag/server.py
 24a7c8d029da6e97d46b110a9fe9dbb3900127f8ae3c142f634fdd91d6c45243  src/nsfwtag/webapp.py
 2c2ea558f1b9095c1150f078ea29c8e0f180cc045a9d1097b83f61bfb145295b  src/photo_analyzer.py
 5fb7ce2f977a17da1f501c45d7985328318ae14298a3f347eab46a6e3f02aab3  src/test_dedup.py
 1673dc76cc60aba56a5b065d9bc9f5dda00342cf2a79d000a3f74686fb7cffec  src/test_nsfw_skip.py
 55aa82f348e0e90be0163ba6aa278e5fc8e445996e5335774917e5ef59ad3563  src/webapp/__init__.py
 ba4342bd0175591a2121f063f14a78a602d5679bcfcf24aa14c8d4b8cd5da1a2  src/webapp/__main__.py
 a60f24035a989909467778f888d62854c1afc2702f47b8d3cca32bf3cf04d5cf  src/webapp/analyzer.html
 018bcc2f770d716444b456db58d6b4a41800138a98598b3c27ba503ab22d939e  src/webapp/page.py
 5f599b107b2b117ca118b6fbdec5e5786a9ab4eea424aa9af1bfea7bf87cebab  src/webapp/query.py
 875cce697caa02717c85a2707ba935c46dd9ace18428fd4abb13105b7a8e24d9  src/webapp/README.md
 af7d0d72d245b4bbb1e0e30f9708239697543212d4171defd1bfe26dd24a4f05  src/webapp/runner.py
 cddf0555b06fe7e4daa14309baaaf91130f8506922cb0ffb6507d76cbe39add4  src/webapp/server.py
--- a/legacy_cli_archive/README.md
+++ b/legacy_cli_archive/README.md
@@ -1,80 +0,0 @@
 # Legacy CLI archive (US07-01)
 Frozen, read-only sources of the command-line tools this application was extracted
 from. They are **reference material and rollback evidence** — provenance for
 behavior that now lives in `photo_pipeline/`, and the only way to answer "what did
 the original actually do?" once the replacement has drifted.
 > **Nothing here is production code.** No module under `photo_pipeline/` imports or
 > executes anything in this directory, and this directory is not on the application's
 > import path. `tests/unit/test_legacy_archive.py` enforces both, along with the
 > checksums and the redaction below.
 ## What is here
 | Path | Role |
 |---|---|
 | `src/photo_analyzer.py` | the analysis CLI: discovery, hashing/dedup, vision analysis, EXIF writing, SQLite schema, album naming |
 | `src/nsfwtag/` | NSFW scoring, EXIF safety keywords, and the review server (`__init__` 1.1.0) |
 | `src/webapp/` | the stdlib review web app: FTS search, stats, subprocess runner, HTML shell (`__init__` 0.1.0) |
 | `src/nsfw_tag.py` | thin backwards-compatible entry point for `nsfwtag` |
 | `src/compare_models.py` | dev-only model comparison script |
 | `src/test_dedup.py`, `src/test_nsfw_skip.py` | the CLIs' own standalone self-checks (never pytest suites) |
 | `donor_ledger.yaml` | the donor ledger: every migrated behavior, its target, its tests, and every intentional delta |
 | `requirements-lock.txt` | the dependency versions the frozen sources were last verified against |
 | `photo_analyzer.env.sample` | the CLI's configuration surface, with every value replaced by a placeholder |
 | `CHECKSUMS.sha256` | SHA-256 of every archived source file |
 `photo_analyzer.py` carries no `__version__`; its identity is its checksum, recorded
 in `CHECKSUMS.sha256` and taken at commit `9b7ee6b` (the merge of US06-06, the last
 commit before archival).
 ## Verifying the archive
 ```bash
 cd legacy_cli_archive && shasum -a 256 -c CHECKSUMS.sha256
 ```
 Any edit to an archived source must be accompanied by a regenerated checksum file
 and a note here explaining why a *frozen* archive changed — the normal answer being
 that it should not.
 ## Schema notes
 `photo_analyzer.py` owned a path-keyed SQLite database (`SCHEMA`, near the top of the
 file):
 - `photos(id, path UNIQUE, status, phash, file_sha1, dup_of, description, tags,
  people_count, setting, time_of_day, season, mood, location_hint, approx_year,
  raw_response, error_message, analyzed_at, exif_written_at)`;
 - `photos_fts` — an FTS5 external-content index over `path, description, tags, mood,
  location_hint`, kept in sync by insert/update/delete triggers;
 - late columns (`phash`, `file_sha1`, `dup_of`) were added by an in-code
  `_migrate_schema()` rather than a migration tool, and their indexes are created
  only after the `ALTER`.
 The replacement keeps the same analysis fields but re-keys everything to a stable
 `assets.id` (Alembic migrations `0001`…), because a path is not an identity: the
 donor's `path UNIQUE` is exactly what broke on every move and rename.
 `nsfwtag` kept its safety scores outside the database in `nsfw_scores.csv`
 (`path,nsfw_score`, four decimals, unreadable rows dropped). That file is no longer a
 source of truth; `photo_pipeline/services/legacy_import.py` imports it into
 `assets.safety_score` and reports exactly what matched, what did not, and why.
 ## Redaction
 The archive contains no credentials. `photo_analyzer.env.sample` documents the
 configuration surface (`LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL`, and the tuning
 variables) with placeholder values only; the CLI itself never contained a key, it
 read one from `photo_analyzer.env` or the environment. No `.env`, database, log, CSV,
 or photo from the author's library is archived.
 ## Why these tools were retired
 Each behavior's fate is recorded per row in `donor_ledger.yaml`: `reuse`, `extract`,
 `refactor`, or `replace`, with the target module, the characterization tests that
 pinned the donor's behavior, the parity tests the replacement passes, and — where the
 replacement deliberately does something else or nothing at all — a `delta` saying so.
 Rows still marked `pending` name the backlog story that will resolve them; they are
 the honest list of what has *not* been carried over yet.
--- a/legacy_cli_archive/photo_analyzer.env.sample
+++ b/legacy_cli_archive/photo_analyzer.env.sample
@@ -1,18 +0,0 @@
 # Sample configuration for the archived photo_analyzer.py CLI (US07-01).
 #
 # REDACTED: no value below is real. Each line names a variable the CLI read and
 # what belongs there; the placeholders are deliberately not key-shaped, so this
 # file can never be mistaken for — or scanned as — a credential.
 LLM_API_KEY=<paste your provider key here>
 LLM_BASE_URL=<provider base url, e.g. the OpenAI-compatible Gemini endpoint>
 LLM_MODEL=<model id, e.g. a Gemini Flash release>
 # Optional tuning the CLI read from the same file:
 PHASH_THRESHOLD=8
 MAX_WORKERS=4
 RETRY_ATTEMPTS=3
 RPD_LIMIT=0
 # The CLI ignored its own shipped placeholder (a literal "sk-REPLACE..." string)
 # until it was replaced, and a shell variable always won over this file.
--- a/legacy_cli_archive/requirements-lock.txt
+++ b/legacy_cli_archive/requirements-lock.txt
@@ -1,20 +0,0 @@
 # Final dependency lock of the archived CLIs (US07-01).
 #
 # These are the versions present in the environment the archive was taken from —
 # what the frozen sources were last verified against by the characterization
 # suite. Restoring a donor for forensics means pinning these, not "latest".
 #
 # Python 3.14.6
 openai==3.0.0          # photo_analyzer: OpenAI-compatible vision client
 numpy==2.4.6           # photo_analyzer, nsfwtag: pixel work
 Pillow==12.3.0         # photo_analyzer, nsfwtag: decode/resize
 rich==15.0.0           # photo_analyzer: console output
 scipy==1.18.0          # photo_analyzer: perceptual-hash DCT
 PyYAML==6.0.3          # tooling that reads the donor ledger
 # NSFW inference (nsfwtag/scoring.py, nsfwtag/bench.py) was never installed in the
 # archiving environment; the model stack is recorded here from the sources so a
 # forensic run can reproduce it, not from a resolved lock:
 #   torch, transformers, timm  — AdamCodd/vit-base-nsfw-detector (see nsfwtag/README.md)
 # exiftool is an external binary, not a Python package.
--- a/migrations/versions/0013_protected_thumbnails.py
+++ b/migrations/versions/0013_protected_thumbnails.py
@@ -1,29 +0,0 @@
 """Protected thumbnails (US06-03).
 Revision ID: 0013_protected_thumbnails
 Revises: 0012_archive_plans
 Create Date: 2026-08-16
 A protected thumbnail is the durable comparison preview of an asset whose
 original has left active storage. It is evidence rather than cache, so the LRU
 quota must not evict it: the archive medium may be offline when it is needed.
 """
 import sqlalchemy as sa
 from alembic import op
 revision = "0013_protected_thumbnails"
 down_revision = "0012_archive_plans"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    op.add_column(
        "thumbnails",
        sa.Column("protected", sa.Boolean(), nullable=False, server_default=sa.false()),
    )
 def downgrade() -> None:
    op.drop_column("thumbnails", "protected")
--- a/migrations/versions/0014_restore_plans.py
+++ b/migrations/versions/0014_restore_plans.py
@@ -1,37 +0,0 @@
 """Restore plans and archive divergence (US06-04).
 Revision ID: 0014_restore_plans
 Revises: 0013_protected_thumbnails
 Create Date: 2026-08-16
 Restore reuses the archive plan and journal tables: the crash-safe question is the
 same one in the opposite direction (copy, verify, publish, register), so the rows
 gain a ``direction`` instead of a parallel pair of tables. ``archive_divergent_at``
 records the moment an archived copy was proven to hold bytes that are not the ones
 the database recorded — a restore must never silently accept a different file.
 """
 import sqlalchemy as sa
 from alembic import op
 revision = "0014_restore_plans"
 down_revision = "0013_protected_thumbnails"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    for table in ("archive_plans", "archive_operations"):
        op.add_column(
            table,
            sa.Column("direction", sa.String(), nullable=False, server_default="archive"),
        )
    op.add_column(
        "assets", sa.Column("archive_divergent_at", sa.DateTime(timezone=True), nullable=True)
    )
 def downgrade() -> None:
    op.drop_column("assets", "archive_divergent_at")
    for table in ("archive_plans", "archive_operations"):
        op.drop_column(table, "direction")
--- a/migrations/versions/0015_exif_projections.py
+++ b/migrations/versions/0015_exif_projections.py
@@ -1,42 +0,0 @@
 """Durable EXIF projections per asset and stage (US07-03).
 Revision ID: 0015_exif_projections
 Revises: 0014_restore_plans
 Create Date: 2026-08-16
 The concept's ``exif_projections`` table, added at the point it earns its keep: a
 checkpoint that finds a field it does not own changed must be able to say so after
 a restart. ``state`` is verified | divergent | failed, and only ``verified`` counts
 as a completed metadata stage.
 """
 import sqlalchemy as sa
 from alembic import op
 revision = "0015_exif_projections"
 down_revision = "0014_restore_plans"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    op.create_table(
        "exif_projections",
        sa.Column("asset_id", sa.String(), sa.ForeignKey("assets.id"), primary_key=True),
        sa.Column("stage", sa.String(), primary_key=True),  # safety | analysis
        sa.Column("id", sa.String(), nullable=False),
        sa.Column("projection_version", sa.Integer(), nullable=False, server_default="0"),
        # What the stage asked for: {"add": [...], "remove": [...]}.
        sa.Column("desired_json", sa.String(), nullable=True),
        # Fields outside the stage's ownership that did not survive the write.
        sa.Column("divergent_fields", sa.String(), nullable=True),
        sa.Column("result_file_sha256", sa.String(), nullable=True),
        sa.Column("state", sa.String(), nullable=False),
        sa.Column("error_code", sa.String(), nullable=True),
        sa.Column("verified_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
    )
 def downgrade() -> None:
    op.drop_table("exif_projections")
--- a/migrations/versions/0016_performance_indexes.py
+++ b/migrations/versions/0016_performance_indexes.py
@@ -1,45 +0,0 @@
 """Indexes the large-library read paths need (US07-06).
 Revision ID: 0016_performance_indexes
 Revises: 0015_exif_projections
 Create Date: 2026-08-17
 Measured, not guessed. At 100k assets the workflow home and the safety queue both
 resolve "the current decision per asset" with a window function over
 ``safety_reviews``; a plain ``asset_id`` index makes SQLite sort every partition by
 hand. Ordering the index by ``(asset_id, created_at DESC)`` halves that query.
 ``duplicate_members(cluster_id, asset_id)`` serves the paged member list of a
 cluster with thousands of members, which is the other page that stopped being cheap.
 """
 from alembic import op
 revision = "0016_performance_indexes"
 down_revision = "0015_exif_projections"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    op.create_index(
        "ix_safety_reviews_asset_created",
        "safety_reviews",
        ["asset_id", "created_at"],
    )
    op.create_index(
        "ix_duplicate_members_cluster_asset",
        "duplicate_members",
        ["cluster_id", "asset_id"],
    )
    op.create_index(
        "ix_analysis_results_approx_year",
        "analysis_results",
        ["approx_year"],
    )
 def downgrade() -> None:
    op.drop_index("ix_analysis_results_approx_year", table_name="analysis_results")
    op.drop_index("ix_duplicate_members_cluster_asset", table_name="duplicate_members")
    op.drop_index("ix_safety_reviews_asset_created", table_name="safety_reviews")
--- a/legacy_cli_archive/src/nsfw_tag.py
+++ b/legacy_cli_archive/src/nsfw_tag.py
--- a/legacy_cli_archive/src/nsfwtag/README.md
+++ b/legacy_cli_archive/src/nsfwtag/README.md
--- a/legacy_cli_archive/src/nsfwtag/init.py
+++ b/legacy_cli_archive/src/nsfwtag/init.py
--- a/legacy_cli_archive/src/nsfwtag/main.py
+++ b/legacy_cli_archive/src/nsfwtag/main.py
--- a/legacy_cli_archive/src/nsfwtag/bench.py
+++ b/legacy_cli_archive/src/nsfwtag/bench.py
--- a/legacy_cli_archive/src/nsfwtag/exif.py
+++ b/legacy_cli_archive/src/nsfwtag/exif.py
--- a/legacy_cli_archive/src/nsfwtag/review.html
+++ b/legacy_cli_archive/src/nsfwtag/review.html
--- a/legacy_cli_archive/src/nsfwtag/scoring.py
+++ b/legacy_cli_archive/src/nsfwtag/scoring.py
--- a/legacy_cli_archive/src/nsfwtag/server.py
+++ b/legacy_cli_archive/src/nsfwtag/server.py
--- a/legacy_cli_archive/src/nsfwtag/webapp.py
+++ b/legacy_cli_archive/src/nsfwtag/webapp.py
--- a/legacy_cli_archive/src/photo_analyzer.py
+++ b/legacy_cli_archive/src/photo_analyzer.py
--- a/photo_pipeline/main.py
+++ b/photo_pipeline/main.py
@@ -1,190 +1,28 @@
-"""Application management CLI:
+"""Application management CLI: ``python -m photo_pipeline {serve,migrate}``."""
 ``python -m photo_pipeline {serve,migrate,worker,import-legacy-scores,backup,verify-backup,restore,diagnostics}``.
 ``serve`` and ``worker`` take the library process lock for their role (US07-05):
 two workers, or the frozen CLI running beside the app, would each be safe on their
 own and destructive together. ``restore`` is here rather than in the API because it
 replaces the state of an installation and belongs to a stopped one.
 """
 from __future__ import annotations
 import argparse
 import json
 from pathlib import Path
 from typing import Sequence
 from photo_pipeline.config import Config
-from photo_pipeline.services.app_lock import LegacyProcessActive, LibraryLock, LockHeld
+from photo_pipeline.db import run_migrations
 from photo_pipeline.services.backup import BackupError, BackupService, migrate_with_backup
 def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser(prog="photo_pipeline")
    commands = parser.add_subparsers(dest="command", required=True)
-    serve_cmd = commands.add_parser("serve", help="Run the API server")
+    commands.add_parser("serve", help="Run the API server")
    commands.add_parser("migrate", help="Upgrade the database to the latest revision")
    worker_cmd = commands.add_parser("worker", help="Run a durable-job worker")
    worker_cmd.add_argument("--id", default="worker-1", help="Worker id (lease owner)")
    for locked in (serve_cmd, worker_cmd):
        locked.add_argument(
            "--allow-legacy",
            action="store_true",
            help="Start even though a legacy CLI looks active (unsafe; you own the outcome)",
        )
    import_cmd = commands.add_parser(
        "import-legacy-scores",
        help="Import the archived CLI's nsfw_scores.csv into the database (US07-01)",
    )
    import_cmd.add_argument("csv", help="Path to nsfw_scores.csv")
    import_cmd.add_argument(
        "--overwrite", action="store_true", help="Replace differing imported scores"
    )
    import_cmd.add_argument(
        "--dry-run", action="store_true", help="Report what would happen and change nothing"
    )
    backup_cmd = commands.add_parser("backup", help="Take an online database backup")
    backup_cmd.add_argument("--reason", default="manual", help="Why (part of the directory name)")
    backup_cmd.add_argument("--keep", type=int, default=7, help="How many backups to retain")
    verify_cmd = commands.add_parser("verify-backup", help="Check a backup is intact and readable")
    verify_cmd.add_argument("backup", help="Path to the backup directory")
    restore_cmd = commands.add_parser(
        "restore", help="Restore a verified backup into a fresh data directory"
    )
    restore_cmd.add_argument("backup", help="Path to the backup directory")
    restore_cmd.add_argument("--into", required=True, help="Fresh data directory to restore into")
    commands.add_parser("diagnostics", help="Report sizes, disk headroom, locks, and warnings")
    bench_cmd = commands.add_parser(
        "benchmark", help="Measure latency and resource use against agreed budgets (US07-06)"
    )
    bench_cmd.add_argument("--profile", default="smoke", help="smoke | short | full | huge")
    bench_cmd.add_argument(
        "--soak-seconds", type=float, default=0.0, help="Also run a soak of this length"
    )
    bench_cmd.add_argument("--output", help="Write the JSON report here as well as to stdout")
    gate_cmd = commands.add_parser(
        "release-gate", help="Run every suite in an isolated stack and keep the evidence"
    )
    gate_cmd.add_argument("--output", help="Evidence directory (default: data/release/<stamp>)")
    dry_cmd = commands.add_parser(
        "dry-run", help="Read-only reconciliation of the configured library (US07-07)"
    )
    dry_cmd.add_argument("--output", help="Write the report here as well as to stdout")
    approve_cmd = commands.add_parser(
        "approve-dry-run", help="Approve a dry-run report, which is what enables mutation"
    )
    approve_cmd.add_argument("report", help="Path to the dry-run report")
    approve_cmd.add_argument("--approver", required=True, help="Who is accepting this")
    args = parser.parse_args(argv)
    config = Config.from_env()
    config.database_path.parent.mkdir(parents=True, exist_ok=True)
    if args.command == "migrate":
-        manifest = migrate_with_backup(config)
+        run_migrations(config.database_url)
        if manifest:
            print(json.dumps({"pre_migration_backup": manifest["name"]}, indent=2))
        return 0
    if args.command == "backup":
        try:
            manifest = BackupService(config).create(reason=args.reason, keep=args.keep)
        except BackupError as error:
            print(str(error))
            return 1
        print(json.dumps(manifest, indent=2))
        return 0
    if args.command == "verify-backup":
        result = BackupService(config).verify(args.backup)
        print(json.dumps(result.as_dict(), indent=2))
        return 0 if result.ok else 1
    if args.command == "restore":
        try:
            report = BackupService(config).restore(args.backup, args.into)
        except BackupError as error:
            print(str(error))
            return 1
        print(json.dumps(report, indent=2))
        return 0
    if args.command == "benchmark":
        from photo_pipeline.services import benchmarks
        try:
            report = benchmarks.run(
                config,
                profile=args.profile,
                soak_seconds=args.soak_seconds,
                output=args.output,
            )
        except ValueError as error:
            print(str(error))
            return 1
        print(json.dumps({k: v for k, v in report.items() if k != "runs"}, indent=2))
        # A breached budget is a failed run, so a scheduled job notices without
        # anyone reading the JSON.
        return 0 if report["ok"] else 1
    if args.command == "release-gate":
        from photo_pipeline.services import release
        report = release.run_gate(config, output=args.output)
        print(
            json.dumps(
                {k: v for k, v in report.items() if k not in ("stages", "matrix")}, indent=2
            )
        )
        return 0 if report["ok"] else 1
    if args.command == "dry-run":
        from photo_pipeline.services import release
        try:
            report = release.dry_run(config)
        except release.ReleaseError as error:
            print(str(error))
            return 1
        if args.output:
            Path(args.output).write_text(json.dumps(report, indent=2))
        print(json.dumps(report, indent=2))
        return 0
    if args.command == "approve-dry-run":
        from photo_pipeline.services import release
        try:
            record = release.approve(config, args.report, approver=args.approver)
        except (release.ReleaseError, OSError, ValueError) as error:
            print(str(error))
            return 1
        print(json.dumps(record, indent=2))
        return 0
    if args.command == "diagnostics":
        from photo_pipeline.services import diagnostics
        print(json.dumps(diagnostics.report(config), indent=2))
        return 0
    if args.command == "import-legacy-scores":
        from photo_pipeline.db import create_db_engine, create_session_factory
        from photo_pipeline.services.legacy_import import LegacyImportService, write_report
        migrate_with_backup(config)
        engine = create_db_engine(config.database_url)
        service = LegacyImportService(create_session_factory(engine))
        report = service.import_nsfw_scores(
            args.csv, overwrite=args.overwrite, dry_run=args.dry_run
        )
        # The report is the point: an import nobody can audit is not a migration.
        if not args.dry_run:
            write_report(report, config.data_dir)
        print(json.dumps(report.counts, indent=2))
        return 0
    if args.command == "worker":
@@ -196,60 +34,18 @@ def main(argv: Sequence[str] | None = None) -> int:
        import photo_pipeline.jobs.domain_handlers  # noqa: F401
        from photo_pipeline.jobs.worker import Worker
-        lock = LibraryLock(config, "worker")
+        run_migrations(config.database_url)
        if (held := _acquire(lock, allow_legacy=args.allow_legacy)) is not None:
            return held
        try:
            migrate_with_backup(config)
        engine = create_db_engine(config.database_url)
-            Worker(
+        Worker(create_session_factory(engine), worker_id=args.id, config=config).run_forever()
                create_session_factory(engine), worker_id=args.id, config=config
            ).run_forever()
        finally:
            lock.release()
        return 0
    import sys
    import uvicorn
-    from photo_pipeline.api.app import ConfigurationRefused, create_app
+    from photo_pipeline.api.app import create_app
-    # An exposed deployment without an access secret must not reach the port at all,
+    uvicorn.run(create_app(config), host=config.host, port=config.port)
    # and the operator needs a sentence, not a traceback (US08-01).
    try:
        app = create_app(config)
    except ConfigurationRefused as error:
        print(str(error), file=sys.stderr)
        return 4
    lock = LibraryLock(config, "api")
    if (held := _acquire(lock, allow_legacy=args.allow_legacy)) is not None:
        return held
    try:
        uvicorn.run(app, host=config.host, port=config.port)
    finally:
        lock.release()
    return 0
 def _acquire(lock: LibraryLock, *, allow_legacy: bool) -> int | None:
    """Take the lock, or explain on stderr why this process must not start.
    Returns an exit code to return, or ``None`` when the lock was acquired.
    """
    import sys
    try:
        lock.acquire(allow_legacy=allow_legacy)
    except LockHeld as error:
        print(str(error), file=sys.stderr)
        return 2
    except LegacyProcessActive as error:
        print(f"{error} (override with --allow-legacy)", file=sys.stderr)
        return 3
    return None
 if __name__ == "__main__":
    raise SystemExit(main())
--- a/photo_pipeline/api/app.py
+++ b/photo_pipeline/api/app.py
@@ -8,15 +8,11 @@ and exposes the versioned ``/api/v1`` surface; US01-02 ships only health.
 from __future__ import annotations
 import logging
 from contextlib import asynccontextmanager
 from pathlib import Path
-from fastapi import FastAPI, Request
+from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from photo_pipeline.api.routes import (
    albums,
@@ -27,86 +23,31 @@ from photo_pipeline.api.routes import (
    inventory,
    jobs,
    library,
    operations,
    renames,
    safety,
    session as session_routes,
    thumbnails,
    uploads,
    workflow,
 )
 from photo_pipeline.api.security import (
    DEFAULT_HEADERS,
    FailureLimiter,
    SecurityMiddleware,
    Session,
    trust_refusal,
 )
 # Registers the safety_score / analysis job handlers on import.
 import photo_pipeline.jobs.domain_handlers  # noqa: F401
 from photo_pipeline.config import Config
-from photo_pipeline.db import create_db_engine, create_session_factory
+from photo_pipeline.db import create_db_engine, create_session_factory, run_migrations
 from photo_pipeline.services.backup import migrate_with_backup
 from photo_pipeline.logging import configure_logging
 from photo_pipeline.services.thumbnails import ThumbnailService
 from photo_pipeline.services.upload_batches import UploadBatchService
 FRONTEND_DIR = Path(__file__).resolve().parents[2] / "frontend"
 log = logging.getLogger(__name__)
 def _envelope(status: int, code: str, message: str) -> JSONResponse:
    return JSONResponse(
        status_code=status,
        content={"error": {"code": code, "message": message}},
        headers=DEFAULT_HEADERS,
    )
 def _install_error_handlers(app: FastAPI) -> None:
    """One JSON error envelope everywhere, and nothing behind it.
    An unhandled exception carries the library's absolute paths, SQL, and sometimes
    a credential in its text; the client gets a code, the operator gets the traceback
    in the server log (US07-02).
    """
    @app.exception_handler(StarletteHTTPException)
    async def _http_error(request: Request, exc: StarletteHTTPException):
        return _envelope(exc.status_code, "http_error", str(exc.detail))
    @app.exception_handler(RequestValidationError)
    async def _validation_error(request: Request, exc: RequestValidationError):
        # Field locations only: the echoed input can be the caller's own data, but it
        # is also what ends up in shared logs and screenshots.
        fields = sorted(".".join(str(part) for part in error["loc"]) for error in exc.errors())
        return _envelope(422, "invalid_request", f"invalid request fields: {', '.join(fields)}")
    @app.exception_handler(Exception)
    async def _unhandled(request: Request, exc: Exception):
        log.exception("unhandled error serving %s", request.url.path)
        return _envelope(500, "internal_error", "internal error")
 class ConfigurationRefused(RuntimeError):
    """The configuration would serve the library to callers it cannot authenticate."""
 def create_app(config: Config | None = None) -> FastAPI:
    config = config or Config.from_env()
    configure_logging(config.log_level, config.log_format)
    # Before anything is built, let alone bound to a port (US08-01).
    if (why := trust_refusal(config)) is not None:
        raise ConfigurationRefused(why)
    @asynccontextmanager
    async def lifespan(app: FastAPI):
        config.database_path.parent.mkdir(parents=True, exist_ok=True)
-        # A schema upgrade is snapshotted first, so a migration that fails halfway
+        run_migrations(config.database_url)
        # leaves a restorable database behind rather than a damaged one (US07-05).
        migrate_with_backup(config)
        engine = create_db_engine(config.database_url)
        app.state.config = config
        app.state.engine = engine
@@ -114,9 +55,6 @@ def create_app(config: Config | None = None) -> FastAPI:
        # An upload whose process died left no outcome behind; resolve it now so the
        # uploader lane is free and the uncertain batch is visible (US05-02).
        UploadBatchService(app.state.session_factory, config=config).recover()
        # A render killed mid-write leaves its temporary beside the cache entry;
        # remove those recognized leftovers, and only those (US07-03).
        ThumbnailService(app.state.session_factory, config).cleanup_temp_files()
        try:
            yield
        finally:
@@ -124,16 +62,6 @@ def create_app(config: Config | None = None) -> FastAPI:
            app.state.engine = None
    app = FastAPI(title="Photo Pipeline", version="0.1.0", lifespan=lifespan)
    # One session per process: the browser exchanges it for a cookie + CSRF token,
    # and every other origin is refused before a route ever runs (US07-02).
    app.state.session = Session.create()
    app.state.access_limiter = FailureLimiter()
    # Also set in the lifespan, but the bootstrap route reads it, and a caller can
    # arrive before anything else has touched app.state.
    app.state.config = config
    app.add_middleware(SecurityMiddleware, session=app.state.session, config=config)
    _install_error_handlers(app)
    app.include_router(session_routes.router, prefix="/api/v1")
    app.include_router(health.router, prefix="/api/v1")
    app.include_router(inventory.router, prefix="/api/v1")
    app.include_router(duplicates.router, prefix="/api/v1")
@@ -147,7 +75,6 @@ def create_app(config: Config | None = None) -> FastAPI:
    app.include_router(renames.router, prefix="/api/v1")
    app.include_router(uploads.router, prefix="/api/v1")
    app.include_router(archives.router, prefix="/api/v1")
    app.include_router(operations.router, prefix="/api/v1")
    # Static single-page app (hash-routed). Mounted last so /api/v1 wins.
    if FRONTEND_DIR.is_dir():
        app.mount("/app", StaticFiles(directory=FRONTEND_DIR, html=True), name="app")
--- a/photo_pipeline/api/routes/analysis.py
+++ b/photo_pipeline/api/routes/analysis.py
@@ -18,10 +18,7 @@ router = APIRouter(tags=["analysis"])
 def _service(request: Request) -> AnalysisService:
-    return AnalysisService(
+    return AnalysisService(request.app.state.session_factory)
        request.app.state.session_factory,
        library_roots=tuple(request.app.state.config.library_roots),
    )
 def _error(status: int, code: str, message: str) -> JSONResponse:
--- a/photo_pipeline/api/routes/archives.py
+++ b/photo_pipeline/api/routes/archives.py
@@ -1,4 +1,4 @@
-"""Archive location, preflight, plan, and restore API (US06-01, US06-02, US06-04).
+"""Archive location, preflight, and plan API (US06-01, US06-02).
 Registering a location writes a marker onto the medium; preflight is a command
 rather than a read, because it probes the destination, hashes the scope, and issues
@@ -13,11 +13,10 @@ from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
-from photo_pipeline.jobs.domain_handlers import ARCHIVE_LOCK, ARCHIVE_PLAN, RESTORE_PLAN
+from photo_pipeline.jobs.domain_handlers import ARCHIVE_LOCK, ARCHIVE_PLAN
 from photo_pipeline.services.archives import ArchiveError, ArchiveService
 from photo_pipeline.services.archive_transfer import ArchiveTransferService
 from photo_pipeline.services.jobs import JobBlocked, JobService
 from photo_pipeline.services.restores import RestoreService
 router = APIRouter(tags=["archives"])
@@ -43,24 +42,10 @@ class CreatePlanRequest(PreflightRequest):
    token: str
 class RestoreRequest(BaseModel):
    location_id: str
    # ``None`` means every asset archived at this location.
    asset_ids: list[str] | None = None
 class CreateRestoreRequest(RestoreRequest):
    token: str
 def _service(request: Request) -> ArchiveService:
    return ArchiveService(request.app.state.session_factory, config=request.app.state.config)
 def _restores(request: Request) -> RestoreService:
    return RestoreService(request.app.state.session_factory, config=request.app.state.config)
 def _transfers(request: Request) -> ArchiveTransferService:
    return ArchiveTransferService(
        request.app.state.session_factory, config=request.app.state.config
@@ -153,76 +138,6 @@ def apply_plan(plan_id: str, request: Request):
    return {"plan_id": plan_id, "job": job}
@router.post("/restore-preflight")
 def restore_preflight(body: RestoreRequest, request: Request):
    """Validate restoring archived assets back into the library. Nothing moves."""
    try:
        return _restores(request).preflight(body.location_id, body.asset_ids)
    except ArchiveError as error:
        return _error(error)
@router.post("/restore-plans", status_code=201)
 def create_restore_plan(body: CreateRestoreRequest, request: Request):
    try:
        return _restores(request).create(body.location_id, body.asset_ids, token=body.token)
    except ArchiveError as error:
        return _error(error)
@router.get("/restore-plans")
 def list_restore_plans(request: Request) -> dict:
    return {"plans": _restores(request).list()}
@router.get("/restore-plans/{plan_id}")
 def get_restore_plan(plan_id: str, request: Request):
    plan = _restores(request).get(plan_id)
    if plan is None:
        return _error(ArchiveError("unknown_plan", f"unknown restore plan {plan_id}"))
    return plan
@router.post("/restore-plans/{plan_id}/apply")
 def apply_restore_plan(plan_id: str, request: Request):
    """Queue the restore on the archiver lane — the same single lane as archiving,
    because both move the same originals."""
    service = _restores(request)
    plan = service.get(plan_id)
    if plan is None:
        return _error(ArchiveError("unknown_plan", f"unknown restore plan {plan_id}"))
    unresolved = [row for row in service.journal.incomplete() if row["plan_id"] != plan_id]
    if unresolved:
        return _error(
            ArchiveError(
                "archive_pending",
                f"an unresolved archive operation ({unresolved[0]['id']}) must be recovered",
            )
        )
    try:
        job = JobService(request.app.state.session_factory).enqueue(
            RESTORE_PLAN,
            lock=ARCHIVE_LOCK,
            idempotency_key=f"restore:{plan_id}:{plan['version']}",
            items=[plan_id],
        )
    except JobBlocked as error:
        return JSONResponse(
            status_code=409, content={"error": {"code": error.code, "message": str(error)}}
        )
    return {"plan_id": plan_id, "job": job}
@router.get("/restore-recovery")
 def restore_recovery_status(request: Request) -> dict:
    return _restores(request).recovery_status()
@router.post("/restore-recovery/resolve")
 def resolve_restore_recovery(request: Request) -> dict:
    return _restores(request).recover()
@router.get("/archive-recovery")
 def recovery_status(request: Request) -> dict:
    """What an interrupted transfer left behind, straight from journal + disk."""
--- a/photo_pipeline/api/routes/duplicates.py
+++ b/photo_pipeline/api/routes/duplicates.py
@@ -11,13 +11,7 @@ from fastapi import APIRouter, Query, Request
 from fastapi.responses import JSONResponse
 from photo_pipeline.schemas import DecisionRequest
-from photo_pipeline.services.duplicates import (
+from photo_pipeline.services.duplicates import ConflictError, DuplicateError, DuplicateService
    MAX_MEMBER_PAGE,
    MEMBER_PAGE,
    ConflictError,
    DuplicateError,
    DuplicateService,
 )
 router = APIRouter(tags=["duplicates"])
@@ -48,13 +42,8 @@ def list_clusters(
@router.get("/duplicates/clusters/{cluster_id}")
-def get_cluster(
+def get_cluster(cluster_id: str, request: Request):
-    cluster_id: str,
+    detail = _service(request).get_cluster(cluster_id)
    request: Request,
    limit: int = Query(MEMBER_PAGE, ge=1, le=MAX_MEMBER_PAGE),
    offset: int = Query(0, ge=0),
 ):
    detail = _service(request).get_cluster(cluster_id, limit=limit, offset=offset)
    if detail is None:
        return _error(404, "not_found", f"unknown cluster {cluster_id}")
    return detail
--- a/photo_pipeline/api/routes/operations.py
+++ b/photo_pipeline/api/routes/operations.py
@@ -1,70 +0,0 @@
 """Operational endpoints: diagnostics and backups (US07-05).
 Backups can be taken and verified here because both are safe, additive, and the
 operator needs them from the same screen that shows the disk filling up.
 **Restore is deliberately not an endpoint.** It replaces the state of the running
 application with an older one, so it belongs to a stopped installation and a person
 at a terminal: ``python -m photo_pipeline restore``. An HTTP call that can silently
 roll the library back to last week is a hole, not a feature.
 """
 from __future__ import annotations
 from fastapi import APIRouter, Query, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 from photo_pipeline.services import diagnostics
 from photo_pipeline.services.backup import DEFAULT_KEEP, BackupError, BackupService
 router = APIRouter(tags=["operations"])
 class CreateBackupRequest(BaseModel):
    reason: str = "manual"
    keep: int = DEFAULT_KEEP
 def _service(request: Request) -> BackupService:
    return BackupService(request.app.state.config)
 def _error(status: int, code: str, message: str) -> JSONResponse:
    return JSONResponse(status_code=status, content={"error": {"code": code, "message": message}})
@router.get("/diagnostics")
 def read_diagnostics(request: Request) -> dict:
    return diagnostics.report(request.app.state.config)
@router.get("/backups")
 def list_backups(request: Request) -> dict:
    return {"backups": _service(request).list()}
@router.post("/backups", status_code=201)
 def create_backup(body: CreateBackupRequest, request: Request):
    try:
        return _service(request).create(reason=body.reason, keep=body.keep)
    except BackupError as error:
        return _error(422, "backup_failed", str(error))
@router.get("/backups/{name}/verify")
 def verify_backup(name: str, request: Request):
    service = _service(request)
    # The name comes from the browser, so it names a backup — it is never joined
    # into a path until it has been matched against one that exists (US07-02).
    if name not in {entry["name"] for entry in service.list()}:
        return _error(404, "not_found", f"unknown backup {name}")
    return {"name": name, **service.verify(service.root / name).as_dict()}
@router.post("/backups/prune")
 def prune_backups(request: Request, keep: int = Query(DEFAULT_KEEP, ge=1)):
    try:
        return {"removed": _service(request).prune(keep=keep)}
    except BackupError as error:
        return _error(422, "invalid_retention", str(error))
--- a/photo_pipeline/api/routes/session.py
+++ b/photo_pipeline/api/routes/session.py
@@ -1,68 +0,0 @@
 """Session bootstrap: the one endpoint reachable without a session (US07-02).
 It sets the ``HttpOnly``/``SameSite=Strict`` session cookie and returns the CSRF
 token in the body. A foreign page can call this — it just cannot read the answer,
 because the app sends no CORS headers — and the cookie it received is never attached
 to a request that foreign page initiated.
 When an access secret is configured (mandatory as soon as the app is reachable from
 another machine, US08-01) this is also the authentication gate: the secret buys the
 cookie, and every route behind it keeps asking for exactly the session and CSRF token
 it asked for before. Wrong secrets are counted, and a burst of them stops being
 answered — otherwise a proxy-exposed deployment could be guessed at indefinitely.
 """
 from __future__ import annotations
 import logging
 import secrets
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 from photo_pipeline.api.security import ACCESS_SECRET_HEADER, SESSION_COOKIE
 router = APIRouter(tags=["session"])
 log = logging.getLogger(__name__)
 def _refuse(status: int, code: str, message: str) -> JSONResponse:
    return JSONResponse(status_code=status, content={"error": {"code": code, "message": message}})
@router.get("/session")
 def start_session(request: Request) -> JSONResponse:
    config = request.app.state.config
    secret = config.access_secret
    if secret is not None:
        limiter = request.app.state.access_limiter
        if limiter.blocked():
            return _refuse(429, "too_many_attempts", "too many failed attempts; retry later")
        offered = request.headers.get(ACCESS_SECRET_HEADER, "")
        if not secrets.compare_digest(offered, secret.get_secret_value()):
            limiter.record_failure()
            # The client address is the whole record: the offered secret, the issued
            # session, and the request body all stay out of the log.
            log.warning(
                "access secret rejected", extra={"client": _client(request), "path": "/session"}
            )
            return _refuse(401, "access_denied", "a valid access secret is required")
    session = request.app.state.session
    response = JSONResponse({"csrf_token": session.csrf_token})
    response.set_cookie(
        SESSION_COOKIE,
        session.id,
        httponly=True,
        samesite="strict",
        # HTTPS outside means the cookie must never travel over a plain hop, even one
        # this process cannot see. Loopback http keeps working unchanged.
        secure=request.scope.get("state", {}).get("external_scheme") == "https",
        path="/",
    )
    return response
 def _client(request: Request) -> str:
    return request.client.host if request.client else "unknown"
--- a/photo_pipeline/api/routes/thumbnails.py
+++ b/photo_pipeline/api/routes/thumbnails.py
@@ -31,7 +31,5 @@ def get_thumbnail(asset_id: str, request: Request, size: int = Query(512)):
    return FileResponse(
        path,
        media_type="image/webp",
-        # private: the URL is versioned and immutable, but these bytes are the user's
+        headers={"Cache-Control": "public, max-age=31536000, immutable"},
        # photos and must never sit in a shared cache (US07-02).
        headers={"Cache-Control": "private, max-age=31536000, immutable"},
    )
--- a/photo_pipeline/api/security.py
+++ b/photo_pipeline/api/security.py
@@ -1,317 +0,0 @@
 """Local-web attack surface: session, CSRF, Origin/Host checks, default headers.
 The app binds to 127.0.0.1, so the attacker is not a remote client but another page
 in the user's browser (concept §15, "Local web attack"): any site can issue requests
 to ``http://127.0.0.1:8000`` and can embed ``<img src=...>`` against media endpoints.
 The defenses stack, because each one alone has a hole:
 * **Host** must be a loopback name — a DNS rebinding host that resolves to 127.0.0.1
  passes the browser's origin rules but not this check.
 * **Origin**, when the browser sends one, must be this exact origin (scheme, host,
  port). There is no CORS middleware at all, so a foreign page can never *read* a
  response even if it manages to send a request.
 * **Sec-Fetch-Site** rejects cross-site loads that carry no Origin, which is what an
  ``<img>`` or ``<script>`` against a media endpoint looks like.
 * A **session cookie** (``SameSite=Strict``, ``HttpOnly``) is required by every
  ``/api/v1`` route except liveness/readiness and the bootstrap itself. Strict means
  the browser never attaches it to a request another site initiated.
 * A **CSRF token** must be echoed in a header on every mutation. It is handed out
  only in the bootstrap response body, which a foreign page cannot read (no CORS) —
  so possessing it proves the caller is same-origin.
 Behind a reverse proxy (US08-01) the same stack holds with two substitutions: the
 allowed host set comes from configuration instead of being the loopback names, and
 the host/scheme the policy judges is the *external* one, which is only read from
 ``X-Forwarded-*`` when the request actually arrived from a configured proxy. The
 loopback check was standing in for authentication, so naming a non-loopback host
 also makes an access secret mandatory — ``trust_refusal`` refuses to start without
 one, and the secret is what the bootstrap endpoint trades for the session cookie.
 ``evaluate`` is a pure function over the request metadata: the whole policy is one
 table that a unit test can enumerate, and the middleware only applies its verdict.
 """
 from __future__ import annotations
 import secrets
 import time
 from collections.abc import Mapping
 from dataclasses import dataclass
 from urllib.parse import urlsplit
 from starlette.datastructures import Headers, MutableHeaders
 from starlette.responses import JSONResponse
 SESSION_COOKIE = "pp_session"
 CSRF_HEADER = "x-csrf-token"
 ACCESS_SECRET_HEADER = "x-access-secret"
 API_PREFIX = "/api/v1"
 SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 # Reachable without a session: liveness/readiness (an orchestrator has no cookie)
 # and the bootstrap that issues the session in the first place.
 PUBLIC_PATHS = frozenset(
    {f"{API_PREFIX}/health/live", f"{API_PREFIX}/health/ready", f"{API_PREFIX}/session"}
 )
 LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "[::1]"})
 # Mutating endpoints that must stay reachable while mutation itself is gated: the
 # backup a careful operator takes first, and its retention (US07-07).
 MUTATION_EXEMPT_PATHS = frozenset({f"{API_PREFIX}/backups", f"{API_PREFIX}/backups/prune"})
 # Applied to every response. No inline script/style is used by the frontend, so the
 # policy can stay strict; `frame-ancestors 'none'` and CORP keep other pages from
 # embedding the app or its thumbnails.
 DEFAULT_HEADERS = {
    "x-content-type-options": "nosniff",
    "x-frame-options": "DENY",
    "referrer-policy": "no-referrer",
    "cross-origin-resource-policy": "same-origin",
    "cross-origin-opener-policy": "same-origin",
    "content-security-policy": (
        "default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; "
        "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
    ),
 }
@dataclass(frozen=True)
 class Session:
    """One process, one session. A local app has exactly one user; a session store
    would be bookkeeping without a second subject to distinguish.
    ponytail: per-session rows if the app ever serves more than one operator.
    """
    id: str
    csrf_token: str
    @classmethod
    def create(cls) -> Session:
        return cls(secrets.token_urlsafe(32), secrets.token_urlsafe(32))
@dataclass(frozen=True)
 class Refusal:
    status: int
    code: str
    message: str
 def split_host(value: str) -> tuple[str, str]:
    """``"127.0.0.1:8000"`` -> ``("127.0.0.1", "8000")``; bracketed IPv6 aware."""
    value = value.strip()
    if value.startswith("["):
        host, _, port = value.partition("]")
        return host + "]", port.lstrip(":")
    host, _, port = value.partition(":")
    return host, port
 def external_view(
    *,
    client: str | None,
    headers: Mapping[str, str],
    scheme: str,
    trusted_proxies: frozenset[str],
 ) -> tuple[str, str]:
    """The ``(scheme, host)`` the caller used, as opposed to the one this hop saw.
    Forwarded headers are a client-supplied claim. Believing them from anyone lets a
    request declare its own origin — and origin is half of this module's evidence —
    so they count only when the connection came from a configured proxy.
    """
    host = headers.get("host", "")
    if client is None or client not in trusted_proxies:
        return scheme, host
    # A chain appends: the first entry is what the original client asked for.
    forwarded_proto = headers.get("x-forwarded-proto", "").split(",")[0].strip().lower()
    forwarded_host = headers.get("x-forwarded-host", "").split(",")[0].strip()
    return forwarded_proto or scheme, forwarded_host or host
 def evaluate(
    *,
    method: str,
    path: str,
    headers: Mapping[str, str],
    session: Session,
    allowed_hosts: frozenset[str] = LOOPBACK_HOSTS,
    scheme: str = "http",
    max_request_bytes: int,
 ) -> Refusal | None:
    """Why this request must be refused, or ``None`` when it may proceed.
    ``headers["host"]`` and ``scheme`` are the external ones (see ``external_view``);
    the allowed origins are the allowed hosts under that scheme and port, so there is
    no second list that can drift away from the first.
    """
    host_header = headers.get("host", "")
    host, port = split_host(host_header)
    if host.lower() not in allowed_hosts:
        return Refusal(403, "host_not_allowed", "request host is not an allowed address")
    origin = headers.get("origin")
    if origin is not None and origin != "":
        parts = urlsplit(origin)
        origin_host, origin_port = split_host(parts.netloc)
        if (
            parts.scheme != scheme
            or origin_host.lower() not in allowed_hosts
            or origin_port != port
        ):
            return Refusal(403, "origin_not_allowed", "request origin is not this application")
    # Absent means a non-browser client; "none" is a user-initiated navigation.
    fetch_site = headers.get("sec-fetch-site")
    if fetch_site is not None and fetch_site not in ("same-origin", "none"):
        return Refusal(403, "cross_site_blocked", "cross-site requests are not accepted")
    length = headers.get("content-length")
    if length and length.isdigit() and int(length) > max_request_bytes:
        return Refusal(413, "payload_too_large", "request body exceeds the configured limit")
    protected = path.startswith(API_PREFIX) and path not in PUBLIC_PATHS
    if not protected:
        return None
    if headers.get("cookie-session") != session.id:
        return Refusal(401, "unauthenticated", "a valid application session is required")
    if method.upper() not in SAFE_METHODS and headers.get(CSRF_HEADER) != session.csrf_token:
        return Refusal(403, "csrf_failed", "missing or invalid CSRF token")
    return None
 def exposed_hosts(config) -> list[str]:
    """Configured names by which this application is reachable from another machine."""
    names = {str(config.host).lower()}
    names.update(split_host(name)[0].lower() for name in config.allowed_hosts)
    return sorted(names - LOOPBACK_HOSTS)
 def trust_refusal(config) -> str | None:
    """Why this configuration must not serve at all, or ``None``.
    Reaching the app used to prove ownership of it. The moment a configuration makes
    it reachable from elsewhere that stops being true, so serving without a secret
    would publish the library — refuse at startup rather than at the first request,
    when the operator is no longer watching (US08-01).
    """
    exposed = exposed_hosts(config)
    if exposed and config.access_secret is None:
        return (
            f"refusing to serve: {', '.join(exposed)} is reachable from outside this "
            "machine, so PHOTO_PIPELINE_ACCESS_SECRET must be set"
        )
    return None
 class FailureLimiter:
    """Bounded failed access-secret attempts, so the secret cannot be guessed online.
    ponytail: one counter for the whole process rather than per client address —
    behind a proxy every attempt arrives from the same address anyway. Per-caller
    buckets if the app is ever exposed without one.
    """
    def __init__(self, limit: int = 5, window: float = 60.0) -> None:
        self.limit = limit
        self.window = window
        self._failures: list[float] = []
    def blocked(self) -> bool:
        now = time.monotonic()
        self._failures = [at for at in self._failures if now - at < self.window]
        return len(self._failures) >= self.limit
    def record_failure(self) -> None:
        self._failures.append(time.monotonic())
 class SecurityMiddleware:
    """Pure-ASGI so the SSE stream keeps streaming (BaseHTTPMiddleware buffers)."""
    def __init__(self, app, *, session: Session, config) -> None:
        self.app = app
        self.session = session
        self.config = config
        self.max_request_bytes = config.max_request_bytes
        self.allowed_hosts = frozenset(
            LOOPBACK_HOSTS
            | {str(config.host).lower()}
            | {split_host(name)[0].lower() for name in config.allowed_hosts}
        )
        self.trusted_proxies = frozenset(config.trusted_proxies)
    async def __call__(self, scope, receive, send) -> None:
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return
        headers = Headers(scope=scope)
        # The cookie is read here and handed to the pure policy as one value, so the
        # policy never has to parse a Cookie header.
        lookup = dict(headers)
        lookup["cookie-session"] = _cookie(headers.get("cookie", ""), SESSION_COOKIE)
        client = scope.get("client")
        scheme, lookup["host"] = external_view(
            client=client[0] if client else None,
            headers=headers,
            scheme=scope.get("scheme", "http"),
            trusted_proxies=self.trusted_proxies,
        )
        # What the session cookie's Secure flag is decided from, one hop later.
        scope.setdefault("state", {})["external_scheme"] = scheme
        refusal = evaluate(
            method=scope.get("method", "GET"),
            path=scope.get("path", "/"),
            headers=lookup,
            session=self.session,
            allowed_hosts=self.allowed_hosts,
            scheme=scheme,
            max_request_bytes=self.max_request_bytes,
        )
        if refusal is None:
            refusal = self._mutation_refusal(scope)
        if refusal is not None:
            response = JSONResponse(
                status_code=refusal.status,
                content={"error": {"code": refusal.code, "message": refusal.message}},
                headers=DEFAULT_HEADERS,
            )
            await response(scope, receive, send)
            return
        async def send_with_headers(message):
            if message["type"] == "http.response.start":
                out = MutableHeaders(scope=message)
                for name, value in DEFAULT_HEADERS.items():
                    out.setdefault(name, value)
            await send(message)
        await self.app(scope, receive, send_with_headers)
    def _mutation_refusal(self, scope) -> Refusal | None:
        """Refuse every mutating request while the library's dry run is unapproved.
        One choke point for the whole API: every mutation the browser can start is a
        non-safe method under ``/api/v1``. Reading stays open — an operator has to be
        able to look at what the application found in order to approve it (US07-07).
        """
        method = scope.get("method", "GET").upper()
        path = scope.get("path", "/")
        if method in SAFE_METHODS or not path.startswith(API_PREFIX):
            return None
        if path in MUTATION_EXEMPT_PATHS:
            return None
        from photo_pipeline.services.release import mutation_blockers
        blockers = mutation_blockers(self.config)
        if not blockers:
            return None
        return Refusal(403, blockers[0]["code"], blockers[0]["message"])
 def _cookie(header: str, name: str) -> str:
    for part in header.split(";"):
        key, _, value = part.strip().partition("=")
        if key == name:
            return value
    return ""
--- a/photo_pipeline/config.py
+++ b/photo_pipeline/config.py
@@ -7,9 +7,6 @@ real external call needs them.
 pydantic-settings would do this too, but a prefix-scan over the declared fields
 is a few lines and one fewer dependency.
 Tuple-valued settings are lists in one variable: library roots are ``os.pathsep``
 separated because they are paths, everything else is comma separated.
 """
 from __future__ import annotations
@@ -21,62 +18,6 @@ from typing import Mapping
 from pydantic import BaseModel, ConfigDict, SecretStr
 ENV_PREFIX = "PHOTO_PIPELINE_"
 ENV_FILE_VAR = f"{ENV_PREFIX}ENV_FILE"
 DEFAULT_ENV_FILE = Path(".env")
 COMMA_LIST_FIELDS = frozenset({"allowed_hosts", "trusted_proxies"})
 # The archived CLI's variable names, so the configuration file an operator already
 # has keeps working. The vision provider reads the OpenAI SDK's names, and the
 # library root is configuration here rather than a bare path (US07-01 donor).
 LEGACY_ALIASES = {
    "LLM_API_KEY": "OPENAI_API_KEY",
    "GEMINI_API_KEY": "OPENAI_API_KEY",
    "LLM_BASE_URL": "OPENAI_BASE_URL",
    "LIBRARY": f"{ENV_PREFIX}LIBRARY_ROOTS",
 }
 def parse_env_file(text: str) -> dict[str, str]:
    """``KEY=value`` lines into a mapping. Comments, blanks, and quotes handled.
    Deliberately not a shell: no interpolation, no ``export``, no multi-line values.
    A configuration file that can run code is a configuration file that can be a
    vulnerability.
    """
    values: dict[str, str] = {}
    for line in text.splitlines():
        line = line.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        key, _, raw = line.partition("=")
        key = key.strip()
        if not key or key.startswith("#"):
            continue
        value = raw.strip().strip('"').strip("'")
        values[key] = value
        alias = LEGACY_ALIASES.get(key)
        if alias:
            values.setdefault(alias, value)
    return values
 def load_env_file(path: Path | str | None = None) -> dict[str, str]:
    """Load ``PHOTO_PIPELINE_ENV_FILE`` (or ``./.env``) into the environment.
    Anything already exported wins: a file is the standing configuration, the shell
    is what you meant *this time*. Returns what it applied, which is what the CLI
    prints — names only, never values.
    """
    candidate = path or os.environ.get(ENV_FILE_VAR) or DEFAULT_ENV_FILE
    candidate = Path(candidate)
    if not candidate.is_file():
        return {}
    applied = {}
    for key, value in parse_env_file(candidate.read_text()).items():
        if key not in os.environ:
            os.environ[key] = value
            applied[key] = value
    return applied
 class Config(BaseModel):
@@ -89,23 +30,6 @@ class Config(BaseModel):
    log_level: str = "INFO"
    log_format: str = "json"  # "json" or "text"
    # Trust boundary (US08-01). Empty means loopback only, which is what the app did
    # before there was a setting: a request whose Host is not a loopback name is
    # refused, and no secret is needed because nothing outside this machine can call.
    # Naming a real hostname here is what makes the app reachable through a reverse
    # proxy, and it is exactly then that ``access_secret`` becomes mandatory.
    allowed_hosts: tuple[str, ...] = ()
    # Addresses whose ``X-Forwarded-Proto``/``X-Forwarded-Host`` may be believed. A
    # client that is not the proxy can otherwise declare its own origin.
    trusted_proxies: tuple[str, ...] = ()
    # Exchanged for the session cookie at the bootstrap endpoint. Once set it is
    # required even on loopback, so a development setup cannot half-enable it.
    access_secret: SecretStr | None = None
    # Largest request body the API accepts. Every endpoint takes small JSON commands;
    # anything larger is a mistake or an attempt to exhaust memory (US07-02).
    max_request_bytes: int = 1_048_576
    # Library boundary for path validation (os.pathsep-separated in the env var).
    library_roots: tuple[Path, ...] = ()
    thumbnail_cache_quota_bytes: int = 500_000_000
@@ -114,12 +38,6 @@ class Config(BaseModel):
    # Free space an archive destination must keep beyond the transfer itself.
    archive_free_space_reserve_bytes: int = 1_000_000_000
    # Refuse every mutating request until a read-only dry run of the configured
    # library has been produced and explicitly approved (US07-07). Off by default so
    # a development setup is unchanged; turn it on before pointing the application at
    # a library whose photos cannot be replaced.
    require_dry_run_approval: bool = False
    vision_api_key: SecretStr | None = None
    immich_api_key: SecretStr | None = None
    immich_server_url: str = ""
@@ -140,18 +58,10 @@ class Config(BaseModel):
    @classmethod
    def from_env(cls, environ: Mapping[str, str] | None = None) -> "Config":
        env = os.environ if environ is None else environ
        if environ is None:
            load_env_file()  # a file never overrides what the shell already set
            env = os.environ
        data: dict = {}
        for name in cls.model_fields:
            raw = env.get(ENV_PREFIX + name.upper())
            if not raw:
                continue
-            if name == "library_roots":
+            data[name] = raw.split(os.pathsep) if name == "library_roots" else raw
                data[name] = raw.split(os.pathsep)
            elif name in COMMA_LIST_FIELDS:
                data[name] = [part.strip() for part in raw.split(",") if part.strip()]
            else:
                data[name] = raw
        return cls(**data)
--- a/photo_pipeline/db.py
+++ b/photo_pipeline/db.py
@@ -41,41 +41,12 @@ def create_session_factory(engine: Engine) -> sessionmaker:
    return sessionmaker(bind=engine, expire_on_commit=False, future=True)
-def _alembic_config(url: str):
+def run_migrations(url: str) -> None:
    """Upgrade the database at ``url`` to the latest revision."""
    from alembic import command
    from alembic.config import Config as AlembicConfig
    cfg = AlembicConfig(str(_REPO_ROOT / "alembic.ini"))
    cfg.set_main_option("script_location", str(_REPO_ROOT / "migrations"))
    cfg.set_main_option("sqlalchemy.url", url)
-    return cfg
+    command.upgrade(cfg, "head")
 def run_migrations(url: str) -> None:
    """Upgrade the database at ``url`` to the latest revision."""
    from alembic import command
    command.upgrade(_alembic_config(url), "head")
 def head_revision() -> str | None:
    """The revision this code expects. ``None`` if the scripts cannot be read."""
    from alembic.script import ScriptDirectory
    try:
        return ScriptDirectory.from_config(_alembic_config("sqlite://")).get_current_head()
    except Exception:
        return None
 def current_revision(url: str) -> str | None:
    """The revision a database is actually at, or ``None`` for an unstamped one."""
    engine = create_db_engine(url)
    try:
        with engine.connect() as connection:
            from alembic.runtime.migration import MigrationContext
            return MigrationContext.configure(connection).get_current_revision()
    except Exception:
        return None
    finally:
        engine.dispose()
--- a/photo_pipeline/faults.py
+++ b/photo_pipeline/faults.py
@@ -1,45 +0,0 @@
 """Test-only fault control points (concept §18, US07-04).
 Crash safety can only be proven by crashing at the exact moment a transition has
 been persisted but its consequence has not. That needs a barrier *inside* the
 production code path — but not a production capability: there is no endpoint, no
 service method, and no configuration file entry that can trigger one. The only
 switch is an environment variable naming a single point, read at the moment it is
 passed, and the only thing it does is kill the process. A deployment that never
 sets it can never reach the barrier.
 ``os._exit`` is deliberate: it skips atexit handlers, buffered flushes, and
 ``finally`` blocks, which is what a real ``SIGKILL`` or power loss does. A clean
 shutdown would prove nothing.
 The points are the persisted transitions of the journalled stages:
    rename    moving | moved | database_updated | verified | complete
    archive   transferring | verified | removing | source_removed | complete
    exif      exif:written        — keywords on disk, checkpoint not yet recorded
    upload    upload:accepted     — uploader exited, outcome not yet persisted
    jobs      job:item_done       — item committed, job outcome not yet written
 Recovery for each is asserted in tests/integration/test_fault_matrix.py and
 tests/e2e/test_crash_recovery.py.
 """
 from __future__ import annotations
 import os
 ENV_VAR = "PHOTO_PIPELINE_FAULT_AFTER"
 EXIF_WRITTEN = "exif:written"
 UPLOAD_ACCEPTED = "upload:accepted"
 JOB_ITEM_DONE = "job:item_done"
 def maybe_fault(point: str) -> None:
    """Die abruptly when ``PHOTO_PIPELINE_FAULT_AFTER`` names ``point``.
    Shared by the rename, archive, restore, EXIF, upload, and job lanes, each
    passing its own state names. Never set the variable outside tests.
    """
    if os.environ.get(ENV_VAR) == point:
        os._exit(9)
--- a/photo_pipeline/imaging.py
+++ b/photo_pipeline/imaging.py
@@ -1,119 +0,0 @@
 """Bounded, defensive image decoding — one door for every pixel this app reads.
 A photo library contains files nobody planned for: truncated downloads, zero-byte
 placeholders, a PNG whose header claims 200000×200000, a TIFF with a broken ICC
 profile, an extension that lies about its content. None of them may take down a
 request or a worker, and none may decode more pixels than the caller allowed
 (concept §17: decoded pixels, not file size, are what exhausts memory).
 ``open_image`` is that single door:
 * the declared dimensions are checked **before** a pixel is decoded;
 * Pillow's decompression-bomb *warning* is promoted to an error, because the
  warning band (between Pillow's limit and twice it) still decodes the image;
 * every decoder failure — at open time or during the caller's decode — becomes one
  of two typed errors, so callers map them to their own item state instead of
  catching ``Exception``;
 * error text names no path: it reaches API responses, and the full reason goes to
  the server log instead (US07-02).
 ``to_srgb`` and ``draft`` are the other two bounded-decode helpers: colour-manage a
 profile-bearing image into sRGB, and let JPEG decode straight to a size near the
 requested one rather than at full resolution.
 """
 from __future__ import annotations
 import io
 import logging
 import warnings
 from contextlib import contextmanager
 from pathlib import Path
 from PIL import Image, ImageCms, ImageFile, UnidentifiedImageError
 log = logging.getLogger(__name__)
 # Matches ``Config.thumbnail_max_pixels``; used where no configuration is at hand
 # (hashing runs inside discovery, which takes no config).
 DEFAULT_MAX_PIXELS = 100_000_000
 class MediaError(Exception):
    """A file could not be turned into pixels safely."""
 class UndecodableImage(MediaError):
    """Corrupt, truncated, empty, or not an image at all."""
 class ImageTooLarge(MediaError):
    """More pixels than this operation is allowed to decode."""
@contextmanager
 def open_image(path: Path | str, *, max_pixels: int = DEFAULT_MAX_PIXELS):
    """Yield an open :class:`PIL.Image.Image`, bounded and with typed failures.
    Decoder errors raised inside the ``with`` body are translated too — a truncated
    JPEG only fails when its pixels are actually pulled, which is the caller's line,
    not this one.
    """
    # Pillow's truncation tolerance is a process-global switch that any library in
    # the process can flip (the donor CLI did). This door decides the policy for its
    # own callers: half a file is not a picture.
    tolerated = ImageFile.LOAD_TRUNCATED_IMAGES
    ImageFile.LOAD_TRUNCATED_IMAGES = False
    with warnings.catch_warnings():
        # The warning band is not a warning for us: it means Pillow was willing to
        # decode an image large enough to be a denial-of-service.
        warnings.simplefilter("error", Image.DecompressionBombWarning)
        try:
            with Image.open(path) as image:
                width, height = image.size
                if width * height > max_pixels:
                    raise ImageTooLarge(f"{width}x{height} exceeds the {max_pixels} pixel limit")
                yield image
        except MediaError:
            raise
        except (Image.DecompressionBombError, Image.DecompressionBombWarning) as error:
            log.info("refused oversized image %s: %s", path, error)
            raise ImageTooLarge("image exceeds the decompression-bomb limit") from error
        except (UnidentifiedImageError, OSError, ValueError, SyntaxError, MemoryError) as error:
            log.info("cannot decode %s: %s", path, error)
            raise UndecodableImage(f"cannot decode image ({type(error).__name__})") from error
        finally:
            ImageFile.LOAD_TRUNCATED_IMAGES = tolerated
 def draft(image: Image.Image, size: int) -> None:
    """Ask the decoder for a smaller image where the format allows it (JPEG).
    This is the difference between decoding a 40-megapixel JPEG and decoding the
    roughly 1-megapixel version a 1280px preview needs.
    """
    try:
        image.draft(None, (size, size))
    except (AttributeError, ValueError, OSError):  # not a draft-capable format
        pass
 def to_srgb(image: Image.Image, *, mode: str) -> Image.Image:
    """Convert into ``mode``, colour-managing through an embedded ICC profile.
    Without this a wide-gamut original renders with visibly wrong colours, because
    its numbers are interpreted as sRGB. A broken or unreadable profile is not a
    reason to fail a preview — the plain conversion is still a correct picture.
    """
    profile = image.info.get("icc_profile")
    if profile:
        try:
            return ImageCms.profileToProfile(
                image,
                ImageCms.ImageCmsProfile(io.BytesIO(profile)),
                ImageCms.createProfile("sRGB"),
                outputMode=mode,
            )
        except Exception as error:  # noqa: BLE001 - any ICC failure falls back
            log.info("ignoring unusable ICC profile on %s: %s", getattr(image, "filename", "?"), error)
    return image.convert(mode)
--- a/photo_pipeline/integrations/exiftool.py
+++ b/photo_pipeline/integrations/exiftool.py
@@ -12,48 +12,11 @@ nt-apply-list, pa-nsfw-filter). No dependency on the archived entry points.
 from __future__ import annotations
 import functools
 import json
 import os
 import shutil
 import subprocess
 from collections.abc import Iterable
 # A hung exiftool must not hang the worker with it: every call is bounded, and a
 # call that runs out of time is treated exactly like a failed one — no metadata
 # answer, nothing marked verified (US07-04). The knob exists because "slow" is a
 # property of the machine, not of the code: huge files on a slow network volume
 # legitimately take longer than the default.
 DEFAULT_TIMEOUT_SECONDS = 120.0
 def _timeout() -> float:
    try:
        return float(os.environ.get("PHOTO_PIPELINE_EXIFTOOL_TIMEOUT", DEFAULT_TIMEOUT_SECONDS))
    except ValueError:
        return DEFAULT_TIMEOUT_SECONDS
 def find_binary(binary: str = "exiftool") -> str | None:
    """Absolute path of exiftool, or ``None`` when it is not installed."""
    return shutil.which(binary)
@functools.lru_cache(maxsize=1)
 def version() -> str | None:
    """Reported exiftool version, or ``None`` when it is missing or unusable.
    Cached: it cannot change inside a running process, and diagnostics asks for it
    on every report (US08-02, where a container image pins this version).
    """
    try:
        result = subprocess.run(
            ["exiftool", "-ver"], capture_output=True, text=True, timeout=_timeout()
        )
    except (OSError, subprocess.SubprocessError):
        return None
    return (result.stdout or "").strip() or None
 def read_keyword_sets(paths: Iterable[str]) -> dict[str, set[str]]:
    """Map each path to its lowercased set of ``Keywords`` + ``Subject`` values.
@@ -71,9 +34,8 @@ def read_keyword_sets(paths: Iterable[str]) -> dict[str, set[str]]:
            input="\n".join(paths),
            capture_output=True,
            text=True,
            timeout=_timeout(),
        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
+    except FileNotFoundError:
        return {}
    out: dict[str, set[str]] = {}
    try:
@@ -94,33 +56,6 @@ def read_keyword_sets(paths: Iterable[str]) -> dict[str, set[str]]:
    return out
 def read_all(path: str) -> dict | None:
    """Every tag exiftool can read from ``path``, or ``None`` when it cannot answer.
    This is the snapshot an EXIF checkpoint compares against: proving that a write
    preserved the fields it does not own requires knowing all of them, not just the
    ones being written (US07-03). ``None`` (exiftool missing, unreadable file,
    unparsable output) is not an empty snapshot — a caller must not read it as
    "nothing was there".
    """
    try:
        result = subprocess.run(
            ["exiftool", "-m", "-j", "-G0:1", path],
            capture_output=True,
            text=True,
            timeout=_timeout(),
        )
    except (FileNotFoundError, subprocess.TimeoutExpired):
        return None
    try:
        records = json.loads(result.stdout or "[]")
    except ValueError:
        return None
    if not records:
        return None
    return {k: v for k, v in records[0].items() if k != "SourceFile"}
 def apply_keywords(path: str, *, add: Iterable[str] = (), remove: Iterable[str] = ()) -> bool:
    """Idempotently add/remove keywords in Keywords + Subject; preserve all else."""
    args = ["exiftool", "-m", "-overwrite_original"]
@@ -132,10 +67,4 @@ def apply_keywords(path: str, *, add: Iterable[str] = (), remove: Iterable[str]
    if len(args) == 3:
        return True
    args.append(path)
-    try:
+    return subprocess.run(args, capture_output=True, text=True).returncode == 0
        return subprocess.run(
            args, capture_output=True, text=True, timeout=_timeout()
        ).returncode == 0
    except (FileNotFoundError, subprocess.TimeoutExpired):
        # A write that never returned is not a write that succeeded.
        return False
--- a/photo_pipeline/integrations/nsfw_model.py
+++ b/photo_pipeline/integrations/nsfw_model.py
@@ -15,8 +15,6 @@ from __future__ import annotations
 from pathlib import Path
 from photo_pipeline import imaging
 MODEL_ID = "AdamCodd/vit-base-nsfw-detector"
 BATCH = 16
@@ -56,17 +54,13 @@ class NsfwModel:
        self._ensure_loaded()
        import numpy as np
        import torch
-        from PIL import Image
+        from PIL import Image, ImageFile
-        # The donor set ``ImageFile.LOAD_TRUNCATED_IMAGES = True`` here. That flag is
+        ImageFile.LOAD_TRUNCATED_IMAGES = True
-        # process-global: in this application the same process also hashes files and
+
-        # renders previews, and those must keep failing loudly on a truncated file
+        def preprocess(image):
-        # rather than quietly working on half of one (US07-03). An unreadable image
+            image = image.convert("RGB").resize((self._size, self._size), Image.BILINEAR)
-        # is skipped instead — it stays unscored, and therefore visibly undecided.
+            array = (np.asarray(image, dtype="float32") / 255.0 - 0.5) / 0.5
        def preprocess(path):
            with imaging.open_image(path) as image:
                small = image.convert("RGB").resize((self._size, self._size), Image.BILINEAR)
            array = (np.asarray(small, dtype="float32") / 255.0 - 0.5) / 0.5
            return torch.from_numpy(array).permute(2, 0, 1)
        results: list[tuple[str, float]] = []
@@ -75,10 +69,9 @@ class NsfwModel:
            tensors, batch_paths = [], []
            for path in items[start : start + self.batch]:
                try:
-                    tensors.append(preprocess(path))
+                    tensors.append(preprocess(Image.open(path)))
                    batch_paths.append(path)
-                except (imaging.MediaError, OSError, ValueError):
+                except Exception:
                    # One bad file must not cost the batch its other fifteen.
                    continue
            if not tensors:
                continue
--- a/photo_pipeline/jobs/domain_handlers.py
+++ b/photo_pipeline/jobs/domain_handlers.py
@@ -1,9 +1,9 @@
 """Domain job handlers: safety scoring, content analysis, uploads, archive
-transfers, restores (US02-06, US05-02, US06-02, US06-04).
+transfers (US02-06, US05-02, US06-02).
 Importing this module registers the ``safety_score``, ``analysis``,
-``upload_batch``, ``archive_plan``, and ``restore_plan`` job types so the generic
+``upload_batch``, and ``archive_plan`` job types so the generic worker can run them
-worker can run them per item. Each handler delegates to its service, which owns the real work and the
+per item. 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, an upload batch refuses to re-run an attempt whose
 outcome is unknown, and an archive plan skips items it already completed.
@@ -20,7 +20,6 @@ SAFETY_SCORE = "safety_score"
 ANALYSIS = "analysis"
 UPLOAD_BATCH = "upload_batch"
 ARCHIVE_PLAN = "archive_plan"
 RESTORE_PLAN = "restore_plan"
 # Both mutate the library's metadata/derived state; one at a time (concept §one job).
 LIBRARY_WRITE_LOCK = "library_write"
 # The uploader lane: one album batch at a time (concept §16).
@@ -38,8 +37,7 @@ def _safety_score_item(asset_id: str, ctx: JobContext) -> None:
 def _analysis_item(asset_id: str, ctx: JobContext) -> None:
    from photo_pipeline.services.analysis import AnalysisService
-    roots = tuple(getattr(ctx.config, "library_roots", ()) or ())
+    AnalysisService(ctx.session_factory).run([asset_id])
    AnalysisService(ctx.session_factory, library_roots=roots).run([asset_id])
 def _upload_batch_item(batch_id: str, ctx: JobContext) -> None:
@@ -72,22 +70,7 @@ def _archive_plan_item(plan_id: str, ctx: JobContext) -> None:
        raise RuntimeError(f"archive plan {plan_id}: {result['failed']} item(s) failed")
 def _restore_plan_item(plan_id: str, ctx: JobContext) -> None:
    """One item = one restore plan. A restore removes nothing, so an item failure
    simply leaves that asset archived (US06-04)."""
    from photo_pipeline.config import Config
    from photo_pipeline.services.restores import RestoreService
    config = ctx.config if ctx.config is not None else Config.from_env()
    result = RestoreService(ctx.session_factory, config=config).apply(
        plan_id, worker_id=ctx.worker_id
    )
    if result["failed"]:
        raise RuntimeError(f"restore plan {plan_id}: {result['failed']} item(s) failed")
 register(SAFETY_SCORE, _safety_score_item)
 register(ANALYSIS, _analysis_item)
 register(UPLOAD_BATCH, _upload_batch_item)
 register(ARCHIVE_PLAN, _archive_plan_item)
 register(RESTORE_PLAN, _restore_plan_item)
--- a/photo_pipeline/jobs/worker.py
+++ b/photo_pipeline/jobs/worker.py
@@ -16,7 +16,6 @@ from collections.abc import Mapping, Sequence
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.faults import JOB_ITEM_DONE, maybe_fault
 from photo_pipeline.jobs.handlers import REGISTRY, Cancelled, Handler, JobContext
 from photo_pipeline.models import JobItem
 from photo_pipeline.services.jobs import ItemState, JobConflict, JobService, JobState
@@ -87,9 +86,6 @@ class Worker:
                )
            else:
                self.service.set_item(job_id, item_key, ItemState.SUCCEEDED, fencing_token=token)
                # One item is durably done, the job outcome is not: the control point
                # for a crash mid-batch (US07-04). Recovery must not re-run this item.
                maybe_fault(JOB_ITEM_DONE)
            self.service.heartbeat(job_id, self.worker_id, lease_seconds=self.lease_seconds)
        self._finalize(job_id, token, cancelled=cancelled, any_failed=any_failed)
--- a/photo_pipeline/models/init.py
+++ b/photo_pipeline/models/init.py
@@ -7,7 +7,6 @@ Alembic environment relies on.
 from photo_pipeline.models.albums import AlbumProposal
 from photo_pipeline.models.archives import ArchiveLocation, ArchiveOperation, ArchivePlan
 from photo_pipeline.models.assets import Asset, AssetPath
 from photo_pipeline.models.exif import ExifProjection
 from photo_pipeline.models.duplicates import (
    DuplicateCluster,
    DuplicateMember,
@@ -29,7 +28,6 @@ __all__ = [
    "DuplicateCluster",
    "DuplicateMember",
    "DuplicateNegativeLink",
    "ExifProjection",
    "Job",
    "JobItem",
    "JobEvent",
--- a/photo_pipeline/models/archives.py
+++ b/photo_pipeline/models/archives.py
@@ -66,8 +66,6 @@ class ArchivePlan(Base):
    # The preflight token this plan was approved against; re-verified before apply.
    token: Mapped[str] = mapped_column(String, nullable=False)
    albums: Mapped[str | None] = mapped_column(String)  # JSON array
    # archive | restore — the same journal read in the opposite direction (US06-04).
    direction: Mapped[str] = mapped_column(String, nullable=False, default="archive")
    # planned | applying | complete | failed
    state: Mapped[str] = mapped_column(String, nullable=False, default="planned")
@@ -102,9 +100,6 @@ class ArchiveOperation(Base):
    album: Mapped[str] = mapped_column(String, nullable=False)
    asset_id: Mapped[str] = mapped_column(ForeignKey("assets.id"), nullable=False, index=True)
    # archive: library → medium. restore: medium → library (US06-04). ``source_path``
    # and ``destination_path`` always mean "from" and "to" for this direction.
    direction: Mapped[str] = mapped_column(String, nullable=False, default="archive")
    source_path: Mapped[str] = mapped_column(String, nullable=False)
    destination_path: Mapped[str] = mapped_column(String, nullable=False)
    # Relative to the location root, because the medium can be mounted elsewhere.
--- a/photo_pipeline/models/assets.py
+++ b/photo_pipeline/models/assets.py
@@ -43,10 +43,6 @@ class Asset(Base):
    # link is written and read by the archive service (US06-02).
    archive_location_id: Mapped[str | None] = mapped_column(String)
    archive_path: Mapped[str | None] = mapped_column(String)
    # Set when the archived copy was proven to hold bytes other than the recorded
    # ones (US06-04). Restore refuses such an asset instead of accepting a different
    # file; cleared as soon as a verification matches again.
    archive_divergent_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    # Duplicate canonical link: NULL when the asset is itself canonical or undecided.
    canonical_asset_id: Mapped[str | None] = mapped_column(ForeignKey("assets.id"))
--- a/photo_pipeline/models/exif.py
+++ b/photo_pipeline/models/exif.py
@@ -1,33 +0,0 @@
 """The durable EXIF projection per asset and stage (concept §3, US07-03).
 One row per ``(asset_id, stage)``: what the stage wanted written, what the file
 looked like afterwards, and whether anything outside the stage's ownership moved.
 ``state = divergent`` is the whole point of the table — it survives restarts, keeps
 the asset out of stages that require verified metadata, and gives a human something
 to look at instead of a silent repair.
 """
 from __future__ import annotations
 from datetime import datetime
 from sqlalchemy import DateTime, ForeignKey, Integer, String
 from sqlalchemy.orm import Mapped, mapped_column
 from photo_pipeline.db import Base
 class ExifProjection(Base):
    __tablename__ = "exif_projections"
    asset_id: Mapped[str] = mapped_column(ForeignKey("assets.id"), primary_key=True)
    stage: Mapped[str] = mapped_column(String, primary_key=True)  # safety | analysis
    id: Mapped[str] = mapped_column(String, nullable=False)
    projection_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
    desired_json: Mapped[str | None] = mapped_column(String)
    divergent_fields: Mapped[str | None] = mapped_column(String)  # JSON array
    result_file_sha256: Mapped[str | None] = mapped_column(String)
    state: Mapped[str] = mapped_column(String, nullable=False)  # verified|divergent|failed
    error_code: Mapped[str | None] = mapped_column(String)
    verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
--- a/photo_pipeline/models/thumbnails.py
+++ b/photo_pipeline/models/thumbnails.py
@@ -11,7 +11,7 @@ from __future__ import annotations
 from datetime import datetime
-from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, func
+from sqlalchemy import DateTime, ForeignKey, Integer, String, func
 from sqlalchemy.orm import Mapped, mapped_column
 from photo_pipeline.db import Base
@@ -29,9 +29,6 @@ class Thumbnail(Base):
    width: Mapped[int | None] = mapped_column(Integer)
    height: Mapped[int | None] = mapped_column(Integer)
    format: Mapped[str | None] = mapped_column(String)
    # Durable comparison evidence for an archived asset: never evicted by the LRU
    # quota, because the original may be on a medium that is no longer reachable.
    protected: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
--- a/photo_pipeline/path_policy.py
+++ b/photo_pipeline/path_policy.py
@@ -49,29 +49,6 @@ def resolve_within(root: Path, path: os.PathLike | str) -> Path:
    return resolved
 def resolve_in_roots(roots: Iterable[os.PathLike | str], path: os.PathLike | str) -> Path:
    """The resolved path, proven to be inside one of ``roots`` and not excluded.
    Callers must use the **returned** path for whatever they do next: validating one
    name and then opening another is the symlink race this exists to close (US07-02).
    The message names no path — it reaches API responses.
    With no roots configured there is no boundary to check; that is a property of the
    configuration, not permission granted to this call.
    """
    if is_excluded(path):
        raise PathPolicyError("path is inside an excluded (_IGNORE/) tree")
    roots = list(roots)
    if not roots:
        return Path(path)
    for root in roots:
        try:
            return resolve_within(Path(root), path)
        except PathPolicyError:
            continue
    raise PathPolicyError("path is outside the configured library roots")
 def iter_supported_files(root: os.PathLike | str) -> Iterator[Path]:
    """Yield supported, non-excluded files under ``root`` in deterministic order.
--- a/photo_pipeline/services/analysis.py
+++ b/photo_pipeline/services/analysis.py
@@ -18,16 +18,17 @@ from __future__ import annotations
 import json
 import os
 import uuid
 from datetime import datetime, timezone
 from typing import Protocol
 from sqlalchemy import func, select
 from sqlalchemy.orm import sessionmaker
-from photo_pipeline import path_policy
+from photo_pipeline.integrations import exiftool
-from photo_pipeline.models import AnalysisResult, Asset
+from photo_pipeline.models import AnalysisResult, Asset, SafetyReview
-from photo_pipeline.services import exif_checkpoint
+from photo_pipeline.services import hashing
-from photo_pipeline.services.safety import SFW, latest_reviews
+from photo_pipeline.services.safety import SFW
 MODEL = "gemini-2.5-flash"
 PROMPT_VERSION = "1"
@@ -58,44 +59,17 @@ def _now() -> datetime:
 class AnalysisService:
-    def __init__(
+    def __init__(self, session_factory: sessionmaker, *, provider: VisionProvider | None = None) -> None:
        self,
        session_factory: sessionmaker,
        *,
        provider: VisionProvider | None = None,
        library_roots: tuple = (),
    ) -> None:
        self._session_factory = session_factory
        self._provider = provider
        self._roots = tuple(library_roots)
    def _sfw_asset_ids(self, session) -> set[str]:
        """Asset ids whose latest safety decision is ``sfw`` — the ONLY assets that
-        may reach the provider.
+        may reach the provider."""
-
+        latest: dict[str, str | None] = {}
-        The "latest row wins" rule is applied in SQL (US07-06); loading every review
+        for review in session.scalars(select(SafetyReview).order_by(SafetyReview.created_at)):
-        to fold it in Python made the gate cost grow with the review history rather
+            latest[review.asset_id] = review.decision
-        than with the work being gated.
+        return {aid for aid, decision in latest.items() if decision == SFW}
        """
        latest = latest_reviews().subquery()
        return set(
            session.scalars(select(latest.c.asset_id).where(latest.c.decision == SFW))
        )
    def _sfw_count(self, session) -> int:
        """How many assets the gate currently allows, without listing them."""
        latest = latest_reviews().subquery()
        return int(
            session.scalar(
                select(func.count()).select_from(latest).where(latest.c.decision == SFW)
            )
            or 0
        )
    def _is_still_sfw(self, asset_id: str) -> bool:
        """Re-read the current safety decision straight from the database."""
        with self._session_factory() as session:
            return asset_id in self._sfw_asset_ids(session)
    def eligible_asset_ids(self) -> list[str]:
        """Confirmed-SFW canonical active assets without a completed analysis."""
@@ -118,12 +92,9 @@ class AnalysisService:
            )
            return [a.id for a in assets if a.id not in done]
-    def counts(self, *, eligible: int | None = None) -> dict[str, int]:
+    def counts(self) -> dict[str, int]:
        """Analysis progress. ``eligible`` may be passed by a caller that has just
        counted confirmed-SFW assets, so the workflow home does not resolve the
        latest decision of every asset twice on one page load (US07-06)."""
        with self._session_factory() as session:
-            eligible = self._sfw_count(session) if eligible is None else eligible
+            sfw = self._sfw_asset_ids(session)
            rows = dict(
                session.execute(
                    select(AnalysisResult.status, func.count()).group_by(AnalysisResult.status)
@@ -132,10 +103,10 @@ class AnalysisService:
            analyzed = int(rows.get("analyzed", 0))
            errored = int(rows.get("error", 0))
            return {
-                "eligible": eligible,
+                "eligible": len(sfw),
                "analyzed": analyzed,
                "error": errored,
-                "pending": max(eligible - analyzed - errored, 0),
+                "pending": max(len(sfw) - analyzed - errored, 0),
            }
    def run(self, asset_ids: list[str] | None = None) -> dict:
@@ -165,40 +136,12 @@ class AnalysisService:
            if not path:
                skipped += 1
                continue
            # Second gate, at the moment of use: the database says where the file
            # was, the filesystem decides what that name means now. A link swapped
            # under an asset after the scan would otherwise send bytes from outside
            # the library — the one place that leaves this machine (US07-02).
            try:
                path = str(path_policy.resolve_in_roots(self._roots, path))
            except path_policy.PathPolicyError as error:
                self._store(
                    asset_id, status="error", result=None, error=str(error), tokens=0, raw=""
                )
                errors += 1
                continue
            try:
                result = provider.analyze(path, album_hint=_album_hint(path))
            except Exception as error:  # provider/validation failure is per-asset
                self._store(asset_id, status="error", result=None, error=str(error), tokens=0, raw="")
                errors += 1
                continue
            # Third gate, after the call: a provider request takes seconds, and the
            # reviewer may have flipped this asset to NSFW while it was in flight.
            # The result describes an asset that is no longer analysable, so it is
            # discarded — not stored, and above all not written into its EXIF
            # (concept §18 scenario 7, US07-04).
            if not self._is_still_sfw(asset_id):
                self._store(
                    asset_id,
                    status="skipped_nsfw",
                    result=None,
                    error="the safety decision changed while analysis was in flight",
                    tokens=0,
                    raw="",
                )
                skipped += 1
                continue
            self._store(
                asset_id,
                status="analyzed",
@@ -207,7 +150,7 @@ class AnalysisService:
                tokens=int(result.get("_tokens", 0)) if isinstance(result, dict) else 0,
                raw=json.dumps(result, ensure_ascii=False),
            )
-            self._write_analysis_exif(asset_id, path, result)
+            _write_analysis_exif(path, result)
            analyzed += 1
        return {"analyzed": analyzed, "skipped": skipped, "errors": errors}
@@ -232,45 +175,10 @@ class AnalysisService:
                row.location_hint = result.get("location_hint")
                row.approx_year = result.get("approx_year")
                row.analyzed_at = now
                row.exif_written_at = now
            session.add(row)
            session.commit()
    def _write_analysis_exif(self, asset_id: str, path: str, result: dict) -> None:
        """The analysis EXIF checkpoint: additive keywords, then prove the rest held.
        Additive by design — safety keywords and the user's own keywords are merged
        with, never replaced (concept §3). ``exif_written_at`` is set only when the
        read-back verified both the new keywords and every field this stage does not
        own; a divergent result is recorded and left for a human (US07-03).
        ponytail: the managed ``AI:`` caption segment, once captions are owned here.
        """
        tags = tuple(str(tag) for tag in (result.get("tags") or []))
        if not tags:
            return
        checkpoint = exif_checkpoint.run(path, add=tags)
        exif_checkpoint.record(
            self._session_factory,
            asset_id=asset_id,
            stage="analysis",
            result=checkpoint,
            add=tags,
        )
        if not checkpoint.verified:
            return
        with self._session_factory() as session:
            row = session.get(AnalysisResult, asset_id)
            if row is not None:
                row.exif_written_at = checkpoint.verified_at
            asset = session.get(Asset, asset_id)
            if asset is not None and checkpoint.sha256:
                # The bytes changed when the container was rewritten; upload must use
                # the hash of what is actually on disk now (concept §3), and the
                # recorded size has to move with it (US07-07).
                asset.current_sha256 = checkpoint.sha256
                if checkpoint.byte_size is not None:
                    asset.byte_size = checkpoint.byte_size
            session.commit()
    def get(self, asset_id: str) -> dict | None:
        with self._session_factory() as session:
            row = session.get(AnalysisResult, asset_id)
@@ -283,6 +191,17 @@ def _album_hint(path: str) -> str:
    return Path(path).parent.name
 def _write_analysis_exif(path: str, result: dict) -> None:
    """Additive analysis keywords into EXIF (Keywords/Subject), preserving safety
    and user keywords. The donor also wrote a managed caption; only keywords are
    written here via the shared adapter.
    ponytail: add the managed ``AI:`` caption segment + read-back preservation check
    when the analysis EXIF checkpoint is hardened."""
    tags = result.get("tags") if isinstance(result, dict) else None
    if tags:
        exiftool.apply_keywords(path, add=[str(t) for t in tags])
 def _result_dict(row: AnalysisResult) -> dict:
    data = {field: getattr(row, field) for field in RESULT_FIELDS}
    data["tags"] = json.loads(row.tags) if row.tags else []
--- a/photo_pipeline/services/app_lock.py
+++ b/photo_pipeline/services/app_lock.py
@@ -1,221 +0,0 @@
 """Library-level process lock, and detection of an incompatible legacy run
 (US07-05, concept §15 "migration and operational risks").
 Every safety this application has — durable job leases, rename journals, archive
 manifests — assumes that one installation owns the library. Two workers, or the
 frozen CLI running beside the app, break that assumption *below* the level those
 mechanisms can see: the second process simply does not know the first one's
 database exists.
 So mutation requires a file lock in the data directory, shaped as JSON so any
 future or migrated entry point can read and honour it without importing this
 package:
    {"lock_version": 1, "role": "worker", "pid": 4242, "host": "...",
     "started_at": "...", "library_roots": ["..."]}
 One holder per role: an API and a worker are designed to run together, a second
 worker is not. A lock whose process is gone is stale and is taken over with the
 takeover recorded — refusing to start because of a crashed predecessor would turn
 one outage into two.
 Legacy detection is deliberately a heuristic, not a promise: the archived CLI has
 no lock of its own, so what can be observed is its state files being written right
 now. Recent writes to them mean something else is mutating this library, and every
 mutating stage should refuse until it stops.
 """
 from __future__ import annotations
 import json
 import os
 import socket
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from photo_pipeline.config import Config
 LOCK_VERSION = 1
 LOCK_SUFFIX = ".lock.json"
 # State files only the archived CLIs write. Their presence is history; a *recent*
 # modification is a running process.
 # ponytail: the real fix is a lock the migrated CLI paths take too — this catches
 # the frozen archive, which has no lock and cannot be changed (US07-01).
 LEGACY_ARTIFACTS = (
    "photo_analyzer.db",
    "nsfw_scores.csv",
    "photo_analyzer_history.jsonl",
    "photo_analyzer.log",
    "photo_analyzer_debug.log",
 )
 LEGACY_ACTIVE_SECONDS = 300
 class LockHeld(RuntimeError):
    """Another live process of the same role owns this library."""
    def __init__(self, holder: "Holder") -> None:
        super().__init__(
            f"{holder.role} is already running for this library "
            f"(pid {holder.pid} on {holder.host}, since {holder.started_at})"
        )
        self.holder = holder
 class LegacyProcessActive(RuntimeError):
    """A legacy CLI appears to be mutating the same library right now."""
@dataclass(frozen=True)
 class Holder:
    role: str
    pid: int
    host: str
    started_at: str
    lock_version: int = LOCK_VERSION
    library_roots: tuple[str, ...] = ()
    @property
    def alive(self) -> bool:
        """Whether the recorded process still exists on this host.
        A lock from another host cannot be probed, so it is believed: assuming a
        remote holder is dead is how two machines end up renaming the same folder.
        """
        if self.host != socket.gethostname():
            return True
        try:
            os.kill(self.pid, 0)
        except ProcessLookupError:
            return False
        except PermissionError:
            return True  # exists, owned by someone else
        return True
    def as_dict(self) -> dict:
        return {
            "lock_version": self.lock_version,
            "role": self.role,
            "pid": self.pid,
            "host": self.host,
            "started_at": self.started_at,
            "library_roots": list(self.library_roots),
            "alive": self.alive,
        }
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def legacy_activity(config: Config) -> dict:
    """Legacy state files written within the activity window, if any."""
    seen: list[dict] = []
    cutoff = _now().timestamp() - LEGACY_ACTIVE_SECONDS
    roots = [Path(root) for root in config.library_roots] + [Path(config.data_dir)]
    for root in roots:
        for name in LEGACY_ARTIFACTS:
            path = root / name
            try:
                modified = path.stat().st_mtime
            except OSError:
                continue
            if modified >= cutoff:
                seen.append(
                    {
                        "path": str(path),
                        "modified_at": datetime.fromtimestamp(modified, timezone.utc).isoformat(),
                    }
                )
    return {"active": bool(seen), "artifacts": seen, "window_seconds": LEGACY_ACTIVE_SECONDS}
 class LibraryLock:
    """One holder per role for one library. Used as a context manager."""
    def __init__(self, config: Config, role: str = "worker") -> None:
        self._config = config
        self.role = role
        self.path = Path(config.data_dir) / f"{role}{LOCK_SUFFIX}"
        self._acquired = False
    # ── inspection ────────────────────────────────────────────────────────────
    def holder(self) -> Holder | None:
        try:
            payload = json.loads(self.path.read_text())
        except (OSError, ValueError):
            return None
        try:
            return Holder(
                role=payload["role"],
                pid=int(payload["pid"]),
                host=payload["host"],
                started_at=payload["started_at"],
                lock_version=int(payload.get("lock_version", LOCK_VERSION)),
                library_roots=tuple(payload.get("library_roots", ())),
            )
        except (KeyError, TypeError, ValueError):
            # An unreadable lock is not an absent lock: something wrote it.
            return Holder(role=self.role, pid=-1, host="unknown", started_at="unknown")
    # ── acquire / release ─────────────────────────────────────────────────────
    def acquire(self, *, allow_legacy: bool = False) -> Holder:
        """Take the lock for this role, or explain who has it.
        Raises ``LockHeld`` when a live process of the same role owns the library,
        and ``LegacyProcessActive`` when the archived CLI looks like it is running
        against it.
        """
        if not allow_legacy:
            legacy = legacy_activity(self._config)
            if legacy["active"]:
                raise LegacyProcessActive(
                    "a legacy CLI is writing this library "
                    f"({', '.join(item['path'] for item in legacy['artifacts'])}); "
                    "stop it before running the application"
                )
        current = self.holder()
        if current is not None:
            if current.alive:
                raise LockHeld(current)
            # Stale: its process is gone. Take over, and say so.
            self.path.unlink(missing_ok=True)
        mine = Holder(
            role=self.role,
            pid=os.getpid(),
            host=socket.gethostname(),
            started_at=_now().isoformat(),
            library_roots=tuple(str(root) for root in self._config.library_roots),
        )
        self.path.parent.mkdir(parents=True, exist_ok=True)
        payload = {k: v for k, v in mine.as_dict().items() if k != "alive"}
        # Exclusive create, so two processes racing here cannot both believe they won.
        try:
            with open(self.path, "x", encoding="utf-8") as handle:
                json.dump(payload, handle, indent=2)
        except FileExistsError:
            winner = self.holder()
            raise LockHeld(winner or mine) from None
        self._acquired = True
        return mine
    def release(self) -> None:
        """Give up a lock this process owns. Another holder's lock is left alone."""
        if not self._acquired:
            return
        current = self.holder()
        if current is not None and current.pid == os.getpid():
            self.path.unlink(missing_ok=True)
        self._acquired = False
    def __enter__(self) -> "LibraryLock":
        self.acquire()
        return self
    def __exit__(self, *_) -> None:
        self.release()
--- a/photo_pipeline/services/archive_journal.py
+++ b/photo_pipeline/services/archive_journal.py
@@ -15,11 +15,6 @@ planned → transferring → verified → removing → complete
              ↘             ↘          ↘ failed
 ```
 A restore (US06-04) uses the same rows with ``direction='restore'``: it copies from
 the medium back into the library and removes nothing, so it goes ``verified →
 complete`` directly. ``source_path``/``destination_path`` always mean "from"/"to",
 which is why the evidence table below needs no direction of its own.
 - ``transferring`` — intent recorded; a temporary copy may exist, the destination
  may or may not have been published. Nothing has been removed.
 - ``verified``     — the archived bytes exist at their final path, hash exactly as
@@ -78,22 +73,10 @@ ALLOWED_TRANSITIONS = {
    ArchiveState.FAILED: {ArchiveState.PLANNED, ArchiveState.TRANSFERRING},
 }
 # A restore removes nothing, so it has no ``removing`` step: a verified published
 # copy is the whole job (US06-04). Keeping this as a separate table means the
 # archive direction still cannot reach ``complete`` without going through removal.
 RESTORE_TRANSITIONS = {
    **ALLOWED_TRANSITIONS,
    ArchiveState.VERIFIED: {ArchiveState.COMPLETE, ArchiveState.FAILED},
 }
 TERMINAL_STATES = frozenset({ArchiveState.COMPLETE})
 # States where this item may already have touched the filesystem.
 UNSAFE_STATES = frozenset({ArchiveState.TRANSFERRING, ArchiveState.VERIFIED, ArchiveState.REMOVING})
 # Which way the bytes move. Same rows, same evidence table, opposite direction.
 ARCHIVE = "archive"
 RESTORE = "restore"
 RESUMABLE = "resumable"
 FORWARD = "forward"
 MANUAL = "manual"
@@ -111,9 +94,8 @@ class JournalConflict(JournalError):
    """Fencing check failed; a newer owner has taken over this operation."""
-def can_transition(current: str, target: str, direction: str = ARCHIVE) -> bool:
+def can_transition(current: str, target: str) -> bool:
-    table = RESTORE_TRANSITIONS if direction == RESTORE else ALLOWED_TRANSITIONS
+    return target in ALLOWED_TRANSITIONS.get(current, set())
    return target in table.get(current, set())
 def _now() -> datetime:
@@ -137,7 +119,7 @@ class ArchiveJournal:
            if row.journal_state in TERMINAL_STATES:
                raise InvalidTransition(f"{row.journal_state} is terminal")
            if row.journal_state != ArchiveState.TRANSFERRING and not can_transition(
-                row.journal_state, ArchiveState.TRANSFERRING, row.direction
+                row.journal_state, ArchiveState.TRANSFERRING
            ):
                raise InvalidTransition(f"{row.journal_state} -> {ArchiveState.TRANSFERRING}")
            if row.journal_state != ArchiveState.TRANSFERRING:
@@ -178,7 +160,7 @@ class ArchiveJournal:
            if row.journal_state == target:
                session.commit()
                return _operation_dict(row)  # idempotent
-            if not can_transition(row.journal_state, target, row.direction):
+            if not can_transition(row.journal_state, target):
                raise InvalidTransition(f"{row.journal_state} -> {target}")
            row.journal_state = target
@@ -210,18 +192,16 @@ class ArchiveJournal:
            )
            return [_operation_dict(row) for row in rows]
-    def incomplete(self, *, direction: str | None = None) -> list[dict]:
+    def incomplete(self) -> list[dict]:
        """Every operation left in a non-terminal, non-planned state — the work a
-        restart has to reason about. Without ``direction`` this spans archives and
+        restart has to reason about."""
        restores, because either one half-done blocks the other."""
        with self._session_factory() as session:
-            stmt = select(ArchiveOperation).where(
+            rows = session.scalars(
                select(ArchiveOperation)
                .where(
                    ArchiveOperation.journal_state.not_in([*TERMINAL_STATES, ArchiveState.PLANNED])
                )
-            if direction is not None:
+                .order_by(ArchiveOperation.plan_id, ArchiveOperation.sequence)
                stmt = stmt.where(ArchiveOperation.direction == direction)
            rows = session.scalars(
                stmt.order_by(ArchiveOperation.plan_id, ArchiveOperation.sequence)
            )
            return [_operation_dict(row) for row in rows]
@@ -251,7 +231,6 @@ class ArchiveJournal:
        return {
            "operation_id": operation_id,
            "plan_id": row["plan_id"],
            "direction": row["direction"],
            "album": row["album"],
            "asset_id": row["asset_id"],
            "source_path": row["source_path"],
@@ -264,8 +243,8 @@ class ArchiveJournal:
            "destination_matches": destination_matches,
        }
-    def classify_all(self, *, direction: str | None = None) -> list[dict]:
+    def classify_all(self) -> list[dict]:
-        return [self.classify(row["id"]) for row in self.incomplete(direction=direction)]
+        return [self.classify(row["id"]) for row in self.incomplete()]
    def blocks_mutation(self) -> bool:
        """True when any item may have the library half-archived."""
@@ -338,7 +317,6 @@ def _operation_dict(row: ArchiveOperation) -> dict:
    return {
        "id": row.id,
        "plan_id": row.plan_id,
        "direction": row.direction,
        "sequence": row.sequence,
        "album": row.album,
        "asset_id": row.asset_id,
--- a/photo_pipeline/services/archive_transfer.py
+++ b/photo_pipeline/services/archive_transfer.py
@@ -52,20 +52,16 @@ from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.config import Config
 from photo_pipeline.faults import maybe_fault
 from photo_pipeline.models import ArchiveLocation, ArchiveOperation, ArchivePlan, Asset, AssetPath
 from photo_pipeline.services.archive_journal import (
    ARCHIVE,
    MANUAL,
    RESUMABLE,
    ArchiveJournal,
    ArchiveState,
 )
 from photo_pipeline.services.archives import MARKER_NAME, ArchiveError, ArchiveService
 from photo_pipeline.services.duplicates import DuplicateService
 from photo_pipeline.services.hashing import sha256_file
-from photo_pipeline.services.rename_apply import PreconditionFailed
+from photo_pipeline.services.rename_apply import PreconditionFailed, maybe_fault
 from photo_pipeline.services.thumbnails import ThumbnailService
 # The per-medium manifest: one JSON line per archived file, appended and fsynced
 # before its source is removed. It lives with the bytes so the archive can still be
@@ -117,7 +113,6 @@ class ArchiveTransferService:
                    location_id=location_id,
                    token=token,
                    albums=json.dumps(albums) if albums is not None else None,
                    direction=ARCHIVE,
                    state="planned",
                    schema_version=MANIFEST_VERSION,
                    asset_count=preflight["totals"]["assets"],
@@ -135,7 +130,6 @@ class ArchiveTransferService:
                        ArchiveOperation(
                            id=str(uuid.uuid4()),
                            plan_id=plan_id,
                            direction=ARCHIVE,
                            sequence=sequence,
                            album=album["album"],
                            asset_id=asset["asset_id"],
@@ -165,11 +159,7 @@ class ArchiveTransferService:
    def list(self) -> list[dict]:
        with self._session_factory() as session:
-            rows = session.scalars(
+            rows = session.scalars(select(ArchivePlan).order_by(ArchivePlan.created_at))
                select(ArchivePlan)
                .where(ArchivePlan.direction == ARCHIVE)
                .order_by(ArchivePlan.created_at)
            )
            return [_plan_dict(row) for row in rows]
    # ── apply ─────────────────────────────────────────────────────────────────
@@ -270,7 +260,7 @@ class ArchiveTransferService:
        if same_filesystem:
            os.rename(source, destination)
        else:
-            copy_verify_publish(source, destination, operation["expected_sha256"])
+            self._copy_and_publish(operation, source, destination)
        _fsync_dir(destination.parent)
        # 4. The published file is the archive only once it hashes as recorded.
@@ -290,6 +280,27 @@ class ArchiveTransferService:
        # 5. Only now may the active source go.
        self._finish(self.journal.get(operation["id"]), location, token=token, worker_id=worker_id)
    def _copy_and_publish(self, operation: dict, source: Path, destination: Path) -> None:
        """Cross-filesystem: copy to a temporary file beside the destination, prove
        its bytes, then publish it atomically. The source is still untouched."""
        temp = destination.with_name(f"{TEMP_PREFIX}{uuid.uuid4().hex}{TEMP_SUFFIX}")
        try:
            with open(source, "rb") as src, open(temp, "wb") as out:
                shutil.copyfileobj(src, out, 1024 * 1024)
                out.flush()
                os.fsync(out.fileno())
            if sha256_file(temp) != operation["expected_sha256"]:
                raise PreconditionFailed("copy_mismatch", f"{source} copied with wrong bytes")
            if destination.exists():
                raise PreconditionFailed(
                    "destination_exists", f"{destination} appeared during the transfer"
                )
            # ponytail: rename after an exists() check. The archiver lane is single
            # and local; use O_EXCL/link-based publish if a second writer ever exists.
            os.rename(temp, destination)
        finally:
            temp.unlink(missing_ok=True)
    def _finish(self, operation: dict, location: dict, *, token: int, worker_id: str) -> None:
        """Drive an item whose archive copy is durable through removal and
        bookkeeping. Every step is idempotent, so recovery may replay it."""
@@ -324,7 +335,6 @@ class ArchiveTransferService:
                raise PreconditionFailed(
                    "archive_unverified", f"{destination} is not a verified archive copy"
                )
            self._require_evidence(operation["asset_id"], destination)
            if source.exists():
                if source.is_symlink():
                    raise PreconditionFailed("symlink", f"{source} became a symlink")
@@ -367,28 +377,6 @@ class ArchiveTransferService:
                    "asset_moved", f"asset {operation['asset_id']} is no longer at {source}"
                )
    def _require_evidence(self, asset_id: str, source: Path) -> dict:
        """Review evidence must be durable before the original goes.
        The perceptual hash keeps the asset in the fuzzy index once its bytes are
        unreachable, and the protected preview is what duplicate review can still
        look at. Both are read from the freshly verified archive copy, which holds
        exactly the bytes being archived. A file that cannot be decoded has neither
        — recorded, not fatal, since its exact hashes remain — but failing to
        produce a preview from a decodable original stops the removal (concept §9).
        """
        DuplicateService(self._session_factory).ensure_phash(asset_id, source=source)
        preview = ThumbnailService(self._session_factory, self._config).ensure_protected(
            asset_id, source=source
        )
        if preview["state"] == "unavailable":
            raise PreconditionFailed(
                "preview_unavailable",
                f"no durable comparison preview for asset {asset_id} "
                f"({preview['error_code']})",
            )
        return preview
    # ── database ──────────────────────────────────────────────────────────────
    def _record_archived(self, operation: dict, location: dict, destination: Path) -> None:
@@ -444,7 +432,7 @@ class ArchiveTransferService:
        """
        results = {"resumed": 0, "completed": 0, "manual": 0}
        touched: set[str] = set()
-        for verdict in self.journal.classify_all(direction=ARCHIVE):
+        for verdict in self.journal.classify_all():
            operation = self.journal.get(verdict["operation_id"])
            touched.add(operation["plan_id"])
            token = (operation["fencing_token"] or 0) + 1
@@ -471,7 +459,7 @@ class ArchiveTransferService:
        return results
    def recovery_status(self) -> dict:
-        verdicts = self.journal.classify_all(direction=ARCHIVE)
+        verdicts = self.journal.classify_all()
        return {
            "operations": verdicts,
            "manual": [v for v in verdicts if v["classification"] == MANUAL],
@@ -515,33 +503,6 @@ class ArchiveTransferService:
 # ── module helpers ───────────────────────────────────────────────────────────
 def copy_verify_publish(source: Path, destination: Path, expected_sha256: str) -> None:
    """Copy to a temporary file beside the destination, prove its bytes, then publish
    it atomically. The source is never touched, so a failure costs nothing.
    Shared by archiving (library → medium) and restoring (medium → library, US06-04):
    both need the same promise that a published file is either complete and correct
    or not there at all.
    """
    temp = destination.with_name(f"{TEMP_PREFIX}{uuid.uuid4().hex}{TEMP_SUFFIX}")
    try:
        with open(source, "rb") as src, open(temp, "wb") as out:
            shutil.copyfileobj(src, out, 1024 * 1024)
            out.flush()
            os.fsync(out.fileno())
        if sha256_file(temp) != expected_sha256:
            raise PreconditionFailed("copy_mismatch", f"{source} copied with wrong bytes")
        if destination.exists():
            raise PreconditionFailed(
                "destination_exists", f"{destination} appeared during the transfer"
            )
        # ponytail: rename after an exists() check. The archiver lane is single and
        # local; use O_EXCL/link-based publish if a second writer ever exists.
        os.rename(temp, destination)
    finally:
        temp.unlink(missing_ok=True)
 def _same_filesystem(source: Path, destination_dir: Path) -> bool:
    """Proven at run time from the actual devices, never from the plan's preview."""
    try:
@@ -632,7 +593,6 @@ def _plan_dict(plan: ArchivePlan) -> dict:
        "id": plan.id,
        "location_id": plan.location_id,
        "token": plan.token,
        "direction": plan.direction,
        "albums": json.loads(plan.albums) if plan.albums else None,
        "state": plan.state,
        "schema_version": plan.schema_version,
--- a/photo_pipeline/services/archives.py
+++ b/photo_pipeline/services/archives.py
@@ -28,11 +28,7 @@ Blocker codes: ``no_library_root``, ``location_offline``, ``wrong_volume``,
 ``unsafe_destination``, ``destination_not_writable``, ``manifest_unwritable``,
 ``insufficient_capacity``, ``backup_unavailable``, ``lock_conflict``,
 ``rename_pending``, ``empty_scope``, ``destination_collision``,
-``upload_unverified``, ``bytes_changed``, ``file_missing``, ``preview_unavailable``.
+``upload_unverified``, ``bytes_changed``, ``file_missing``.
 Preflight also *creates* the durable comparison preview of every asset in scope
 (US06-03): it is the evidence duplicate review falls back on once the original is
 on a medium that may be offline, so it has to exist before the original leaves.
 Like upload preflight, the confirmation token is *derived* from the report rather
 than stored: any change to the scope, the bytes, the destination, or the blockers
@@ -63,16 +59,14 @@ from photo_pipeline.models import ArchiveLocation, Asset, UploadBatch, UploadIte
 from photo_pipeline.path_policy import PathPolicyError, is_excluded, normalize_root, resolve_within
 from photo_pipeline.services.albums import album_label
 from photo_pipeline.services.archive_journal import ArchiveJournal
 from photo_pipeline.services.availability import MARKER_NAME, read_marker as _read_marker
 from photo_pipeline.services.availability import refresh as refresh_availability
 from photo_pipeline.services.hashing import sha256_file
 from photo_pipeline.services.jobs import JobService
 from photo_pipeline.services.rename_journal import RenameJournal
 from photo_pipeline.services.thumbnails import ThumbnailService
 from photo_pipeline.services.upload_reports import VERIFIED
 PREFLIGHT_VERSION = 1
 TOKEN_PREFIX = f"v{PREFLIGHT_VERSION}"
 MARKER_NAME = ".photo-pipeline-archive.json"
 MANIFEST_NAME = "archive-manifest.json"
 # Upload outcomes that prove Immich holds these exact bytes. ``skipped``/``failed``/
@@ -169,9 +163,6 @@ class ArchiveService:
                    location.capabilities = json.dumps(probe["capabilities"])
                reports.append(self._location_report(location, probe=probe))
            session.commit()
        # A medium that just appeared or vanished changes what is readable, so the
        # archived assets are re-derived from the same probe (US06-03).
        refresh_availability(self._session_factory)
            return reports
    # ── preflight ─────────────────────────────────────────────────────────────
@@ -208,12 +199,9 @@ class ArchiveService:
            report["blockers"].append(
                _issue(
                    "insufficient_capacity",
                    # The free-space number is deliberately left out: it drifts between
                    # two identical preflights, and the token is a digest of this text,
                    # so quoting it here would invalidate every approval instantly.
                    f"{report['totals']['bytes']} B plus a "
-                    f"{self._config.archive_free_space_reserve_bytes} B reserve do not fit on "
+                    f"{self._config.archive_free_space_reserve_bytes} B reserve do not fit in "
-                    "the medium",
+                    f"{report['capacity']['free_bytes']} B of free space",
                )
            )
        report["backup"] = self._backup_probe()
@@ -432,10 +420,7 @@ class ArchiveService:
    def _album(self, name: str, rows: list[dict], root: Path, *, reachable: bool) -> dict:
        folder = Path(rows[0]["path"]).parent
-        items = sorted(
+        items = sorted((_item(row) for row in rows), key=lambda item: item["current_path"])
            (self._with_preview(_item(row)) for row in rows),
            key=lambda item: item["current_path"],
        )
        blocked = [item for item in items if item["blockers"]]
        blockers: list[dict] = []
@@ -471,30 +456,6 @@ class ArchiveService:
            "assets": items,
        }
    def _with_preview(self, item: dict) -> dict:
        """Create the durable comparison preview while the original is still here.
        This is the last moment it can be made: once the file is archived and the
        medium leaves, only the retained preview can answer "is this new photo the
        same picture?". An original that cannot be decoded at all has no preview to
        keep — its hashes and metadata stay the evidence — but a preview that fails
        for any other reason blocks the archive (concept §9).
        """
        preview = self._previews().ensure_protected(item["asset_id"])
        item["preview"] = preview
        if preview["state"] == "unavailable" and not item["blockers"]:
            item["blockers"].append(
                _issue(
                    "preview_unavailable",
                    f"a durable comparison preview of {item['current_path']} could not be "
                    f"created ({preview['error_code']})",
                )
            )
        return item
    def _previews(self) -> ThumbnailService:
        return ThumbnailService(self._session_factory, self._config)
 # ── internals ────────────────────────────────────────────────────────────────
@@ -551,6 +512,13 @@ def _transfer_method(folder: Path, root: Path) -> str:
    return "copy_verify_remove"
 def _read_marker(root: Path) -> dict | None:
    try:
        return json.loads((root / MARKER_NAME).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return None
 def _probe_write(path: Path, payload: bytes, *, keep: bool = False) -> str | None:
    """Write ``payload`` to ``path``; return the failure detail or ``None``."""
    try:
--- a/photo_pipeline/services/availability.py
+++ b/photo_pipeline/services/availability.py
@@ -1,124 +0,0 @@
 """Where an asset's bytes are right now (US06-03).
 Archiving removes the original from the active library but never removes the
 asset: its identity, hashes, decisions, and evidence stay. This module is the one
 place that answers "can these bytes be read, and if not, why" so inventory,
 duplicate review, thumbnails, and the archive service all give the same answer.
 States (concept §9):
 - ``active``             — the original is in the active library;
 - ``archived_online``    — the recorded medium is mounted and holds the file;
 - ``archived_offline``   — archived, but the medium is not available right now;
 - ``missing_unexpected`` — neither an active path nor the recorded archive
  location explains the absence. This is the state that must never be confused
  with ``archived_offline``: an unmounted disk is normal, a mounted disk with a
  hole in it is not.
 A medium is identified by its marker file, never by its mountpoint, so a
 different disk mounted at the recorded root is offline rather than accepted.
 """
 from __future__ import annotations
 import json
 from collections import Counter
 from datetime import datetime, timezone
 from pathlib import Path
 from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 from photo_pipeline.models import ArchiveLocation, Asset
 ACTIVE = "active"
 ARCHIVED_ONLINE = "archived_online"
 ARCHIVED_OFFLINE = "archived_offline"
 MISSING_UNEXPECTED = "missing_unexpected"
 ARCHIVED = (ARCHIVED_ONLINE, ARCHIVED_OFFLINE)
 MARKER_NAME = ".photo-pipeline-archive.json"
 def read_marker(root: Path) -> dict | None:
    """The medium's identity marker, or ``None`` when it is not readable."""
    try:
        return json.loads((root / MARKER_NAME).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return None
 def location_online(location: ArchiveLocation) -> bool:
    """True only when the *recorded* medium is mounted at its root."""
    marker = read_marker(Path(location.root))
    return bool(marker) and marker.get("media_id") == location.media_id
 def archive_file(session: Session, asset: Asset) -> Path | None:
    """The archived file's absolute path, whether or not the medium is mounted."""
    if not asset.archive_location_id or not asset.archive_path:
        return None
    location = session.get(ArchiveLocation, asset.archive_location_id)
    if location is None:
        return None
    return Path(location.root) / asset.archive_path
 def readable_path(session: Session, asset: Asset) -> Path | None:
    """A path whose bytes can be read now: the active file, else the archive copy."""
    if asset.current_path and Path(asset.current_path).exists():
        return Path(asset.current_path)
    archived = archive_file(session, asset)
    if archived is None:
        return None
    location = session.get(ArchiveLocation, asset.archive_location_id)
    if not location_online(location) or not archived.exists():
        return None
    return archived
 def state_of(session: Session, asset: Asset, *, online: dict[str, bool] | None = None) -> str:
    """The availability this asset's storage actually justifies right now."""
    if asset.current_path:
        return ACTIVE if Path(asset.current_path).exists() else MISSING_UNEXPECTED
    if not asset.archive_location_id:
        return MISSING_UNEXPECTED if asset.availability_state != ACTIVE else ACTIVE
    location = session.get(ArchiveLocation, asset.archive_location_id)
    if location is None:
        return MISSING_UNEXPECTED
    reachable = (
        online[location.id] if online and location.id in online else location_online(location)
    )
    if not reachable:
        return ARCHIVED_OFFLINE
    archived = archive_file(session, asset)
    # The medium is mounted and identified: the file is either there, or it is
    # genuinely gone — that is not "offline", it needs a human.
    return ARCHIVED_ONLINE if archived and archived.exists() else MISSING_UNEXPECTED
 def refresh(session_factory: sessionmaker) -> dict[str, int]:
    """Re-derive availability for every archived asset from the media themselves.
    Only archived assets are probed: whether an *active* file is present is the
    inventory scan's job and costs one stat per library file. Each medium is
    probed once, not once per asset.
    """
    counts: Counter[str] = Counter()
    now = datetime.now(timezone.utc)
    with session_factory() as session:
        online = {
            location.id: location_online(location)
            for location in session.scalars(select(ArchiveLocation))
        }
        for asset in session.scalars(
            select(Asset).where(Asset.archive_location_id.is_not(None))
        ):
            state = state_of(session, asset, online=online)
            counts[state] += 1
            if state != asset.availability_state:
                asset.availability_state = state
                asset.state_version += 1
                asset.updated_at = now
        session.commit()
    return dict(counts)
--- a/photo_pipeline/services/backup.py
+++ b/photo_pipeline/services/backup.py
@@ -1,413 +0,0 @@
 """Online backups, verification, retention, and restore drills (US07-05).
 A backup taken by copying a live SQLite file is not a backup: with WAL enabled the
 file on disk is missing every committed page still in the write-ahead log, and a
 writer mid-transaction makes the copy inconsistent. So every backup here goes
 through SQLite's online backup API, which takes a consistent snapshot of a database
 that is still being used (concept §3).
 A backup directory holds exactly two things:
    photo_pipeline.db   the snapshot
    manifest.json       what it is, what it came from, and how to check it
 The manifest is what makes the snapshot restorable by someone who was not there
 when it was taken: the schema revision, the snapshot's SHA-256, the row counts it
 should still have, the archive locations whose media the library depends on, and
 which configuration values were set — **names and non-secret values only**. A
 secret is recorded as "configured", never as its value, so a manifest can be
 attached to a bug report.
 Restore never writes into a live installation: it refuses a target that already
 holds a database, because the one thing worse than a lost library is a half-merged
 one. The drill is documented in README ("Backup and recovery").
 """
 from __future__ import annotations
 import hashlib
 import json
 import shutil
 import sqlite3
 from contextlib import closing
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from sqlalchemy import text
 from photo_pipeline.config import Config
 from photo_pipeline.db import create_db_engine, create_session_factory
 SCHEMA_VERSION = 1
 DB_NAME = "photo_pipeline.db"
 MANIFEST_NAME = "manifest.json"
 # How many backups the retention helper keeps by default. Small on purpose: a
 # backup is a snapshot of state that is itself recoverable from the library, and
 # the disk it lives on is the same one the low-disk warning watches.
 DEFAULT_KEEP = 7
 # Tables whose row counts are worth proving after a restore. Not the whole schema —
 # these are the ones whose loss would be silent.
 COUNTED_TABLES = (
    "assets",
    "asset_paths",
    "safety_reviews",
    "analysis_results",
    "exif_projections",
    "upload_batches",
    "upload_items",
    "archive_locations",
    "archive_plans",
    "archive_operations",
    "rename_plans",
    "rename_operations",
 )
 class BackupError(RuntimeError):
    """The backup could not be created, read, verified, or restored."""
@dataclass(frozen=True)
 class VerifyResult:
    ok: bool
    issues: tuple[str, ...] = ()
    revision: str | None = None
    counts: dict | None = None
    def as_dict(self) -> dict:
        return {
            "ok": self.ok,
            "issues": list(self.issues),
            "revision": self.revision,
            "counts": self.counts,
        }
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()
 def _revision(database: Path) -> str | None:
    with closing(sqlite3.connect(database)) as connection:
        try:
            row = connection.execute("SELECT version_num FROM alembic_version").fetchone()
        except sqlite3.Error:
            return None
    return row[0] if row else None
 def _counts(database: Path) -> dict:
    counts: dict[str, int] = {}
    with closing(sqlite3.connect(database)) as connection:
        for table in COUNTED_TABLES:
            try:
                counts[table] = connection.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
            except sqlite3.Error:
                continue  # a table this revision does not have yet
    return counts
 def _integrity(database: Path) -> tuple[str, list[str]]:
    """``PRAGMA integrity_check`` plus ``foreign_key_check`` — structure and links.
    Structural soundness is not referential soundness: a database can pass
    ``integrity_check`` and still hold an upload item pointing at an asset that
    is gone.
    """
    issues: list[str] = []
    with closing(sqlite3.connect(database)) as connection:
        try:
            result = connection.execute("PRAGMA integrity_check").fetchone()[0]
            if result != "ok":
                issues.append(f"integrity_check: {result}")
            violations = connection.execute("PRAGMA foreign_key_check").fetchall()
            if violations:
                issues.append(f"foreign_key_check: {len(violations)} violation(s)")
        except sqlite3.DatabaseError as error:
            issues.append(f"unreadable: {error}")
            return "error", issues
    return "ok" if not issues else "damaged", issues
 def configuration_references(config: Config) -> dict:
    """Which configuration a restore has to reproduce — never the secrets themselves.
    Paths and URLs are recorded because a restore into a fresh root has to be told
    where the library and the Immich server were; API keys are recorded as
    ``configured`` so an operator knows one is required without the manifest ever
    carrying it.
    """
    return {
        "data_dir": str(config.data_dir),
        "database_path": str(config.database_path),
        "library_roots": [str(root) for root in config.library_roots],
        "thumbnail_cache_dir": str(config.thumbnail_cache_dir),
        "immich_server_url": config.immich_server_url,
        "immich_go_binary": config.immich_go_binary,
        "secrets": {
            "immich_api_key": "configured" if config.immich_api_key else "unset",
            "vision_api_key": "configured" if config.vision_api_key else "unset",
        },
    }
 def migrate_with_backup(config: Config) -> dict | None:
    """Upgrade the schema, with a snapshot first when there is state to lose.
    A migration is the one routine operation that can damage every record at once,
    and Alembic's own transaction does not cover SQLite DDL reliably. So a pending
    upgrade is preceded by an online backup, and a failed upgrade names it in the
    error: recovery is "restore that directory", not "reconstruct the library".
    Returns the manifest of the backup it took, or ``None`` when none was needed.
    """
    import logging
    from photo_pipeline.db import run_migrations
    service = BackupService(config)
    manifest = service.pre_migration() if service.migration_pending() else None
    try:
        run_migrations(config.database_url)
    except Exception:
        if manifest is not None:
            logging.getLogger(__name__).error(
                "migration failed; restore the pre-migration backup at %s",
                service.root / manifest["name"],
            )
        raise
    return manifest
 class BackupService:
    def __init__(self, config: Config) -> None:
        self._config = config
    @property
    def root(self) -> Path:
        return self._config.data_dir / "backups"
    # ── create ────────────────────────────────────────────────────────────────
    def create(self, *, reason: str = "manual", keep: int | None = DEFAULT_KEEP) -> dict:
        """Take an online snapshot and describe it. Returns the manifest."""
        source = self._config.database_path
        if not source.exists():
            raise BackupError(f"no database at {source}")
        stamp = _now().strftime("%Y%m%dT%H%M%SZ")
        safe_reason = "".join(c for c in reason if c.isalnum() or c in "-_") or "manual"
        directory = self.root / f"{stamp}-{safe_reason}"
        if directory.exists():  # same second, same reason
            directory = self.root / f"{stamp}-{safe_reason}-{len(list(self.root.iterdir()))}"
        directory.mkdir(parents=True)
        target = directory / DB_NAME
        try:
            with closing(sqlite3.connect(source)) as src, closing(sqlite3.connect(target)) as dst:
                src.backup(dst)  # the online backup API, not a file copy
        except (sqlite3.Error, OSError) as error:
            shutil.rmtree(directory, ignore_errors=True)
            raise BackupError(f"backup failed: {error}") from error
        state, issues = _integrity(target)
        manifest = {
            "schema_version": SCHEMA_VERSION,
            "name": directory.name,
            "created_at": _now().isoformat(),
            "reason": reason,
            "revision": _revision(target),
            "database": {
                "name": DB_NAME,
                "bytes": target.stat().st_size,
                "sha256": sha256_file(target),
                "integrity": state,
                "issues": issues,
            },
            "counts": _counts(target),
            "archive_locations": self._archive_locations(),
            "configuration": configuration_references(self._config),
            "retention": {
                "keep": keep,
                "guidance": (
                    "Keep the newest snapshot on a different disk than data_dir, and one "
                    "off-site copy per archive medium. A backup only covers the database: "
                    "the photos themselves live in the library and archive locations named "
                    "above, which need their own copies."
                ),
            },
        }
        (directory / MANIFEST_NAME).write_text(json.dumps(manifest, indent=2))
        if keep is not None:
            manifest["pruned"] = self.prune(keep=keep)
        return manifest
    def migration_pending(self) -> bool:
        """True when the database exists and is not at the revision this code wants."""
        from photo_pipeline.db import current_revision, head_revision
        if not self._config.database_path.exists():
            return False
        return current_revision(self._config.database_url) != head_revision()
    def pre_migration(self) -> dict | None:
        """Snapshot before a schema change, when there is something to lose.
        Returns ``None`` when the database does not exist yet (a fresh install has
        no state a failed migration could damage).
        """
        if not self._config.database_path.exists():
            return None
        return self.create(reason="pre-migration")
    def _archive_locations(self) -> list[dict]:
        """The media the library's archived originals live on.
        A restored database still points at these; if they are not restored too,
        the pictures are gone even though every record survived.
        """
        engine = create_db_engine(self._config.database_url)
        try:
            factory = create_session_factory(engine)
            with factory() as session:
                rows = session.execute(
                    text("SELECT id, name, root, media_id, state FROM archive_locations")
                ).mappings().all()
        except Exception:
            return []
        finally:
            engine.dispose()
        return [
            {
                "id": row["id"],
                "name": row["name"],
                "root": row["root"],
                "media_id": row["media_id"],
                "last_state": row["state"],
                "mounted": Path(row["root"]).is_dir(),
            }
            for row in rows
        ]
    # ── inspect ───────────────────────────────────────────────────────────────
    def list(self) -> list[dict]:
        """Every backup, newest first, with what is known about it."""
        if not self.root.is_dir():
            return []
        entries = []
        for directory in sorted(self.root.iterdir(), reverse=True):
            if not directory.is_dir():
                continue
            manifest = self.manifest(directory)
            database = directory / DB_NAME
            entries.append(
                {
                    "name": directory.name,
                    "path": str(directory),
                    "created_at": (manifest or {}).get("created_at"),
                    "reason": (manifest or {}).get("reason"),
                    "revision": (manifest or {}).get("revision"),
                    "bytes": database.stat().st_size if database.exists() else 0,
                    "complete": bool(manifest) and database.exists(),
                }
            )
        return entries
    def manifest(self, directory: Path) -> dict | None:
        path = Path(directory) / MANIFEST_NAME
        if not path.exists():
            return None
        try:
            return json.loads(path.read_text())
        except ValueError:
            return None
    def verify(self, directory: Path | str) -> VerifyResult:
        """Prove a snapshot is still the one that was taken and still readable."""
        directory = Path(directory)
        if not directory.is_dir():
            return VerifyResult(False, (f"no backup at {directory}",))
        manifest = self.manifest(directory)
        if manifest is None:
            return VerifyResult(False, ("manifest is missing or unreadable",))
        database = directory / manifest["database"]["name"]
        if not database.exists():
            return VerifyResult(False, ("the snapshot file is missing",), manifest.get("revision"))
        issues: list[str] = []
        if sha256_file(database) != manifest["database"]["sha256"]:
            # Bit rot, a truncated copy, or an edited snapshot: all three mean the
            # bytes are not the ones that were verified when the backup was made.
            issues.append("sha256 does not match the manifest")
        state, structural = _integrity(database)
        issues.extend(structural)
        counts = _counts(database) if state != "error" else None
        if counts is not None and manifest.get("counts") and counts != manifest["counts"]:
            issues.append(f"row counts changed: {manifest['counts']} -> {counts}")
        return VerifyResult(not issues, tuple(issues), manifest.get("revision"), counts)
    # ── retention ─────────────────────────────────────────────────────────────
    def prune(self, *, keep: int = DEFAULT_KEEP) -> list[str]:
        """Delete the oldest backups beyond ``keep``. Never deletes the newest one."""
        if keep < 1:
            raise BackupError("retention must keep at least one backup")
        removed = []
        for entry in self.list()[keep:]:
            shutil.rmtree(entry["path"], ignore_errors=True)
            removed.append(entry["name"])
        return removed
    # ── restore ───────────────────────────────────────────────────────────────
    def restore(self, directory: Path | str, target_data_dir: Path | str) -> dict:
        """Restore a verified snapshot into a **fresh** data directory.
        Refuses a target that already holds a database. Restoring on top of a live
        installation would merge two histories that disagree about which files were
        renamed, uploaded, and archived — the one failure this whole story exists to
        prevent. Recovering in place is: stop everything, move the old data
        directory aside, restore into a new one.
        """
        directory = Path(directory)
        result = self.verify(directory)
        if not result.ok:
            raise BackupError(f"refusing to restore an unverified backup: {result.issues}")
        target = Path(target_data_dir)
        target.mkdir(parents=True, exist_ok=True)
        destination = target / DB_NAME
        if destination.exists():
            raise BackupError(
                f"{destination} already exists; restore into a fresh data directory"
            )
        shutil.copy2(directory / DB_NAME, destination)
        # The write-ahead log of the *source* installation must not travel with a
        # snapshot: the backup API already folded every committed page into it.
        for leftover in (target / f"{DB_NAME}-wal", target / f"{DB_NAME}-shm"):
            leftover.unlink(missing_ok=True)
        restored = _integrity(destination)
        return {
            "backup": directory.name,
            "restored_to": str(destination),
            "revision": result.revision,
            "counts": _counts(destination),
            "integrity": restored[0],
            "issues": restored[1],
            "next_steps": [
                "point PHOTO_PIPELINE_DATA_DIR at the restored directory",
                "run `python -m photo_pipeline migrate` to reach the current revision",
                "run an inventory scan so paths are reconciled against the real library",
                "mount every archive location listed in the manifest before archiving again",
            ],
        }
--- a/photo_pipeline/services/benchmarks.py
+++ b/photo_pipeline/services/benchmarks.py
@@ -1,502 +0,0 @@
 """Load, soak, and resource-budget harness (US07-06, concept §17 and §18).
 Performance here is not "it felt fast on my library". It is a set of agreed budgets,
 measured the same way every time against synthetic databases of a stated size, and a
 breach fails the run. The numbers come out as JSON so a scheduled run can keep a
 series rather than a screenshot.
    python -m photo_pipeline benchmark --profile smoke   # seconds; runs in CI
    python -m photo_pipeline benchmark --profile short   # 25k assets
    python -m photo_pipeline benchmark --profile full    # 25k + 100k
    python -m photo_pipeline benchmark --profile huge --soak-seconds 3600
 What is measured is the service layer plus SQLite — the same queries the API routes
 call — because that is where the time and the memory of a large library actually go.
 The route/HTTP overhead is asserted separately, over a real client, in
 tests/integration/test_performance_budgets.py.
 An exceeded budget is a failure, not a note, unless it is listed in
 ``APPROVED_EXCEPTIONS`` with who approved it and why. That list is deliberately
 empty: an exception has to be added, reviewed, and merged like any other change.
 """
 from __future__ import annotations
 import gc
 import json
 import os
 import resource
 import statistics
 import sqlite3
 import time
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from sqlalchemy import func, insert, select
 from photo_pipeline.config import Config
 from photo_pipeline.db import create_db_engine, create_session_factory, run_migrations
 from photo_pipeline.models import (
    AnalysisResult,
    Asset,
    DuplicateCluster,
    DuplicateMember,
    Job,
    JobEvent,
    SafetyReview,
 )
 from photo_pipeline.services.duplicates import DuplicateService
 from photo_pipeline.services.inventory import InventoryService
 from photo_pipeline.services.jobs import ACTIVE_STATES, JobService
 from photo_pipeline.services.library import LibraryService
 from photo_pipeline.services.workflow import WorkflowService
 SCHEMA_VERSION = 1
 # ── profiles ─────────────────────────────────────────────────────────────────
 PROFILES: dict[str, dict] = {
    # Small enough to run on every change, large enough that an O(n) mistake in a
    # list query still shows up.
    "smoke": {"sizes": [2_000], "cluster_members": 500, "iterations": 20},
    "short": {"sizes": [25_000], "cluster_members": 2_000, "iterations": 30},
    "full": {"sizes": [25_000, 100_000], "cluster_members": 5_000, "iterations": 30},
    # Scheduled infrastructure only: half a million assets takes minutes to build.
    "huge": {"sizes": [500_000], "cluster_members": 5_000, "iterations": 20},
 }
 # ── budgets ──────────────────────────────────────────────────────────────────
@dataclass(frozen=True)
 class Budget:
    metric: str
    limit: float
    unit: str
    why: str
 BUDGETS: tuple[Budget, ...] = (
    Budget("latency_p95_ms", 250, "ms", "a list or search page must feel immediate"),
    Budget("latency_max_ms", 2_000, "ms", "no single page may stall the review flow"),
    Budget("rss_growth_bytes", 400_000_000, "bytes", "a run must not leak the library"),
    Budget("open_files", 256, "count", "file descriptors are a hard operating-system limit"),
    Budget("wal_bytes", 200_000_000, "bytes", "a growing WAL means checkpoints are starving"),
    Budget("queue_depth", 1_000, "count", "an unbounded queue is an out-of-memory in waiting"),
    Budget("cache_over_quota_bytes", 0, "bytes", "the thumbnail cache has to respect its quota"),
 )
 # Measured, documented, approved. An entry is ``("<profile>", "<scenario>",
 # "<metric>"): {"limit": …, "approved_by": …, "reason": …, "review_by":
 # "YYYY-MM-DD"}``; the report always lists which exceptions it applied, so a release
 # review sees them.
 #
 # The two below are the half-million-asset scale point. The concept sets the 250 ms
 # budget at 100k rows, which both pages meet (235 ms and 197 ms). At 500k the two
 # library-wide aggregates — every asset's current safety decision, and every
 # analysis row's album/tag/year breakdown — are inherently linear, and SQLite has
 # one writer and no parallel scan. Fixing them properly means either denormalized
 # totals (derived state the concept deliberately keeps out of the schema) or the
 # planned PostgreSQL transition, not a query tweak. Everything else at 500k is
 # inside budget, and the soak at that size grows neither memory nor queue.
 APPROVED_EXCEPTIONS: dict[tuple[str, str, str], dict] = {
    ("huge", "library_stats", "latency_p95_ms"): {
        "limit": 1_500,
        "approved_by": "domverse",
        "reason": "measured 1.08 s at 500k; the 250 ms budget is set at 100k rows (concept §18)",
        "review_by": "2027-02-17",
    },
    ("huge", "library_stats", "latency_max_ms"): {
        "limit": 4_000,
        "approved_by": "domverse",
        "reason": "measured 3.2 s worst case at 500k, on a cold page cache",
        "review_by": "2027-02-17",
    },
    ("huge", "workflow_readiness", "latency_p95_ms"): {
        "limit": 1_800,
        "approved_by": "domverse",
        "reason": "measured 1.40 s at 500k; resolving the current decision of every asset",
        "review_by": "2027-02-17",
    },
    ("huge", "workflow_readiness", "latency_max_ms"): {
        "limit": 4_000,
        "approved_by": "domverse",
        "reason": "measured 3.3 s worst case at 500k, on a cold page cache",
        "review_by": "2027-02-17",
    },
 }
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 # ── resource sampling ────────────────────────────────────────────────────────
 def rss_bytes() -> int:
    """Resident set size of this process, without a psutil dependency."""
    usage = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
    # Linux reports kilobytes, BSD/macOS bytes.
    return usage if usage > 1 << 32 or os.uname().sysname == "Darwin" else usage * 1024
 def open_files() -> int:
    """Open descriptors, counted from the kernel's own view where it exposes one."""
    for directory in ("/proc/self/fd", "/dev/fd"):
        try:
            return len(os.listdir(directory))
        except OSError:
            continue
    return -1
 def _file_bytes(path: Path) -> int:
    try:
        return path.stat().st_size
    except OSError:
        return 0
 def _tree_bytes(path: Path) -> int:
    if not path.is_dir():
        return 0
    return sum(p.stat().st_size for p in path.rglob("*") if p.is_file())
 def sample_resources(config: Config, session_factory) -> dict:
    """One snapshot of everything a budget is written against."""
    database = config.database_path
    with session_factory() as session:
        queue_depth = int(
            session.scalar(select(func.count()).select_from(Job).where(Job.state.in_(ACTIVE_STATES)))
            or 0
        )
        events = int(session.scalar(select(func.count()).select_from(JobEvent)) or 0)
    cache_bytes = _tree_bytes(config.thumbnail_cache_dir)
    return {
        "at": _now().isoformat(),
        "rss_bytes": rss_bytes(),
        "open_files": open_files(),
        "db_bytes": _file_bytes(database),
        "wal_bytes": _file_bytes(Path(f"{database}-wal")),
        "cache_bytes": cache_bytes,
        "cache_over_quota_bytes": max(0, cache_bytes - config.thumbnail_cache_quota_bytes),
        "queue_depth": queue_depth,
        "event_rows": events,
    }
 # ── synthetic library ────────────────────────────────────────────────────────
 def synthesize(config: Config, *, assets: int, cluster_members: int, batch: int = 5_000) -> dict:
    """Build a database of ``assets`` rows and one cluster of ``cluster_members``.
    Rows only — no image files. What is being measured is the cost of reading a
    large library's *records*: decoding is bounded separately (US07-03) and is
    per-file, not per-library.
    """
    config.database_path.parent.mkdir(parents=True, exist_ok=True)
    run_migrations(config.database_url)
    engine = create_db_engine(config.database_url)
    factory = create_session_factory(engine)
    started = time.monotonic()
    root = config.library_roots[0] if config.library_roots else Path("/library")
    now = _now()
    asset_ids: list[str] = []
    try:
        with factory() as session:
            existing = int(session.scalar(select(func.count()).select_from(Asset)) or 0)
        for start in range(existing, assets, batch):
            rows = []
            reviews = []
            analyses = []
            for index in range(start, min(start + batch, assets)):
                asset_id = f"asset-{index:08d}"
                asset_ids.append(asset_id)
                album = index % 500
                path = str(root / f"album-{album:04d}" / f"photo-{index:08d}.jpg")
                rows.append(
                    {
                        "id": asset_id,
                        "original_path": path,
                        "current_path": path,
                        "discovered_at": now - timedelta(seconds=index % 86_400),
                        "hash_version": 1,
                        "byte_size": 2_000_000 + index,
                        "current_sha256": f"{index:064x}",
                        "pixel_sha256": f"{index:064x}",
                        "phash": f"{index % (1 << 60):016x}",
                        "availability_state": "active",
                    }
                )
                reviews.append(
                    {
                        "id": str(uuid.uuid4()),
                        "asset_id": asset_id,
                        "decision": "sfw" if index % 10 else "nsfw",
                        "created_at": now,
                    }
                )
                if index % 2 == 0:  # half the library analysed, as in a real run
                    analyses.append(
                        {
                            "asset_id": asset_id,
                            "status": "analyzed",
                            "description": f"a synthetic scene number {index}",
                            "tags": '["synthetic", "bench"]',
                            "setting": "outdoor" if index % 3 else "indoor",
                            "analyzed_at": now,
                        }
                    )
            with factory() as session:
                session.execute(insert(Asset), rows)
                session.execute(insert(SafetyReview), reviews)
                if analyses:
                    session.execute(insert(AnalysisResult), analyses)
                session.commit()
        if cluster_members:
            with factory() as session:
                cluster_id = str(uuid.uuid4())
                session.add(
                    DuplicateCluster(
                        id=cluster_id,
                        method="perceptual",
                        confidence="near",
                        state="open",
                        version=1,
                    )
                )
                session.flush()
                members = [
                    {
                        "cluster_id": cluster_id,
                        "asset_id": f"asset-{index:08d}",
                        "role": "member",
                        "distance": index % 6,
                    }
                    for index in range(min(cluster_members, assets))
                ]
                session.execute(insert(DuplicateMember), members)
                session.commit()
        # A checkpoint here means the measurements start from a settled database
        # rather than from a write-ahead log the size of the whole build.
        with sqlite3.connect(config.database_path) as connection:
            connection.execute("PRAGMA wal_checkpoint(TRUNCATE)")
    finally:
        engine.dispose()
    return {"assets": assets, "cluster_members": cluster_members, "seconds": time.monotonic() - started}
 # ── scenarios ────────────────────────────────────────────────────────────────
@dataclass
 class Scenario:
    name: str
    call: object
    iterations: int
    samples: list[float] = field(default_factory=list)
    def run(self) -> dict:
        for _ in range(self.iterations):
            started = time.perf_counter()
            self.call()
            self.samples.append((time.perf_counter() - started) * 1000)
        ordered = sorted(self.samples)
        index = max(0, int(round(0.95 * len(ordered))) - 1)
        return {
            "scenario": self.name,
            "iterations": self.iterations,
            "latency_p50_ms": round(statistics.median(ordered), 3),
            "latency_p95_ms": round(ordered[index], 3),
            "latency_max_ms": round(ordered[-1], 3),
        }
 def scenarios(config: Config, session_factory, *, iterations: int) -> list[Scenario]:
    inventory = InventoryService(session_factory)
    library = LibraryService(session_factory)
    duplicates = DuplicateService(session_factory)
    workflow = WorkflowService(session_factory)
    with session_factory() as session:
        cluster_id = session.scalar(select(DuplicateCluster.id))
    built = [
        Scenario("inventory_page", lambda: inventory.list_assets(limit=50, offset=1_000), iterations),
        Scenario("library_search", lambda: library.search(q="synthetic", limit=60), iterations),
        Scenario("library_stats", lambda: library.stats(), iterations),
        Scenario("workflow_readiness", lambda: workflow.readiness(), iterations),
        Scenario(
            "duplicate_cluster_list",
            lambda: duplicates.list_clusters(limit=50, offset=0),
            iterations,
        ),
    ]
    if cluster_id:
        built.append(
            Scenario(
                "duplicate_cluster_page",
                lambda: duplicates.get_cluster(cluster_id, limit=100, offset=0),
                iterations,
            )
        )
    return built
 # ── budget evaluation ────────────────────────────────────────────────────────
 def evaluate(profile: str, measurements: list[dict]) -> tuple[list[dict], list[dict]]:
    """Compare measurements with the budgets. Returns ``(breaches, exceptions_used)``."""
    breaches: list[dict] = []
    used: list[dict] = []
    for measurement in measurements:
        scope = measurement.get("scenario", "resources")
        for budget in BUDGETS:
            if budget.metric not in measurement:
                continue
            value = measurement[budget.metric]
            if value is None or value < 0:
                continue
            limit = budget.limit
            exception = APPROVED_EXCEPTIONS.get((profile, scope, budget.metric))
            if exception:
                limit = exception["limit"]
                used.append({"scope": scope, "metric": budget.metric, **exception})
            if value > limit:
                breaches.append(
                    {
                        "scope": scope,
                        "metric": budget.metric,
                        "value": value,
                        "limit": limit,
                        "unit": budget.unit,
                        "why": budget.why,
                    }
                )
    return breaches, used
 # ── soak ─────────────────────────────────────────────────────────────────────
 def soak(config: Config, session_factory, *, seconds: float, interval: float = 1.0) -> dict:
    """Browse, queue, cancel, and retry for a while; watch what grows.
    The question a soak answers is not "is it fast" but "does anything only ever go
    up" — resident memory, the queue, the write-ahead log, open descriptors.
    """
    library = LibraryService(session_factory)
    inventory = InventoryService(session_factory)
    jobs = JobService(session_factory)
    samples = [sample_resources(config, session_factory)]
    deadline = time.monotonic() + seconds
    last_sample = time.monotonic()
    cycles = 0
    while time.monotonic() < deadline:
        offset = (cycles * 50) % 1_000
        library.search(q="synthetic", limit=60, offset=offset)
        inventory.list_assets(limit=50, offset=offset)
        job = jobs.enqueue("scan", items=[f"soak-{cycles}"])
        jobs.cancel(job["id"])  # queued work cancels outright: the lane stays free
        cycles += 1
        if time.monotonic() - last_sample >= interval:
            gc.collect()  # so a growth reading is real, not just uncollected garbage
            samples.append(sample_resources(config, session_factory))
            last_sample = time.monotonic()
    samples.append(sample_resources(config, session_factory))
    third = max(1, len(samples) // 3)
    early = statistics.mean(sample["rss_bytes"] for sample in samples[:third])
    late = statistics.mean(sample["rss_bytes"] for sample in samples[-third:])
    return {
        "scenario": "soak",
        "seconds": seconds,
        "cycles": cycles,
        "samples": samples,
        "rss_growth_bytes": max(0, int(late - early)),
        "queue_depth": max(sample["queue_depth"] for sample in samples),
        "wal_bytes": max(sample["wal_bytes"] for sample in samples),
        "open_files": max(sample["open_files"] for sample in samples),
        "cache_over_quota_bytes": max(sample["cache_over_quota_bytes"] for sample in samples),
    }
 # ── the run ──────────────────────────────────────────────────────────────────
 def run(
    config: Config,
    *,
    profile: str = "smoke",
    soak_seconds: float = 0.0,
    output: Path | str | None = None,
 ) -> dict:
    """Build, measure, evaluate. Returns the report; the caller decides the exit code."""
    if profile not in PROFILES:
        raise ValueError(f"unknown profile {profile!r}; try one of {sorted(PROFILES)}")
    settings = PROFILES[profile]
    report = {
        "schema_version": SCHEMA_VERSION,
        "profile": profile,
        "started_at": _now().isoformat(),
        "budgets": [
            {"metric": b.metric, "limit": b.limit, "unit": b.unit, "why": b.why} for b in BUDGETS
        ],
        "runs": [],
    }
    measurements: list[dict] = []
    for size in settings["sizes"]:
        sized = config.model_copy(update={"data_dir": Path(config.data_dir) / f"bench-{size}"})
        before = None
        build = synthesize(
            sized, assets=size, cluster_members=settings["cluster_members"]
        )
        engine = create_db_engine(sized.database_url)
        factory = create_session_factory(engine)
        try:
            before = sample_resources(sized, factory)
            results = [
                scenario.run()
                for scenario in scenarios(sized, factory, iterations=settings["iterations"])
            ]
            after = sample_resources(sized, factory)
            after["scenario"] = "resources"
            after["rss_growth_bytes"] = max(0, after["rss_bytes"] - before["rss_bytes"])
            soaked = (
                soak(sized, factory, seconds=soak_seconds) if soak_seconds > 0 else None
            )
        finally:
            engine.dispose()
        measurements.extend(results)
        measurements.append(after)
        if soaked:
            measurements.append(soaked)
        report["runs"].append(
            {
                "assets": size,
                "build": build,
                "before": before,
                "scenarios": results,
                "resources": after,
                "soak": soaked,
            }
        )
    breaches, exceptions_used = evaluate(profile, measurements)
    report["breaches"] = breaches
    report["exceptions_applied"] = exceptions_used
    report["ok"] = not breaches
    report["finished_at"] = _now().isoformat()
    if output:
        path = Path(output)
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(report, indent=2))
    return report
--- a/photo_pipeline/services/diagnostics.py
+++ b/photo_pipeline/services/diagnostics.py
@@ -1,223 +0,0 @@
 """Operational diagnostics: what the application is using, and what is about to
 run out (US07-05, concept §17).
 Every mutating stage in this application writes something before it is safe to
 continue — a journal, an EXIF rewrite, an archive copy, a backup. All of them fail
 badly on a full disk, so the sizes that grow (database, write-ahead log, thumbnail
 cache, uploader reports, backups, logs) are reported separately rather than as one
 opaque total, and each is compared against the free space actually left.
 This is a read-only report. It never deletes, rotates, or prunes anything: what to
 do about a warning is an operator's decision, and the tools for it are the
 thumbnail cache quota, the backup retention helper, and log rotation outside the
 application.
 """
 from __future__ import annotations
 import functools
 import json
 import shutil
 from pathlib import Path
 from photo_pipeline.config import Config
 from photo_pipeline.integrations import exiftool, immich_go
 from photo_pipeline.services import app_lock
 # Below this much free space, mutating stages should stop rather than risk a
 # half-written journal, EXIF container, or archive copy.
 LOW_DISK_BYTES = 1_000_000_000
 CRITICAL_DISK_BYTES = 200_000_000
 # Written into the container image at build time (US08-02). The image pins exiftool
 # and immich-go, and this file is how a running container reports which versions it
 # was built with — so a drifted or missing binary is visible here rather than in a
 # failed EXIF checkpoint or a misparsed upload report.
 IMAGE_VERSIONS_FILE = Path("/etc/photo-pipeline/versions.json")
 def _tree_bytes(path: Path) -> int:
    if not path.exists():
        return 0
    if path.is_file():
        return path.stat().st_size
    total = 0
    for child in path.rglob("*"):
        try:
            if child.is_file() and not child.is_symlink():
                total += child.stat().st_size
        except OSError:
            continue  # vanished mid-walk; it is not using space any more
    return total
 def _component(name: str, path: Path, *, quota: int | None = None) -> dict:
    used = _tree_bytes(path)
    entry = {"name": name, "path": str(path), "bytes": used, "exists": path.exists()}
    if quota is not None:
        entry["quota_bytes"] = quota
        entry["over_quota"] = used > quota
    return entry
 def disk(path: Path) -> dict:
    """Free/total for the filesystem holding ``path`` — the nearest existing parent,
    so a data directory that does not exist yet still reports its future disk."""
    probe = path
    while not probe.exists() and probe != probe.parent:
        probe = probe.parent
    try:
        usage = shutil.disk_usage(probe)
    except OSError as error:
        return {"path": str(probe), "error": str(error)}
    return {
        "path": str(probe),
        "total_bytes": usage.total,
        "free_bytes": usage.free,
        "used_bytes": usage.used,
    }
 def _pinned_versions() -> dict[str, str]:
    """The versions this image recorded at build time; empty outside a container."""
    try:
        recorded = json.loads(IMAGE_VERSIONS_FILE.read_text())
    except (OSError, ValueError):
        return {}
    if not isinstance(recorded, dict):
        return {}
    return {str(name): str(value) for name, value in recorded.items()}
@functools.lru_cache(maxsize=4)
 def _uploader_version(binary: str) -> str | None:
    """Cached: the uploader cannot change version inside one process."""
    return immich_go.version(binary)
 def tools(config: Config) -> list[dict]:
    """The external executables the pipeline shells out to, and their versions.
    ``pinned`` is what the image was built against, ``version`` is what is actually
    installed. They differ only when the binary was replaced or mounted over.
    """
    return [
        {
            "name": "exiftool",
            "path": exiftool.find_binary(),
            "version": exiftool.version(),
            "pinned": _pinned_versions().get("exiftool"),
        },
        {
            "name": "immich-go",
            "path": immich_go.find_binary(config.immich_go_binary),
            "version": _uploader_version(config.immich_go_binary),
            "pinned": _pinned_versions().get("immich-go"),
        },
    ]
 def report(config: Config) -> dict:
    """Sizes, disk headroom, tool versions, warnings, and who holds the library lock."""
    database = config.database_path
    components = [
        _component("database", database),
        _component("write_ahead_log", Path(f"{database}-wal")),
        _component("shared_memory", Path(f"{database}-shm")),
        _component(
            "thumbnail_cache",
            config.thumbnail_cache_dir,
            quota=config.thumbnail_cache_quota_bytes,
        ),
        _component("upload_reports", config.data_dir / "uploads"),
        _component("backups", config.data_dir / "backups"),
        _component("logs", config.data_dir / "logs"),
    ]
    space = disk(config.data_dir)
    free = space.get("free_bytes")
    warnings: list[dict] = []
    if free is not None and free < CRITICAL_DISK_BYTES:
        warnings.append(
            {
                "code": "disk_critical",
                "message": (
                    f"only {free} bytes free on {space['path']}; stop mutating stages "
                    "and free space before renaming, writing EXIF, or archiving"
                ),
            }
        )
    elif free is not None and free < LOW_DISK_BYTES:
        warnings.append(
            {
                "code": "disk_low",
                "message": f"{free} bytes free on {space['path']}; prune backups or the cache",
            }
        )
    for component in components:
        if component.get("over_quota"):
            warnings.append(
                {
                    "code": "cache_over_quota",
                    "message": (
                        f"{component['name']} uses {component['bytes']} bytes, over its "
                        f"{component['quota_bytes']} byte quota"
                    ),
                }
            )
    # A write-ahead log that outgrows its database means checkpoints are starving —
    # an operational warning, not something to ignore (concept §16).
    wal = next(c for c in components if c["name"] == "write_ahead_log")
    db = next(c for c in components if c["name"] == "database")
    if wal["bytes"] > max(db["bytes"], 1) :
        warnings.append(
            {
                "code": "wal_growth",
                "message": (
                    f"the write-ahead log ({wal['bytes']} bytes) is larger than the database "
                    f"({db['bytes']} bytes); a long-running read may be blocking checkpoints"
                ),
            }
        )
    installed_tools = tools(config)
    for tool in installed_tools:
        # A missing tool is reported as ``version: null`` rather than warned about: on a
        # development machine the uploader is legitimately absent, and the stages that
        # need it already refuse to run. A *drifted* tool is different — the image pinned
        # a version and something replaced it.
        if tool["version"] and tool["pinned"] and tool["pinned"] not in tool["version"]:
            warnings.append(
                {
                    "code": "tool_version_drift",
                    "message": (
                        f"{tool['name']} reports {tool['version']} but this image pinned "
                        f"{tool['pinned']}"
                    ),
                }
            )
    locks = {}
    for role in ("api", "worker"):
        holder = app_lock.LibraryLock(config, role).holder()
        locks[role] = holder.as_dict() if holder else None
    legacy = app_lock.legacy_activity(config)
    if legacy["active"]:
        warnings.append(
            {
                "code": "legacy_process_active",
                "message": (
                    "a legacy CLI is writing this library; mutating stages are refused "
                    "until it stops"
                ),
            }
        )
    return {
        "components": components,
        "total_bytes": sum(component["bytes"] for component in components),
        "disk": space,
        "tools": installed_tools,
        "warnings": warnings,
        "locks": locks,
        "legacy_activity": legacy,
    }
--- a/photo_pipeline/services/duplicates.py
+++ b/photo_pipeline/services/duplicates.py
@@ -11,12 +11,6 @@ Detection runs in two categories:
  band (NEAR/SIMILAR). These are review candidates: never decided automatically, and
  negative-linked pairs are suppressed so a rejected pair is not re-suggested.
 Archived assets stay in both indexes (US06-03): a new active copy of an archived
 original is recognised through its hashes even while the medium is offline, and
 cluster review falls back to the retained protected preview plus hash evidence.
 An exact/pixel match links straight to the archived canonical; a perceptual match
 is a review candidate that names the medium to mount for a pixel-level decision.
 Decisions (``canonical`` / ``not_duplicate`` / ``deferred``) persist with evidence,
 use optimistic version checks, are reversible, and can never form a canonical cycle.
 A new content-identical member of an already-decided cluster inherits the established
@@ -40,25 +34,16 @@ from sqlalchemy import func, select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.models import (
    ArchiveLocation,
    Asset,
    DuplicateCluster,
    DuplicateMember,
    DuplicateNegativeLink,
    Thumbnail,
 )
-from photo_pipeline.services import availability, hashing
+from photo_pipeline.services import hashing
 NEAR_MAX = 5
 SIMILAR_MAX = 10
 # Member paging (US07-06). A burst or a re-imported folder can put thousands of
 # assets in one cluster; review looks at a few at a time, so neither the list view
 # nor the detail view may load them all.
 MEMBER_PAGE = 100
 MAX_MEMBER_PAGE = 500
 SNAPSHOT_MEMBER_PREVIEW = 20
 class Method(str, Enum):
    EXACT = "exact"
@@ -142,18 +127,18 @@ class DuplicateService:
    # ── perceptual hash backfill ───────────────────────────────────────────
    def ensure_phashes(self) -> int:
        """Hash whatever is readable now — an archived asset keeps the hash it
        already has, and gains one whenever its medium happens to be mounted."""
        updated = 0
        with self._session_factory() as session:
-            assets = session.execute(select(Asset)).scalars()
+            assets = session.execute(
                select(Asset).where(
                    Asset.availability_state == "active",
                    Asset.current_path.isnot(None),
                )
            ).scalars()
            for asset in assets:
                if asset.phash is not None and asset.phash_version == hashing.PHASH_VERSION:
                    continue
-                source = availability.readable_path(session, asset)
+                value = hashing.safe_phash(asset.current_path)
                if source is None:
                    continue
                value = hashing.safe_phash(str(source))
                if value is not None:
                    asset.phash = value
                    asset.phash_version = hashing.PHASH_VERSION
@@ -161,40 +146,20 @@ class DuplicateService:
            session.commit()
        return updated
    def ensure_phash(self, asset_id: str, *, source=None) -> str | None:
        """Backfill one asset's perceptual hash while its bytes are still readable.
        Archiving calls this before the original leaves — passing the archive copy
        as ``source``, since the database does not point at it yet — because an
        asset without a pHash silently drops out of the fuzzy index the moment its
        medium is away.
        """
        with self._session_factory() as session:
            asset = session.get(Asset, asset_id)
            if asset is None:
                return None
            if asset.phash is not None and asset.phash_version == hashing.PHASH_VERSION:
                return asset.phash
            source = source or availability.readable_path(session, asset)
            if source is None:
                return None
            value = hashing.safe_phash(str(source))
            if value is not None:
                asset.phash = value
                asset.phash_version = hashing.PHASH_VERSION
                session.commit()
            return value
    # ── detection ──────────────────────────────────────────────────────────
    def detect(self) -> DetectionReport:
        self.ensure_phashes()
        now = datetime.now(timezone.utc)
        report = DetectionReport()
        with self._session_factory() as session:
-            # Every known asset stays in the indexes, archived or not: a copy of an
+            assets = list(
-            # archived original must be recognised as a duplicate rather than
+                session.execute(
-            # treated as a new photo (concept §9, invariant 12).
+                    select(Asset).where(
-            assets = list(session.execute(select(Asset)).scalars())
+                        Asset.availability_state == "active",
                        Asset.current_path.isnot(None),
                    )
                ).scalars()
            )
            by_id = {a.id: a for a in assets}
            negatives = {
                _pair(link.asset_a, link.asset_b)
@@ -466,19 +431,10 @@ class DuplicateService:
    @staticmethod
    def _recommend_canonical(ids, by_id) -> str:
-        # ponytail: largest file, then the archived copy, then path as a
+        # ponytail: largest file, path as deterministic tie-break. The concept's
-        # deterministic tie-break. Archived wins ties because it is the reviewed,
+        # richer policy (resolution, least recompression, metadata richness) lands
-        # uploaded original — a fresh active copy must not demote it to a variant.
+        # with the review UI story.
-        # The concept's richer policy (resolution, least recompression, metadata
+        return max(ids, key=lambda i: (by_id[i].byte_size or 0, by_id[i].current_path or ""))
        # richness) lands with the review UI story.
        return max(
            ids,
            key=lambda i: (
                by_id[i].byte_size or 0,
                by_id[i].availability_state in availability.ARCHIVED,
                by_id[i].current_path or by_id[i].archive_path or "",
            ),
        )
    def _apply_canonical(self, session, cluster, ids, canonical_id):
        for member in session.execute(
@@ -527,65 +483,33 @@ class DuplicateService:
            items = [self._snapshot(session, c.id) for c in rows]
        return {"items": items, "total": int(total or 0), "limit": limit, "offset": offset}
-    def get_cluster(
+    def get_cluster(self, cluster_id: str) -> dict | None:
-        self, cluster_id: str, *, limit: int = MEMBER_PAGE, offset: int = 0
+        """Cluster detail enriched with per-member asset evidence for comparison."""
    ) -> dict | None:
        """Cluster detail enriched with per-member asset evidence for comparison.
        Members are paged and their evidence is loaded in batches (US07-06). A
        cluster of a few thousand near-identical frames is a real shape for a phone
        library, and the review screen only ever shows a handful at a time: loading
        every member — each with its own asset, thumbnail, and location query — made
        opening such a cluster cost thousands of round trips and megabytes of JSON.
        """
        limit = max(1, min(limit, MAX_MEMBER_PAGE))
        offset = max(0, offset)
        with self._session_factory() as session:
            cluster = session.get(DuplicateCluster, cluster_id)
            if cluster is None:
                return None
            member_total = int(
                session.scalar(
                    select(func.count())
                    .select_from(DuplicateMember)
                    .where(DuplicateMember.cluster_id == cluster_id)
                )
                or 0
            )
            rows = list(
                session.execute(
                    select(DuplicateMember)
                    .where(DuplicateMember.cluster_id == cluster_id)
                    .order_by(DuplicateMember.asset_id)
                    .limit(limit)
                    .offset(offset)
                ).scalars()
            )
            evidence = self._member_evidence(session, [row.asset_id for row in rows])
            members = []
-            for member in rows:
+            for member in session.execute(
                select(DuplicateMember).where(DuplicateMember.cluster_id == cluster_id)
            ).scalars():
                asset = session.get(Asset, member.asset_id)
                try:
-                    member_evidence = json.loads(member.evidence) if member.evidence else {}
+                    evidence = json.loads(member.evidence) if member.evidence else {}
                except json.JSONDecodeError:
-                    member_evidence = {}
+                    evidence = {}
                asset, offline = evidence[member.asset_id]
                members.append(
                    {
                        "asset_id": member.asset_id,
                        "role": member.role,
                        "distance": member.distance,
-                        "evidence": member_evidence,
+                        "evidence": evidence,
                        "current_path": asset.current_path if asset else None,
                        "byte_size": asset.byte_size if asset else None,
                        "phash": asset.phash if asset else None,
                        **offline,
                    }
                )
-            # A full-resolution comparison of an offline original is impossible; the
+            members.sort(key=lambda m: m["asset_id"])
            # UI asks for that named medium instead of guessing (concept §9). The
            # answer covers the whole cluster, not just this page, so a mount is not
            # discovered halfway through a review.
            mount_required = self._mount_required(session, cluster_id)
            return {
                "id": cluster.id,
                "method": cluster.method,
@@ -595,111 +519,9 @@ class DuplicateService:
                "canonical_asset_id": cluster.canonical_asset_id,
                "version": cluster.version,
                "requires_confirmation": cluster.method == Method.PERCEPTUAL.value,
                "mount_required": mount_required,
                "members": members,
                "member_total": member_total,
                "limit": limit,
                "offset": offset,
            }
    def _member_evidence(self, session, asset_ids: list[str]) -> dict:
        """``{asset_id: (asset, offline_evidence)}`` for one page, in three queries."""
        if not asset_ids:
            return {}
        assets = {
            asset.id: asset
            for asset in session.execute(
                select(Asset).where(Asset.id.in_(asset_ids))
            ).scalars()
        }
        previews: dict[str, list] = {}
        for thumbnail in session.execute(
            select(Thumbnail).where(Thumbnail.asset_id.in_(asset_ids))
        ).scalars():
            previews.setdefault(thumbnail.asset_id, []).append(thumbnail)
        location_ids = {
            asset.archive_location_id for asset in assets.values() if asset.archive_location_id
        }
        locations = (
            {
                location.id: location
                for location in session.execute(
                    select(ArchiveLocation).where(ArchiveLocation.id.in_(location_ids))
                ).scalars()
            }
            if location_ids
            else {}
        )
        return {
            asset_id: (
                assets.get(asset_id),
                self._offline_evidence(
                    assets.get(asset_id),
                    locations=locations,
                    thumbnails=previews.get(asset_id, []),
                ),
            )
            for asset_id in asset_ids
        }
    def _mount_required(self, session, cluster_id: str) -> list[str]:
        """Archive media whose originals this cluster needs, across every member."""
        rows = session.execute(
            select(ArchiveLocation.name)
            .select_from(DuplicateMember)
            .join(Asset, Asset.id == DuplicateMember.asset_id)
            .join(ArchiveLocation, ArchiveLocation.id == Asset.archive_location_id)
            .where(
                DuplicateMember.cluster_id == cluster_id,
                Asset.availability_state == availability.ARCHIVED_OFFLINE,
            )
            .distinct()
        ).scalars()
        return sorted(rows)
    def _offline_evidence(
        self, asset: Asset | None, *, locations: dict, thumbnails: list
    ) -> dict:
        """What review can still rely on when a member's original is not readable.
        Takes the already-loaded locations and thumbnails for its page rather than
        querying per member (US07-06).
        """
        if asset is None:
            return {
                "availability_state": None,
                "archive_location": None,
                "archive_location_id": None,
                "archive_path": None,
                "preview": {"state": "missing", "protected": False},
                "requires_mount": False,
            }
        location = locations.get(asset.archive_location_id)
        preview = self._preview_evidence(thumbnails)
        archived = asset.availability_state in availability.ARCHIVED
        return {
            "availability_state": asset.availability_state,
            "archive_location": location.name if location else None,
            "archive_location_id": asset.archive_location_id,
            "archive_path": asset.archive_path,
            "preview": preview,
            # Offline archived members can still be compared through their retained
            # preview and hash evidence; only pixel-level review needs the medium.
            "requires_mount": archived
            and asset.availability_state == availability.ARCHIVED_OFFLINE
            and bool(location),
        }
    @staticmethod
    def _preview_evidence(rows: list) -> dict:
        ready = [r for r in rows if r.state == "ready" and r.path]
        if ready:
            best = max(ready, key=lambda r: (bool(r.protected), r.size or 0))
            return {"state": "ready", "protected": bool(best.protected), "size": best.size}
        if rows:
            return {"state": "unsupported", "protected": False, "size": rows[0].size}
        return {"state": "missing", "protected": False, "size": None}
    # ── decisions ────────────────────────────────────────────────────────────
    def decide(
        self,
@@ -783,29 +605,11 @@ class DuplicateService:
                session.delete(link)
    def _snapshot(self, session, cluster_id) -> dict:
        """A cluster and a *bounded* preview of its members.
        The list view shows a count and a few ids; a snapshot that loaded every
        member turned one page of 200 clusters into hundreds of thousands of rows
        (US07-06). ``member_total`` is the honest count either way.
        """
        cluster = session.get(DuplicateCluster, cluster_id)
        member_total = int(
            session.scalar(
                select(func.count())
                .select_from(DuplicateMember)
                .where(DuplicateMember.cluster_id == cluster_id)
            )
            or 0
        )
        members = session.execute(
-            select(DuplicateMember)
+            select(DuplicateMember).where(DuplicateMember.cluster_id == cluster_id)
            .where(DuplicateMember.cluster_id == cluster_id)
            .order_by(DuplicateMember.asset_id)
            .limit(SNAPSHOT_MEMBER_PREVIEW)
        ).scalars()
        return {
            "member_total": member_total,
            "id": cluster.id,
            "method": cluster.method,
            "confidence": cluster.confidence,
--- a/photo_pipeline/services/exif_checkpoint.py
+++ b/photo_pipeline/services/exif_checkpoint.py
@@ -1,187 +0,0 @@
 """The EXIF checkpoint every metadata stage ends with (concept §3, US07-03).
 A stage does not own a file's metadata; it owns a few fields in it. So writing is
 never "set these tags" — it is:
    snapshot everything → write only the owned fields → read everything back
    → prove the owned fields landed → prove nothing else moved
    → refresh the file hash → record the projection
 Non-destructive here means *semantic* preservation: exiftool may rewrite the whole
 container, so the file's bytes, size, and timestamps legitimately change. What may
 not change is any field this stage does not own. When one does, the checkpoint is
 ``divergent``: the result is recorded, the stage is **not** marked verified, and
 nothing is silently repaired — a later stage that needs verified metadata (upload)
 therefore stays blocked until a human looks.
 ``failed`` is the third outcome and is deliberately distinct: exiftool missing, an
 unreadable file, or a write that did not take is not evidence that metadata is fine.
 """
 from __future__ import annotations
 import json
 import os
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from photo_pipeline.faults import EXIF_WRITTEN, maybe_fault
 from photo_pipeline.integrations import exiftool
 from photo_pipeline.models import ExifProjection
 from photo_pipeline.services import hashing
 # The tags the safety and analysis stages may change. Matched on the tag name, so
 # every group carries the same rule (IPTC:Keywords, XMP:XMP-dc:Subject, ...).
 OWNED_TAGS = frozenset({"Keywords", "Subject"})
 # Not metadata about the picture: filesystem facts, the digest that necessarily
 # moves whenever IPTC does, and the structural tags exiftool has to create the first
 # time it writes an IPTC or XMP block. Comparing these would report every write as
 # divergent and make the signal worthless.
 VOLATILE_PREFIXES = ("File:System:", "ExifTool:")
 VOLATILE_KEYS = frozenset(
    {
        "File:CurrentIPTCDigest",
        "IPTC:ApplicationRecordVersion",
        "XMP:XMP-x:XMPToolkit",
        "XMP:XMP-xmp:MetadataDate",
    }
 )
 VERIFIED = "verified"
 DIVERGENT = "divergent"
 FAILED = "failed"
@dataclass(frozen=True)
 class CheckpointResult:
    state: str  # verified | divergent | failed
    changed_fields: tuple[str, ...] = ()
    sha256: str | None = None
    # exiftool rewrites the container, so the file's size moves with its hash. Both
    # are inventory facts about the current bytes and both have to be refreshed
    # together, or the next stage compares against a size that no longer exists
    # (US07-07: a rename plan blocked itself forever after any EXIF write).
    byte_size: int | None = None
    verified_at: datetime | None = None
    reason: str | None = None
    @property
    def verified(self) -> bool:
        return self.state == VERIFIED
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def is_owned(key: str) -> bool:
    return key.rsplit(":", 1)[-1] in OWNED_TAGS
 def is_volatile(key: str) -> bool:
    return key in VOLATILE_KEYS or key.startswith(VOLATILE_PREFIXES)
 def compare(before: dict, after: dict) -> tuple[str, ...]:
    """Fields outside this stage's ownership whose value did not survive the write.
    Additions count: a tag that appears out of nowhere is as much a divergence as a
    tag that disappeared — both mean the write did more than it was asked to.
    """
    keys = set(before) | set(after)
    return tuple(
        sorted(
            key
            for key in keys
            if not is_owned(key)
            and not is_volatile(key)
            and before.get(key) != after.get(key)
        )
    )
 def owned_values(snapshot: dict) -> set[str]:
    """Lowercased Keywords/Subject values across every group in the snapshot."""
    values: set[str] = set()
    for key, value in snapshot.items():
        if not is_owned(key):
            continue
        items = value if isinstance(value, list) else [value]
        values.update(str(item).strip().lower() for item in items if item is not None)
    return values
 def run(
    path: str,
    *,
    add: tuple[str, ...] = (),
    remove: tuple[str, ...] = (),
 ) -> CheckpointResult:
    """Write the owned keywords for one asset and verify the whole file around them."""
    before = exiftool.read_all(path)
    if before is None:
        return CheckpointResult(FAILED, reason="metadata_unreadable")
    if not exiftool.apply_keywords(path, add=add, remove=remove):
        return CheckpointResult(FAILED, reason="write_failed")
    # The file on disk has changed; nothing about it is recorded yet. A crash here
    # is the worst case for metadata, so it is a fault control point (US07-04).
    maybe_fault(EXIF_WRITTEN)
    after = exiftool.read_all(path)
    if after is None:
        return CheckpointResult(FAILED, reason="readback_unreadable")
    present = owned_values(after)
    wanted = {value.strip().lower() for value in add}
    unwanted = {value.strip().lower() for value in remove}
    if not wanted <= present or (unwanted & present):
        return CheckpointResult(FAILED, reason="owned_fields_not_written")
    changed = compare(before, after)
    sha256 = hashing.sha256_file(path)
    byte_size = os.path.getsize(path)
    if changed:
        return CheckpointResult(
            DIVERGENT, changed_fields=changed, sha256=sha256, byte_size=byte_size
        )
    return CheckpointResult(VERIFIED, sha256=sha256, byte_size=byte_size, verified_at=_now())
 def record(
    session_factory,
    *,
    asset_id: str,
    stage: str,
    result: CheckpointResult,
    add: tuple[str, ...] = (),
    remove: tuple[str, ...] = (),
 ) -> None:
    """Persist the projection for ``(asset_id, stage)`` — one current row per pair.
    The row is what makes divergence durable and reviewable rather than a log line
    that scrolled away.
    """
    with session_factory() as session:
        row = session.get(ExifProjection, (asset_id, stage))
        if row is None:
            row = ExifProjection(asset_id=asset_id, stage=stage, id=str(uuid.uuid4()))
            session.add(row)
        row.projection_version = (row.projection_version or 0) + 1
        row.desired_json = json.dumps({"add": list(add), "remove": list(remove)})
        row.divergent_fields = json.dumps(list(result.changed_fields))
        row.result_file_sha256 = result.sha256
        row.state = result.state
        row.error_code = result.reason
        row.verified_at = result.verified_at
        row.updated_at = _now()
        session.commit()
 def state_for(session_factory, asset_id: str, stage: str) -> str | None:
    with session_factory() as session:
        row = session.get(ExifProjection, (asset_id, stage))
        return row.state if row else None
--- a/photo_pipeline/services/hashing.py
+++ b/photo_pipeline/services/hashing.py
@@ -16,9 +16,7 @@ from __future__ import annotations
 import hashlib
 from pathlib import Path
-from PIL import ImageOps
+from PIL import Image, ImageOps
 from photo_pipeline import imaging
 PIXEL_HASH_VERSION = 1
 PHASH_VERSION = 1
@@ -43,9 +41,7 @@ def _digest_file(path: Path | str, digest) -> str:
 def pixel_sha256(path: Path | str) -> str:
-    # Bounded decode: a header claiming a billion pixels is refused before it is
+    with Image.open(path) as image:
    # ever turned into memory (US07-03).
    with imaging.open_image(path) as image:
        oriented = ImageOps.exif_transpose(image)
        rgb = oriented.convert("RGB")
        header = f"{PIXEL_HASH_VERSION}:{rgb.width}x{rgb.height}:".encode()
@@ -72,9 +68,7 @@ def phash(path: Path | str) -> str:
    import numpy as np
    from scipy.fftpack import dct
-    from PIL import Image
+    with Image.open(path) as image:
    with imaging.open_image(path) as image:
        small = image.convert("L").resize((32, 32), Image.LANCZOS)
        matrix = np.asarray(small, dtype=np.float64)
    transformed = dct(dct(matrix, axis=0), axis=1)
--- a/photo_pipeline/services/inventory.py
+++ b/photo_pipeline/services/inventory.py
@@ -13,11 +13,8 @@ renames. Every discovered or absent path is classified as one occurrence:
 - ``missing``          — a known active asset whose file is gone (kept, flagged).
 Missing files are never pruned (that would break identity); the asset is retained
-with ``missing_at`` set and its availability becomes ``missing_unexpected`` —
+with ``missing_at`` set. Archived assets are left untouched. Rescanning unchanged
-nothing explains where the bytes went. Archived assets are left untouched: their
+input makes no durable change.
 absence from the active roots is expected, and each scan re-derives whether their
 medium is reachable (:mod:`photo_pipeline.services.availability`). Rescanning
 unchanged input makes no durable change.
 Extracted from photo_analyzer.discover_photos/reconcile_moved/prune_missing
 (see donor_ledger.yaml: pa-discovery, pa-prune-missing).
@@ -33,12 +30,12 @@ from enum import Enum
 from pathlib import Path
 from typing import Iterable
-from sqlalchemy import func, or_, select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session, sessionmaker
 from photo_pipeline import path_policy
 from photo_pipeline.models import Asset, AssetPath
-from photo_pipeline.services import availability, hashing
+from photo_pipeline.services import hashing
 class Occurrence(str, Enum):
@@ -63,8 +60,6 @@ def _asset_dict(asset: Asset) -> dict:
        "id": asset.id,
        "current_path": asset.current_path,
        "availability_state": asset.availability_state,
        "archive_location_id": asset.archive_location_id,
        "archive_path": asset.archive_path,
        "byte_size": asset.byte_size,
        "current_sha256": asset.current_sha256,
        "pixel_sha256": asset.pixel_sha256,
@@ -106,9 +101,7 @@ class InventoryService:
                result.asset_ids[str(path)] = asset.id
            for asset in assets:
-                # Archived assets are explained by their location, not by the active
+                if asset.availability_state != "active" or asset.id in seen_ids:
                # roots: a scan must never prune or flag them (concept §9).
                if asset.availability_state in availability.ARCHIVED or asset.id in seen_ids:
                    continue
                if asset.current_path and asset.current_path not in discovered_paths:
                    if not Path(asset.current_path).exists():
@@ -116,18 +109,10 @@ class InventoryService:
                            asset.missing_at = now
                            asset.state_version += 1
                            asset.updated_at = now
                        # Nothing explains this absence — it is not an offline medium.
                        if asset.availability_state != availability.MISSING_UNEXPECTED:
                            asset.availability_state = availability.MISSING_UNEXPECTED
                            asset.state_version += 1
                            asset.updated_at = now
                        result.occurrences[asset.current_path] = Occurrence.MISSING.value
            session.commit()
        # Media may have been mounted or removed since the last scan.
        availability.refresh(self._session_factory)
        result.counts = dict(Counter(result.occurrences.values()))
        return result
@@ -147,11 +132,7 @@ class InventoryService:
            if availability:
                stmt = stmt.where(Asset.availability_state == availability)
            if query:
-                like = f"%{query}%"
+                stmt = stmt.where(Asset.current_path.like(f"%{query}%"))
                # An archived asset has no active path; it is searched where it lives.
                stmt = stmt.where(
                    or_(Asset.current_path.like(like), Asset.archive_path.like(like))
                )
            total = session.scalar(select(func.count()).select_from(stmt.subquery()))
            rows = session.execute(
                stmt.order_by(Asset.current_path).limit(limit).offset(offset)
@@ -188,7 +169,6 @@ class InventoryService:
                self._open_path(session, existing.id, path_str, now, occ.value)
            if existing.missing_at is not None:
                existing.missing_at = None
                existing.availability_state = availability.ACTIVE
                existing.state_version += 1
                existing.updated_at = now
            return existing, occ
@@ -209,7 +189,6 @@ class InventoryService:
            moved_from.current_path = path_str
            moved_from.byte_size = size
            moved_from.missing_at = None
            moved_from.availability_state = availability.ACTIVE
            moved_from.state_version += 1
            moved_from.updated_at = now
            self._open_path(session, moved_from.id, path_str, now, Occurrence.MOVED.value)
--- a/photo_pipeline/services/jobs.py
+++ b/photo_pipeline/services/jobs.py
@@ -236,32 +236,17 @@ class JobService:
                raise InvalidTransition(f"{job.state} -> {to_state}")
            if worker_id is not None and job.lease_owner not in (None, worker_id):
                raise JobConflict(f"job {job_id} owned by {job.lease_owner}, not {worker_id}")
-
+            job.state = to_state
-            # Compare-and-set on the version this decision was made against. Without
+            job.version += 1
-            # it a transition validated against a row that has since been claimed,
+            job.updated_at = now
            # cancelled, or finished would overwrite that newer state (concept §16
            # database rule 6) — a cancel racing a claim used to un-claim a running
            # job and leave the worker finalizing a job it no longer owned.
            values = {
                "state": to_state,
                "version": job.version + 1,
                "updated_at": now,
            }
            if error:
-                values["error_code"], values["error_message"] = error
+                job.error_code, job.error_message = error
            if to_state in TERMINAL_STATES:
-                values.update(finished_at=now, lease_owner=None, lease_expires_at=None)
+                job.finished_at = now
-            result = session.execute(
+                job.lease_owner = None
-                update(Job).where(Job.id == job_id, Job.version == job.version).values(**values)
+                job.lease_expires_at = None
            )
            if result.rowcount != 1:
                session.rollback()
                raise JobConflict(
                    f"job {job_id} changed while transitioning to {to_state}; retry"
                )
            self._event(session, job_id, f"state:{to_state}", error[1] if error else None)
            session.commit()
            session.expire_all()  # the core UPDATE bypassed the identity map
            return self._snapshot(session, job_id)
    def cancel(self, job_id: str) -> dict:
--- a/photo_pipeline/services/legacy_import.py
+++ b/photo_pipeline/services/legacy_import.py
@@ -1,220 +0,0 @@
 """Import the last path-keyed CSV state into the database (US07-01).
 ``nsfwtag`` cached its safety scores in ``nsfw_scores.csv`` next to the library:
 one ``path,nsfw_score`` row per photo, four decimals, unreadable rows dropped. That
 file stops being a source of truth when the CLI is archived, so its scores are
 imported once — as scored-but-unreviewed ``safety_reviews`` rows on the stable
 ``assets.id`` each path resolves to — and the CSV is left untouched on disk as its
 own backup.
 The import is deliberately conservative, because a score is evidence about a photo
 and a path is not an identity:
 - a row whose path matches no known asset is **unmatched**, never a new asset;
 - an asset a human already reviewed is **never** touched: a score is evidence, a
  decision is a judgement, and an import may not overwrite the second with the
  first — the difference is reported as a conflict instead;
 - a row for an asset that already carries a score is **skipped** unless
  ``overwrite`` is asked for, and a differing score is reported either way;
 - an unparsable score or a duplicate path is **rejected** with its reason;
 - rerunning changes nothing that is already imported.
 Everything it did — and everything it refused to do — comes back as a
 reconciliation report, which the caller can persist next to the database. The
 donor's own reader is the specification for the format (donor ledger:
 ``nt-score-cache``).
 """
 from __future__ import annotations
 import csv
 import json
 import uuid
 from collections import Counter
 from dataclasses import asdict, dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.models import Asset, AssetPath, SafetyReview
 REPORT_VERSION = 1
 # The donor wrote scores as four-decimal strings; anything outside 0..1 was never
 # something it produced, so it is data corruption rather than a score.
 SCORE_RANGE = (0.0, 1.0)
 # Recorded as the reviewer so an imported score is never mistaken for a judgement.
 REVIEWER = "legacy-csv-import"
@dataclass
 class ImportReport:
    source: str
    rows: int = 0
    imported: int = 0
    skipped_existing: int = 0
    unchanged: int = 0
    reviewed: int = 0
    unmatched: list[str] = field(default_factory=list)
    rejected: list[dict] = field(default_factory=list)
    conflicts: list[dict] = field(default_factory=list)
    generated_at: str = ""
    schema_version: int = REPORT_VERSION
    def to_dict(self) -> dict:
        return asdict(self)
    @property
    def counts(self) -> dict[str, int]:
        return {
            "rows": self.rows,
            "imported": self.imported,
            "skipped_existing": self.skipped_existing,
            "unchanged": self.unchanged,
            "reviewed": self.reviewed,
            "unmatched": len(self.unmatched),
            "rejected": len(self.rejected),
            "conflicts": len(self.conflicts),
        }
 class LegacyImportService:
    def __init__(self, session_factory: sessionmaker) -> None:
        self._session_factory = session_factory
    def import_nsfw_scores(
        self, csv_path: Path | str, *, overwrite: bool = False, dry_run: bool = False
    ) -> ImportReport:
        """Import ``nsfw_scores.csv`` onto asset identity and report what happened."""
        path = Path(csv_path)
        report = ImportReport(source=str(path))
        if not path.is_file():
            report.rejected.append({"path": str(path), "reason": "csv_missing"})
            return self._stamp(report)
        with self._session_factory() as session:
            # Paths are matched against every occurrence an asset ever had, so a
            # photo scored before a rename is still recognised.
            by_path = self._path_index(session)
            latest = self._latest_reviews(session)
            seen: Counter[str] = Counter()
            for row in self._rows(path, report):
                report.rows += 1
                raw_path, raw_score = row
                seen[raw_path] += 1
                if seen[raw_path] > 1:
                    report.rejected.append({"path": raw_path, "reason": "duplicate_path"})
                    continue
                score = _parse_score(raw_score)
                if score is None:
                    report.rejected.append(
                        {"path": raw_path, "reason": "unparsable_score", "value": raw_score}
                    )
                    continue
                asset_id = by_path.get(raw_path)
                if asset_id is None:
                    report.unmatched.append(raw_path)
                    continue
                current = latest.get(asset_id)
                if current is not None and current.decision:
                    # A human decided this one; the CSV is older evidence.
                    report.reviewed += 1
                    if current.score is None or abs(current.score - score) >= 1e-9:
                        report.conflicts.append(
                            {
                                "path": raw_path,
                                "asset_id": asset_id,
                                "current": current.score,
                                "decision": current.decision,
                                "csv": score,
                            }
                        )
                    continue
                if current is not None and current.score is not None:
                    if abs(current.score - score) < 1e-9:
                        report.unchanged += 1
                        continue
                    report.conflicts.append(
                        {
                            "path": raw_path,
                            "asset_id": asset_id,
                            "current": current.score,
                            "decision": None,
                            "csv": score,
                        }
                    )
                    if not overwrite:
                        report.skipped_existing += 1
                        continue
                session.add(
                    SafetyReview(
                        id=str(uuid.uuid4()),
                        asset_id=asset_id,
                        score=score,
                        reviewer=REVIEWER,
                    )
                )
                latest[asset_id] = SafetyReview(asset_id=asset_id, score=score)
                report.imported += 1
            if dry_run:
                session.rollback()
            else:
                session.commit()
        return self._stamp(report)
    @staticmethod
    def _rows(path: Path, report: ImportReport):
        """Yield ``(path, score)`` pairs, tolerating the donor's own sloppiness."""
        with open(path, newline="", encoding="utf-8", errors="replace") as handle:
            for row in csv.DictReader(handle):
                raw_path = (row.get("path") or "").strip()
                if not raw_path:
                    report.rejected.append({"path": "", "reason": "missing_path"})
                    continue
                yield raw_path, row.get("nsfw_score")
    @staticmethod
    def _latest_reviews(session) -> dict[str, SafetyReview]:
        """The current safety row per asset — latest wins, as everywhere else."""
        latest: dict[str, SafetyReview] = {}
        for review in session.scalars(select(SafetyReview).order_by(SafetyReview.created_at)):
            latest[review.asset_id] = review
        return latest
    @staticmethod
    def _path_index(session) -> dict[str, str]:
        """Every path an asset is or was known by → its stable id."""
        index: dict[str, str] = {}
        for asset_id, path in session.execute(select(AssetPath.asset_id, AssetPath.path)):
            index.setdefault(path, asset_id)
        for asset_id, path in session.execute(select(Asset.id, Asset.current_path)):
            if path:
                index[path] = asset_id  # the current path wins over a closed one
        return index
    @staticmethod
    def _stamp(report: ImportReport) -> ImportReport:
        report.generated_at = datetime.now(timezone.utc).isoformat()
        return report
 def write_report(report: ImportReport, directory: Path) -> Path:
    """Persist the reconciliation report; the import is not evidence until it is."""
    directory.mkdir(parents=True, exist_ok=True)
    path = directory / "legacy-nsfw-import.json"
    path.write_text(json.dumps(report.to_dict(), indent=2, sort_keys=True), encoding="utf-8")
    return path
 def _parse_score(value) -> float | None:
    try:
        score = float(value)
    except (TypeError, ValueError):
        return None
    if not SCORE_RANGE[0] <= score <= SCORE_RANGE[1]:
        return None
    return score
--- a/photo_pipeline/services/library.py
+++ b/photo_pipeline/services/library.py
@@ -15,9 +15,10 @@ from __future__ import annotations
 import json
 import re
 from collections import Counter
 from pathlib import Path
-from sqlalchemy import String, and_, case, cast, func, or_, select, text
+from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.models import AnalysisResult, Asset
@@ -70,75 +71,38 @@ class LibraryService:
        return {"rows": rows, "total": total, "offset": offset, "limit": limit}
    def stats(self) -> dict:
        """Library-wide totals, aggregated in SQL (US07-06).
        This page used to load every analysis row — object, tags, and all — to count
        them in Python, which cost half a second at 100k assets and grew from there.
        Only the album breakdown still walks rows, and only their path and status:
        SQLite has no ``dirname``, and two short strings per asset is cheap.
        """
        with self._session_factory() as session:
            status = dict(
                session.execute(
                    select(AnalysisResult.status, func.count()).group_by(AnalysisResult.status)
                ).all()
            )
-            albums: dict[str, dict] = {}
+            rows = list(
-            for path, row_status in session.execute(
+                session.execute(
-                select(Asset.current_path, AnalysisResult.status).join(
+                    select(AnalysisResult, Asset.current_path).join(
                        Asset, Asset.id == AnalysisResult.asset_id
                    )
-            ):
+                )
            )
            albums: dict[str, dict] = {}
            tag_counts: Counter = Counter()
            year_counts: Counter = Counter()
            people: Counter = Counter()
            errors = []
            for result, path in rows:
                album = _album_of(path)
                bucket = albums.setdefault(album, {"album": album, "done": 0, "total": 0})
                bucket["total"] += 1
-                if row_status in DONE:
+                if result.status in DONE:
                    bucket["done"] += 1
-            year_counts = dict(
+                for tag in _tags(result.tags):
-                session.execute(
+                    tag_counts[tag] += 1
-                    select(AnalysisResult.approx_year, func.count())
+                if result.approx_year is not None:
-                    .where(AnalysisResult.approx_year.is_not(None))
+                    year_counts[result.approx_year] += 1
-                    .group_by(AnalysisResult.approx_year)
+                if result.people_count is not None:
-                ).all()
+                    people["3+" if result.people_count >= 3 else str(result.people_count)] += 1
-            )
+                if result.status == "error":
-            people = dict(
+                    errors.append({"path": path, "error": result.error_message})
                session.execute(
                    select(
                        case(
                            (AnalysisResult.people_count >= 3, "3+"),
                            else_=cast(AnalysisResult.people_count, String),
                        ),
                        func.count(),
                    )
                    .where(AnalysisResult.people_count.is_not(None))
                    .group_by(
                        case(
                            (AnalysisResult.people_count >= 3, "3+"),
                            else_=cast(AnalysisResult.people_count, String),
                        )
                    )
                ).all()
            )
            # SQLite's JSON1 counts the tag arrays where they are: parsing 50k JSON
            # strings in Python to keep the top 40 is the definition of doing work
            # the database already does. Malformed tags are skipped, not fatal.
            tag_counts = session.execute(
                text(
                    "SELECT tag.value AS value, count(*) AS total "
                    "FROM analysis_results, json_each(analysis_results.tags) AS tag "
                    "WHERE analysis_results.tags IS NOT NULL "
                    "AND json_valid(analysis_results.tags) "
                    "GROUP BY tag.value ORDER BY total DESC, value LIMIT 40"
                )
            ).all()
            errors = [
                {"path": path, "error": message}
                for path, message in session.execute(
                    select(Asset.current_path, AnalysisResult.error_message)
                    .join(Asset, Asset.id == AnalysisResult.asset_id)
                    .where(AnalysisResult.status == "error")
                )
            ]
        return {
            "total": sum(status.values()),
            "status": status,
@@ -147,7 +111,7 @@ class LibraryService:
            "season": self._facet("season"),
            "people": [{"value": v, "count": n} for v, n in sorted(people.items())],
            "years": [{"value": y, "count": year_counts[y]} for y in sorted(year_counts)],
-            "top_tags": [{"value": t, "count": n} for t, n in tag_counts],
+            "top_tags": [{"value": t, "count": n} for t, n in tag_counts.most_common(40)],
            "albums": sorted(albums.values(), key=lambda d: d["album"]),
            "errors": sorted(errors, key=lambda e: e["path"] or ""),
        }
--- a/photo_pipeline/services/release.py
+++ b/photo_pipeline/services/release.py
@@ -1,399 +0,0 @@
 """The release gate, the real-library dry run, and the approval that unlocks
 mutation (US07-07, concept §18 release gates).
 Three things live here because they are one decision:
 1. **The gate** — one command that provisions an isolated stack, runs every suite in
   a fixed order, and retains versioned evidence with checksums. A release is not
   "the tests passed on my machine last Tuesday"; it is a report that says which
   revision, which suites, how long, and what the artefacts hash to.
 2. **The dry run** — a strictly read-only pass over the real photo library that
   answers "what would this application do to it?" before it is allowed to do
   anything. It opens no file for writing, creates no database rows, and touches no
   metadata; it counts, classifies, and reconciles against whatever the database
   already knows.
 3. **The approval** — a person reads that report and signs it off for exactly the
   library roots it describes. Until then, with
   ``PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL`` set, every mutating request is
   refused. Change the roots, or produce a newer report, and the approval no longer
   matches: it approves *that* reconciliation, not the idea of mutating.
 """
 from __future__ import annotations
 import hashlib
 import json
 import os
 import subprocess
 import sys
 import time
 from collections import Counter
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from photo_pipeline import path_policy
 from photo_pipeline.config import Config
 SCHEMA_VERSION = 1
 APPROVAL_NAME = "dry-run-approval.json"
 CHECKSUMS_NAME = "CHECKSUMS.sha256"
 REPORT_NAME = "release-report.json"
 # The suites, in the order a failure is cheapest to read: units before the stacks
 # they compose. ``label`` is what the report and the operator see.
 STAGES: tuple[tuple[str, tuple[str, ...]], ...] = (
    ("unit", ("tests/unit",)),
    ("characterization", ("tests/characterization",)),
    ("integration", ("tests/integration",)),
    ("browser", ("tests/e2e",)),
 )
 # Skips the gate accepts, because they describe the machine rather than the code. The
 # container ones (US08-02) belong here for the same reason exiftool does: the image
 # build needs a Docker daemon and the network, and its definition is still checked
 # offline in tests/integration/test_container_image.py.
 ALLOWED_SKIP_REASONS = (
    "exiftool not installed",
    "root ignores directory permissions",
    "no Docker daemon available",
    "bind-mount ownership is virtualised",
 )
 class ReleaseError(RuntimeError):
    pass
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()
 def sha256_bytes(payload: bytes) -> str:
    return hashlib.sha256(payload).hexdigest()
 def revision() -> str | None:
    """The commit this gate ran against, when the tree is a git checkout."""
    try:
        result = subprocess.run(
            ["git", "rev-parse", "HEAD"],
            capture_output=True,
            text=True,
            timeout=10,
            cwd=str(Path(__file__).resolve().parents[2]),
        )
    except (OSError, subprocess.SubprocessError):
        return None
    return result.stdout.strip() or None
 # ── the story matrix ─────────────────────────────────────────────────────────
 def story_matrix(repo: Path | None = None) -> dict:
    """Every backlog story, and how it is covered.
    A story is ``delivered`` (mapped to test files that exist) or ``planned`` (an
    accepted, not-yet-implemented story). Anything else — a story file nobody
    mapped, or a mapping to a file that is gone — is a hole in the matrix, and the
    gate fails on it rather than reporting a green run over missing coverage.
    """
    repo = repo or Path(__file__).resolve().parents[2]
    traceability = json.loads((repo / "tests" / "story_traceability.json").read_text())
    mapped: dict[str, list[str]] = traceability["stories"]
    planned: list[str] = traceability.get("planned", [])
    stories = sorted(
        "-".join(path.stem.split("-")[:2])
        for path in (repo / "delivery_backlog" / "stories").glob("US*.md")
    )
    missing_tests = [
        f"{story}: {rel}"
        for story, files in mapped.items()
        for rel in files
        if not (repo / rel).is_file()
    ]
    unmapped = [s for s in stories if s not in mapped and s not in planned]
    unknown = [s for s in list(mapped) + planned if s not in stories]
    overlap = sorted(set(mapped) & set(planned))
    return {
        "stories": len(stories),
        "delivered": sorted(mapped),
        "planned": sorted(planned),
        "problems": [
            *(f"story with no tests and not planned: {s}" for s in unmapped),
            *(f"mapped test file is missing — {entry}" for entry in missing_tests),
            *(f"mapped story is not in the backlog: {s}" for s in unknown),
            *(f"story is both delivered and planned: {s}" for s in overlap),
        ],
    }
 # ── the gate ─────────────────────────────────────────────────────────────────
@dataclass
 class StageResult:
    label: str
    command: list[str]
    returncode: int
    seconds: float
    summary: str
    skipped: list[str]
    def as_dict(self) -> dict:
        return {
            "stage": self.label,
            "command": self.command,
            "returncode": self.returncode,
            "seconds": round(self.seconds, 2),
            "summary": self.summary,
            "skipped": self.skipped,
            "ok": self.returncode == 0,
        }
 def _run_stage(label: str, paths: tuple[str, ...], *, repo: Path, log_dir: Path) -> StageResult:
    command = [sys.executable, "-m", "pytest", *paths, "-q", "-rs"]
    started = time.monotonic()
    result = subprocess.run(command, cwd=str(repo), capture_output=True, text=True)
    elapsed = time.monotonic() - started
    output = result.stdout + result.stderr
    (log_dir / f"{label}.log").write_text(output)
    lines = [line for line in output.splitlines() if line.strip()]
    summary = lines[-1] if lines else ""
    skipped = [line for line in lines if line.startswith("SKIPPED")]
    return StageResult(label, command, result.returncode, elapsed, summary, skipped)
 def unexpected_skips(results: list[StageResult]) -> list[str]:
    """Skips the gate will not accept: everything but the documented environment ones."""
    return [
        line
        for result in results
        for line in result.skipped
        if not any(reason in line for reason in ALLOWED_SKIP_REASONS)
    ]
 def run_gate(
    config: Config,
    *,
    output: Path | str | None = None,
    stages: tuple[tuple[str, tuple[str, ...]], ...] = STAGES,
    repo: Path | None = None,
 ) -> dict:
    """Run every suite in an isolated stack and retain checksummed evidence.
    The stack is isolated by construction: each pytest run builds its own temporary
    data directories and libraries, so the gate never reads or writes the operator's
    photos. What it keeps afterwards is the report, the per-stage logs, and a
    checksum file over both.
    """
    repo = repo or Path(__file__).resolve().parents[2]
    directory = Path(output) if output else Path(config.data_dir) / "release" / _now().strftime(
        "%Y%m%dT%H%M%SZ"
    )
    logs = directory / "logs"
    logs.mkdir(parents=True, exist_ok=True)
    matrix = story_matrix(repo)
    results = [_run_stage(label, paths, repo=repo, log_dir=logs) for label, paths in stages]
    skips = unexpected_skips(results)
    report = {
        "schema_version": SCHEMA_VERSION,
        "started_at": _now().isoformat(),
        "revision": revision(),
        "python": sys.version.split()[0],
        "platform": os.uname().sysname,
        "matrix": matrix,
        "stages": [result.as_dict() for result in results],
        "unexpected_skips": skips,
        "failures": [result.label for result in results if result.returncode != 0],
    }
    report["ok"] = not report["failures"] and not matrix["problems"] and not skips
    report["finished_at"] = _now().isoformat()
    (directory / REPORT_NAME).write_text(json.dumps(report, indent=2))
    # The evidence is only evidence if it can be shown to be the evidence that was
    # produced. Checksums are the honest version of "signed" without a key: a real
    # signature belongs to whatever key management the release actually has.
    checksums = "\n".join(
        f"{sha256_file(path)}  {path.relative_to(directory)}"
        for path in sorted(directory.rglob("*"))
        if path.is_file() and path.name != CHECKSUMS_NAME
    )
    (directory / CHECKSUMS_NAME).write_text(checksums + "\n")
    report["evidence"] = str(directory)
    return report
 # ── the real-library dry run ─────────────────────────────────────────────────
 def dry_run(config: Config, *, roots: tuple[Path, ...] | None = None) -> dict:
    """Read-only reconciliation of the configured library. Changes nothing.
    Opens no file for writing, writes no database row, and reads only what
    ``os.stat`` and the existing database already say. The point is to be able to
    look at a real library — the one with the irreplaceable photos in it — and see
    what the application believes about it before it is allowed to act.
    """
    roots = roots or tuple(Path(root) for root in config.library_roots)
    if not roots:
        raise ReleaseError("no library roots are configured")
    by_extension: Counter = Counter()
    folders: set[str] = set()
    files: list[str] = []
    unreadable: list[str] = []
    excluded = 0
    total_bytes = 0
    for root in roots:
        if not Path(root).is_dir():
            raise ReleaseError(f"library root {root} is not a directory")
        for path in sorted(Path(root).rglob("*")):
            if path.is_dir():
                # Never traverse into an excluded directory, and never report its
                # contents: proving exclusion must not require opening it.
                if path_policy.is_excluded(path):
                    excluded += 1
                continue
            if path_policy.is_excluded(path):
                continue
            try:
                stat = path.stat()
            except OSError:
                unreadable.append(str(path))
                continue
            files.append(str(path))
            folders.add(str(path.parent))
            by_extension[path.suffix.lower() or "(none)"] += 1
            total_bytes += stat.st_size
    known = _known_paths(config)
    on_disk = set(files)
    report = {
        "schema_version": SCHEMA_VERSION,
        "generated_at": _now().isoformat(),
        "revision": revision(),
        "library_roots": [str(root) for root in roots],
        "files": len(files),
        "folders": len(folders),
        "bytes": total_bytes,
        "excluded_directories": excluded,
        "unreadable": unreadable,
        "by_extension": dict(sorted(by_extension.items())),
        "reconciliation": {
            "known_to_database": len(known),
            "already_registered": len(on_disk & known),
            "new_to_the_application": len(on_disk - known),
            "recorded_but_absent": sorted(known - on_disk)[:100],
            "recorded_but_absent_total": len(known - on_disk),
        },
        "mutation": "none — this pass is read-only",
    }
    report["checksum"] = sha256_bytes(
        json.dumps(report, sort_keys=True).encode("utf-8")
    )
    return report
 def _known_paths(config: Config) -> set[str]:
    """Current asset paths the database holds, or an empty set if there is none."""
    if not config.database_path.exists():
        return set()
    from sqlalchemy import select
    from photo_pipeline.db import create_db_engine, create_session_factory
    from photo_pipeline.models import Asset
    engine = create_db_engine(config.database_url)
    try:
        with create_session_factory(engine)() as session:
            return {
                path
                for path in session.scalars(select(Asset.current_path))
                if path is not None
            }
    except Exception:
        return set()
    finally:
        engine.dispose()
 # ── the approval ─────────────────────────────────────────────────────────────
 def approval_path(config: Config) -> Path:
    return Path(config.data_dir) / APPROVAL_NAME
 def approve(config: Config, report: dict | Path | str, *, approver: str) -> dict:
    """Record that a person read this reconciliation and accepts mutation for it."""
    if isinstance(report, (str, Path)):
        report = json.loads(Path(report).read_text())
    if "checksum" not in report:
        raise ReleaseError("this is not a dry-run report: it has no checksum")
    record = {
        "schema_version": SCHEMA_VERSION,
        "approved_at": _now().isoformat(),
        "approved_by": approver,
        "report_checksum": report["checksum"],
        "library_roots": report["library_roots"],
        "files": report["files"],
        "revision": report.get("revision"),
    }
    path = approval_path(config)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(record, indent=2))
    return record
 def mutation_blockers(config: Config) -> list[dict]:
    """Why mutation must stay refused, or an empty list.
    Only enforced when ``require_dry_run_approval`` is configured — the loopback
    developer setup keeps working unchanged, and an operator turns this on before
    pointing the application at the library they cannot replace.
    """
    if not config.require_dry_run_approval:
        return []
    path = approval_path(config)
    if not path.exists():
        return [
            {
                "code": "dry_run_not_approved",
                "message": (
                    "run `python -m photo_pipeline dry-run` and approve its report "
                    "before mutation is enabled"
                ),
            }
        ]
    try:
        record = json.loads(path.read_text())
    except ValueError:
        return [{"code": "approval_unreadable", "message": f"{path} is not readable JSON"}]
    approved_roots = [str(root) for root in record.get("library_roots", [])]
    configured = [str(root) for root in config.library_roots]
    if sorted(approved_roots) != sorted(configured):
        return [
            {
                "code": "approval_scope_mismatch",
                "message": (
                    f"the approval covers {approved_roots}, but the configured library "
                    f"is {configured}; run a new dry run"
                ),
            }
        ]
    return []
--- a/photo_pipeline/services/rename_apply.py
+++ b/photo_pipeline/services/rename_apply.py
@@ -46,11 +46,9 @@ from pathlib import Path
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.faults import maybe_fault
 from photo_pipeline.models import Asset, AssetPath, RenamePlan
 from photo_pipeline.services import hashing
 from photo_pipeline.services.rename_journal import (
    ALLOWED_TRANSITIONS,
    MANUAL,
    RESUMABLE,
    JournalState,
@@ -85,6 +83,18 @@ def _now() -> datetime:
    return datetime.now(timezone.utc)
 def maybe_fault(state: str) -> None:
    """Test-only crash barrier (concept §18 fault injection).
    When ``PHOTO_PIPELINE_FAULT_AFTER`` names a journal state, the process dies
    abruptly the moment that state has been persisted — modelling a real kill at
    exactly that transition. Never set outside tests. Shared with the archive
    transfer journal (US06-02), which uses the same env var and its own state names.
    """
    if os.environ.get("PHOTO_PIPELINE_FAULT_AFTER") == state:
        os._exit(9)
 class RenameApplyService:
    def __init__(self, session_factory: sessionmaker, *, library_roots: tuple = ()) -> None:
        self._session_factory = session_factory
@@ -133,10 +143,20 @@ class RenameApplyService:
                self._apply_one(operation, token=token, worker_id=worker_id)
                applied += 1
            except PreconditionFailed as error:
-                self._record_failure(operation["id"], token, error.code, str(error))
+                self.journal.transition(
                    operation["id"],
                    JournalState.FAILED,
                    fencing_token=token,
                    error=(error.code, str(error)),
                )
                failed += 1
            except Exception as error:  # unexpected: record and stop touching disk
-                self._record_failure(operation["id"], token, "apply_error", str(error))
+                self.journal.transition(
                    operation["id"],
                    JournalState.FAILED,
                    fencing_token=token,
                    error=("apply_error", str(error)),
                )
                failed += 1
        state = self.journal.sync_plan_state(plan_id)
        return {
@@ -147,26 +167,6 @@ class RenameApplyService:
            "state": state,
        }
    def _record_failure(self, operation_id: str, token: int, code: str, message: str) -> None:
        """Record a failed operation in a state its journal can actually reach.
        ``failed`` only makes sense while nothing has moved. Once the folder is at
        its destination — a postcondition failure such as bytes edited during the
        move — the operation is not "failed and forgotten": the disk changed and
        the database followed, so it becomes ``rollback_required`` and waits for a
        human (US07-04). Guessing an unreachable transition used to raise out of
        ``apply`` and lose the record entirely.
        """
        current = self.journal.get(operation_id)["journal_state"]
        target = (
            JournalState.FAILED
            if JournalState.FAILED in ALLOWED_TRANSITIONS.get(current, set())
            else JournalState.ROLLBACK_REQUIRED
        )
        self.journal.transition(
            operation_id, target, fencing_token=token, error=(code, message)
        )
    def _apply_one(self, operation: dict, *, token: int, worker_id: str) -> None:
        source = Path(operation["source_path"])
        destination = Path(operation["destination_path"])
--- a/photo_pipeline/services/rename_journal.py
+++ b/photo_pipeline/services/rename_journal.py
@@ -81,17 +81,7 @@ ALLOWED_TRANSITIONS = {
 TERMINAL_STATES = frozenset({JournalState.COMPLETE, JournalState.ROLLED_BACK})
 # States where the disk may already have been touched by this operation.
-# ``rollback_required`` belongs here too (US07-04): the move happened and someone
+UNSAFE_STATES = frozenset({JournalState.MOVING, JournalState.MOVED, JournalState.DATABASE_UPDATED})
 # has to decide what to do about it, so the library is not in a state another
 # mutation may build on.
 UNSAFE_STATES = frozenset(
    {
        JournalState.MOVING,
        JournalState.MOVED,
        JournalState.DATABASE_UPDATED,
        JournalState.ROLLBACK_REQUIRED,
    }
 )
 RESUMABLE = "resumable"
 ROLLBACK_SAFE = "rollback_safe"
--- a/photo_pipeline/services/restores.py
+++ b/photo_pipeline/services/restores.py
@@ -1,651 +0,0 @@
 """RestoreService — plan and execute safe restores (US06-04).
 Restore is archiving read backwards, with one decisive difference: it removes
 nothing. The archived copy stays on its medium, so every failure mode here costs
 at most a discarded temporary file. What restore must never do is *lose identity*
 — the asset that comes back is the same asset, with its duplicate decision, safety
 review, analysis, and upload history intact — or *overwrite* something in the
 active library.
 Preflight proves, per concept §9 "Restore":
 - the recorded medium is mounted and is the right one (marker ``media_id``);
 - every selected asset is archived, its archive copy exists, and it hashes to
  exactly the bytes the database recorded — a mismatch is ``divergent`` and is
  refused, never silently accepted as "the file";
 - the destination lies inside the library, outside ``_IGNORE/``, and is free; a
  taken path is answered with a collision-free name, never an overwrite;
 - the library filesystem has room for the scope plus the configured reserve;
 - no rename, archive, or restore lease is holding the lane.
 Blocker codes: ``no_library_root``, ``location_offline``, ``wrong_volume``,
 ``unsafe_destination``, ``library_not_writable``, ``insufficient_capacity``,
 ``lock_conflict``, ``rename_pending``, ``archive_pending``, ``empty_scope``,
 ``not_archived``, ``archive_missing``, ``bytes_changed``.
 Per item the sequence is:
 ```
 journal.begin (transferring)   ← intent persisted BEFORE any disk change
 recheck: medium, hash, free destination, asset still archived
 copy to a temporary file beside the destination, fsync, hash it back
 atomically publish into the library
 journal → verified
 current_path = destination, availability = active, path occurrence opened
 journal → complete
 ```
 Like archiving, the confirmation token is derived from the report, so a changed
 scope, a swapped medium, or a destination that filled up invalidates it.
 """
 from __future__ import annotations
 import hashlib
 import json
 import os
 import shutil
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.config import Config
 from photo_pipeline.faults import maybe_fault
 from photo_pipeline.jobs.domain_handlers import ARCHIVE_LOCK, LIBRARY_WRITE_LOCK, UPLOAD_LOCK
 from photo_pipeline.models import ArchiveLocation, ArchiveOperation, ArchivePlan, Asset, AssetPath
 from photo_pipeline.path_policy import PathPolicyError, is_excluded, normalize_root, resolve_within
 from photo_pipeline.services import availability
 from photo_pipeline.services.archive_journal import (
    MANUAL,
    RESTORE,
    RESUMABLE,
    ArchiveJournal,
    ArchiveState,
 )
 from photo_pipeline.services.archive_transfer import (
    _clean_temp_files,
    _fsync_dir,
    _plan_dict,
    copy_verify_publish,
 )
 from photo_pipeline.services.archives import ArchiveError
 from photo_pipeline.services.hashing import sha256_file
 from photo_pipeline.services.jobs import JobService
 from photo_pipeline.services.rename_apply import PreconditionFailed
 from photo_pipeline.services.rename_journal import RenameJournal
 PREFLIGHT_VERSION = 1
 TOKEN_PREFIX = f"r{PREFLIGHT_VERSION}"
 # What a restored file is called when its original name is taken. The suffix is
 # visible on purpose: a restore that quietly reuses a name is indistinguishable
 # from an overwrite.
 RESTORED_SUFFIX = "restored"
 LOCKS = (LIBRARY_WRITE_LOCK, UPLOAD_LOCK, ARCHIVE_LOCK)
 APPLYABLE_PLAN_STATES = frozenset({"planned", "applying", "failed", "complete"})
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def _issue(code: str, message: str) -> dict:
    return {"code": code, "message": message}
 class RestoreService:
    def __init__(self, session_factory: sessionmaker, *, config: Config) -> None:
        self._session_factory = session_factory
        self._config = config
        self._roots = tuple(normalize_root(root) for root in config.library_roots)
        self.journal = ArchiveJournal(session_factory)
    # ── preflight ─────────────────────────────────────────────────────────────
    def preflight(self, location_id: str, asset_ids: list[str] | None = None) -> dict:
        """Validate a restore scope and issue its token. Nothing is written."""
        with self._session_factory() as session:
            location = session.get(ArchiveLocation, location_id)
            if location is None:
                raise ArchiveError("unknown_location", f"unknown archive location {location_id!r}")
            root = Path(location.root)
            online = availability.location_online(location)
            marker = availability.read_marker(root)
            report = {
                "schema_version": PREFLIGHT_VERSION,
                "location": {
                    "id": location.id,
                    "name": location.name,
                    "root": str(root),
                    "media_id": location.media_id,
                    "state": _location_state(root, marker, location.media_id),
                },
                "blockers": [],
            }
            items = self._items(session, location, asset_ids, reachable=online)
        report["blockers"] += self._destination_blockers(report["location"]["state"], root)
        report["blockers"] += self._lock_blockers()
        report["items"] = items
        report["totals"] = {
            "assets": len(items),
            "blocked": sum(1 for item in items if item["blockers"]),
            "bytes": sum(item["byte_size"] or 0 for item in items),
        }
        report["capacity"] = self._capacity(report["totals"]["bytes"])
        if not report["capacity"]["sufficient"]:
            report["blockers"].append(
                _issue(
                    "insufficient_capacity",
                    # No free-space number here: it drifts between two identical
                    # preflights and the token is a digest of this text (US06-06).
                    f"{report['totals']['bytes']} B plus a "
                    f"{self._config.archive_free_space_reserve_bytes} B reserve do not fit in "
                    "the library",
                )
            )
        if not items:
            report["blockers"].append(
                _issue("empty_scope", "no archived assets are in the selected scope")
            )
        report["state"] = (
            "ready"
            if not report["blockers"] and not report["totals"]["blocked"]
            else "blocked"
        )
        report["token"] = _token(report)
        report["generated_at"] = _now().isoformat()
        return report
    def verify_token(self, token: str, location_id: str, asset_ids: list[str] | None = None) -> bool:
        return bool(token) and token == self.preflight(location_id, asset_ids)["token"]
    def _items(
        self, session, location: ArchiveLocation, asset_ids: list[str] | None, *, reachable: bool
    ) -> list[dict]:
        stmt = select(Asset).where(Asset.archive_location_id == location.id)
        if asset_ids is None:
            # A restored asset keeps its archive link; the default scope is only what
            # is still archived, so restoring twice is an empty scope, not a blocker.
            stmt = stmt.where(Asset.availability_state.in_(availability.ARCHIVED))
        else:
            stmt = stmt.where(Asset.id.in_(asset_ids))
        assets = list(session.scalars(stmt.order_by(Asset.archive_path)))
        if asset_ids is not None:
            unknown = sorted(set(asset_ids) - {asset.id for asset in assets})
            if unknown:
                raise ArchiveError(
                    "unknown_asset", f"not archived at this location: {', '.join(unknown)}"
                )
        taken: set[str] = set()
        return [self._item(asset, location, reachable=reachable, taken=taken) for asset in assets]
    def _item(self, asset: Asset, location: ArchiveLocation, *, reachable: bool, taken: set) -> dict:
        source = Path(location.root) / (asset.archive_path or "")
        blockers: list[dict] = []
        archive_sha256 = None
        if asset.availability_state not in availability.ARCHIVED:
            blockers.append(
                _issue("not_archived", f"asset {asset.id} is {asset.availability_state}")
            )
        if reachable:
            if not source.exists():
                blockers.append(_issue("archive_missing", f"{source} is not on the medium"))
            else:
                archive_sha256 = sha256_file(source)
                if asset.current_sha256 and archive_sha256 != asset.current_sha256:
                    blockers.append(
                        _issue(
                            "bytes_changed",
                            f"{source} holds bytes that are not the recorded ones; "
                            "the archived copy is divergent",
                        )
                    )
        destination, destination_blockers = self._destination(asset, taken)
        blockers += destination_blockers
        if destination is not None:
            taken.add(str(destination))
        return {
            "asset_id": asset.id,
            "archive_path": asset.archive_path,
            "source_path": str(source),
            "destination_path": str(destination) if destination else None,
            "expected_sha256": asset.current_sha256,
            "archive_sha256": archive_sha256,
            "byte_size": asset.byte_size,
            "availability_state": asset.availability_state,
            "blockers": blockers,
        }
    def _destination(self, asset: Asset, taken: set) -> tuple[Path | None, list[dict]]:
        """A free path inside the library that mirrors the archived layout.
        Restoring onto an existing file is never an option, so a taken name is
        answered with ``name (restored).ext`` — visible, ordinary, and impossible to
        confuse with an overwrite.
        """
        if not self._roots:
            return None, [_issue("no_library_root", "no library root is configured")]
        root = self._roots[0]
        try:
            candidate = resolve_within(root, root / (asset.archive_path or ""))
        except PathPolicyError as error:
            return None, [_issue("unsafe_destination", str(error))]
        if is_excluded(candidate):
            return None, [
                _issue("unsafe_destination", f"{candidate} is inside an excluded (_IGNORE/) tree")
            ]
        return _free_path(candidate, taken), []
    def _destination_blockers(self, state: str, root: Path) -> list[dict]:
        blockers: list[dict] = []
        if not self._roots:
            blockers.append(_issue("no_library_root", "no library root is configured"))
        elif not os.access(self._roots[0], os.W_OK):
            blockers.append(
                _issue("library_not_writable", f"{self._roots[0]} is not writable")
            )
        if state == "offline":
            blockers.append(
                _issue("location_offline", f"the archive medium is not mounted at {root}")
            )
        elif state == "wrong_volume":
            blockers.append(_issue("wrong_volume", f"{root} holds a different archive medium"))
        return blockers
    def _lock_blockers(self) -> list[dict]:
        blockers: list[dict] = []
        jobs = JobService(self._session_factory)
        for lock in LOCKS:
            held = jobs.blockers(lock)
            if held:
                blockers.append(
                    _issue("lock_conflict", f"the {lock} lane is busy: job {held[0]['id']}")
                )
        if RenameJournal(self._session_factory).blocks_mutation():
            blockers.append(
                _issue("rename_pending", "an unresolved rename must be recovered before restoring")
            )
        if self.journal.blocks_mutation():
            blockers.append(
                _issue(
                    "archive_pending",
                    "an unresolved archive or restore must be recovered before restoring",
                )
            )
        return blockers
    def _capacity(self, required: int) -> dict:
        reserve = self._config.archive_free_space_reserve_bytes
        free = shutil.disk_usage(self._roots[0]).free if self._roots else None
        return {
            "required_bytes": required,
            "reserve_bytes": reserve,
            "free_bytes": free,
            "sufficient": free is not None and free >= required + reserve,
        }
    # ── plans ─────────────────────────────────────────────────────────────────
    def create(self, location_id: str, asset_ids: list[str] | None = None, *, token: str) -> dict:
        preflight = self.preflight(location_id, asset_ids)
        if not token or token != preflight["token"]:
            raise ArchiveError("stale_token", "the restore preflight changed since it was approved")
        if preflight["state"] != "ready":
            codes = ", ".join(sorted({issue["code"] for issue in preflight["blockers"]})) or "-"
            blocked = sorted(
                {issue["code"] for item in preflight["items"] for issue in item["blockers"]}
            )
            raise ArchiveError(
                "blocked", f"the restore scope is blocked: {', '.join(blocked) or codes}"
            )
        plan_id = str(uuid.uuid4())
        with self._session_factory() as session:
            session.add(
                ArchivePlan(
                    id=plan_id,
                    location_id=location_id,
                    token=token,
                    albums=json.dumps(asset_ids) if asset_ids is not None else None,
                    direction=RESTORE,
                    state="planned",
                    schema_version=PREFLIGHT_VERSION,
                    asset_count=preflight["totals"]["assets"],
                    byte_size=preflight["totals"]["bytes"],
                )
            )
            session.flush()
            for sequence, item in enumerate(preflight["items"]):
                session.add(
                    ArchiveOperation(
                        id=str(uuid.uuid4()),
                        plan_id=plan_id,
                        direction=RESTORE,
                        sequence=sequence,
                        album=Path(item["archive_path"]).parent.name or "(root)",
                        asset_id=item["asset_id"],
                        source_path=item["source_path"],
                        destination_path=item["destination_path"],
                        archive_path=item["archive_path"],
                        expected_sha256=item["expected_sha256"],
                        byte_size=item["byte_size"],
                        journal_state=ArchiveState.PLANNED,
                    )
                )
            session.commit()
        return self.get(plan_id)
    def get(self, plan_id: str) -> dict | None:
        with self._session_factory() as session:
            plan = session.get(ArchivePlan, plan_id)
            if plan is None or plan.direction != RESTORE:
                return None
            report = _plan_dict(plan)
        report["operations"] = self.journal.operations(plan_id)
        return report
    def list(self) -> list[dict]:
        with self._session_factory() as session:
            rows = session.scalars(
                select(ArchivePlan)
                .where(ArchivePlan.direction == RESTORE)
                .order_by(ArchivePlan.created_at)
            )
            return [_plan_dict(row) for row in rows]
    # ── apply ─────────────────────────────────────────────────────────────────
    def apply(
        self, plan_id: str, *, expected_version: int | None = None, worker_id: str = "restore"
    ) -> dict:
        plan = self._require_plan(plan_id)
        if expected_version is not None and plan["version"] != expected_version:
            raise ArchiveError(
                "stale_plan",
                f"plan {plan_id} is at version {plan['version']}, expected {expected_version}",
            )
        if plan["state"] not in APPLYABLE_PLAN_STATES:
            raise ArchiveError("invalid_state", f"plan {plan_id} is {plan['state']}")
        blocking = [row for row in self.journal.incomplete() if row["plan_id"] != plan_id]
        if blocking:
            raise ArchiveError(
                "archive_pending",
                f"another archive operation is unresolved ({blocking[0]['id']}); recover it first",
            )
        token = self._claim_plan(plan_id)
        location = self._location(plan["location_id"])
        restored = failed = skipped = 0
        for operation in self.journal.operations(plan_id):
            if operation["journal_state"] == ArchiveState.COMPLETE:
                skipped += 1
                continue
            try:
                if operation["journal_state"] == ArchiveState.VERIFIED:
                    self._finish(operation, token=token)
                else:
                    self._restore_one(operation, location, token=token, worker_id=worker_id)
                restored += 1
            except PreconditionFailed as error:
                self._fail(operation, token, error.code, str(error))
                failed += 1
            except Exception as error:  # unexpected: record and stop touching disk
                self._fail(operation, token, "restore_error", str(error))
                failed += 1
        state = self.journal.sync_plan_state(plan_id)
        return {
            "plan_id": plan_id,
            "restored": restored,
            "failed": failed,
            "skipped": skipped,
            "state": state,
        }
    def _restore_one(self, operation: dict, location: dict, *, token: int, worker_id: str) -> None:
        source = Path(operation["source_path"])
        destination = Path(operation["destination_path"])
        # 1. Intent first; from here a crash is resolvable from journal + disk.
        self.journal.begin(operation["id"], worker_id=worker_id, fencing_token=token)
        maybe_fault(ArchiveState.TRANSFERRING)
        # 2. Recheck against the medium and the library as they are right now.
        self._recheck(operation, source, destination, location)
        destination.parent.mkdir(parents=True, exist_ok=True)
        # 3. Always copy: the archived original stays on its medium.
        copy_verify_publish(source, destination, operation["expected_sha256"])
        _fsync_dir(destination.parent)
        if sha256_file(destination) != operation["expected_sha256"]:
            raise PreconditionFailed(
                "restore_mismatch", f"{destination} does not hold the expected bytes"
            )
        self.journal.transition(operation["id"], ArchiveState.VERIFIED, fencing_token=token)
        maybe_fault(ArchiveState.VERIFIED)
        self._finish(self.journal.get(operation["id"]), token=token)
    def _finish(self, operation: dict, *, token: int) -> None:
        """Publish the restored file to the database. Idempotent, so recovery may
        replay it after a crash between the copy and the bookkeeping."""
        destination = Path(operation["destination_path"])
        if not destination.exists() or sha256_file(destination) != operation["expected_sha256"]:
            raise PreconditionFailed(
                "restore_unverified", f"{destination} is not a verified restored copy"
            )
        self._record_restored(operation, destination)
        self.journal.transition(operation["id"], ArchiveState.COMPLETE, fencing_token=token)
        maybe_fault(ArchiveState.COMPLETE)
    def _recheck(self, operation: dict, source: Path, destination: Path, location: dict) -> None:
        root = Path(location["root"])
        if not root.is_dir() or not (root / availability.MARKER_NAME).exists():
            raise PreconditionFailed("location_offline", f"{root} is not the archive medium")
        if not source.exists():
            raise PreconditionFailed("archive_missing", f"{source} is not on the medium")
        if source.is_symlink() or destination.is_symlink():
            raise PreconditionFailed("symlink", "refusing to restore through a symlink")
        if destination.exists():
            # Never overwrite: the plan's free path was taken since it was made.
            raise PreconditionFailed(
                "destination_exists", f"destination {destination} is occupied"
            )
        if not self._inside_library(destination):
            raise PreconditionFailed(
                "destination_escape", f"{destination} is outside the library roots"
            )
        if sha256_file(source) != operation["expected_sha256"]:
            self._mark_divergent(operation["asset_id"])
            raise PreconditionFailed(
                "bytes_changed", f"{source} changed since the plan was approved"
            )
        with self._session_factory() as session:
            asset = session.get(Asset, operation["asset_id"])
            if asset is None or asset.availability_state not in availability.ARCHIVED:
                raise PreconditionFailed(
                    "not_archived", f"asset {operation['asset_id']} is no longer archived"
                )
    def _inside_library(self, destination: Path) -> bool:
        for root in self._roots:
            try:
                resolve_within(root, destination)
                return True
            except PathPolicyError:
                continue
        return False
    # ── database ──────────────────────────────────────────────────────────────
    def _record_restored(self, operation: dict, destination: Path) -> None:
        """The bytes are back in the library: open the new active occurrence and set
        availability. Identity, decisions, and history are untouched — that is the
        entire point of restoring rather than re-importing."""
        now = _now()
        with self._session_factory() as session:
            asset = session.get(Asset, operation["asset_id"])
            if asset is None:
                raise PreconditionFailed(
                    "asset_missing", f"asset {operation['asset_id']} no longer exists"
                )
            # A restored asset may be returning to a path it once held, so only an
            # *open* occurrence counts as already registered — that is what keeps
            # recovery idempotent without collapsing the path history.
            recorded = session.scalar(
                select(AssetPath).where(
                    AssetPath.asset_id == asset.id,
                    AssetPath.path == str(destination),
                    AssetPath.valid_until.is_(None),
                )
            )
            if recorded is None:  # idempotent: recovery may replay this
                session.add(
                    AssetPath(
                        asset_id=asset.id,
                        path=str(destination),
                        valid_from=now,
                        reason="restore",
                    )
                )
            asset.current_path = str(destination)
            asset.availability_state = availability.ACTIVE
            asset.missing_at = None
            # The archive copy stays where it is; keeping the link means a restored
            # asset still knows which medium holds its archived bytes.
            asset.archive_divergent_at = None
            asset.state_version += 1
            asset.updated_at = now
            session.commit()
    def _mark_divergent(self, asset_id: str) -> None:
        """Record that the archived copy is not the recorded file. Durable, because
        the next restore attempt must not rediscover this from scratch."""
        with self._session_factory() as session:
            asset = session.get(Asset, asset_id)
            if asset is None:
                return
            asset.archive_divergent_at = _now()
            asset.state_version += 1
            session.commit()
    # ── recovery ──────────────────────────────────────────────────────────────
    def recover(self, *, worker_id: str = "restore-recovery") -> dict:
        """Resolve every incomplete restore from journal + disk evidence.
        A restore never removed anything, so ``resumable`` simply discards the
        temporary debris and re-plans the item; ``forward`` finishes the bookkeeping
        for a published file; ``manual`` is left untouched and keeps blocking.
        """
        results = {"resumed": 0, "completed": 0, "manual": 0}
        touched: set[str] = set()
        for verdict in self.journal.classify_all(direction=RESTORE):
            operation = self.journal.get(verdict["operation_id"])
            touched.add(operation["plan_id"])
            token = (operation["fencing_token"] or 0) + 1
            if verdict["classification"] == MANUAL:
                results["manual"] += 1
                continue
            if verdict["classification"] == RESUMABLE:
                _clean_temp_files(Path(operation["destination_path"]).parent)
                self.journal.transition(operation["id"], ArchiveState.PLANNED, fencing_token=token)
                results["resumed"] += 1
                continue
            try:
                self._finish(operation, token=token)
                results["completed"] += 1
            except PreconditionFailed as error:
                self._fail(operation, token, error.code, str(error))
                results["manual"] += 1
        for plan_id in touched:
            self.journal.sync_plan_state(plan_id)
        return results
    def recovery_status(self) -> dict:
        verdicts = self.journal.classify_all(direction=RESTORE)
        return {
            "operations": verdicts,
            "manual": [v for v in verdicts if v["classification"] == MANUAL],
            "blocks_mutation": self.journal.blocks_mutation(),
        }
    # ── helpers ───────────────────────────────────────────────────────────────
    def _fail(self, operation: dict, token: int, code: str, message: str) -> None:
        self.journal.transition(
            operation["id"], ArchiveState.FAILED, fencing_token=token, error=(code, message)
        )
    def _require_plan(self, plan_id: str) -> dict:
        plan = self.get(plan_id)
        if plan is None:
            raise ArchiveError("unknown_plan", f"unknown restore plan {plan_id!r}")
        return plan
    def _location(self, location_id: str) -> dict:
        with self._session_factory() as session:
            location = session.get(ArchiveLocation, location_id)
            if location is None:
                raise ArchiveError("unknown_location", f"unknown archive location {location_id!r}")
            return {"id": location.id, "root": location.root, "media_id": location.media_id}
    def _claim_plan(self, plan_id: str) -> int:
        with self._session_factory() as session:
            plan = session.get(ArchivePlan, plan_id)
            plan.version += 1
            plan.state = "applying"
            plan.updated_at = _now()
            token = plan.version
            session.commit()
        return token
 # ── module helpers ───────────────────────────────────────────────────────────
 def _location_state(root: Path, marker: dict | None, media_id: str) -> str:
    if not root.is_dir() or marker is None:
        return "offline"
    return "online" if marker.get("media_id") == media_id else "wrong_volume"
 def _free_path(candidate: Path, taken: set) -> Path:
    """``a.jpg`` → ``a (restored).jpg`` → ``a (restored 2).jpg`` …
    ``taken`` holds the destinations already claimed by earlier items of the same
    plan, so two restores in one scope cannot plan the same path.
    """
    if not candidate.exists() and str(candidate) not in taken:
        return candidate
    stem, suffix = candidate.stem, candidate.suffix
    attempt = 1
    while True:
        label = RESTORED_SUFFIX if attempt == 1 else f"{RESTORED_SUFFIX} {attempt}"
        alternative = candidate.with_name(f"{stem} ({label}){suffix}")
        if not alternative.exists() and str(alternative) not in taken:
            return alternative
        attempt += 1
 def _token(report: dict) -> str:
    """Digest of everything the report asserts about the scope and the medium.
    Free space is excluded: it drifts constantly without changing what a restore
    would do, and the capacity verdict itself is part of the digest.
    """
    payload = {key: value for key, value in report.items() if key not in ("generated_at", "token")}
    payload["capacity"] = {
        key: value for key, value in payload["capacity"].items() if key != "free_bytes"
    }
    digest = hashlib.sha256(
        json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")
    ).hexdigest()
    return f"{TOKEN_PREFIX}:{digest}"
--- a/photo_pipeline/services/safety.py
+++ b/photo_pipeline/services/safety.py
@@ -105,11 +105,12 @@ def exif_projection(decision: str) -> dict[str, list[str]]:
 import uuid
 from datetime import datetime, timezone
-from sqlalchemy import column, func, select
+from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
-from photo_pipeline.models import Asset, ExifProjection, SafetyReview
+from photo_pipeline.integrations import exiftool
-from photo_pipeline.services import exif_checkpoint
+from photo_pipeline.models import Asset, SafetyReview
 from photo_pipeline.services import hashing
 DECISIONS = {SFW, NSFW, "deferred"}
@@ -139,8 +140,8 @@ class SafetyService:
    # -- reads ----------------------------------------------------------------
    def _latest_by_asset(self, session) -> dict[str, SafetyReview]:
-        """The current review per asset, as ORM rows. Only for small, known sets —
+        # Latest row per asset. Small local scale: order ascending, let later rows
-        every library-wide caller uses ``latest_reviews()`` in SQL instead."""
+        # overwrite. ponytail: a windowed query if safety_reviews ever grows huge.
        latest: dict[str, SafetyReview] = {}
        for review in session.scalars(select(SafetyReview).order_by(SafetyReview.created_at)):
            latest[review.asset_id] = review
@@ -148,99 +149,49 @@ class SafetyService:
    def current_decision(self, asset_id: str) -> str | None:
        with self._session_factory() as session:
-            latest = latest_reviews().subquery()
+            review = self._latest_by_asset(session).get(asset_id)
-            return session.scalar(
+            return review.decision if review else None
                select(latest.c.decision).where(latest.c.asset_id == asset_id)
            )
    def counts(self) -> dict[str, int]:
-        """Decision breakdown over canonical, active assets — the workflow totals.
+        """Decision breakdown over canonical, active assets — the workflow totals."""
        Aggregated in SQL: the workflow home asks for this on every load, and
        materialising every asset and every review to count them cost hundreds of
        milliseconds at 25k assets and would scale linearly from there (US07-06).
        """
        latest = latest_reviews().subquery()
        with self._session_factory() as session:
-            rows = session.execute(
+            assets = list(session.scalars(_eligible_assets_query()))
-                select(
+            latest = self._latest_by_asset(session)
                    func.coalesce(latest.c.decision, "undecided"),
                    func.count(),
                    func.count(latest.c.score),
                )
                .select_from(Asset)
                .join(latest, latest.c.asset_id == Asset.id, isouter=True)
                .where(
                    Asset.canonical_asset_id.is_(None),
                    Asset.availability_state == "active",
                )
                .group_by(func.coalesce(latest.c.decision, "undecided"))
            ).all()
            out = {SFW: 0, NSFW: 0, "deferred": 0, "undecided": 0, "scored": 0}
-        for decision, total, scored in rows:
+            for asset in assets:
                review = latest.get(asset.id)
                decision = review.decision if review else None
                if decision in (SFW, NSFW, "deferred"):
-                out[decision] += int(total)
+                    out[decision] += 1
                else:
-                # Anything that is not one of the three decisions is undecided —
+                    out["undecided"] += 1
-                # including a score-only review, which is what "scored" counts.
+                    if review and review.score is not None:
-                out["undecided"] += int(total)
+                        out["scored"] += 1
                out["scored"] += int(scored)
            return out
    def review_queue(self, state: str = "", limit: int = 100, offset: int = 0) -> dict:
-        """Assets for the review UI, filtered by ``state`` (undecided/sfw/nsfw/deferred).
+        """Assets for the review UI, filtered by ``state`` (undecided/sfw/nsfw/deferred)."""
        Filtered, counted, and paged in SQL (US07-06): the queue for a large library
        is thousands of rows and the reviewer sees one page of it.
        """
        latest = latest_reviews().subquery()
        projections = (
            select(ExifProjection.asset_id, ExifProjection.state.label("exif_state"))
            .where(ExifProjection.stage == "safety")
            .subquery()
        )
        effective = func.coalesce(latest.c.decision, "undecided")
        query = (
            select(
                Asset.id,
                Asset.current_path,
                latest.c.score,
                latest.c.decision,
                latest.c.exif_verified_at,
                projections.c.exif_state,
            )
            .select_from(Asset)
            .join(latest, latest.c.asset_id == Asset.id, isouter=True)
            .join(projections, projections.c.asset_id == Asset.id, isouter=True)
            .where(
                Asset.canonical_asset_id.is_(None),
                Asset.availability_state == "active",
            )
        )
        if state:
            query = query.where(effective == state)
        with self._session_factory() as session:
-            total = int(
+            assets = list(session.scalars(_eligible_assets_query().order_by(Asset.current_path)))
-                session.scalar(select(func.count()).select_from(query.subquery())) or 0
+            latest = self._latest_by_asset(session)
-            )
+            rows = []
-            rows = session.execute(
+            for asset in assets:
-                query.order_by(Asset.current_path).limit(limit).offset(offset)
+                review = latest.get(asset.id)
-            ).all()
+                decision = review.decision if review else None
-        return {
+                effective = decision or "undecided"
-            "total": total,
+                if state and state != effective:
-            "items": [
+                    continue
                rows.append(
                    {
-                    "asset_id": asset_id,
+                        "asset_id": asset.id,
-                    "current_path": current_path,
+                        "current_path": asset.current_path,
-                    "score": score,
+                        "score": review.score if review else None,
                        "decision": decision,
-                    "suggested": classify(score) if score is not None else None,
+                        "suggested": classify(review.score) if review and review.score is not None else None,
-                    "exif_verified": bool(exif_verified_at),
+                        "exif_verified": bool(review and review.exif_verified_at),
                    "exif_state": exif_state,
                }
                for asset_id, current_path, score, decision, exif_verified_at, exif_state in rows
            ],
                    }
                )
            return {"total": len(rows), "items": rows[offset : offset + limit]}
    def scorable_asset_ids(self) -> list[str]:
        """Canonical active assets with a path — the items a scoring job enqueues."""
@@ -294,28 +245,15 @@ class SafetyService:
        exif_verified_at = None
        result_sha256 = None
        result_byte_size = None
        if write_exif and decision in (SFW, NSFW) and path:
            ops = exif_projection(decision)
-            # The full checkpoint: write the owned keyword, read the whole file back,
+            if exiftool.apply_keywords(path, add=ops["add"], remove=ops["remove"]):
-            # and prove every field this stage does not own survived. A divergent
+                # Read back: the chosen keyword present, the opposite absent.
-            # result is recorded and left alone — it must not count as verified, so
+                keywords = exiftool.read_keyword_sets([path]).get(path, set())
-            # upload stays blocked until a human decides (US07-03).
+                opposite = NSFW if decision == SFW else SFW
-            result = exif_checkpoint.run(
+                if decision in keywords and opposite not in keywords:
-                path, add=tuple(ops["add"]), remove=tuple(ops["remove"])
+                    exif_verified_at = _now()
-            )
+                    result_sha256 = hashing.sha256_file(path)
            exif_checkpoint.record(
                self._session_factory,
                asset_id=asset_id,
                stage="safety",
                result=result,
                add=tuple(ops["add"]),
                remove=tuple(ops["remove"]),
            )
            if result.verified:
                exif_verified_at = result.verified_at
                result_sha256 = result.sha256
                result_byte_size = result.byte_size
        now = _now()
        with self._session_factory() as session:
@@ -334,8 +272,6 @@ class SafetyService:
            if result_sha256:
                asset = session.get(Asset, asset_id)
                asset.current_sha256 = result_sha256
                if result_byte_size is not None:
                    asset.byte_size = result_byte_size
            session.commit()
        return {
            "asset_id": asset_id,
@@ -345,34 +281,6 @@ class SafetyService:
        }
 def latest_reviews():
    """One row per asset: its current safety review, chosen in SQL.
    ``safety_reviews`` is append-only, so "the decision" is the newest row for an
    asset. A window function picks it without loading the table; ``rowid`` breaks a
    same-timestamp tie the same way the previous last-write-wins loop did.
    """
    ranked = (
        select(
            SafetyReview.asset_id,
            SafetyReview.decision,
            SafetyReview.score,
            SafetyReview.exif_verified_at,
            func.row_number()
            .over(
                partition_by=SafetyReview.asset_id,
                order_by=(SafetyReview.created_at.desc(), column("rowid").desc()),
            )
            .label("rank"),
        )
        .select_from(SafetyReview)
        .subquery()
    )
    return select(
        ranked.c.asset_id, ranked.c.decision, ranked.c.score, ranked.c.exif_verified_at
    ).where(ranked.c.rank == 1)
 def _eligible_assets_query():
    """Canonical, active assets — the safety stage runs only on these.
--- a/photo_pipeline/services/thumbnails.py
+++ b/photo_pipeline/services/thumbnails.py
@@ -8,11 +8,6 @@ an EXIF-only edit reuses the file while a real pixel change invalidates it; writ
 are atomic and the cache is bounded by an LRU quota. Failures are persisted as typed
 errors so a broken original is not retried on every request.
 An archived asset is served from its medium when that medium is mounted, and from
 its *protected* preview when it is not (US06-03). Protected previews are evidence,
 not cache: the quota never evicts them, because the original they describe may be
 unreachable when duplicate review needs it.
 Reuses photo_analyzer.prepare_image decode/resize/HEIC handling, adding the missing
 EXIF-orientation step, WebP output, and a managed cache (donor_ledger.yaml:
 pa-imaging).
@@ -20,19 +15,17 @@ pa-imaging).
 from __future__ import annotations
 import os
 import uuid
 from pathlib import Path
-from PIL import Image, ImageOps
+from PIL import Image, ImageOps, UnidentifiedImageError
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import sessionmaker
-from photo_pipeline import imaging, path_policy
+from photo_pipeline import path_policy
 from photo_pipeline.config import Config
 from photo_pipeline.models import Asset, Thumbnail
 from photo_pipeline.services import availability
 # Best-effort HEIC support: registered only if the optional decoder is installed.
 try:  # pragma: no cover - depends on an optional native dependency
@@ -43,13 +36,8 @@ except Exception:  # pragma: no cover
    pass
 SIZES = (256, 512, 1280)
 # Every in-flight render writes one of these beside its destination; startup
 # cleanup recognises exactly this pattern and nothing else.
 TEMP_SUFFIX = ".tmp"
 THUMB_VERSION = 1
 THUMB_FORMAT = "webp"
 # The size kept as durable comparison evidence for archived assets (concept §9).
 PROTECTED_SIZE = 1280
 class ThumbnailError(RuntimeError):
@@ -98,12 +86,7 @@ class ThumbnailService:
        self._config = config
        self._cache_dir = config.thumbnail_cache_dir
-    def generate(
+    def generate(self, asset_id: str, size: int) -> Path:
        self, asset_id: str, size: int, *, protected: bool = False, source: Path | None = None
    ) -> Path:
        """Render (or reuse) a preview. ``source`` overrides where the bytes are read
        from — the archiver passes its verified archive copy, which the database does
        not yet point at while the transfer is still in flight."""
        if size not in SIZES:
            raise InvalidSize(f"size must be one of {SIZES}")
@@ -111,7 +94,9 @@ class ThumbnailService:
            asset = session.get(Asset, asset_id)
            if asset is None:
                raise ThumbnailNotFound(f"unknown asset {asset_id}")
-            archived = asset.availability_state in availability.ARCHIVED
+            if asset.availability_state != "active" or not asset.current_path:
                raise ThumbnailUnavailable(f"asset {asset_id} has no active file")
            self._validate_path(asset.current_path)
            cache_key = self._cache_key(asset, size)
            row = session.get(Thumbnail, cache_key)
@@ -122,21 +107,9 @@ class ThumbnailService:
                    )
                if row.path and Path(row.path).exists():
                    _touch(row.path)
                    if protected and not row.protected:
                        self._protect(cache_key)
                    return Path(row.path)
-            # An archived original is read from its medium; when that medium is not
+            source = asset.current_path
            # mounted the retained preview above is the only evidence there is.
            source = source or availability.readable_path(session, asset)
            if source is None:
                raise ThumbnailUnavailable(f"asset {asset_id} has no readable file")
            source = str(source)
            if source == asset.current_path:
                # Render the *resolved* path the check approved: revalidating and then
                # reopening the original name would let a symlink swapped in between
                # the two steps decide which bytes are served (US07-02).
                source = str(self._validate_path(source))  # archive roots lie outside
        # Rendering happens outside the DB session (no transaction held during I/O).
        try:
@@ -146,72 +119,25 @@ class ThumbnailService:
                self._record_error(cache_key, asset_id, size, error.code)
            raise
-        # Archived assets keep their preview permanently: it is the comparison
+        self._record_ready(cache_key, asset_id, size, rendered)
        # evidence that survives the original leaving active storage.
        self._record_ready(cache_key, asset_id, size, rendered, protected=protected or archived)
        self._enforce_quota(keep=rendered["path"])
        return Path(rendered["path"])
    def ensure_protected(self, asset_id: str, *, source: Path | None = None) -> dict:
        """Produce (or confirm) the durable comparison preview for an asset.
        Returns evidence rather than raising, because the caller — archive
        preflight and the transfer itself — decides what an unrenderable original
        means. ``unsupported`` is a recorded property of the file, not a failure of
        the policy: its hashes and metadata remain the comparison evidence.
        """
        try:
            path = self.generate(asset_id, PROTECTED_SIZE, protected=True, source=source)
        except tuple(_PERSISTED_ERRORS) as error:
            return {"state": "unsupported", "error_code": error.code, "path": None}
        except ThumbnailError as error:
            return {"state": "unavailable", "error_code": error.code, "path": None}
        return {"state": "ready", "error_code": None, "path": str(path)}
    def evidence(self, asset_id: str) -> dict:
        """What durable preview this asset has right now, without rendering."""
        with self._session_factory() as session:
            rows = list(
                session.execute(
                    select(Thumbnail).where(Thumbnail.asset_id == asset_id)
                ).scalars()
            )
        for row in rows:
            if row.state == "ready" and row.path and Path(row.path).exists():
                return {
                    "state": "ready",
                    "protected": bool(row.protected),
                    "size": row.size,
                    "error_code": None,
                }
        for row in rows:
            if row.state == "error":
                return {
                    "state": "unsupported",
                    "protected": False,
                    "size": row.size,
                    "error_code": row.error_code,
                }
        return {"state": "missing", "protected": False, "size": None, "error_code": None}
    def _protect(self, cache_key: str) -> None:
        with self._session_factory() as session:
            row = session.get(Thumbnail, cache_key)
            if row is not None:
                row.protected = True
                session.commit()
    # ── path safety ──────────────────────────────────────────────────────────
-    def _validate_path(self, current_path: str) -> Path:
+    def _validate_path(self, current_path: str) -> None:
-        """The resolved path to read, or ``PathNotAllowed``.
+        path = Path(current_path)
-
+        if path_policy.is_excluded(path):
-        The message names no path: a refusal is returned to the browser, and where
+            raise PathNotAllowed(f"excluded path: {current_path}")
-        the library lives is not the caller's business (US07-02).
+        roots = self._config.library_roots
-        """
+        if not roots:
            return
        for root in roots:
            try:
-            return path_policy.resolve_in_roots(self._config.library_roots, current_path)
+                path_policy.resolve_within(Path(root), path)
-        except path_policy.PathPolicyError as error:
+                return
-            raise PathNotAllowed(str(error)) from None
+            except path_policy.PathPolicyError:
                continue
        raise PathNotAllowed(f"path outside configured roots: {current_path}")
    # ── cache key + rendering ──────────────────────────────────────────────────
    @staticmethod
@@ -226,33 +152,28 @@ class ThumbnailService:
        return self._cache_dir / safe[:2] / f"{safe}.{THUMB_FORMAT}"
    def _render(self, source: str, size: int, cache_key: str) -> dict:
        """Decode bounded, orient, colour-manage, resize, and write atomically.
        The temporary file is removed on every failure path: a decoder that dies
        halfway through ``save`` would otherwise leave a stray ``.tmp`` in the cache
        forever (US07-03).
        """
        destination = self._cache_path(cache_key)
        destination.parent.mkdir(parents=True, exist_ok=True)
        tmp = destination.with_name(f".{destination.name}.{uuid.uuid4().hex}{TEMP_SUFFIX}")
        try:
-            with imaging.open_image(source, max_pixels=self._config.thumbnail_max_pixels) as image:
+            with Image.open(source) as image:
-                imaging.draft(image, size)  # JPEG decodes near the target size
+                width, height = image.size
                if width * height > self._config.thumbnail_max_pixels:
                    raise ImageTooLarge(
                        f"{width}x{height} exceeds {self._config.thumbnail_max_pixels} px"
                    )
                oriented = ImageOps.exif_transpose(image)
                mode = "RGBA" if _has_alpha(oriented) else "RGB"
-                converted = imaging.to_srgb(oriented, mode=mode)
+                converted = oriented.convert(mode)
                converted.thumbnail((size, size), Image.LANCZOS)
                out_width, out_height = converted.size
                destination = self._cache_path(cache_key)
                destination.parent.mkdir(parents=True, exist_ok=True)
                tmp = destination.with_name(f".{destination.name}.{uuid.uuid4().hex}.tmp")
                converted.save(tmp, format="WEBP", quality=82, method=4)
-        except imaging.ImageTooLarge as error:
+        except ImageTooLarge:
            tmp.unlink(missing_ok=True)
            raise ImageTooLarge(str(error)) from None
        except imaging.UndecodableImage as error:
            tmp.unlink(missing_ok=True)
            raise UnsupportedImage(str(error)) from None
        except Exception:
            tmp.unlink(missing_ok=True)
            raise
        except (UnidentifiedImageError, OSError, ValueError) as error:
            raise UnsupportedImage(f"cannot decode {source}: {error}") from error
        import os
        os.replace(tmp, destination)
        return {
@@ -262,32 +183,8 @@ class ThumbnailService:
            "format": THUMB_FORMAT,
        }
    def cleanup_temp_files(self) -> int:
        """Remove leftover render temporaries, and only those.
        Runs at startup, where the concept is explicit: clean *recognized* stale
        temporary files, never arbitrary ones. The pattern is this service's own —
        a dot-prefixed name inside the managed cache directory ending in
        ``.tmp`` — so nothing outside the cache and nothing a user put there can
        match. Returns how many were removed.
        """
        if not self._cache_dir.is_dir():
            return 0
        removed = 0
        for leftover in self._cache_dir.rglob(f".*{TEMP_SUFFIX}"):
            if not leftover.is_file() or leftover.is_symlink():
                continue
            try:
                leftover.unlink()
                removed += 1
            except OSError:  # pragma: no cover - a racing render already won
                pass
        return removed
    # ── persistence ────────────────────────────────────────────────────────────
-    def _record_ready(
+    def _record_ready(self, cache_key: str, asset_id: str, size: int, rendered: dict) -> None:
        self, cache_key: str, asset_id: str, size: int, rendered: dict, *, protected: bool = False
    ) -> None:
        with self._session_factory() as session:
            session.merge(
                Thumbnail(
@@ -300,7 +197,6 @@ class ThumbnailService:
                    width=rendered["width"],
                    height=rendered["height"],
                    format=rendered["format"],
                    protected=protected,
                )
            )
            try:
@@ -334,10 +230,6 @@ class ThumbnailService:
        if total <= quota:
            return
        files.sort(key=lambda f: f.stat().st_mtime)  # least-recently-used first
        # Protected previews are evidence, not cache: an archived original cannot be
        # re-rendered once its medium is away, so eviction never touches them.
        protected = self._protected_paths()
        files = [f for f in files if str(f) not in protected]
        keep_path = str(Path(keep)) if keep else None
        evicted: list[str] = []
        for f in files:
@@ -355,16 +247,6 @@ class ThumbnailService:
        if evicted:
            self._forget(evicted)
    def _protected_paths(self) -> set[str]:
        with self._session_factory() as session:
            return {
                row.path
                for row in session.execute(
                    select(Thumbnail).where(Thumbnail.protected.is_(True))
                ).scalars()
                if row.path
            }
    def _forget(self, paths: list[str]) -> None:
        with self._session_factory() as session:
            rows = session.execute(
--- a/photo_pipeline/services/upload_batches.py
+++ b/photo_pipeline/services/upload_batches.py
@@ -37,7 +37,6 @@ from sqlalchemy import select, update
 from sqlalchemy.orm import sessionmaker
 from photo_pipeline.config import Config
 from photo_pipeline.faults import UPLOAD_ACCEPTED, maybe_fault
 from photo_pipeline.integrations import immich_go
 from photo_pipeline.models import UploadBatch, UploadItem
 from photo_pipeline.services.hashing import sha1_file
@@ -237,10 +236,6 @@ class UploadBatchService:
            error = ("uploader_failed", f"immich-go exited with {result['exit_code']}")
            item_state = ItemState.FAILED
        # The uploader is done and Immich may already hold every file, but nothing
        # about that is durable yet — the control point for "accepted, outcome not
        # recorded" (US07-04). Recovery must answer ``unknown_requires_verification``.
        maybe_fault(UPLOAD_ACCEPTED)
        self._finish(batch_id, token=token, state=state, error=error, result=result)
        if item_state:
            self._set_items(batch_id, item_state)
--- a/photo_pipeline/services/workflow.py
+++ b/photo_pipeline/services/workflow.py
@@ -47,9 +47,7 @@ class WorkflowService:
            active = self._active_job(session)
        safety = SafetyService(self._session_factory).counts()
-        # Reuse the confirmed-SFW total just computed: resolving the current decision
+        analysis = AnalysisService(self._session_factory).counts()
        # of every asset is the expensive part of this page (US07-06).
        analysis = AnalysisService(self._session_factory).counts(eligible=safety[_SFW])
        undecided_clusters = cluster_states.get("open", 0) + cluster_states.get("reopened", 0)
        stages = [
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -8,38 +8,22 @@ dependencies = [
    "sqlalchemy>=2.0",
    "alembic>=1.13",
    "pydantic>=2.7",
    # Imaging is runtime, not test-only: thumbnails decode through Pillow, and the
    # perceptual hash is a DCT over the decoded pixels (services/hashing.py).
    "pillow>=10",
    "numpy>=1.26",
    "scipy>=1.11",
 ]
 [project.optional-dependencies]
 # The cloud vision provider. Optional because the analysis stage is the only thing
 # that needs it, and a local review-only install should not pull an API client.
 vision = ["openai>=1.30"]
 test = [
    "pytest>=8",
    "httpx>=0.27",
    "pillow>=10",
    "numpy>=1.26",
    "scipy>=1.11",
    "playwright>=1.40",
    "pytest-playwright>=0.4",
 ]
 [build-system]
 requires = ["setuptools>=68"]
 build-backend = "setuptools.build_meta"
 [tool.setuptools]
 # The importable application. ``migrations`` and ``work_item`` live beside it but
 # are not part of the package; without this, an editable install cannot guess.
 packages = ["photo_pipeline"]
 # Browser end-to-end tests also require: python -m playwright install chromium
 [tool.ruff]
 line-length = 100
 # The frozen CLI archive is evidence, not code under maintenance (US07-01).
 extend-exclude = ["legacy_cli_archive"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -49,5 +33,4 @@ markers = [
    "phase_d: Phase D end-to-end acceptance (US04-06) — guarded rename API, fault, and browser journeys",
    "phase_e: Phase E end-to-end acceptance (US05-06) — upload preflight, uploader, and browser journeys",
    "phase_f: Phase F end-to-end acceptance (US06-06) — archive destination, transfer, and restore journeys",
    "container: builds and runs the container image (US08-02) — needs a Docker daemon and network",
 ]
--- a/legacy_cli_archive/src/test_dedup.py
+++ b/legacy_cli_archive/src/test_dedup.py
--- a/legacy_cli_archive/src/test_nsfw_skip.py
+++ b/legacy_cli_archive/src/test_nsfw_skip.py
--- a/tests/_artifacts.py
+++ b/tests/_artifacts.py
@@ -1,96 +0,0 @@
 """Failure artifacts for the fault and race suites (US07-04).
 A randomized concurrency failure that leaves nothing behind is a failure nobody
 can diagnose: the temporary library is deleted, the database goes with it, and the
 seed that produced the interleaving is gone. So when a test fails, everything
 needed to reproduce and read it is copied out of the temporary directory:
    <artifacts>/<test id>/
        seeds.json     recorded properties (``race_seed``) and the failing test id
        manifest.json  every file under the temporary directory: path, size, sha256
        files/...      the databases (with -wal/-shm), journals, and logs themselves
 The manifest covers the whole tree — including files too large or too private to
 copy — so a missing or unexpected file is still visible afterwards. Copying is
 bounded by ``MAX_COPY_BYTES``: artifacts must not turn a failing CI run into a
 disk-full one.
 Set ``PHOTO_PIPELINE_TEST_ARTIFACTS`` to choose the destination; the default is
 ``.artifacts/`` in the repository root.
 """
 from __future__ import annotations
 import hashlib
 import json
 import os
 import re
 import shutil
 from pathlib import Path
 REPO = Path(__file__).resolve().parents[1]
 DEFAULT_DIR = REPO / ".artifacts"
 MAX_COPY_BYTES = 25 * 1024 * 1024
 # Databases (and their write-ahead logs), journals exported as files, and logs.
 COPY_SUFFIXES = (".db", ".db-wal", ".db-shm", ".sqlite", ".log", ".json", ".jsonl", ".argv")
 def artifacts_dir() -> Path:
    return Path(os.environ.get("PHOTO_PIPELINE_TEST_ARTIFACTS", DEFAULT_DIR))
 def _slug(test_id: str) -> str:
    return re.sub(r"[^A-Za-z0-9._-]+", "_", test_id)[:120]
 def manifest(root: Path) -> list[dict]:
    """Every file under ``root``: relative path, byte size, and SHA-256.
    The filesystem state at the moment of failure — what was moved, what was left
    behind, what was half-written.
    """
    entries = []
    for path in sorted(root.rglob("*")):
        if not path.is_file() or path.is_symlink():
            continue
        try:
            body = path.read_bytes()
        except OSError as error:
            entries.append({"path": str(path.relative_to(root)), "error": str(error)})
            continue
        entries.append(
            {
                "path": str(path.relative_to(root)),
                "bytes": len(body),
                "sha256": hashlib.sha256(body).hexdigest(),
            }
        )
    return entries
 def collect(root: Path, test_id: str, *, properties: dict | None = None) -> Path:
    """Copy the evidence for one failed test out of ``root``. Returns its directory."""
    destination = artifacts_dir() / _slug(test_id)
    files = destination / "files"
    files.mkdir(parents=True, exist_ok=True)
    entries = manifest(root)
    (destination / "manifest.json").write_text(json.dumps(entries, indent=1))
    (destination / "seeds.json").write_text(
        json.dumps({"test": test_id, "properties": properties or {}}, indent=1)
    )
    budget = MAX_COPY_BYTES
    for path in sorted(root.rglob("*")):
        if not path.is_file() or path.is_symlink():
            continue
        if not path.name.endswith(COPY_SUFFIXES):
            continue
        size = path.stat().st_size
        if size > budget:
            continue  # the manifest still records it; the copy is what is skipped
        target = files / path.relative_to(root)
        target.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(path, target)
        budget -= size
    return destination
--- a/tests/characterization/conftest.py
+++ b/tests/characterization/conftest.py
@@ -14,11 +14,6 @@ import pytest
 from PIL import Image
 REPO = Path(__file__).resolve().parents[2]
 # The donors are frozen in the read-only archive (US07-01). Only this suite — and
 # the parity test that compares against them — puts that directory on sys.path;
 # production never does, which tests/unit/test_legacy_archive.py enforces.
 ARCHIVED_SOURCES = REPO / "legacy_cli_archive" / "src"
 sys.path.insert(0, str(ARCHIVED_SOURCES))
 sys.path.insert(0, str(REPO))
 EXIFTOOL = shutil.which("exiftool")
--- a/tests/characterization/test_donor_ledger.py
+++ b/tests/characterization/test_donor_ledger.py
@@ -1,20 +1,13 @@
-"""Ledger lint (US01-01, extended by US07-01).
+"""Ledger lint (US01-01): every donor-ledger row must carry a real source
-
+reference, a target location, and either existing characterization test IDs or
-Every donor-ledger row must carry a real source reference — now inside the frozen
+a real pending backlog story."""
 archive — a target location, and either existing characterization test IDs or a
 real pending backlog story. Since archival (US07-01) a row may also be ``resolved``:
 its replacement has shipped, ``parity`` names tests that exist and prove it, and
 ``delta`` states every intentional difference. Nothing may quietly become
 "finished" without one of those two."""
 import re
 from pathlib import Path
 import yaml
 REPO = Path(__file__).resolve().parents[2]
-ARCHIVE = REPO / "legacy_cli_archive"
+LEDGER = REPO / "donor_ledger.yaml"
 LEDGER = ARCHIVE / "donor_ledger.yaml"
 ARCHIVED_SOURCES = ARCHIVE / "src"
 STORIES = REPO / "delivery_backlog" / "stories"
 TESTS_DIR = Path(__file__).resolve().parent
@@ -22,7 +15,7 @@ CLASSIFICATIONS = {"reuse", "extract", "refactor", "replace"}
 REQUIRED_AREAS = {"discovery", "hashing", "imaging", "nsfw", "vision", "exif",
                  "database", "ui", "configuration", "logging", "cancellation",
                  "error"}
-STATUSES = {"characterized", "resolved", "pending"}
+STATUSES = {"characterized", "pending"}
 def load_rows():
@@ -56,11 +49,10 @@ def test_rows_have_required_fields_and_unique_ids():
 def test_source_references_resolve():
    """Source paths are relative to the archive: the donors moved there, whole."""
    for r in load_rows():
        src = r["source"]
-        f = ARCHIVED_SOURCES / src["file"]
+        f = REPO / src["file"]
-        assert f.is_file(), f"{r['id']}: source file {src['file']} missing from the archive"
+        assert f.is_file(), f"{r['id']}: source file {src['file']} missing"
        text = f.read_text(encoding="utf-8")
        for sym in src["symbols"]:
            assert sym in text, f"{r['id']}: symbol {sym!r} not found in {src['file']}"
@@ -71,9 +63,7 @@ def test_rows_have_tests_or_pending_story():
    for r in load_rows():
        tests = r.get("tests", [])
        pending = r.get("pending_story")
-        parity = r.get("parity", [])
+        assert tests or pending, f"{r['id']}: neither tests nor pending_story"
        assert tests or pending or parity, \
            f"{r['id']}: neither characterization tests, parity tests, nor a pending story"
        for t in tests:
            assert t in known_tests, f"{r['id']}: unknown test id {t}"
        if pending:
@@ -83,58 +73,16 @@ def test_rows_have_tests_or_pending_story():
            assert tests, f"{r['id']}: characterized rows need test ids"
 def test_resolved_rows_name_their_parity_or_their_delta():
    """A resolved row is a claim that the behavior is handled. It has to say how:
    tests that prove the replacement, or a stated difference — usually both."""
    for r in load_rows():
        if r["status"] != "resolved":
            assert "parity" not in r, f"{r['id']}: parity on a non-resolved row"
            continue
        parity = r.get("parity", [])
        delta = r.get("delta")
        assert parity or delta, f"{r['id']}: resolved without parity tests or a delta"
        if delta:
            assert len(str(delta).strip()) >= 20, f"{r['id']}: delta too thin to be a reason"
        for ref in parity:
            rel, _, func = ref.partition("::")
            path = REPO / rel
            assert path.is_file(), f"{r['id']}: parity test file {rel} missing"
            assert f"def {func}" in path.read_text(encoding="utf-8"), \
                f"{r['id']}: parity test {ref} not found"
 def test_pending_rows_are_the_only_unfinished_work():
    """The ledger is the honest list of what has not been carried over: a pending
    row names the story that will, and that story must still be open work."""
    for r in load_rows():
        if r["status"] != "pending":
            continue
        story = r.get("pending_story")
        assert story, f"{r['id']}: pending without a story"
        assert list(STORIES.glob(f"{story}-*.md")), f"{r['id']}: unknown story {story}"
 def test_every_target_module_exists():
    """A row is only finished if the thing it points at is really there."""
    for r in load_rows():
        if r["status"] == "pending":
            continue
        modules = re.findall(r"photo_pipeline/[\w/]+\.py", str(r["target"]))
        for module in modules:
            assert (REPO / module).is_file(), f"{r['id']}: target {module} does not exist"
 def test_all_required_areas_covered():
    covered = {r["area"] for r in load_rows()}
    assert REQUIRED_AREAS <= covered, f"uncovered areas: {REQUIRED_AREAS - covered}"
    assert covered <= REQUIRED_AREAS, f"unknown areas: {covered - REQUIRED_AREAS}"
-def test_every_donor_is_in_the_archive_and_nowhere_else():
+def test_no_legacy_file_moved():
-    """US01-01 forbade archiving before characterization; US07-01 requires it after.
+    # US01-01 explicitly forbids moving/archiving donors; the ledger's source
-    Each donor exists exactly once — frozen, in the archive."""
+    # files must all still exist at their original locations.
    for donor in ("photo_analyzer.py", "nsfwtag/scoring.py", "nsfwtag/exif.py",
                  "nsfwtag/server.py", "webapp/query.py", "webapp/runner.py",
                  "webapp/server.py"):
-        assert (ARCHIVED_SOURCES / donor).is_file(), f"donor missing from archive: {donor}"
+        assert (REPO / donor).is_file(), f"donor moved: {donor}"
        assert not (REPO / donor).exists(), f"donor still live at the repo root: {donor}"
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,16 +1,4 @@
-"""Make the repository root importable for the pipeline test suites, give every
+"""Make the repository root importable for the pipeline test suites."""
 suite the application session the API requires since US07-02, and keep the evidence
 of any failure (US07-04).
 The suites drive the API the way the browser does — module-level ``httpx`` calls and
 ``TestClient`` — so instead of threading a cookie through several hundred call sites,
 both clients bootstrap the session themselves exactly like ``frontend/js/api.js``:
 fetch ``/api/v1/session`` once, then send the cookie plus the CSRF header, and
 re-bootstrap once on 401 (a restarted server issues a new session).
 Security tests deliberately bypass this by constructing their own ``httpx.Client``;
 only the module-level helpers are wrapped.
 """
 import sys
 from pathlib import Path
@@ -18,112 +6,3 @@ from pathlib import Path
 REPO = Path(__file__).resolve().parents[1]
 if str(REPO) not in sys.path:
    sys.path.insert(0, str(REPO))
 import httpx
 import httpx._api  # httpx.get/post resolve `request` in this module
 import pytest
 from starlette.testclient import TestClient
 from photo_pipeline.api.security import CSRF_HEADER, SESSION_COOKIE
 _SESSIONS: dict[str, tuple[str, str]] = {}  # base url -> (session id, csrf token)
 def _base(url) -> str:
    parts = httpx.URL(str(url))
    return f"{parts.scheme}://{parts.netloc.decode()}"
 def _bootstrap(base: str) -> tuple[str, str]:
    if base not in _SESSIONS:
        response = httpx.Client(timeout=10).get(f"{base}/api/v1/session")
        _SESSIONS[base] = (
            response.cookies.get(SESSION_COOKIE, ""),
            response.json().get("csrf_token", ""),
        )
    return _SESSIONS[base]
 def session_client(base_url: str, **kwargs) -> httpx.Client:
    """An ``httpx.Client`` that has bootstrapped its own application session.
    For suites that keep one client for a whole journey; it holds its own cookie, so
    a client made after a server restart picks up the new session by construction.
    """
    client = httpx.Client(base_url=base_url, **kwargs)
    client.headers[CSRF_HEADER] = client.get("/api/v1/session").json()["csrf_token"]
    return client
 def _authorized(url, headers, cookies):
    session_id, token = _bootstrap(_base(url))
    headers = dict(headers or {})
    headers.setdefault(CSRF_HEADER, token)
    cookies = dict(cookies or {})
    cookies.setdefault(SESSION_COOKIE, session_id)
    return headers, cookies
@pytest.fixture(autouse=True, scope="session")
 def _api_session():
    real_request, real_stream = httpx._api.request, httpx._api.stream
    real_client_request, real_client_init = TestClient.request, TestClient.__init__
    def request(method, url, *, headers=None, cookies=None, **kwargs):
        sent, jar = _authorized(url, headers, cookies)
        response = real_request(method, url, headers=sent, cookies=jar, **kwargs)
        if response.status_code == 401:
            _SESSIONS.pop(_base(url), None)
            sent, jar = _authorized(url, headers, cookies)
            response = real_request(method, url, headers=sent, cookies=jar, **kwargs)
        return response
    def stream(method, url, *, headers=None, cookies=None, **kwargs):
        sent, jar = _authorized(url, headers, cookies)
        return real_stream(method, url, headers=sent, cookies=jar, **kwargs)
    def client_init(self, app, *args, base_url="http://127.0.0.1", **kwargs):
        # The default "http://testserver" is not a local host, which is exactly what
        # the Host check refuses; in-process tests are still same-origin callers.
        real_client_init(self, app, *args, base_url=base_url, **kwargs)
    def client_request(self, method, url, *, headers=None, **kwargs):
        if CSRF_HEADER not in self.headers:
            response = real_client_request(self, "GET", "/api/v1/session")
            self.headers[CSRF_HEADER] = response.json()["csrf_token"]
        return real_client_request(self, method, url, headers=headers, **kwargs)
    httpx._api.request, httpx.request = request, request
    httpx._api.stream, httpx.stream = stream, stream
    TestClient.request, TestClient.__init__ = client_request, client_init
    yield
    httpx._api.request, httpx.request = real_request, real_request
    httpx._api.stream, httpx.stream = real_stream, real_stream
    TestClient.request, TestClient.__init__ = real_client_request, real_client_init
@pytest.hookimpl(hookwrapper=True)
 def pytest_runtest_makereport(item, call):
    """On failure, keep the temporary library, database, journals, logs, and seed.
    ``tmp_path`` is deleted a few runs later and its contents are the only record
    of what a randomized or fault-injected failure actually did, so they are copied
    out while they still exist (US07-04).
    """
    outcome = yield
    report = outcome.get_result()
    if report.when != "call" or not report.failed:
        return
    root = item.funcargs.get("tmp_path")
    if root is None or not Path(root).exists():
        return
    from tests._artifacts import collect
    try:
        destination = collect(
            Path(root), item.nodeid, properties=dict(getattr(report, "user_properties", []))
        )
    except OSError as error:  # never let evidence collection mask the real failure
        report.sections.append(("failure artifacts", f"could not be collected: {error}"))
    else:
        report.sections.append(("failure artifacts", str(destination)))
--- a/tests/e2e/_pipeline_harness.py
+++ b/tests/e2e/_pipeline_harness.py
@@ -393,125 +393,6 @@ def mark_upload_ready(seeded: Seeded, *, unverified: tuple[str, ...] = ()) -> No
            session.commit()
 # ── Phase F: an archivable album and a mountable fake medium ─────────────────
 def mark_uploaded(seeded: Seeded, *, album: str = "rome") -> None:
    """Give every seeded photo the verified upload evidence archiving requires.
    Archiving refuses anything Immich is not proven to hold, and that proof is an
    upload batch — recorded here as fixture state so the archive journeys do not
    have to re-run an upload they are not testing.
    """
    from sqlalchemy import select
    from photo_pipeline.models import Asset, UploadBatch, UploadItem
    from photo_pipeline.services.hashing import sha256_file
    with session_factory(seeded) as sf:
        with sf() as session:
            batch_id = str(uuid.uuid4())
            session.add(
                UploadBatch(
                    id=batch_id,
                    album=album,
                    folder=str(seeded.lib / album),
                    album_name=album,
                    state="succeeded",
                    preflight_token="v1:e2e",
                    outcome_state="verified",
                    created_at=NOW,
                )
            )
            for asset in session.scalars(select(Asset)):
                if not asset.current_path:
                    continue
                session.add(
                    UploadItem(
                        batch_id=batch_id,
                        asset_id=asset.id,
                        path=asset.current_path,
                        sha256=sha256_file(asset.current_path),
                        sha1="0" * 40,
                        state="sent",
                        outcome="uploaded",
                    )
                )
            session.commit()
 class ArchiveStack:
    """A seeded, archivable library plus the server, the worker, and a fake medium.
    The medium is an ordinary directory whose marker file makes it identifiable;
    ``unmount()`` takes that marker away, which is exactly what the application sees
    when an external disk is unplugged.
    """
    MARKER = ".photo-pipeline-archive.json"
    def __init__(self, tmp_path: Path, seeded: Seeded) -> None:
        self.tmp_path = tmp_path
        self.seeded = seeded
        self.archive = tmp_path / "archive"
        self.archive.mkdir(exist_ok=True)
        self.server: Server | None = None
        self.worker: subprocess.Popen | None = None
        self.base = ""
    def start(self, *, worker: bool = True, extra_env: dict[str, str] | None = None) -> "ArchiveStack":
        env = {"PHOTO_PIPELINE_ARCHIVE_FREE_SPACE_RESERVE_BYTES": "0", **(extra_env or {})}
        self.server = Server(self.seeded, extra_env=env).start()
        self.base = self.server.base
        if worker:
            self.worker = start_worker(self.seeded, extra_env=env)
        return self
    def register(self, name: str = "external") -> dict:
        response = httpx.post(
            f"{self.base}/api/v1/archive-locations",
            json={"name": name, "root": str(self.archive)},
            timeout=20,
        )
        response.raise_for_status()
        return response.json()
    def unmount(self) -> None:
        (self.archive / self.MARKER).rename(self.archive / f"{self.MARKER}.away")
    def remount(self) -> None:
        (self.archive / f"{self.MARKER}.away").rename(self.archive / self.MARKER)
    def plans(self) -> list[dict]:
        return httpx.get(f"{self.base}/api/v1/archive-plans", timeout=20).json()["plans"]
    def assets(self) -> list[dict]:
        return httpx.get(
            f"{self.base}/api/v1/inventory/assets", params={"limit": 200}, timeout=20
        ).json()["items"]
    def restart_server(self) -> None:
        self.server.stop()
        self.server.start()
    def restart_worker(self, *, extra_env: dict[str, str] | None = None) -> None:
        """Replace the worker — a healthy one after a crashed one, by default."""
        if self.worker is not None and self.worker.poll() is None:
            self.worker.kill()
            self.worker.wait(timeout=10)
        self.worker = start_worker(
            self.seeded,
            extra_env={"PHOTO_PIPELINE_ARCHIVE_FREE_SPACE_RESERVE_BYTES": "0", **(extra_env or {})},
        )
    def stop(self) -> None:
        if self.worker is not None:
            self.worker.kill()
            self.worker.wait(timeout=10)
        if self.server is not None:
            self.server.stop()
 class UploadStack:
    """A seeded, upload-ready library plus the server, worker, and fake Immich."""
--- a/tests/e2e/test_archive_ui.py
+++ b/tests/e2e/test_archive_ui.py
@@ -1,302 +0,0 @@
 """Browser journeys for the archive view (US06-05).
 Archiving is the only stage that removes originals, so these journeys check the
 two things a browser must never get wrong about it: that the preview names exactly
 what would leave and where it would go, and that nothing offers an action the
 server would refuse. The medium is a real directory whose marker makes it
 identifiable; unmounting it is what an unplugged disk looks like from here.
 Nothing is mocked inside the browser: the transfer runs in the real worker process
 and the assertions read the filesystem afterwards.
 """
 from __future__ import annotations
 import pytest
 from playwright.sync_api import expect
 from tests.e2e._pipeline_harness import (
    ArchiveStack,
    mark_uploaded,
    seed_album,
    session_factory,
    wait_until,
 )
 pytestmark = pytest.mark.phase_f  # part of the Phase F acceptance gate (US06-06)
 TIMEOUT = 10
 RUN_TIMEOUT = 30_000
@pytest.fixture
 def stack(tmp_path):
    seeded = seed_album(tmp_path)
    mark_uploaded(seeded)
    running = ArchiveStack(tmp_path, seeded)
    try:
        yield running
    finally:
        running.stop()
 def _open(page, stack) -> None:
    page.goto(f"{stack.base}/app/#/archive")
    page.get_by_test_id("archive-locations").wait_for()
 def _archive(page, stack) -> None:
    """Confirm the archive and wait for the worker to finish the run."""
    _open(page, stack)
    page.get_by_test_id("start-archive").click()
    expect(page.get_by_test_id("detail-state")).to_have_text("complete", timeout=RUN_TIMEOUT)
 def _archived_paths(stack) -> list[str]:
    return sorted(p.name for p in (stack.archive / "rome").glob("*.jpg"))
 # ── preview and confirmation ─────────────────────────────────────────────────
 def test_the_preview_names_the_scope_destination_and_reclaimable_bytes(page, stack):
    errors = []
    page.on("console", lambda m: errors.append(m.text) if m.type == "error" else None)
    stack.start(worker=False)
    location = stack.register()
    _open(page, stack)
    row = page.get_by_test_id("location-row").first
    expect(row.get_by_test_id("location-label")).to_have_text("external")
    expect(row.get_by_test_id("location-media")).to_have_text(location["media_id"])
    expect(row.get_by_test_id("location-state")).to_have_text("online")
    album = page.get_by_test_id("archive-album-row").first
    expect(album.get_by_test_id("album-name")).to_have_text("rome")
    expect(album.get_by_test_id("album-destination")).to_have_text(str(stack.archive / "rome"))
    expect(album.get_by_test_id("album-assets")).to_have_text("2")
    expect(album.get_by_test_id("album-state")).to_have_text("ready")
    # Same filesystem here, so the transfer method is the move path — and it is
    # named, because copy-verify-remove and move fail differently.
    expect(album.get_by_test_id("album-method")).to_contain_text("move")
    expect(page.get_by_test_id("destination-identity")).to_contain_text(location["media_id"])
    expect(page.get_by_test_id("capacity")).to_contain_text("reserve")
    expect(page.get_by_test_id("start-archive")).to_contain_text("Archive 1 album(s) · reclaim")
    expect(page.get_by_test_id("start-archive")).to_be_enabled()
    assert stack.plans() == [], "previewing may not create anything"
    assert errors == [], f"console errors: {errors}"
 def test_an_offline_medium_blocks_the_confirmation_and_says_what_to_mount(page, stack):
    stack.start(worker=False)
    location = stack.register()
    stack.unmount()
    _open(page, stack)
    expect(page.get_by_test_id("location-state")).to_have_text("offline")
    expect(page.get_by_test_id("preflight-blocker").first).to_have_attribute(
        "data-code", "location_offline"
    )
    instruction = page.get_by_test_id("mount-instruction")
    expect(instruction).to_contain_text("external")
    expect(instruction).to_contain_text(location["media_id"])
    expect(page.get_by_test_id("start-archive")).to_be_disabled()
 def test_an_unuploaded_album_is_blocked_with_its_reason(page, stack):
    # No upload evidence at all: archiving would remove the only copy.
    seeded = stack.seeded
    with session_factory(seeded) as sf:
        from sqlalchemy import delete
        from photo_pipeline.models import UploadItem
        with sf() as session:
            session.execute(delete(UploadItem))
            session.commit()
    stack.start(worker=False)
    stack.register()
    _open(page, stack)
    expect(page.get_by_test_id("album-state")).to_have_text("blocked")
    expect(page.get_by_test_id("album-blocker").first).to_have_attribute(
        "data-code", "partial_scope"
    )
    expect(page.get_by_test_id("start-archive")).to_be_disabled()
 # ── running, progress, reload ────────────────────────────────────────────────
 def test_a_confirmed_archive_runs_and_separates_transfer_verify_and_removal(page, stack):
    stack.start()
    stack.register()
    _archive(page, stack)
    expect(page.get_by_test_id("count-complete")).to_have_text("complete: 2")
    expect(page.get_by_test_id("count-failed")).to_have_text("failed: 0")
    expect(page.get_by_test_id("count-transfer")).to_have_text("transfer: 0")
    expect(page.get_by_test_id("count-verified")).to_have_text("verified: 0")
    expect(page.get_by_test_id("count-removing")).to_have_text("removing: 0")
    expect(page.get_by_test_id("operation-phase").first).to_have_text("complete")
    # The library really lost the originals and the medium really holds them.
    assert _archived_paths(stack) == ["a.jpg", "b.jpg"]
    assert not (stack.seeded.lib / "rome" / "a.jpg").exists()
    assert {a["availability_state"] for a in stack.assets()} == {"archived_online"}
 def test_the_run_survives_a_reload_because_the_state_is_the_servers(page, stack):
    stack.start()
    stack.register()
    _archive(page, stack)
    page.reload()
    page.get_by_test_id("plan-detail").wait_for()
    expect(page.get_by_test_id("detail-state")).to_have_text("complete")
    expect(page.get_by_test_id("count-complete")).to_have_text("complete: 2")
    # And the run stays addressable by its own URL.
    plan_id = stack.plans()[0]["id"]
    page.goto(f"{stack.base}/app/#/archive?plan={plan_id}")
    expect(page.get_by_test_id("plan-detail")).to_have_attribute("data-plan", plan_id)
 # ── recovery ─────────────────────────────────────────────────────────────────
 def test_an_interrupted_transfer_is_shown_with_evidence_and_a_safe_action(page, stack):
    stack.start(worker=False)
    stack.register()
    _open(page, stack)
    page.get_by_test_id("start-archive").click()
    expect(page.get_by_test_id("archive-result")).to_be_visible()
    # No worker ran, so every item is still planned; leave one mid-transfer as a
    # crash would: intent recorded, nothing published, source intact.
    _interrupt(stack)
    page.reload()
    page.get_by_test_id("archive-recovery").wait_for()
    row = page.get_by_test_id("recovery-row").first
    expect(row).to_have_attribute("data-classification", "resumable")
    expect(row.get_by_test_id("recovery-reason")).to_contain_text("source present")
    page.get_by_test_id("resolve-recovery").click()
    expect(page.get_by_test_id("archive-recovery")).to_have_count(0)
    assert (stack.seeded.lib / "rome" / "a.jpg").exists(), "recovery may not move anything"
 def test_ambiguous_evidence_offers_no_action_at_all(page, stack):
    stack.start(worker=False)
    stack.register()
    _open(page, stack)
    page.get_by_test_id("start-archive").click()
    expect(page.get_by_test_id("archive-result")).to_be_visible()
    # Journal says the copy is verified, but the medium holds nothing: no evidence
    # supports either finishing or retrying this item.
    _interrupt(stack, state="verified")
    page.reload()
    page.get_by_test_id("archive-recovery").wait_for()
    expect(page.get_by_test_id("recovery-row").first).to_have_attribute(
        "data-classification", "manual"
    )
    expect(page.get_by_test_id("recovery-manual")).to_be_visible()
    expect(page.get_by_test_id("resolve-recovery")).to_have_count(0)
    expect(page.get_by_test_id("no-safe-recovery")).to_be_visible()
 def _interrupt(stack, *, state: str = "transferring") -> None:
    """Leave the plan's first operation in a non-terminal journal state."""
    with session_factory(stack.seeded) as sf:
        from photo_pipeline.services.archive_journal import ArchiveJournal
        journal = ArchiveJournal(sf)
        plan_id = stack.plans()[0]["id"]
        operation = journal.operations(plan_id)[0]
        journal.begin(operation["id"], worker_id="crashed", fencing_token=1)
        if state != "transferring":
            journal.transition(operation["id"], state, fencing_token=1)
 # ── offline browsing and restore ─────────────────────────────────────────────
 def test_archived_photos_stay_browsable_while_the_medium_is_away(page, stack):
    stack.start()
    stack.register()
    _archive(page, stack)
    stack.unmount()
    page.reload()
    page.get_by_test_id("archived-assets").wait_for()
    row = page.get_by_test_id("archived-row").first
    expect(row.get_by_test_id("archived-availability")).to_have_text("archived · medium away")
    expect(row.get_by_test_id("archived-path")).to_contain_text("rome/")
    expect(row.get_by_test_id("archived-medium")).to_have_text("external")
    expect(page.get_by_test_id("mount-instruction")).to_contain_text("external")
    # The retained protected preview is served even though the original is gone.
    preview = row.get_by_test_id("archived-preview")
    assert preview.evaluate("img => img.complete && img.naturalWidth > 0")
    # Restoring is impossible right now, and says so instead of failing later.
    expect(page.get_by_test_id("start-restore")).to_be_disabled()
 def test_restoring_brings_the_photos_back_without_losing_identity(page, stack):
    stack.start()
    stack.register()
    _archive(page, stack)
    before = {asset["id"] for asset in stack.assets()}
    page.reload()
    page.get_by_test_id("restore").wait_for()
    expect(page.get_by_test_id("restore-row").first.get_by_test_id("restore-destination")).to_contain_text(
        str(stack.seeded.lib / "rome")
    )
    page.get_by_test_id("start-restore").click()
    wait_until(
        lambda: all(a["availability_state"] == "active" for a in stack.assets()),
        timeout=30,
    )
    assert {asset["id"] for asset in stack.assets()} == before  # same identities
    assert (stack.seeded.lib / "rome" / "a.jpg").exists()
    assert _archived_paths(stack) == ["a.jpg", "b.jpg"]  # the archive copy stays
 def test_a_taken_name_is_restored_beside_it_never_over_it(page, stack):
    stack.start()
    stack.register()
    _archive(page, stack)
    squatter = stack.seeded.lib / "rome" / "a.jpg"
    squatter.parent.mkdir(parents=True, exist_ok=True)
    squatter.write_bytes(b"a different photo now lives here")
    page.reload()
    page.get_by_test_id("restore").wait_for()
    destinations = page.get_by_test_id("restore-destination").all_inner_texts()
    assert any("(restored)" in text for text in destinations), destinations
    page.get_by_test_id("start-restore").click()
    wait_until(
        lambda: all(a["availability_state"] == "active" for a in stack.assets()),
        timeout=30,
    )
    assert squatter.read_bytes() == b"a different photo now lives here"
    assert (stack.seeded.lib / "rome" / "a (restored).jpg").exists()
 # ── keyboard ─────────────────────────────────────────────────────────────────
 def test_the_whole_archive_can_be_confirmed_from_the_keyboard(page, stack):
    stack.start()
    stack.register()
    _open(page, stack)
    button = page.get_by_test_id("start-archive")
    button.focus()
    expect(button).to_be_focused()
    page.keyboard.press("Enter")
    expect(page.get_by_test_id("detail-state")).to_have_text("complete", timeout=RUN_TIMEOUT)
    assert _archived_paths(stack) == ["a.jpg", "b.jpg"]
--- a/tests/e2e/test_container_runtime.py
+++ b/tests/e2e/test_container_runtime.py
@@ -1,306 +0,0 @@
 """US08-02: the built image, actually built and actually run.
 This is the acceptance test for the image itself, so nothing here is faked: Docker
 builds from a clean context, the container starts under a chosen UID/GID against a
 mounted data directory, and the assertions are made over HTTP and against the files
 the container left on the host.
 It is skipped without a Docker daemon — the build also needs the network for the base
 image, the pinned exiftool package, and the pinned uploader release. The contract the
 Dockerfile itself has to keep (pins, non-root, health target, build context) is checked
 offline in ``tests/integration/test_container_image.py``, so a machine without Docker
 still fails on a broken image definition; only the running proof needs the daemon. CI
 builds the image on every change (US08-04), which is where this runs unskipped.
 """
 from __future__ import annotations
 import json
 import os
 import platform
 import re
 import socket
 import subprocess
 import sys
 import time
 from pathlib import Path
 import httpx
 import pytest
 REPO = Path(__file__).resolve().parents[2]
 IMAGE = "photo-pipeline-test:us08-02"
 SECRET = "container-acceptance-secret"
 HOSTNAME = "photos.test"
 READY_TIMEOUT_SECONDS = 120
 BUILD_TIMEOUT_SECONDS = 30 * 60
 pytestmark = pytest.mark.container
 def docker_available() -> bool:
    try:
        return subprocess.run(["docker", "info"], capture_output=True, timeout=60).returncode == 0
    except (OSError, subprocess.SubprocessError):
        return False
 needs_docker = pytest.mark.skipif(not docker_available(), reason="no Docker daemon available")
 def docker(*args: str, check: bool = True, timeout: int = 120) -> subprocess.CompletedProcess:
    result = subprocess.run(
        ["docker", *args], capture_output=True, text=True, timeout=timeout
    )
    if check and result.returncode != 0:
        raise AssertionError(f"docker {' '.join(args)} failed:\n{result.stdout}\n{result.stderr}")
    return result
 def pins() -> dict[str, str]:
    """The pinned versions, read from the Dockerfile that produced the image."""
    text = (REPO / "Dockerfile").read_text()
    found = dict(re.findall(r"^ARG\s+([A-Z0-9_]+)=(.+)$", text, re.MULTILINE))
    return {
        # The Debian package version carries a packaging suffix; exiftool reports the
        # upstream version only.
        "exiftool": found["EXIFTOOL_VERSION"].split("+")[0].split("-")[0],
        "immich-go": found["IMMICH_GO_VERSION"],
    }
 def free_port() -> int:
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]
@pytest.fixture(scope="module")
 def image() -> str:
    """Build from a clean checkout: the build context is the repository, unmodified."""
    if not docker_available():
        pytest.skip("no Docker daemon available")
    docker(
        "build",
        "--build-arg",
        f"UID={os.getuid()}",
        "--build-arg",
        f"GID={os.getgid()}",
        "-t",
        IMAGE,
        str(REPO),
        timeout=BUILD_TIMEOUT_SECONDS,
    )
    return IMAGE
@pytest.fixture
 def data_dir(tmp_path) -> Path:
    data = tmp_path / "data"
    data.mkdir()
    return data
 def run_detached(image: str, port: int, *args: str, data: Path | None = None) -> str:
    """Start a container. ``data`` bind-mounts the host's data directory when the test
    is about the files themselves; otherwise the image's own /data is used, because a
    macOS bind mount arrives with an ownership the container did not choose."""
    result = docker(
        "run",
        "--detach",
        "--rm",
        "--publish",
        f"127.0.0.1:{port}:8000",
        *(("--volume", f"{data}:/data") if data is not None else ()),
        "--env",
        # Reachable from outside the container means reachable from another machine as
        # far as the application is concerned, so the access secret is mandatory
        # (US08-01) — the image must not weaken that.
        "PHOTO_PIPELINE_HOST=0.0.0.0",
        "--env",
        f"PHOTO_PIPELINE_ACCESS_SECRET={SECRET}",
        "--env",
        f"PHOTO_PIPELINE_ALLOWED_HOSTS={HOSTNAME}",
        image,
        *args,
    )
    return result.stdout.strip()
 def wait_until_ready(base: str, container: str) -> None:
    deadline = time.monotonic() + READY_TIMEOUT_SECONDS
    while time.monotonic() < deadline:
        try:
            if httpx.get(f"{base}/api/v1/health/ready", timeout=5).status_code == 200:
                return
        except httpx.HTTPError:
            pass
        if docker("inspect", "-f", "{{.State.Running}}", container, check=False).stdout.strip() in (
            "false",
            "",
        ):
            break
        time.sleep(0.5)
    logs = docker("logs", container, check=False)
    raise AssertionError(f"container never became ready:\n{logs.stdout}\n{logs.stderr}")
@pytest.fixture
 def serving(image):
    port = free_port()
    container = run_detached(image, port, "serve")
    try:
        base = f"http://127.0.0.1:{port}"
        wait_until_ready(base, container)
        yield base, container
    finally:
        docker("rm", "--force", container, check=False)
 def session(base: str) -> httpx.Client:
    client = httpx.Client(base_url=base, timeout=30)
    bootstrap = client.get("/api/v1/session", headers={"X-Access-Secret": SECRET})
    assert bootstrap.status_code == 200, bootstrap.text
    client.headers["X-CSRF-Token"] = bootstrap.json()["csrf_token"]
    return client
 # ── the image serves, and says what it contains ──────────────────────────────
@needs_docker
 def test_the_container_serves_the_frontend_and_the_pinned_tool_versions(serving):
    base, container = serving
    index = httpx.get(f"{base}/app/index.html", timeout=30)
    assert index.status_code == 200
    assert "<title" in index.text.lower(), "the application shell, not an API error"
    client = session(base)
    try:
        tools = {tool["name"]: tool for tool in client.get("/api/v1/diagnostics").json()["tools"]}
    finally:
        client.close()
    for name, pinned in pins().items():
        assert tools[name]["pinned"] == pinned, name
        # Recorded *and* installed: the reported version comes from running the binary.
        assert pinned in tools[name]["version"], (name, tools[name])
        assert tools[name]["path"], f"{name} is not on PATH inside the image"
    logs = docker("logs", container, check=False)
    assert SECRET not in logs.stdout + logs.stderr, "the access secret never reaches the log"
@needs_docker
 def test_the_declared_health_check_reports_readiness(serving):
    """The declared HEALTHCHECK is readiness, so Docker's own verdict is the assertion."""
    _, container = serving
    deadline = time.monotonic() + READY_TIMEOUT_SECONDS
    status = ""
    while time.monotonic() < deadline:
        status = docker(
            "inspect", "-f", "{{.State.Health.Status}}", container, check=False
        ).stdout.strip()
        if status == "healthy":
            break
        time.sleep(1)
    assert status == "healthy"
    probe = docker("exec", container, "/usr/local/bin/healthcheck.sh", check=False)
    assert probe.returncode == 0
    # Point the probe at a port nothing serves: the same script must fail, which is
    # what makes the healthy verdict above evidence rather than a default.
    unready = docker(
        "exec",
        "--env",
        "PHOTO_PIPELINE_PORT=1",
        container,
        "/usr/local/bin/healthcheck.sh",
        check=False,
    )
    assert unready.returncode != 0
 # ── identity: never root, always the configured owner ────────────────────────
@needs_docker
 def test_the_container_refuses_to_run_as_root(image, data_dir):
    result = docker(
        "run",
        "--rm",
        "--user",
        "0:0",
        "--volume",
        f"{data_dir}:/data",
        image,
        "diagnostics",
        check=False,
    )
    assert result.returncode != 0
    assert "refusing to run as root" in result.stderr + result.stdout
    assert not list(data_dir.iterdir()), "a refused container writes nothing"
@needs_docker
 def test_what_the_container_writes_is_owned_by_the_build_arguments(image):
    """The identity the image was built with is the identity on disk afterwards.
    Asserted from inside the container so it holds on every host: a macOS bind mount
    reports an ownership the container never chose. The host-side proof, which is what
    the mounted library actually needs, is the Linux test below.
    """
    port = free_port()
    container = run_detached(image, port, "serve")
    try:
        wait_until_ready(f"http://127.0.0.1:{port}", container)
        owner = docker(
            "exec", container, "stat", "-c", "%u:%g", "/data/photo_pipeline.db"
        ).stdout.strip()
        assert owner == f"{os.getuid()}:{os.getgid()}"
        assert docker("exec", container, "id", "-u").stdout.strip() == str(os.getuid())
    finally:
        docker("rm", "--force", container, check=False)
@needs_docker
@pytest.mark.skipif(
    platform.system() != "Linux",
    reason="bind-mount ownership is virtualised by Docker Desktop on macOS/Windows",
 )
 def test_files_the_container_writes_keep_the_configured_ownership(image, data_dir):
    docker("run", "--rm", "--volume", f"{data_dir}:/data", image, "migrate", timeout=300)
    written = sorted(path for path in data_dir.rglob("*") if path.is_file())
    assert written, "migrate creates the database in the mounted data directory"
    for path in written:
        assert (path.stat().st_uid, path.stat().st_gid) == (os.getuid(), os.getgid()), path
@needs_docker
 def test_the_worker_role_runs_from_the_same_image(image, data_dir):
    """One image, two roles: the worker is the same entrypoint with another argument."""
    port = free_port()
    container = run_detached(image, port, "worker", "--id", "container-worker")
    try:
        # Taking the worker's library lock is the observable proof that it started,
        # migrated, and reached its job loop — no sleep required (US07-05).
        deadline = time.monotonic() + READY_TIMEOUT_SECONDS
        lock = ""
        while not lock and time.monotonic() < deadline:
            assert docker("inspect", "-f", "{{.State.Running}}", container).stdout.strip() == (
                "true"
            ), docker("logs", container, check=False).stdout
            lock = docker("exec", container, "cat", "/data/worker.lock.json", check=False).stdout
            time.sleep(0.5)
        assert lock, docker("logs", container, check=False).stdout
        assert json.loads(lock)["role"] == "worker"
        role = docker("exec", container, "cat", "/tmp/photo-pipeline-role").stdout.strip()
        assert role == "worker", "the health check can tell which role this container is"
    finally:
        docker("rm", "--force", container, check=False)
 if __name__ == "__main__":  # a quick way to run just this file
    raise SystemExit(pytest.main([__file__, "-v", *sys.argv[1:]]))
--- a/tests/e2e/test_crash_recovery.py
+++ b/tests/e2e/test_crash_recovery.py
@@ -1,274 +0,0 @@
 """Process death at the newer control points (US07-04, concept §18).
 The rename and archive journals already prove crash safety at each of their
 transitions (tests/integration/test_rename_recovery.py,
 tests/integration/test_archive_recovery.py). The three transitions covered here
 are the remaining ones where a kill leaves the world and the database disagreeing:
 - ``exif:written``   — keywords are on disk, nothing about them is recorded;
 - ``upload:accepted``— the uploader finished, no outcome is stored;
 - ``job:item_done``  — one item is durably done, the job is not finished.
 Each test kills a real child process at the barrier and then asserts what a
 restart does: resume idempotently, or say plainly that a human has to look. Never
 "assume it worked".
 """
 from __future__ import annotations
 import os
 import shutil
 import subprocess
 import sys
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 import numpy as np
 import pytest
 from PIL import Image
 from sqlalchemy import select
 from photo_pipeline.config import Config
 from photo_pipeline.db import create_db_engine, create_session_factory, run_migrations
 from photo_pipeline.faults import EXIF_WRITTEN, JOB_ITEM_DONE, UPLOAD_ACCEPTED
 from photo_pipeline.integrations import exiftool
 from photo_pipeline.jobs.worker import Worker
 from photo_pipeline.models import Asset, SafetyReview
 from photo_pipeline.services import exif_checkpoint, hashing
 from photo_pipeline.services.jobs import ItemState, JobService, JobState
 from photo_pipeline.services.safety import SafetyService
 from photo_pipeline.services.upload_batches import BatchState, UploadBatchService
 from photo_pipeline.services.upload_verification import retry_blockers
 from photo_pipeline.services.uploads import UploadService
 from tests.e2e._pipeline_harness import (
    SILENT_UPLOADER,
    FakeImmich,
    fake_uploader,
    mark_upload_ready,
    seed_album,
 )
 REPO = Path(__file__).resolve().parents[2]
 NOW = datetime(2026, 1, 1, tzinfo=timezone.utc)
 def _child(script: str, *args: str, barrier: str, tmp_path: Path) -> None:
    """Run ``script`` in a child that dies at ``barrier``; assert it really died."""
    path = tmp_path / f"child_{barrier.replace(':', '_')}.py"
    path.write_text(script.format(repo=str(REPO)))
    env = dict(os.environ)
    env["PHOTO_PIPELINE_FAULT_AFTER"] = barrier
    result = subprocess.run(
        [sys.executable, str(path), *args], env=env, capture_output=True
    )
    assert result.returncode in (9, -9), (
        f"child should have been killed at {barrier}, got {result.returncode}: "
        f"{result.stderr.decode(errors='replace')[-400:]}"
    )
 def _env(tmp_path, **extra):
    (tmp_path / "data").mkdir(exist_ok=True)
    lib = tmp_path / "lib"
    lib.mkdir(exist_ok=True)
    config = Config.from_env(
        {
            "PHOTO_PIPELINE_DATA_DIR": str(tmp_path / "data"),
            "PHOTO_PIPELINE_LIBRARY_ROOTS": str(lib),
            **extra,
        }
    )
    run_migrations(config.database_url)
    return config, create_session_factory(create_db_engine(config.database_url)), lib
 def _image(path: Path, seed: int = 3) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    pixels = np.random.default_rng(seed).integers(0, 256, (64, 96, 3), dtype=np.uint8)
    Image.fromarray(pixels).save(path, quality=90)
 def _register(sf, path: Path) -> str:
    asset_id = str(uuid.uuid4())
    with sf() as session:
        session.add(
            Asset(
                id=asset_id,
                original_path=str(path),
                current_path=str(path),
                discovered_at=NOW,
                hash_version=1,
                byte_size=path.stat().st_size,
                current_sha256=hashing.sha256_file(path),
            )
        )
        session.commit()
    return asset_id
 # ── EXIF written, checkpoint not recorded ────────────────────────────────────
 DECIDE_SCRIPT = """
 import sys
 sys.path.insert(0, {repo!r})
 from photo_pipeline.db import create_db_engine, create_session_factory
 from photo_pipeline.services.safety import SafetyService
 db_url, asset_id = sys.argv[1], sys.argv[2]
 sf = create_session_factory(create_db_engine(db_url))
 SafetyService(sf).decide(asset_id, "nsfw")
 """
@pytest.mark.skipif(shutil.which("exiftool") is None, reason="exiftool not installed")
 def test_a_crash_after_the_exif_write_leaves_nothing_verified_and_re_runs_cleanly(tmp_path):
    config, sf, lib = _env(tmp_path)
    path = lib / "a.jpg"
    _image(path)
    asset_id = _register(sf, path)
    original_sha = hashing.sha256_file(path)
    _child(
        DECIDE_SCRIPT, config.database_url, asset_id, barrier=EXIF_WRITTEN, tmp_path=tmp_path
    )
    # The file changed, but the application claims nothing about it: no decision,
    # no projection, and the stored hash is still the pre-write one.
    assert "nsfw" in exiftool.read_keyword_sets([str(path)])[str(path)]
    assert hashing.sha256_file(path) != original_sha
    with sf() as session:
        assert session.scalars(select(SafetyReview)).all() == []
        assert session.get(Asset, asset_id).current_sha256 == original_sha
    assert exif_checkpoint.state_for(sf, asset_id, "safety") is None
    # Re-running is the recovery: the write is idempotent, so the second attempt
    # verifies and records what the first one only did to the file.
    review = SafetyService(sf).decide(asset_id, "nsfw")
    assert review["exif_verified"] is True
    assert exif_checkpoint.state_for(sf, asset_id, "safety") == exif_checkpoint.VERIFIED
    keywords = exiftool.read_keyword_sets([str(path)])[str(path)]
    assert "nsfw" in keywords and "sfw" not in keywords
    with sf() as session:
        asset = session.get(Asset, asset_id)
        assert asset.current_sha256 == hashing.sha256_file(path)
 # ── uploader accepted, outcome not persisted ─────────────────────────────────
 UPLOAD_SCRIPT = """
 import sys
 sys.path.insert(0, {repo!r})
 from photo_pipeline.config import Config
 from photo_pipeline.db import create_db_engine, create_session_factory
 from photo_pipeline.services.upload_batches import UploadBatchService
 db_url, data_dir, lib, binary, server, batch_id = sys.argv[1:7]
 config = Config.from_env(
    {{
        "PHOTO_PIPELINE_DATA_DIR": data_dir,
        "PHOTO_PIPELINE_LIBRARY_ROOTS": lib,
        "PHOTO_PIPELINE_IMMICH_GO_BINARY": binary,
        "PHOTO_PIPELINE_IMMICH_SERVER_URL": server,
        "PHOTO_PIPELINE_IMMICH_API_KEY": "sentinel",
    }}
 )
 sf = create_session_factory(create_db_engine(db_url))
 UploadBatchService(sf, config=config).run(batch_id)
 """
 def test_a_crash_after_the_uploader_accepted_requires_verification(tmp_path):
    """immich-go exited cleanly and the server may hold every file, but nothing was
    written down. Recovery must not guess success — and must not blindly retry."""
    seeded = seed_album(tmp_path)
    mark_upload_ready(seeded)
    immich = FakeImmich()
    binary = fake_uploader(tmp_path, SILENT_UPLOADER)
    config = Config.from_env(
        {
            "PHOTO_PIPELINE_DATA_DIR": str(seeded.data),
            "PHOTO_PIPELINE_LIBRARY_ROOTS": str(seeded.lib),
            "PHOTO_PIPELINE_IMMICH_GO_BINARY": str(binary),
            "PHOTO_PIPELINE_IMMICH_SERVER_URL": immich.url,
            "PHOTO_PIPELINE_IMMICH_API_KEY": "sentinel",
        }
    )
    engine = create_db_engine(config.database_url)
    sf = create_session_factory(engine)
    service = UploadBatchService(sf, config=config)
    report = UploadService(sf, config=config).preflight(["rome"])
    assert report["state"] == "ready", report["blockers"]
    batch_id = service.create(["rome"], token=report["token"])[0]["id"]
    try:
        # The batch is claimed by the child, which dies once the uploader has run.
        _child(
            UPLOAD_SCRIPT,
            config.database_url,
            str(seeded.data),
            str(seeded.lib),
            str(binary),
            immich.url,
            batch_id,
            barrier=UPLOAD_ACCEPTED,
            tmp_path=tmp_path,
        )
    finally:
        immich.stop()
    assert service.get(batch_id)["state"] == BatchState.RUNNING  # lane still held
    recovered = service.recover()
    assert recovered == {"interrupted": 1}
    batch = service.get(batch_id)
    assert batch["state"] == BatchState.UNKNOWN and batch["error_code"] == "interrupted"
    assert [b["code"] for b in retry_blockers(batch)] == ["requires_verification"]
    assert all(item["state"] == "pending" for item in batch["items"]), "nothing claimed as sent"
 # ── one item done, the job unfinished ────────────────────────────────────────
 WORKER_SCRIPT = """
 import sys
 sys.path.insert(0, {repo!r})
 from pathlib import Path
 from photo_pipeline.db import create_db_engine, create_session_factory
 from photo_pipeline.jobs.worker import Worker
 db_url, log = sys.argv[1], Path(sys.argv[2])
 def handler(item_key, ctx):
    with log.open("a") as handle:
        handle.write(item_key + "\\n")
 sf = create_session_factory(create_db_engine(db_url))
 Worker(sf, {{"scan": handler}}, "killable", lease_seconds=1).run_once()
 """
 def test_a_crash_between_items_resumes_without_running_the_done_item_twice(tmp_path):
    config, sf, lib = _env(tmp_path)
    service = JobService(sf)
    job = service.enqueue("scan", items=["a", "b", "c"])
    log = tmp_path / "handled.log"
    _child(
        WORKER_SCRIPT, config.database_url, str(log), barrier=JOB_ITEM_DONE, tmp_path=tmp_path
    )
    crashed = log.read_text().split()
    assert crashed == ["a"], "the child should have died right after its first item"
    assert service.get(job["id"])["state"] == JobState.RUNNING
    # A fresh worker takes over once the dead lease expires.
    import time
    time.sleep(1.1)  # the child's lease is one second long
    fresh = Worker(sf, {"scan": lambda item, ctx: log.open("a").write(item + "\n")}, "alive")
    fresh.run_once()
    assert service.get(job["id"])["state"] == JobState.SUCCEEDED
    handled = log.read_text().split()
    assert sorted(handled) == ["a", "b", "c"], f"an item ran twice or not at all: {handled}"
    assert service.progress(job["id"])["by_state"] == {ItemState.SUCCEEDED: 3}
--- a/tests/e2e/test_phase_a_pipeline.py
+++ b/tests/e2e/test_phase_a_pipeline.py
@@ -22,8 +22,6 @@ import numpy as np
 import pytest
 from PIL import Image
 from tests.conftest import session_client
 REPO = Path(__file__).resolve().parents[2]
@@ -94,7 +92,7 @@ class ServerController:
                pytest.fail(f"server exited: {err.decode(errors='replace')}")
            try:
                if httpx.get(f"{self.base}/api/v1/health/ready", timeout=1).status_code == 200:
-                    self.client = session_client(self.base, timeout=10)
+                    self.client = httpx.Client(base_url=self.base, timeout=10)
                    return
            except httpx.HTTPError:
                time.sleep(0.2)
--- a/Show More
+++ b/Show More