US06-05: Operate Archive and Restore in the Browser

2026-08-16 20:38:39 +02:00
139 changed files with 315 additions and 15006 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/.env.example
+++ b/.env.example
@@ -1,85 +0,0 @@
 # Every setting the application and its composition read, with no values in it.
 # Copy to `.env`, fill in what you need, and keep that copy out of git (it is
 # gitignored, and the work-item safety checks refuse to stage it).
 #
 #   cp .env.example .env
 #
 # Empty means "use the default noted beside it". Anything already exported in the
 # shell wins over this file, both for the app and for `docker compose`.
 # ── the composition (host side; read by docker-compose.yml only) ─────────────
 # The photo library on this host. Bind-mounted at PHOTO_PIPELINE_LIBRARY_ROOTS.
 PHOTO_PIPELINE_LIBRARY_HOST_PATH=
 # Which image to run. Default: photo-pipeline:dev (what `up --build` builds).
 PHOTO_PIPELINE_IMAGE=
 # Must be the owner of the library above: what the containers rename and rewrite
 # keeps this ownership. Default: 1000 / 1000.
 PHOTO_PIPELINE_UID=
 PHOTO_PIPELINE_GID=
 # Host address the API port is published on. Default: 127.0.0.1. Anything else
 # exposes the app beyond this machine — then ALLOWED_HOSTS and ACCESS_SECRET below
 # are what stand in for the loopback boundary (US08-01).
 PHOTO_PIPELINE_PUBLISH_ADDRESS=
 # This file's own path, if it is not ./.env. Default: .env.
 PHOTO_PIPELINE_ENV_FILE=
 # ── library and data ────────────────────────────────────────────────────────
 # os.pathsep-separated. In a container these are the *container-side* mount paths,
 # and `serve`/`worker` refuse to start when they are not mounted.
 PHOTO_PIPELINE_LIBRARY_ROOTS=
 # Database, WAL, thumbnail cache, journals, backups. Default: data (the container
 # sets /data, which is the persistent volume; a network mount is unsupported).
 PHOTO_PIPELINE_DATA_DIR=
 # Database file, if it should not live in the data directory. Default:
 # <data dir>/photo_pipeline.db.
 PHOTO_PIPELINE_DB_PATH=
 # ── serving ─────────────────────────────────────────────────────────────────
 # Bind address. Default: 127.0.0.1. The composition sets 0.0.0.0 inside the
 # container and publishes to loopback on the host instead.
 PHOTO_PIPELINE_HOST=
 # Under the composition this is the *published* host port; the container serves
 # 8000. Default: 8000.
 PHOTO_PIPELINE_PORT=
 # Comma-separated hostnames the app answers to besides loopback. Empty means
 # loopback only. Naming one makes the access secret mandatory.
 PHOTO_PIPELINE_ALLOWED_HOSTS=
 # Traded for the session cookie at GET /api/v1/session via X-Access-Secret.
 # Required as soon as the app is reachable from anywhere but loopback. Generate
 # one with: python -c 'import secrets; print(secrets.token_urlsafe(32))'
 PHOTO_PIPELINE_ACCESS_SECRET=
 # Comma-separated peer addresses whose X-Forwarded-Proto/-Host may be believed.
 # Only the reverse proxy's address belongs here. Default: none.
 PHOTO_PIPELINE_TRUSTED_PROXIES=
 # Largest request body accepted, in bytes. Default: 1048576.
 PHOTO_PIPELINE_MAX_REQUEST_BYTES=
 # ── logging ─────────────────────────────────────────────────────────────────
 # Default: INFO.
 PHOTO_PIPELINE_LOG_LEVEL=
 # json or text. Default: json.
 PHOTO_PIPELINE_LOG_FORMAT=
 # ── limits ──────────────────────────────────────────────────────────────────
 # Thumbnail cache quota in bytes. Default: 500000000.
 PHOTO_PIPELINE_THUMBNAIL_CACHE_QUOTA_BYTES=
 # Refuse to decode images larger than this many pixels. Default: 100000000.
 PHOTO_PIPELINE_THUMBNAIL_MAX_PIXELS=
 # Free space an archive destination must keep beyond the transfer. Default:
 # 1000000000.
 PHOTO_PIPELINE_ARCHIVE_FREE_SPACE_RESERVE_BYTES=
 # ── safety gate ─────────────────────────────────────────────────────────────
 # true refuses every mutating request until a read-only dry run of this library has
 # been produced and approved (US07-07). Default: false. Turn it on before pointing
 # the app at photos that cannot be replaced.
 PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL=
 # ── external services ───────────────────────────────────────────────────────
 # Vision provider key for the analysis stage. Without it, analysis cannot run.
 PHOTO_PIPELINE_VISION_API_KEY=
 # Immich server and its API key, for the upload stage.
 PHOTO_PIPELINE_IMMICH_SERVER_URL=
 PHOTO_PIPELINE_IMMICH_API_KEY=
 # Uploader binary. Default: immich-go (on PATH; pinned inside the image).
 PHOTO_PIPELINE_IMMICH_GO_BINARY=
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -1,99 +0,0 @@
 # Publish and redeploy (US08-04). Adapted from the crowdsec-admin deploy workflow:
 # build, log in to the Gitea registry, push, trigger the Portainer webhook, prune.
 # The difference is the gate — this project has a required suite that must not be
 # skipped, so publishing happens only after `Test` (`.gitea/workflows/test.yml`)
 # succeeded on `main`, never on the push itself.
 #
 # The stack is managed by Portainer from git (`docker-compose.yml`), and the runtime
 # secrets it needs — vision key, Immich key, access secret — live in the Portainer
 # stack's environment. They are deliberately not repository secrets and are not in the
 # image: rotation stays in one place, and a repository read never discloses them.
 #
 # Repository secrets required:
 #   REGISTRY_USER          user with write:package on the registry
 #   REGISTRY_TOKEN         that user's token
 #   PORTAINER_WEBHOOK_URL  POST URL from the stack's auto-update setting
 name: Deploy
 on:
  workflow_run:
    workflows:
      - Test
    types:
      - completed
    branches:
      - main
  workflow_dispatch:
    inputs:
      dry_run:
        description: Build and push a scratch tag only — leave `latest` and the running stack alone
        type: boolean
        default: true
 concurrency:
  # Deliberately not keyed by commit: the point is that two deploys of *different*
  # commits cannot overlap. Queued, not cancelled — a half-pushed tag set is worse
  # than a late one.
  group: deploy
  cancel-in-progress: false
 env:
  IMAGE: git.domverse-berlin.eu/domverse/photoanalyzer
  # The commit that was tested, not whatever `main` points at by the time this starts.
  SHA: ${{ gitea.event.workflow_run.head_sha || gitea.sha }}
 jobs:
  publish:
    # A completed `Test` run is not a passing one.
    if: >-
      (gitea.event_name == 'workflow_run' && gitea.event.workflow_run.conclusion == 'success')
      || (gitea.event_name == 'workflow_dispatch' && inputs.dry_run == false)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ env.SHA }}
      - name: Log in to the Gitea registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.domverse-berlin.eu -u "${{ secrets.REGISTRY_USER }}" --password-stdin
      - name: Build and push
        # The commit tag is pushed first, so a `latest` that exists is always a tag
        # that also exists under its own commit — which is what makes a rollback a
        # tag change rather than a rebuild.
        run: |
          docker build -t "$IMAGE:$SHA" -t "$IMAGE:latest" .
          docker push "$IMAGE:$SHA"
          docker push "$IMAGE:latest"
      - name: Trigger the Portainer redeploy
        # --fail turns an HTTP error into a non-zero exit: a redeploy that did not
        # happen must not read as a green deploy.
        run: curl -sS --fail -X POST "${{ secrets.PORTAINER_WEBHOOK_URL }}"
      - name: Prune dangling images
        # Untagged layers only. Published tags are the rollback history; `-a` would
        # delete exactly the images this workflow exists to keep.
        run: docker image prune -f
  dry-run:
    # Manual only, and the default: prove the image still builds and the registry
    # still accepts it without moving `latest` or touching the running stack.
    if: gitea.event_name == 'workflow_dispatch' && inputs.dry_run
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Log in to the Gitea registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.domverse-berlin.eu -u "${{ secrets.REGISTRY_USER }}" --password-stdin
      - name: Build and push a scratch tag
        run: |
          docker build -t "$IMAGE:scratch-$SHA" .
          docker push "$IMAGE:scratch-$SHA"
      - name: Prune dangling images
        run: docker image prune -f
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -1,103 +0,0 @@
 # The test gate. Deploy waits for this workflow by name (`.gitea/workflows/deploy.yml`
 # triggers on `workflow_run: [Test]`), so renaming it here without renaming it there
 # would leave `main` publishing without a suite. `tests/integration/test_deploy_workflows.py`
 # asserts both halves of that link, and that the commands below are still the ones
 # configured in `work_item/.work-item.yml`.
 name: Test
 on:
  pull_request:
  push:
    branches:
      - main
 concurrency:
  # One run per branch; a newer push makes the older run's answer irrelevant.
  group: test-${{ gitea.ref }}
  cancel-in-progress: true
 jobs:
  suites:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install exiftool
        # The EXIF checkpoints are the safety invariant of every metadata stage; a run
        # without exiftool would skip them for a reason the release gate accepts.
        run: |
          SUDO=
          if [ "$(id -u)" -ne 0 ]; then SUDO=sudo; fi
          $SUDO apt-get update
          $SUDO apt-get install -y --no-install-recommends libimage-exiftool-perl
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install the application and its test dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e '.[test]'
          python -m playwright install --with-deps chromium
      - name: Helper suite
        run: work_item/scripts/python -m unittest discover -s work_item/tests -v
      - name: Application suite
        run: work_item/scripts/python -m pytest tests -q
  # The deployed container, verified the way the host application is (US08-05). It
  # runs on `main` only — a pull request has nothing published to upgrade *from*, and
  # building two images per push would pay for that on every commit. Deploy waits for
  # this whole workflow, so a red container gate is a deploy that does not happen.
  container:
    if: gitea.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        # The upgrade journey builds the previous commit's tree when no published
        # image is named, so the history has to be there.
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install the application and its test dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e '.[test]'
          python -m playwright install --with-deps chromium
      - name: Container acceptance gate
        # One command: it builds the image, provisions the composition against a
        # temporary fixture library and an isolated volume, runs the phase_h journeys,
        # destroys the stack, and writes the evidence. Any skipped check fails it.
        env:
          # The fixture libraries are bind-mounted into the containers, so this path
          # has to be one the Docker daemon can see. On a runner that talks to a
          # sibling daemon, point it at a shared host path instead of the workspace —
          # an unshared path arrives as an empty mount and the journeys fail on the
          # scan, which is the symptom to recognise.
          PHOTO_PIPELINE_DATA_DIR: ${{ gitea.workspace }}/gate-data
          PHOTO_PIPELINE_LIBRARY_ROOTS: ${{ gitea.workspace }}/gate-library
          PHOTO_PIPELINE_TEST_MOUNT_BASE: ${{ gitea.workspace }}/gate-mounts
        run: |
          mkdir -p "$PHOTO_PIPELINE_LIBRARY_ROOTS" "$PHOTO_PIPELINE_TEST_MOUNT_BASE"
          python -m photo_pipeline container-gate --output gate-evidence
      - name: Keep the evidence
        # Retained per run, and retained on failure especially: the logs are the only
        # account of what the containers did.
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: container-gate-${{ gitea.sha }}
          path: gate-evidence
--- 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,274 +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.
 ## Composed runtime (US08-03)
 `docker-compose.yml` is the deployment: one `serve` container, one `worker`
 container, one bind-mounted library, one data volume, and a one-shot `migrate` that
 both roles wait for.
 ```bash
 cp .env.example .env && $EDITOR .env    # nothing has a value in it; fill in yours
 docker compose up -d --build
 ```
 `.env.example` lists every `PHOTO_PIPELINE_*` variable with its default in a comment
 and no values at all. The three the composition cannot start without are
 `PHOTO_PIPELINE_LIBRARY_HOST_PATH` (the library on this host),
 `PHOTO_PIPELINE_LIBRARY_ROOTS` (where it is mounted *inside* the container), and
 `PHOTO_PIPELINE_ACCESS_SECRET` — publishing the port means the app is reachable from
 outside the container, so US08-01 makes the secret mandatory. Set
 `PHOTO_PIPELINE_UID`/`GID` to the owner of the library: what the containers rename
 and rewrite keeps that ownership.
 | invariant | how the composition keeps it |
 |---|---|
 | one writer | `serve` and `worker` take their role's library lock (US07-05) in the shared `/data` volume, so `--scale worker=2` is refused by the lock, not by convention |
 | migrations first | `migrate` runs the backup-then-migrate path and must exit 0 before `api` and `worker` start; a failed upgrade leaves the previous database and its pre-migration backup intact |
 | container paths | `PHOTO_PIPELINE_LIBRARY_ROOTS` is both the mount target and the configured root; a root that is not mounted makes `serve`/`worker` exit 5 at startup instead of writing into the container's throwaway layer |
 | loopback by default | the port is published to `127.0.0.1` unless `PHOTO_PIPELINE_PUBLISH_ADDRESS` says otherwise, and exposing it needs the hostname in `PHOTO_PIPELINE_ALLOWED_HOSTS` plus the access secret |
 | restart safety | both roles are `restart: unless-stopped` with a 30 s stop grace period, and a job interrupted by a restart resumes exactly as it does on a host restart |
 The `data` volume holds the database, its write-ahead log, the thumbnail cache,
 journals, and backups. **It must stay on a local filesystem** — SQLite in WAL mode
 needs real local locking, so NFS, SMB, and network volume drivers are unsupported
 there and corrupt the database rather than slow it down. The library bind mount has
 no such restriction.
 Operating the deployment is operating the same CLI:
 ```bash
 docker compose run --rm --no-deps api diagnostics
 docker compose run --rm --no-deps api backup --reason pre-upgrade
 docker compose run --rm --no-deps api verify-backup /data/backups/<name>
 docker compose run --rm --no-deps api restore /data/backups/<name> --into /data/restored
 docker compose logs -f worker
 ```
 `--no-deps` keeps a one-off command from starting a second stack; `api` is only the
 service the command borrows the image and mounts from. `restore` is deliberately not
 an API call: it replaces the state of an installation and belongs to a stopped one,
 so stop `api` and `worker` first and restart them against the restored directory.
 ## Publishing and deploying (US08-04)
 Two workflows in `.gitea/workflows/` make `main` the only path to the running stack:
 | workflow | runs on | does |
 |---|---|---|
 | `test.yml` (**Test**) | every pull request, and every push to `main` | installs exiftool, the package, and Chromium, then runs the suites configured in `work_item/.work-item.yml` |
 | `deploy.yml` (**Deploy**) | a **successful** `Test` run on `main`, or manual dispatch | builds the image, pushes it, triggers the Portainer webhook, prunes dangling layers |
 Deploy waits for `Test` through `workflow_run`, so publishing is downstream of a green
 suite rather than of a push. `completed` is not `success`: the publish job runs only on
 `conclusion == 'success'`. Because an unmatched `workflow_run` filter does not fail but
 simply never fires, `tests/integration/test_deploy_workflows.py` asserts the link from
 both ends — renaming either workflow, or dropping one of the configured suites out of
 the test job, fails that test rather than silently unhooking the gate.
 The image is `git.domverse-berlin.eu/domverse/photoanalyzer`, tagged with the commit
 SHA and `latest`. The commit tag is pushed first, so a `latest` that exists always has
 a commit tag beside it and **a rollback is a tag change, not a rebuild**:
 ```bash
 docker pull  git.domverse-berlin.eu/domverse/photoanalyzer:<known-good-sha>
 docker tag   git.domverse-berlin.eu/domverse/photoanalyzer:<known-good-sha> \
             git.domverse-berlin.eu/domverse/photoanalyzer:latest
 docker push  git.domverse-berlin.eu/domverse/photoanalyzer:latest
 # then trigger the Portainer webhook, or redeploy the stack from Portainer
 ```
 Manual dispatch defaults to **dry run**: it builds and pushes `scratch-<sha>` only, and
 touches neither `latest` nor the running stack. Clear the `dry_run` input to publish by
 hand. A workflow-level `concurrency: deploy` group with `cancel-in-progress: false`
 queues deploys instead of overlapping them, so two commits can never race to `latest`.
 ### Secrets
 Repository secrets — used only by the pipeline:
 | secret | purpose |
 |---|---|
 | `REGISTRY_USER` | registry user with `write:package` |
 | `REGISTRY_TOKEN` | that user's token, passed on stdin, never as an argument |
 | `PORTAINER_WEBHOOK_URL` | the stack's auto-update POST URL; `curl --fail` makes a refused redeploy a failed workflow |
 Runtime secrets — `PHOTO_PIPELINE_VISION_API_KEY`, `PHOTO_PIPELINE_IMMICH_API_KEY`,
 `PHOTO_PIPELINE_ACCESS_SECRET` — are **not** repository secrets and are not in the
 image. The stack is managed by Portainer from git (`docker-compose.yml`), and those
 values live in the Portainer stack's environment, so rotation is one place and a
 repository read discloses nothing. A test asserts the workflows never name them.
 ## Container acceptance gate (US08-05)
 The deployed container is verified the way the host application is, by one command:
 ```bash
 work_item/scripts/python -m photo_pipeline container-gate --output gate-evidence
 ```
 It builds the image, provisions the composition against a **temporary fixture library
 on a bind mount and an isolated data volume**, runs the `phase_h` journeys against it,
 destroys every stack afterwards, and writes `release-report.json`, `logs/container.log`,
 and `CHECKSUMS.sha256` into the evidence directory. It exits non-zero when a journey
 fails, when the story matrix has a hole, **or when any check skipped at all** — unlike
 the release gate, this one accepts no environment excuse: a run that never reached the
 containers proved nothing about them.
 The journeys (`tests/e2e/test_phase_h_container.py`) are:
 | journey | what it proves |
 |---|---|
 | browser | discovery, duplicate review, analysis, album proposal, rename, upload preflight, and archive views, driven through the containerized frontend — including a rename that really moves the operator's folder on the bind mount |
 | upgrade | the previous version's image runs first, then this one against the same volume: schema at the new head, assets, analysis results, job progress, the unapplied rename plan, and the thumbnail cache all survive |
 | restart | `docker kill` on both containers mid-job; the job resumes, every photo ends with exactly one stored result, and only the in-flight item ever reaches the provider twice |
 | security | no session refused, a forged `X-Forwarded-Host` cannot smuggle an allowed hostname past the check, a symlink out of the mounted library is refused, an unmounted library root refuses startup, and no secret appears in `docker compose logs` |
 The upgrade journey builds the previous commit's tree when no published image is named;
 point it at the real one with `PHOTO_PIPELINE_PREVIOUS_IMAGE`. On a Docker VM (Colima,
 Docker Desktop) the fixture library must live on a shared path — it defaults to
 `~/.cache/photo-pipeline`, overridable with `PHOTO_PIPELINE_TEST_MOUNT_BASE`.
 CI runs this gate as the `container` job of **Test** on pushes to `main` and keeps its
 evidence as a run artefact. Deploy waits for the whole `Test` workflow, so a red
 container gate is a publish that does not happen.
 ## Testing
 One offline command runs the whole suite (unit, integration, and browser
@@ -427,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/E09-documentation.md
+++ b/delivery_backlog/E09-documentation.md
@@ -1,77 +0,0 @@
 # E09 — Product Documentation
 Concept phase: none. Like [E08](E08-container-deployment.md), this epic is a delivery
 addition rather than a product-scope change: the same application, documented well
 enough that somebody who did not build it can install it, understand it, and operate it
 without reading the source.
 It does not change the product scope in
 [`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md). No safety
 invariant moves, no schema changes, no new runtime capability. The one change to the
 running application is a documentation view and the static assets it needs.
 ## Why the application serves its own documentation
 The manuals describe an application that is reached over HTTP behind an access secret.
 Documentation that lives only in the repository is unreachable from the deployment it
 describes: an operator who has just been handed a URL and a secret has no Gitea account
 in front of them. So the same markdown files are both the repository's documentation and
 the deployment's `/docs` view, and neither is a copy of the other.
 ## Decisions made in this epic
 **Markdown is the source.** Everything is written as markdown under `docs/`, so it is
 reviewable in a diff, readable on Gitea, and renderable in the app. No documentation
 format that only a tool can read.
 **The renderer is vendored, not written and not fetched.** `marked` (MIT, no
 dependencies, ships an ES module) is pinned and committed under
 `frontend/js/vendor/`. A CDN is not an option: the application is deployed to a network
 whose outbound access is not assumed, and `default-src 'self'` forbids it.
 **Diagrams are mermaid, rendered client-side, with the script boundary intact.** The
 claim that mermaid requires `'unsafe-eval'` was tested rather than believed: mermaid 11's
 bundle contains no `eval(` and no `new Function` — only a lodash `Function("return this")`
 global-detection fallback that short-circuits on `globalThis` and never executes.
 Rendered under this application's exact CSP, a flowchart produced a 15.8 KB SVG and
 raised **no `script-src` violation**. What it does raise is `style-src`: mermaid styles
 its output with an injected `<style>` element and `style=` attributes.
 So `script-src 'self'` stays exactly as US07-02 and US08-01 left it, and `style-src`
 gains `'unsafe-inline'`. That relaxation is bounded on purpose: with `script-src` intact
 no injected markup can execute, and with `img-src`, `connect-src`, and `font-src` all
 still `'self'`, the CSS-based exfiltration channels stay closed. What remains is
 defacement of a page the operator is already authenticated on.
 The rejected alternative is recorded because it may become the better trade later:
 pre-rendering each diagram to a committed SVG with the already-installed Playwright
 (no Node toolchain needed) and serving that, which would leave CSP untouched entirely at
 the cost of a generator and a freshness check. If `style-src 'unsafe-inline'` is ever
 judged too much, that is the migration, and it does not change a single markdown file.
 **Screenshots are produced, not pasted.** Every screenshot in the user manual is captured
 by Playwright from the real application against a temporary fixture library, by the same
 kind of code that already drives the browser suites. A screenshot nobody can regenerate
 is a screenshot that silently stops being true.
 **The documentation is held to the code by tests.** Configuration keys, CLI commands,
 exit codes, API error codes, job and journal states, and module names all appear in both
 the code and the manuals. Each of those is cross-checked, so the failure mode of stale
 documentation is a red test rather than a misled operator.
 ## Stories
 1. [US09-01 — Serve the documentation inside the application](stories/US09-01-docs-in-app.md)
 2. [US09-02 — Write the installation and operations manual](stories/US09-02-installation-manual.md)
 3. [US09-03 — Write the architecture overview](stories/US09-03-architecture-overview.md)
 4. [US09-04 — Write the user manual with generated screenshots](stories/US09-04-user-manual.md)
 5. [US09-05 — Automate documentation acceptance](stories/US09-05-docs-gate.md)
 ## Epic outcome
 A deployed instance serves its own installation manual, architecture overview, and
 illustrated user manual at `/app/#/docs`, rendered from the same markdown files that are
 readable in the repository. Screenshots are regenerated from the running application,
 every documented command, setting, state, and error code is cross-checked against the
 code that implements it, and one gate fails the build when documentation and application
 disagree.
--- a/delivery_backlog/README.md
+++ b/delivery_backlog/README.md
@@ -2,14 +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 two delivery-format
+epics and small, independently verifiable user stories.
 epics: E08 packages the released application as a deployable container, and E09
 documents it for the people who install, operate, and use it.
 ## Numbering and file naming
- Epics: `E01` through `E07`, matching concept Phases A through G; `E08` and `E09`
+- Epics: `E01` through `E07`, matching concept Phases A through G.
  have no 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`.
@@ -39,8 +36,6 @@ documents it for the people who install, operate, and use it.
 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)
 9. [E09 — Product documentation](E09-documentation.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/delivery_backlog/stories/US09-01-docs-in-app.md
+++ b/delivery_backlog/stories/US09-01-docs-in-app.md
@@ -1,49 +0,0 @@
 # US09-01 — Serve the Documentation Inside the Application
 Epic: [E09](../E09-documentation.md)
 As an operator who was handed a URL and an access secret, I want the manuals inside the
 application I am looking at, so that understanding it does not require a repository
 checkout or an internet connection.
 ## Acceptance criteria
 - Documentation lives as markdown under `docs/`, with an index that names every page and
  the order it is meant to be read in. The same files render on Gitea without
  modification.
 - The application serves a `/docs` view reachable from the main navigation, listing the
  pages and rendering the selected one.
 - Rendering uses a vendored, version-pinned markdown library committed under
  `frontend/js/vendor/`. It is not fetched from a CDN, not bundled by a build step, and
  not written by hand. The build records the version and a checksum of the vendored file.
 - Diagrams written as ```mermaid``` fenced blocks render as diagrams. Mermaid is vendored
  the same way.
 - `script-src` in the Content-Security-Policy is unchanged: no `'unsafe-eval'`, no
  `'unsafe-inline'`. Only `style-src` gains `'unsafe-inline'`, and the reason is recorded
  where the policy is defined.
 - Links between documents work in the app: a relative `../foo.md#section` link navigates
  to that page and heading rather than downloading a file or leaving the application.
  Every heading has a stable anchor, and a deep link to an anchor scrolls to it.
 - An unknown page renders a documentation-specific not-found message with a link back to
  the index, and never exposes a filesystem path.
 - Documentation is readable without an access secret **or** behind the same session as
  the rest of the application — whichever is chosen is stated explicitly in the story's
  implementation notes and covered by a test, because an operator locked out by a
  configuration mistake is exactly who needs the troubleshooting page.
 - The view works with no outbound network access at all.
 ## Automated tests
 - Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of
  relative markdown links into in-app routes.
 - Integration: every markdown file under `docs/` is reachable from the index; every
  internal link in every document resolves to a file and, where an anchor is given, to a
  heading that exists; the vendored library files match their recorded checksums.
 - Browser: the documentation view renders a page, follows an internal link, deep-links to
  an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an
  unknown page — all with **zero console errors and zero CSP violations**, asserted, not
  eyeballed.
 ## Dependencies
 - None beyond the delivered application.
--- a/delivery_backlog/stories/US09-02-installation-manual.md
+++ b/delivery_backlog/stories/US09-02-installation-manual.md
@@ -1,46 +0,0 @@
 # US09-02 — Write the Installation and Operations Manual
 Epic: [E09](../E09-documentation.md)
 As somebody installing this application for the first time, I want one manual that takes
 me from nothing to a running instance pointed at my photo library, so that I do not have
 to reconstruct the procedure from the README, the compose file, and the test suite.
 ## Acceptance criteria
 - A **host installation** path: prerequisites and their versions (Python, exiftool,
  immich-go, Playwright's browser for the test suite), virtual environment, dependency
  install, `.env`, database migration, starting `serve` and `worker`, and how to verify
  the install succeeded.
 - A **container installation** path: the published image, the compose file, the data
  volume, the library bind mount and why it is mounted the way it is, published ports,
  running behind a reverse proxy with `PHOTO_PIPELINE_ALLOWED_HOSTS` and
  `PHOTO_PIPELINE_TRUSTED_PROXIES`, and the Portainer/webhook deployment already in use.
 - A **configuration reference**: every `PHOTO_PIPELINE_*` setting with its meaning,
  default, accepted values, and whether it is a secret. Secrets are described, never
  exemplified with a real-looking value.
 - A **first run checklist** that ends in a verified state: library discovered, worker
  claiming jobs, readiness endpoint green, diagnostics clean.
 - **Operations**: upgrading (including what the migration backup does), backup, verify,
  restore, pruning, diagnostics, and the log locations for each role.
 - **Troubleshooting**: each refusal an operator can hit at startup — every non-zero exit
  code of the CLI, the trust-boundary refusal, the unmounted library root refusal, the
  library lock being held, and a legacy CLI still running — with the cause and the fix.
 - The manual states the safety invariants an installer must not work around: one worker
  writes, `_IGNORE/` is never read, EXIF is verified before upload, and the library lock
  is authoritative.
 ## Automated tests
 - Every `PHOTO_PIPELINE_*` setting documented exists as a field on `Config`, and every
  field on `Config` is documented — both directions, so a new setting cannot ship
  undocumented.
 - Every CLI command and flag named in the manual exists in the argument parser, and every
  subcommand the parser accepts appears in the manual.
 - Every exit code documented is one the CLI can actually return.
 - No documented example value collides with a real secret pattern (the repository's own
  credential scanner runs over `docs/`).
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-03-architecture-overview.md
+++ b/delivery_backlog/stories/US09-03-architecture-overview.md
@@ -1,47 +0,0 @@
 # US09-03 — Write the Architecture Overview
 Epic: [E09](../E09-documentation.md)
 As a developer or reviewer new to this repository, I want an architecture overview that
 explains what the pieces are and which rules they enforce, so that I can find the right
 module and not violate an invariant I never knew existed.
 ## Acceptance criteria
 - A **context diagram**: the operator, the browser application, the API and worker, the
  photo library, the Immich server, the vision provider, and the archive destination —
  with the direction and nature of every interaction, including which ones leave the
  machine.
 - A **runtime diagram**: the migrate/api/worker composition, the data volume, the library
  bind mount, the SQLite database, and the process lock — showing what is shared and what
  is exclusive.
 - A **module map**: every package under `photo_pipeline/` with its responsibility and the
  boundary it must not cross (which modules may touch the filesystem, which may call an
  external provider, which own schema).
 - **Key flows**, each as a diagram plus prose: the durable job lifecycle from enqueue to
  recovery; the rename journal state machine including the rollback and manual-resolution
  paths; the upload lifecycle through preflight, run, report ingestion, and verification.
 - **The invariants and where they are enforced**, each pointing at the module that owns
  it: one writer at a time, the library process lock, the path policy and library roots,
  `_IGNORE/` exclusion, verified EXIF before upload, safety decisions gating the vision
  provider, and restart-safety of every mutation.
 - **The data model**: the tables, what identity means for an asset, and how a moved file
  keeps its identity.
 - A short **history and donor** section: what was migrated out of the legacy CLIs, where
  the archive and its ledger live, and why they are kept.
 - Diagrams are ```mermaid``` blocks so the source is diffable and Gitea renders them
  natively.
 ## Automated tests
 - Every package and top-level module under `photo_pipeline/` appears in the module map,
  and every module named in the map exists — a new service cannot appear on the map's
  blind side.
 - Every job state, journal state, and upload batch state named in the document exists in
  the code, and every state the code defines is named in the document.
 - Every mermaid block parses (rendered in the browser test without an error node).
 - Every code path referenced by file name exists.
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-04-user-manual.md
+++ b/delivery_backlog/stories/US09-04-user-manual.md
@@ -1,52 +0,0 @@
 # US09-04 — Write the User Manual with Generated Screenshots
 Epic: [E09](../E09-documentation.md)
 As the person actually sorting a photo library, I want a manual that walks the workflow
 screen by screen and tells me what each refusal means, so that I can use the application
 confidently and know what it is about to do to my files before it does it.
 ## Acceptance criteria
 - One page per workflow stage, in the order the application presents them: discovery and
  inventory, duplicate review, safety review, analysis, album proposals, renames, upload,
  archive, and diagnostics. Each page answers the same four questions: what this stage is
  for, what I have to decide, **what it changes on disk or on the server**, and what it
  refuses to do.
 - A **guided first pass** that takes a new library from scan to a verified upload, naming
  the point of no return in each stage and what is reversible after it.
 - Every stage page carries at least one screenshot of the real application showing the
  state being described.
 - Screenshots are **generated** by a committed Playwright script that seeds a temporary
  fixture library, drives the application, and writes the images. Regenerating them is one
  documented command. No screenshot is captured by hand.
 - Screenshots contain no real library paths, no personal photos, and no secrets — the
  fixture library is synthetic, and this is asserted rather than assumed.
 - An **error and refusal catalogue**: every `error.code` the API can return, with what
  causes it, what the application did or refused to do, and what the operator should do
  next. Refusals that protect data (`lock_held`, `rename_recovery_required`,
  `stale_preflight`, `path_not_allowed`, `host_not_allowed`, `dry_run_not_approved`,
  conflict codes) are explained as intentional, not as faults.
 - A **recovery** page: an interrupted rename, an uncertain upload, a failed migration, a
  restored backup — what the application does by itself and what needs a decision.
 - The work-item safety allow list is extended to permit `docs/images/**`, since the
  repository denies image files by default. This is an explicit, reviewed change, not a
  quiet one, and it stays narrow enough that a real photo still cannot be committed.
 ## Automated tests
 - Every `error.code` the application can emit is documented, and every code documented
  exists in the code — both directions.
 - Every image referenced by a documentation page exists, and every image under
  `docs/images/` is referenced by a page.
 - The screenshot generator runs end to end in the test environment and produces every
  image the manual references, against a temporary fixture library that is destroyed
  afterwards.
 - Generated screenshots are checked for library paths outside the fixture root and for
  the configured secrets.
 - Browser: each stage page renders in the documentation view with its screenshot loaded
  and no console error.
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-05-docs-gate.md
+++ b/delivery_backlog/stories/US09-05-docs-gate.md
@@ -1,38 +0,0 @@
 # US09-05 — Automate Documentation Acceptance
 Epic: [E09](../E09-documentation.md)
 As a release owner, I want one gate that proves the documentation still describes the
 application, so that a change to the code cannot quietly make the manuals wrong.
 ## Acceptance criteria
 - One documented command runs every documentation check and retains its evidence, in the
  shape the release and container gates already use.
 - The gate fails when: an internal link or anchor is dead; a page is unreachable from the
  index; an image is referenced but missing or present but unreferenced; a documented
  setting, command, exit code, error code, or state does not exist in the code; a code
  path exists that the documentation is required to cover and does not.
 - The gate regenerates the screenshots and fails when a regenerated image no longer
  matches the committed one beyond a stated tolerance, so a UI change that invalidates the
  manual is a red build rather than a discovery months later.
 - The gate renders every documentation page in a real browser and fails on any console
  error or CSP violation, and asserts that `script-src` contains neither `'unsafe-eval'`
  nor `'unsafe-inline'`.
 - The checks run on a `phase_i` marker; CI runs the gate, and the earlier epic suites keep
  running unchanged.
 - The README and the application's documentation index point at each other, so neither is
  the forgotten copy.
 - Documentation stories are mapped in the story traceability matrix like every other
  story.
 ## Automated tests
 - The gate's own contract is testable without a browser: a seeded broken link, a missing
  image, an undocumented error code, and a stale screenshot each fail it, and a clean tree
  passes.
 - The full documentation suite runs on `phase_i` in CI.
 ## Dependencies
 - US09-01 through US09-04
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,105 +0,0 @@
 # The deployed runtime (US08-03): one API, one worker, one library, one volume.
 #
 # The same image (US08-02) runs both roles, so what is composed here is process
 # topology, not a second application. Three invariants shape it:
 #
 #   * one writer — `serve` and `worker` each take the library process lock for their
 #     role (US07-05), and both containers mount the *same* data volume, which is what
 #     makes the lock file visible to both. Scaling `worker` past 1 is refused by that
 #     lock rather than by anyone remembering not to;
 #   * one local filesystem — the database, its write-ahead log, the thumbnail cache,
 #     and the backups live in the `data` volume, and SQLite in WAL mode requires real
 #     local-filesystem locking. A network mount (NFS, SMB, or a cloud volume driver)
 #     is unsupported for it; that is a corrupted database, not a slow one;
 #   * one library path vocabulary — `PHOTO_PIPELINE_LIBRARY_ROOTS` names the path
 #     *inside* the container, which is also the bind mount's target below. A root
 #     that is not mounted there makes `serve` and `worker` refuse at startup instead
 #     of writing into the container's throwaway layer.
 #
 # Configuration and secrets come from the environment only: copy `.env.example` to
 # `.env` and fill it in. Nothing is baked into the image and nothing with a value in
 # it is committed.
 #
 #   cp .env.example .env && $EDITOR .env
 #   docker compose up -d --build
 #
 # Operating it is operating the same CLI — `docker compose run --rm --no-deps api
 # <command>` — see README, "Composed runtime".
 name: photo-pipeline
 x-runtime: &runtime
  image: ${PHOTO_PIPELINE_IMAGE:-photo-pipeline:dev}
  build:
    context: .
    args:
      # Everything the app renames or rewrites has to stay owned by the host user
      # the library already belongs to.
      UID: ${PHOTO_PIPELINE_UID:-1000}
      GID: ${PHOTO_PIPELINE_GID:-1000}
  user: "${PHOTO_PIPELINE_UID:-1000}:${PHOTO_PIPELINE_GID:-1000}"
  env_file:
    - ${PHOTO_PIPELINE_ENV_FILE:-.env}
  volumes:
    - data:/data
    - "${PHOTO_PIPELINE_LIBRARY_HOST_PATH:?set PHOTO_PIPELINE_LIBRARY_HOST_PATH to the photo library on this host}:${PHOTO_PIPELINE_LIBRARY_ROOTS:?set PHOTO_PIPELINE_LIBRARY_ROOTS to the container-side library path}"
  # Jobs check for cancellation between items and leave a resumable record; a
  # too-short grace period turns an orderly stop into a recovery on next start.
  stop_grace_period: 30s
 x-environment: &environment
  # Set here rather than left to the file: these two are what the composition itself
  # promises, and an `.env` that disagreed would move the database off the volume or
  # the library off its mount.
  PHOTO_PIPELINE_DATA_DIR: /data
  PHOTO_PIPELINE_LIBRARY_ROOTS: ${PHOTO_PIPELINE_LIBRARY_ROOTS}
 services:
  # Migrations run to completion before either role accepts work, through the same
  # backup-then-migrate path the roles use (US07-05): a pending upgrade is snapshotted
  # first, and a failed one exits non-zero with the backup named — so `api` and
  # `worker` never start, and the previous database is left intact and restorable.
  migrate:
    <<: *runtime
    command: ["migrate"]
    environment: *environment
    restart: "no"
  api:
    <<: *runtime
    command: ["serve"]
    environment:
      <<: *environment
      # Published to host loopback below. Inside the container the server must bind
      # the container's own interface for that publish to reach it, which is exactly
      # what makes the access secret mandatory (US08-01) — `serve` refuses to start
      # without one. Exposing the port beyond loopback additionally needs
      # PHOTO_PIPELINE_ALLOWED_HOSTS to name the hostname it is reached under.
      PHOTO_PIPELINE_HOST: 0.0.0.0
      PHOTO_PIPELINE_PORT: 8000
    ports:
      # Host side only: PHOTO_PIPELINE_PORT in `.env` moves the *published* port, and
      # the container always serves 8000, which is what the image's health check probes.
      - "${PHOTO_PIPELINE_PUBLISH_ADDRESS:-127.0.0.1}:${PHOTO_PIPELINE_PORT:-8000}:8000"
    depends_on:
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped
  # One worker. A second one is refused by the library lock in the shared data
  # volume, which is the point: `docker compose up --scale worker=2` fails loudly
  # instead of running two writers against one library.
  worker:
    <<: *runtime
    command: ["worker", "--id", "worker-1"]
    environment: *environment
    depends_on:
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped
 volumes:
  # Local driver on purpose: the database, WAL, thumbnail cache, and backups need a
  # real local filesystem. Do not point this at NFS, SMB, or a network volume driver.
  data:
    driver: local
--- 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/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",
--- a/frontend/js/app.js
+++ b/frontend/js/app.js
@@ -193,7 +193,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 +207,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 +298,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);
 }
--- 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/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,237 +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,benchmark,release-gate,container-gate,dry-run,approve-dry-run}``.
 ``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
 import sys
 from pathlib import Path
 from typing import Sequence
 from photo_pipeline import path_policy
 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>)")
    container_cmd = commands.add_parser(
        "container-gate",
        help="Provision the composition from the built image, run the phase_h "
        "acceptance suite against it, destroy it, and keep the evidence (US08-05)",
    )
    container_cmd.add_argument(
        "--output", help="Evidence directory (default: data/container-gate/<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)
    # In a container the two roles that touch the library check their boundary before
    # they take a lock or bind a port: the configured roots must name the mount paths,
    # and a mismatch is cheaper to refuse than to discover at the first write (US08-03).
    # Only in a container — on a host an unmounted root is an ordinary Tuesday (an
    # archive medium that is not plugged in), and refusing to serve would take the
    # offline half of the library away with it.
    if args.command in ("serve", "worker") and path_policy.in_container():
        refusal = path_policy.roots_refusal(config.library_roots, require_mount=True)
        if refusal is not None:
            print(refusal, file=sys.stderr)
            return 5
    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 == "container-gate":
        from datetime import datetime, timezone
        from photo_pipeline.services import release
        # The suite provisions and destroys the composition itself; what this command
        # adds is the single entry point and the retained evidence. No skip is an
        # environment limit here: a gate that did not reach the containers proved
        # nothing about them.
        output = args.output or Path(config.data_dir) / "container-gate" / datetime.now(
            timezone.utc
        ).strftime("%Y%m%dT%H%M%SZ")
        report = release.run_gate(
            config,
            output=output,
            stages=release.CONTAINER_STAGES,
            allowed_skips=release.CONTAINER_ALLOWED_SKIP_REASONS,
        )
        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":
@@ -243,56 +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:
+        engine = create_db_engine(config.database_url)
-            return held
+        Worker(create_session_factory(engine), worker_id=args.id, config=config).run_forever()
        try:
            migrate_with_backup(config)
            engine = create_db_engine(config.database_url)
            Worker(
                create_session_factory(engine), worker_id=args.id, config=config
            ).run_forever()
        finally:
            lock.release()
        return 0
    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.
    """
    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/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
@@ -38,8 +38,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:
--- 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/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/path_policy.py
+++ b/photo_pipeline/path_policy.py
@@ -15,7 +15,9 @@ import os
 from pathlib import Path
 from typing import Iterable, Iterator
-SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif", ".tiff", ".tif"}
+SUPPORTED_EXTENSIONS = {
    ".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif", ".tiff", ".tif"
 }
 EXCLUDED_DIR_NAMES = {"_IGNORE", ".@__thumb"}
@@ -47,86 +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 in_container() -> bool:
    """Whether this process is running inside a container image build of the app."""
    return Path("/.dockerenv").exists()
 def _under_mount(path: Path) -> bool:
    """Whether ``path`` or one of its parents below ``/`` is a mounted filesystem."""
    current = path.resolve()
    while current != current.parent:
        if os.path.ismount(current):
            return True
        current = current.parent
    return False
 def roots_refusal(roots: Iterable[os.PathLike | str], *, require_mount: bool = False) -> str | None:
    """Why the configured library roots cannot be worked with, or ``None`` (US08-03).
    The roots name the directories this installation renames folders in, rewrites
    EXIF in, and archives from. Container path policy is the same problem as host
    path policy with one new failure mode: the configured roots must name the
    *container-side* mount paths. A host path configured inside a container is
    either absent or an ordinary directory of the image, so the library looks empty
    and the first write lands in the container's throwaway layer instead of in the
    library. That is worth refusing at startup, while an operator is still watching,
    rather than at the first write.
    ``require_mount`` is the container-only half of that: inside a container a real
    library arrives through a bind mount, so a root that is not on (or under) a
    mount point is not the library the deployment meant.
    Writability is deliberately *not* checked: a bind mount's ownership is
    virtualised by Docker Desktop and Colima (it arrives as ``root:root``), so
    ``os.access`` there is evidence about the virtio layer rather than about the
    library. A wrong UID/GID surfaces as a refused rename with the real errno, which
    is at least true; a refusal here would be false on two supported platforms.
    """
    for root in roots:
        path = Path(root)
        if not path.exists():
            return (
                f"library root {path} does not exist: PHOTO_PIPELINE_LIBRARY_ROOTS must "
                "name paths that exist here, and in a container that means the mount path"
            )
        if not path.is_dir():
            return f"library root {path} is not a directory"
        if not os.access(path, os.R_OK | os.X_OK):
            return f"library root {path} is not readable by this process"
        if require_mount and not _under_mount(path):
            return (
                f"library root {path} is not on a mounted filesystem in this container: "
                "the library was not bind-mounted there, so PHOTO_PIPELINE_LIBRARY_ROOTS "
                "names a directory of the image rather than the library"
            )
    return None
 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,256 +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 — refusing
 to start because of a crashed predecessor would turn one outage into two.
 Ownership is an advisory ``flock`` on that file, not the record inside it. The
 record says *who*; the kernel says *whether*. That distinction is what makes the
 lock work in containers (US08-03), where a PID and a hostname are namespaced: a
 lock left behind by a container that no longer exists names a pid that still
 "exists" in the new container and a host that cannot be probed, so believing the
 file would deadlock every restart. A flock is released when its holder dies however
 it dies, and is seen by every process that can open the file — which for a local
 data directory is every container of this deployment.
 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 fcntl
 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 _in_container() -> bool:
    from photo_pipeline import path_policy
    return path_policy.in_container()
 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
        self._handle = None
    # ── 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"
                )
        self.path.parent.mkdir(parents=True, exist_ok=True)
        # The kernel decides, because the file cannot: a container's PID and hostname
        # are namespaced, so a lock left by a container that no longer exists names a
        # pid that "exists" and a host that cannot be probed (US08-03). An advisory
        # flock is held by a live process or by nobody, is released when that process
        # dies however it dies, and is shared by every process that can open this
        # file — which, for a local data directory, is every role in every container
        # of this deployment.
        handle = open(self.path, "a+", encoding="utf-8")
        try:
            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
        except OSError:
            handle.close()
            raise LockHeld(self.holder() or Holder(self.role, -1, "unknown", "unknown")) from None
        current = self.holder()
        if current is not None and current.host != socket.gethostname() and not _in_container():
            # We hold the kernel's lock, so nothing on *this* machine holds the file.
            # On a host that still leaves one case open: a data directory shared with
            # another machine, whose flock we cannot trust. Believe its record rather
            # than run two writers. In a container the data volume is local by
            # construction (US08-03), and a foreign hostname is only a dead container.
            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
            handle.close()
            raise LockHeld(current)
        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),
        )
        payload = {k: v for k, v in mine.as_dict().items() if k != "alive"}
        handle.seek(0)
        handle.truncate()
        json.dump(payload, handle, indent=2)
        handle.flush()
        # Held open on purpose: closing it is what releases the lock, and that must
        # happen when this process ends, not when this method returns.
        self._handle = handle
        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
        self.path.unlink(missing_ok=True)
        if self._handle is not None:
            self._handle.close()  # closing the descriptor releases the kernel lock
            self._handle = None
        self._acquired = False
    def __enter__(self) -> "LibraryLock":
        self.acquire()
        return self
    def __exit__(self, *_) -> None:
        self.release()
--- a/photo_pipeline/services/archive_transfer.py
+++ b/photo_pipeline/services/archive_transfer.py
@@ -52,7 +52,6 @@ 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,
@@ -64,7 +63,7 @@ from photo_pipeline.services.archive_journal import (
 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
--- a/photo_pipeline/services/archives.py
+++ b/photo_pipeline/services/archives.py
@@ -208,12 +208,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()
--- 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
@@ -52,13 +52,6 @@ from photo_pipeline.services import availability, 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"
@@ -527,65 +520,39 @@ 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,
+                        **self._offline_evidence(session, asset),
                    }
                )
            members.sort(key=lambda m: m["asset_id"])
            # A full-resolution comparison of an offline original is impossible; the
-            # UI asks for that named medium instead of guessing (concept §9). The
+            # UI asks for that named medium instead of guessing (concept §9).
-            # answer covers the whole cluster, not just this page, so a mount is not
+            mount_required = sorted(
-            # discovered halfway through a review.
+                {m["archive_location"] for m in members if m["requires_mount"]}
-            mount_required = self._mount_required(session, cluster_id)
+            )
            return {
                "id": cluster.id,
                "method": cluster.method,
@@ -597,74 +564,10 @@ class DuplicateService:
                "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:
+    def _offline_evidence(self, session, asset: Asset | None) -> dict:
-        """``{asset_id: (asset, offline_evidence)}`` for one page, in three queries."""
+        """What review can still rely on when a member's original is not readable."""
        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,
@@ -674,8 +577,12 @@ class DuplicateService:
                "preview": {"state": "missing", "protected": False},
                "requires_mount": False,
            }
-        location = locations.get(asset.archive_location_id)
+        location = (
-        preview = self._preview_evidence(thumbnails)
+            session.get(ArchiveLocation, asset.archive_location_id)
            if asset.archive_location_id
            else None
        )
        preview = self._preview_evidence(session, asset.id)
        archived = asset.availability_state in availability.ARCHIVED
        return {
            "availability_state": asset.availability_state,
@@ -691,7 +598,10 @@ class DuplicateService:
        }
    @staticmethod
-    def _preview_evidence(rows: list) -> dict:
+    def _preview_evidence(session, asset_id: str) -> dict:
        rows = list(
            session.execute(select(Thumbnail).where(Thumbnail.asset_id == asset_id)).scalars()
        )
        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))
@@ -783,29 +693,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/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
+                        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,414 +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",
 )
 # The container acceptance gate (US08-05): the deployed application, verified the way
 # the host application is. Deliberately one stage selected by marker, so adding a
 # phase_h test is enough to put it in front of a deploy.
 CONTAINER_STAGES: tuple[tuple[str, tuple[str, ...]], ...] = (
    ("container", ("tests/e2e", "-m", "phase_h")),
 )
 # Nothing. This gate exists to prove the *deployed* runtime, and every reason a check
 # would skip here — no daemon, no compose, no browser — means it was not proven.
 CONTAINER_ALLOWED_SKIP_REASONS: tuple[str, ...] = ()
 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], allowed: tuple[str, ...] = ALLOWED_SKIP_REASONS
 ) -> 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)
    ]
 def run_gate(
    config: Config,
    *,
    output: Path | str | None = None,
    stages: tuple[tuple[str, tuple[str, ...]], ...] = STAGES,
    allowed_skips: tuple[str, ...] = ALLOWED_SKIP_REASONS,
    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)
    started_at = _now()
    matrix = story_matrix(repo)
    results = [_run_stage(label, paths, repo=repo, log_dir=logs) for label, paths in stages]
    skips = unexpected_skips(results, allowed_skips)
    report = {
        "schema_version": SCHEMA_VERSION,
        "started_at": started_at.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
@@ -53,7 +53,6 @@ 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
@@ -74,7 +73,7 @@ from photo_pipeline.services.archive_transfer import (
 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_apply import PreconditionFailed, maybe_fault
 from photo_pipeline.services.rename_journal import RenameJournal
 PREFLIGHT_VERSION = 1
@@ -141,11 +140,9 @@ class RestoreService:
            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",
+                    f"{report['capacity']['free_bytes']} B of free space",
                )
            )
        if not items:
--- 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"),
+            out = {SFW: 0, NSFW: 0, "deferred": 0, "undecided": 0, "scored": 0}
-                    func.count(),
+            for asset in assets:
-                    func.count(latest.c.score),
+                review = latest.get(asset.id)
-                )
+                decision = review.decision if review else None
-                .select_from(Asset)
+                if decision in (SFW, NSFW, "deferred"):
-                .join(latest, latest.c.asset_id == Asset.id, isouter=True)
+                    out[decision] += 1
-                .where(
+                else:
-                    Asset.canonical_asset_id.is_(None),
+                    out["undecided"] += 1
-                    Asset.availability_state == "active",
+                    if review and review.score is not None:
-                )
+                        out["scored"] += 1
-                .group_by(func.coalesce(latest.c.decision, "undecided"))
+            return out
            ).all()
        out = {SFW: 0, NSFW: 0, "deferred": 0, "undecided": 0, "scored": 0}
        for decision, total, scored in rows:
            if decision in (SFW, NSFW, "deferred"):
                out[decision] += int(total)
            else:
                # Anything that is not one of the three decisions is undecided —
                # including a score-only review, which is what "scored" counts.
                out["undecided"] += int(total)
                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,
+                    {
-                    "current_path": current_path,
+                        "asset_id": asset.id,
-                    "score": score,
+                        "current_path": asset.current_path,
-                    "decision": decision,
+                        "score": review.score if review else None,
-                    "suggested": classify(score) if score is not None else None,
+                        "decision": decision,
-                    "exif_verified": bool(exif_verified_at),
+                        "suggested": classify(review.score) if review and review.score is not None else None,
-                    "exif_state": exif_state,
+                        "exif_verified": bool(review and review.exif_verified_at),
-                }
+                    }
-                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
@@ -20,16 +20,15 @@ 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
@@ -43,9 +42,6 @@ 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).
@@ -133,10 +129,7 @@ class ThumbnailService:
                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
+                self._validate_path(source)  # archive roots lie outside the library
                # 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:
@@ -202,16 +195,20 @@ class ThumbnailService:
                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:
-        try:
+            return
-            return path_policy.resolve_in_roots(self._config.library_roots, current_path)
+        for root in roots:
-        except path_policy.PathPolicyError as error:
+            try:
-            raise PathNotAllowed(str(error)) from None
+                path_policy.resolve_within(Path(root), path)
                return
            except path_policy.PathPolicyError:
                continue
        raise PathNotAllowed(f"path outside configured roots: {current_path}")
    # ── cache key + rendering ──────────────────────────────────────────────────
    @staticmethod
@@ -226,33 +223,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,28 +254,6 @@ 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(
        self, cache_key: str, asset_id: str, size: int, rendered: dict, *, protected: bool = False
--- 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,41 +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",
    # The composition and the workflows are configuration, and the tests that hold
    # them to their promises read them (US08-03, US08-04).
    "pyyaml>=6",
 ]
 [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"]
@@ -52,6 +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 and its composition (US08-02, US08-03) — needs a Docker daemon, the compose plugin, and the network",
    "phase_h: Phase H container deployment acceptance (US08-05) — the browser, upgrade, restart, and security journeys against the composed stack",
 ]
--- 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/_container_harness.py
+++ b/tests/e2e/_container_harness.py
@@ -1,260 +0,0 @@
 """The composed stack, as a fixture: build, provision, drive, destroy (US08-03/US08-05).
 Extracted from ``tests/e2e/test_compose_stack.py`` when the container acceptance gate
 needed the same stack under a different image, project, and library. One
 implementation, because two would drift on exactly the details that make a container
 test worth anything — the mount, the volume, the ports, and the teardown.
 Nothing here fakes anything below the process boundary: Docker builds the image,
 Compose starts the real containers, and every helper talks to them over HTTP or the
 Docker CLI.
 """
 from __future__ import annotations
 import os
 import shutil
 import socket
 import subprocess
 import tempfile
 import time
 from pathlib import Path
 import httpx
 import pytest
 from PIL import Image
 REPO = Path(__file__).resolve().parents[2]
 COMPOSE_FILE = REPO / "docker-compose.yml"
 CONTAINER_LIBRARY = "/library"
 READY_TIMEOUT_SECONDS = 180
 JOB_TIMEOUT_SECONDS = 300
 UP_TIMEOUT_SECONDS = 30 * 60
 def compose_available() -> bool:
    try:
        return (
            subprocess.run(
                ["docker", "compose", "version"], capture_output=True, timeout=60
            ).returncode
            == 0
        )
    except (OSError, subprocess.SubprocessError):
        return False
 def free_port() -> int:
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]
 def mount_base() -> Path:
    """A directory a Docker VM shares with the host.
    Not pytest's ``tmp_path``: on macOS that is ``/var/folders/...``, which a Docker VM
    (Colima, Docker Desktop) does not share, so the bind mount would arrive empty and
    every assertion would be about nothing. ``$HOME`` is shared by every default
    configuration.
    """
    base = Path(
        os.environ.get("PHOTO_PIPELINE_TEST_MOUNT_BASE", Path.home() / ".cache" / "photo-pipeline")
    )
    base.mkdir(parents=True, exist_ok=True)
    return base
 def temporary_library(albums: dict[str, int], *, prefix: str = "library-") -> Path:
    """A fixture library on a shareable host path, with the exclusion sentinel in it."""
    root = Path(tempfile.mkdtemp(prefix=prefix, dir=mount_base()))
    for position, (album, count) in enumerate(albums.items()):
        (root / album).mkdir(parents=True, exist_ok=True)
        for index in range(count):
            # Distinct per album *and* index: two solid images of the same colour are
            # byte-identical, which would make them a duplicate cluster by accident.
            colour = (17 + 7 * index, 31 + 29 * position, 160 - 3 * index)
            Image.new("RGB", (64, 48), colour).save(root / album / f"{album}_{index}.jpg")
    # Never discovered, counted, analyzed, or uploaded — asserted from outside it.
    (root / "_IGNORE").mkdir(exist_ok=True)
    Image.new("RGB", (32, 32), (0, 0, 0)).save(root / "_IGNORE" / "sentinel.jpg")
    return root
 def remove_library(root: Path) -> None:
    shutil.rmtree(root, ignore_errors=True)
 def write_env_file(path: Path, secret: str, extra: dict[str, str] | None = None) -> Path:
    """Configuration and secrets come from the environment, so a test writes its own
    file rather than borrowing the operator's ``.env``."""
    lines = [
        f"PHOTO_PIPELINE_ACCESS_SECRET={secret}",
        "PHOTO_PIPELINE_LOG_FORMAT=text",
        # The deterministic vision seam, in the data volume so both roles and the test
        # can read it (concept §18).
        "PHOTO_PIPELINE_FAKE_VISION_LOG=/data/vision.log",
        *(f"{key}={value}" for key, value in (extra or {}).items()),
    ]
    path.write_text("\n".join(lines) + "\n")
    return path
 class Stack:
    """The composition under test, plus the environment it was started with."""
    def __init__(
        self,
        library: Path,
        env_file: Path,
        *,
        project: str,
        image: str,
        secret: str,
    ) -> None:
        self.library = library
        self.project = project
        self.secret = secret
        self.port = free_port()
        self.base = f"http://127.0.0.1:{self.port}"
        # Compose reads the repository's own .env for substitution; the process
        # environment wins over it, so the test's values are the ones that apply.
        self.env = {
            **os.environ,
            "PHOTO_PIPELINE_IMAGE": image,
            "PHOTO_PIPELINE_ENV_FILE": str(env_file),
            "PHOTO_PIPELINE_LIBRARY_HOST_PATH": str(library),
            "PHOTO_PIPELINE_LIBRARY_ROOTS": CONTAINER_LIBRARY,
            "PHOTO_PIPELINE_PORT": str(self.port),
            "PHOTO_PIPELINE_UID": str(os.getuid()),
            "PHOTO_PIPELINE_GID": str(os.getgid()),
        }
    # ── the compose lifecycle ────────────────────────────────────────────────
    def compose(self, *args: str, check: bool = True, timeout: int = 300):
        result = subprocess.run(
            ["docker", "compose", "-p", self.project, "-f", str(COMPOSE_FILE), *args],
            capture_output=True,
            text=True,
            env=self.env,
            cwd=REPO,
            timeout=timeout,
        )
        if check and result.returncode != 0:
            raise AssertionError(
                f"docker compose {' '.join(args)} failed:\n{result.stdout}\n{result.stderr}\n"
                f"{self.compose('logs', '--tail', '80', check=False).stdout}"
            )
        return result
    def up(self, *extra: str) -> None:
        self.compose("up", "--detach", *extra, timeout=UP_TIMEOUT_SECONDS)
    def down(self, *, volumes: bool = True) -> None:
        self.compose(
            "down",
            *(("--volumes",) if volumes else ()),
            "--remove-orphans",
            check=False,
            timeout=300,
        )
    def use_image(self, image: str) -> None:
        """Point the composition at another tag — the upgrade path (US08-05)."""
        self.env["PHOTO_PIPELINE_IMAGE"] = image
    def logs(self, *services: str) -> str:
        result = self.compose("logs", *services, check=False)
        return result.stdout + result.stderr
    def wait_until_ready(self) -> None:
        deadline = time.monotonic() + READY_TIMEOUT_SECONDS
        while time.monotonic() < deadline:
            try:
                if httpx.get(f"{self.base}/api/v1/health/ready", timeout=5).status_code == 200:
                    return
            except httpx.HTTPError:
                pass
            time.sleep(0.5)
        raise AssertionError(f"the stack never became ready:\n{self.logs()}")
    # ── talking to it ────────────────────────────────────────────────────────
    def client(self) -> httpx.Client:
        """A browser that has loaded the app: session cookie in the jar, token in a
        header. The session belongs to the API process, so it is re-bootstrapped after
        every restart."""
        client = httpx.Client(base_url=f"{self.base}/api/v1", timeout=60)
        bootstrap = client.get("/session", headers={"X-Access-Secret": self.secret})
        assert bootstrap.status_code == 200, bootstrap.text
        client.headers["X-CSRF-Token"] = bootstrap.json()["csrf_token"]
        return client
 def await_job(client: httpx.Client, job_id: str, states=("succeeded",)) -> dict:
    deadline = time.monotonic() + JOB_TIMEOUT_SECONDS
    snapshot: dict = {}
    while time.monotonic() < deadline:
        response = client.get(f"/jobs/{job_id}")
        if response.status_code == 200:
            snapshot = response.json()
            if snapshot["state"] in states:
                return snapshot
        time.sleep(0.5)
    raise AssertionError(f"job {job_id} never reached {states}: {snapshot}")
 def build_image(tag: str, *, revision: str | None = None) -> str:
    """Build the application image; from a git revision's tree when one is named.
    ``revision`` is how the upgrade journey gets the *previous* version without a
    registry: the tree of that commit is the build context, so what it produces is the
    image that commit would have published.
    """
    if revision is None:
        subprocess.run(
            [
                "docker",
                "build",
                "--build-arg",
                f"UID={os.getuid()}",
                "--build-arg",
                f"GID={os.getgid()}",
                "-t",
                tag,
                str(REPO),
            ],
            check=True,
            timeout=UP_TIMEOUT_SECONDS,
        )
        return tag
    archive = subprocess.run(
        ["git", "archive", "--format=tar", revision],
        cwd=REPO,
        capture_output=True,
        check=True,
        timeout=300,
    ).stdout
    subprocess.run(
        [
            "docker",
            "build",
            "--build-arg",
            f"UID={os.getuid()}",
            "--build-arg",
            f"GID={os.getgid()}",
            "-t",
            tag,
            "-",
        ],
        input=archive,
        check=True,
        timeout=UP_TIMEOUT_SECONDS,
    )
    return tag
 needs_compose = pytest.mark.skipif(
    not compose_available(), reason="no Docker daemon with the compose plugin"
 )
--- a/tests/e2e/_pipeline_harness.py
+++ b/tests/e2e/_pipeline_harness.py
@@ -494,16 +494,6 @@ class ArchiveStack:
        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()
--- a/tests/e2e/test_compose_stack.py
+++ b/tests/e2e/test_compose_stack.py
@@ -1,212 +0,0 @@
 """US08-03: the composition, actually composed.
 Nothing here is faked below the process boundary: Docker builds the image, Compose
 starts the migrate/API/worker containers against a temporary fixture library on a
 real bind mount, and every assertion is made over HTTP or against what the stack
 left in its data volume. The vision provider is the deterministic fake seam the
 other end-to-end suites use, because an upload of real photos to a real model is not
 what this story is about — the mount, the lock, the volume, and the restart are.
 The file contract (one API, one worker, migrations first, no committed values) is
 checked without a daemon in ``tests/integration/test_compose_runtime.py``; only the
 running proof needs Docker, and CI is where it runs unskipped (US08-04).
 The stack itself lives in ``tests/e2e/_container_harness.py``, shared with the
 container acceptance gate (US08-05).
 """
 from __future__ import annotations
 import json
 import sys
 from pathlib import Path
 import pytest
 from tests.e2e._container_harness import (
    CONTAINER_LIBRARY,
    Stack,
    await_job,
    compose_available,
    needs_compose,
    remove_library,
    temporary_library,
    write_env_file,
 )
 PROJECT = "photo-pipeline-us0803"
 IMAGE = "photo-pipeline-test:us08-03"
 SECRET = "compose-acceptance-secret"
 pytestmark = pytest.mark.container
@pytest.fixture(scope="module")
 def library() -> Path:
    root = temporary_library({"01_day": 2, "02_night": 1})
    try:
        yield root
    finally:
        remove_library(root)
@pytest.fixture(scope="module")
 def env_file(tmp_path_factory) -> Path:
    return write_env_file(tmp_path_factory.mktemp("config") / "compose.env", SECRET)
@pytest.fixture(scope="module")
 def stack(library, env_file):
    if not compose_available():
        pytest.skip("no Docker daemon with the compose plugin")
    running = Stack(library, env_file, project=PROJECT, image=IMAGE, secret=SECRET)
    running.down()
    running.up("--build")
    try:
        running.wait_until_ready()
        yield running
    finally:
        running.down()
 # ── the mounted library ──────────────────────────────────────────────────────
@needs_compose
 def test_the_stack_scans_the_bind_mounted_library_at_its_container_paths(stack):
    client = stack.client()
    try:
        scanned = client.post("/inventory/scan")
        assert scanned.status_code == 200, scanned.text
        assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
    finally:
        client.close()
    assert len(assets) == 3, assets
    paths = {asset["current_path"] for asset in assets}
    assert all(path.startswith(CONTAINER_LIBRARY + "/") for path in paths), paths
    assert not any("_IGNORE" in path or "sentinel" in path for path in paths)
    # The host paths are what the operator mounted, and they are not what the
    # application records: the roots are the container's.
    assert not any(str(stack.library) in path for path in paths)
@needs_compose
 def test_a_library_root_that_is_not_mounted_is_refused_at_startup(stack):
    """The container-specific failure: configured roots that name nothing mounted."""
    refused = stack.compose(
        "run",
        "--rm",
        "--no-deps",
        "--env",
        "PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos",
        "api",
        "serve",
        check=False,
    )
    assert refused.returncode == 5, refused.stdout + refused.stderr
    assert "library root /srv/photos" in refused.stdout + refused.stderr
@needs_compose
 def test_a_second_worker_is_refused_by_the_library_lock(stack):
    """Not by convention: the running worker's lock is in the shared data volume."""
    refused = stack.compose(
        "run", "--rm", "--no-deps", "worker", "worker", "--id", "worker-2", check=False
    )
    assert refused.returncode == 2, refused.stdout + refused.stderr
    assert "worker is already running" in refused.stdout + refused.stderr
 # ── restart, resume, and the data volume ─────────────────────────────────────
@needs_compose
 def test_a_queued_job_resumes_after_both_containers_restart(stack):
    client = stack.client()
    try:
        client.post("/inventory/scan").raise_for_status()
        assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
        for asset in assets:
            decided = client.post(
                "/safety/decisions", json={"asset_id": asset["id"], "decision": "sfw"}
            )
            assert decided.status_code == 200, decided.text
        # Stop the worker first, so the job is provably still queued when the restart
        # happens: a job that finished before the restart would prove nothing.
        stack.compose("stop", "worker")
        job = client.post("/analysis/jobs").json()
        assert client.get(f"/jobs/{job['id']}").json()["state"] == "queued"
    finally:
        client.close()
    stack.compose("restart", "api", "worker")
    stack.wait_until_ready()
    client = stack.client()  # the session is per API process, so it is re-bootstrapped
    try:
        finished = await_job(client, job["id"])
        assert finished["state"] == "succeeded", finished
        # The database is intact and the work is durable, not merely reported.
        after = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
        assert {asset["id"] for asset in after} == {asset["id"] for asset in assets}
        analysed = client.get(f"/analysis/results/{assets[0]['id']}")
        assert analysed.status_code == 200, analysed.text
        assert analysed.json()["description"]
        # Only the mounted library's own photos were analysed: the sentinel under
        # _IGNORE is not an asset, so it can never have become an item of this job.
        assert finished["progress"]["total"] == len(assets)
    finally:
        client.close()
@needs_compose
 def test_the_data_volume_survives_recreating_the_containers(stack):
    """`down` without `--volumes` then `up` is the upgrade path: state stays."""
    client = stack.client()
    try:
        client.post("/inventory/scan").raise_for_status()
        before = {a["id"] for a in client.get("/inventory/assets").json()["items"]}
    finally:
        client.close()
    stack.down(volumes=False)
    stack.up()
    stack.wait_until_ready()
    client = stack.client()
    try:
        after = {a["id"] for a in client.get("/inventory/assets").json()["items"]}
    finally:
        client.close()
    assert after == before, "the same assets, from the same database, on the same volume"
 # ── operating it ─────────────────────────────────────────────────────────────
@needs_compose
 def test_backup_verify_and_diagnostics_run_as_container_commands(stack):
    backup = stack.compose("run", "--rm", "--no-deps", "api", "backup", "--reason", "compose")
    manifest = json.loads(backup.stdout[backup.stdout.index("{") :])
    assert manifest["name"].startswith("2")
    verified = stack.compose(
        "run", "--rm", "--no-deps", "api", "verify-backup", f"/data/backups/{manifest['name']}"
    )
    assert json.loads(verified.stdout[verified.stdout.index("{") :])["ok"] is True
    report = stack.compose("run", "--rm", "--no-deps", "api", "diagnostics")
    diagnostics = json.loads(report.stdout[report.stdout.index("{") :])
    components = {c["name"]: c["path"] for c in diagnostics["components"]}
    # Database, WAL, thumbnail cache, and backups all live in the mounted volume.
    for name in ("database", "write_ahead_log", "thumbnail_cache", "backups"):
        assert components[name].startswith("/data/"), (name, components[name])
    assert {tool["name"] for tool in diagnostics["tools"]} >= {"exiftool", "immich-go"}
    # And the worker running beside this command is visible as the lock's holder.
    assert diagnostics["locks"]["worker"]["role"] == "worker"
 if __name__ == "__main__":  # a quick way to run just this file
    raise SystemExit(pytest.main([__file__, "-v", *sys.argv[1:]]))
--- 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