fix(audiobooks): cache plugin poster images

fix(migrations): preserve personal collection types
Harden ABS auth and access control
2026-05-28 09:49:42 -04:00 · 2026-05-27 19:55:02 -04:00 · 2026-05-27 19:16:21 -04:00 · 2026-05-27 17:38:16 -04:00 · 2026-05-27 21:40:26 +02:00 · 2026-05-27 21:26:10 +02:00
4183 changed files with 25447 additions and 180313 deletions
@@ -1,12 +1,6 @@
 # Silo Docker deployment
 # For the default docker compose setup, MEDIA_ROOT is the main value you need to set.

-# Optional: layer compose files through env. Leave unset for CPU-only defaults.
-# Linux/macOS example for enabling NVIDIA override:
-# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml
-# Windows example:
-# COMPOSE_FILE=docker-compose.yml;docker-compose.nvidia.yml
-
 # Required for docker compose: host path to your media library.
 # Example: MEDIA_ROOT=/srv/media
 MEDIA_ROOT=/srv/media
@@ -26,43 +20,13 @@ SILO_IMAGE=ghcr.io/silo-server/silo-server:latest
 POSTGRES_USER=silo
 POSTGRES_PASSWORD=silo
 POSTGRES_DB=silo
-POSTGRES_SHM_SIZE=8gb
-
-# PostgreSQL auto-tuning is enabled by default in docker-compose.yml. Silo
-# applies pgtune-style OLTP recommendations through ALTER SYSTEM at startup.
-# Set POSTGRES_TUNE=off if you manage PostgreSQL tuning yourself.
-# POSTGRES_TUNE=off
-# POSTGRES_TUNE_PROFILE=oltp
-# POSTGRES_TUNE_MEMORY=auto
-# POSTGRES_TUNE_MEMORY_BUDGET_PERCENT=75
-# POSTGRES_TUNE_CPUS=auto
-# POSTGRES_TUNE_STORAGE=ssd
-# POSTGRES_TUNE_DB_SIZE=auto
-# POSTGRES_TUNE_CONNECTIONS=100

 # Optional host port overrides for docker-compose.yml.
 # PORT=8090
-# Used only after Jellyfin-compatible app support is enabled by an admin.
 # JF_PORT=8096
 # PROXY_PORT=8083
 # TRANSCODE_PORT=8082

-# Optional NVIDIA override controls (used by docker-compose.nvidia.yml).
-# NVIDIA_GPU_COUNT=1
-
-# REQUIRED: master key for at-rest credential encryption. Silo refuses to start
-# without it. Integration API keys, S3 keys, and other server-owned secrets are
-# encrypted under a key derived from this value, so it must be at least 32
-# characters and kept secret. Generate one with:
-#   openssl rand -base64 48
-# Back it up SEPARATELY from your database dumps (treat it like a CA private
-# key): losing it makes every encrypted secret unrecoverable. See
-# docs/architecture/secret-encryption.md.
-# SECRET_KEY=replace-with-output-of-openssl-rand-base64-48
-
-# Optional public URL for Silo. If not set, the server will use the IP address of the container.
-# SILO_PUBLIC_URL=https://silo.example.com
-
 # Run from source / advanced overrides
 # Only DATABASE_URL is required when running Silo outside the default docker compose stack.
 # DATABASE_URL=postgres://silo:password@localhost:5432/silo
@@ -1,2 +0,0 @@
-# v1 scope lock — changes to the lock artifact require maintainer review
-/docs/architecture/v1-scope.md @Quick104
@@ -1,56 +0,0 @@
-name: v1 capability proposal
-description: Propose a user-facing capability for the Silo v1 scope lock
-title: "[v1] <capability name>"
-labels: ["v1-proposed"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        One proposal per **user-facing capability** (e.g. "Manga library type", "Transcoded playback"),
-        not per PR or per endpoint. Locked capabilities are what the client teams plan against —
-        the **API surface** section is mandatory for a capability to be lockable.
-        Scope state and lock rules: `docs/architecture/v1-scope.md`.
-  - type: textarea
-    id: summary
-    attributes:
-      label: Summary
-      description: One paragraph, user-facing language. What can a user do when this ships?
-    validations:
-      required: true
-  - type: textarea
-    id: value
-    attributes:
-      label: User value / why v1
-      description: Why does v1 need this rather than v1.1?
-    validations:
-      required: true
-  - type: textarea
-    id: api-surface
-    attributes:
-      label: API surface
-      description: >
-        Endpoints/payloads clients will call (method + path + notable request/response fields).
-        Plain list now; OpenAPI pointers once the #135 tooling lands. A capability cannot be
-        Locked without this section filled in.
-      placeholder: |
-        GET  /api/v1/manga/{seriesId}/chapters — list chapters (id, index, volume, read_state)
-        POST /api/v1/watch-progress — records reading progress (existing endpoint, new item type)
-    validations:
-      required: true
-  - type: textarea
-    id: client-impact
-    attributes:
-      label: Client impact (android / apple / web)
-      description: What must each client build to surface this capability? "None" is a valid answer per client.
-    validations:
-      required: true
-  - type: dropdown
-    id: size
-    attributes:
-      label: Rough size (server-side)
-      options:
-        - S
-        - M
-        - L
-    validations:
-      required: true
@@ -1,26 +0,0 @@
-name: v1 proposal labeler
-
-# The issue form applies `v1-proposed` automatically, but only for submissions
-# through the web form. Contributors filing via the API/CLI (or from a fork)
-# cannot apply labels without triage/write access, so their proposals would land
-# unlabeled and never auto-add to the Silo v1 project. This stamps `v1-proposed`
-# on any issue whose title starts with `[v1]`, regardless of who filed it.
-
-on:
-  issues:
-    types: [opened]
-
-permissions:
-  issues: write
-
-jobs:
-  label:
-    if: startsWith(github.event.issue.title, '[v1]')
-    runs-on: ubuntu-latest
-    steps:
-      - name: Apply v1-proposed
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ISSUE_NUMBER: ${{ github.event.issue.number }}
-          REPO: ${{ github.repository }}
-        run: gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --add-label v1-proposed
@@ -20,7 +20,6 @@ coverage.html
 # Temp
 /tmp/
 *.tmp
-.local/

 # Worktrees
 .worktrees/
@@ -41,7 +40,6 @@ go.work.sum

 # Frontend
 web/node_modules/
-.pnpm-store/
 web/dist/
 plugins/metadb/dist/
 web/*.tsbuildinfo
@@ -59,5 +57,6 @@ node_modules/
 logs/
 .playwright-mcp/
 demo/
+docker-compose.dev.yml
 .playwright-cli/
 output/
@@ -1,7 +1,7 @@
 # Repository Guidelines

 ## Project Structure & Module Organization
-`cmd/silo` contains the main server entrypoint. Backend code lives in `internal/`, organized by domain (`api`, `catalog`, `metadata`, `playback`, `scanner`, `jellycompat`, etc.); keep new code in the package that owns the behavior instead of creating catch-all helpers. Database changes belong in `migrations/sql/` as Goose SQL migrations. Legacy converted migrations intentionally keep their original numeric versions so existing `schema_versions` rows can bootstrap cleanly into Goose. New migrations must use timestamped filenames created with `make migrate-create NAME=add_thing`; do not run `goose fix` or create paired `.up.sql` / `.down.sql` files. The React frontend lives in `web/src/`, with feature code split across `components/`, `pages/`, `hooks/`, `player/`, and `lib/`. Reference material belongs in `docs/architecture/` or `docs/superpowers/{specs,plans}/`; ad hoc SQL helpers live in `scripts/`.
+`cmd/silo` contains the main server entrypoint. Backend code lives in `internal/`, organized by domain (`api`, `catalog`, `metadata`, `playback`, `scanner`, `jellycompat`, etc.); keep new code in the package that owns the behavior instead of creating catch-all helpers. Database changes belong in `migrations/` as paired numbered `.up.sql` and `.down.sql` files. The React frontend lives in `web/src/`, with feature code split across `components/`, `pages/`, `hooks/`, `player/`, and `lib/`. Reference material belongs in `docs/architecture/` or `docs/superpowers/{specs,plans}/`; ad hoc SQL helpers live in `scripts/`.

 When creating or editing `docs/superpowers/specs/` or `docs/superpowers/plans/`, never include local absolute filesystem paths or transient worktree IDs. Use repository-relative paths and wording like "Commands assume the repository root is the cwd."

@@ -53,7 +53,6 @@ Use the checked-in `Makefile` for the common paths:
 - `make dev-frontend`: start the Vite dev server with HMR
 - `make dev-proxy` / `make dev-transcode`: run standalone worker modes
 - `make lint`: run `golangci-lint` and frontend ESLint
- `make migrate-status` / `make migrate-up`: inspect or apply Goose migrations through Silo's legacy-safe bootstrapping runner

 Run before opening a merge request:

@@ -88,21 +87,3 @@ Recent history follows Conventional Commit-style subjects such as `feat(playback
 - Silo separates login accounts (`users`) from household profiles; multiple profiles on one account share the same `user_id`.
 - Profile `is_primary` marks the household parent for that account; it is not the same as server-wide `admin` role on the user account.
 - Point the Vite dev frontend at a remote backend with `VITE_API_PROXY_TARGET` in `web/.env.local` (or inline) when running `make dev-frontend`; the frontend calls relative `/api` URLs proxied by Vite.
-
-## Silo v1 Process (scope lock & API rules)
-
-Silo is working toward a locked v1 feature set so client teams can plan against a stable core. These rules apply to every change.
-
-**Scope gate.** Before implementing a new user-facing capability, check `docs/architecture/v1-scope.md`. If the capability is not listed there — or the file says scope is not yet locked — do NOT open a feature PR. File a **v1 capability proposal** issue (template in this repo) and wait for triage. Bug fixes, refactors, and work on already-locked capabilities proceed normally.
-
-**API rules — additive-only within `/api/v1`.**
- Never rename or remove a response field, change a field's type, or repurpose a status code on an existing endpoint.
- New functionality adds new fields/endpoints; removals go through the existing Deprecation/Sunset header flow only.
- New features expose capability endpoints (feature detection) rather than relying on version sniffing.
- Contract strategy and tooling: issue #135.
-
-**PR requirements.**
- Link the capability epic or sub-issue the PR serves (`Part of #NNN`). PRs with no linked scope item will be questioned at review.
- One concern per PR; Conventional Commit subject; AI-use disclosure in the PR body.
-
-**Pre-push checklist.** `make lint` · `cd web && pnpm run lint && pnpm run format:check` · `make verify-local-paths` · Go tests in a libvips-capable container (a bare-host `go test ./...` silently skips CGO packages, including `internal/api/handlers`).
@@ -3,7 +3,6 @@ FROM node:22-slim AS frontend
 RUN corepack enable && corepack prepare pnpm@10.32.1 --activate
 WORKDIR /app/web
 COPY web/package.json web/pnpm-lock.yaml ./
-COPY web/vendor/foliate-js ./vendor/foliate-js
 RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile
 COPY web/ .
@@ -23,7 +22,6 @@ ENV GONOSUMDB=github.com/Silo-Server/*
 RUN apt-get update && apt-get install -y --no-install-recommends libvips-dev && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY go.mod go.sum ./
-COPY internal/compat/zishang520-webtransport-go/ internal/compat/zishang520-webtransport-go/
 RUN --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=cache,target=/go/pkg/mod \
    go mod download
@@ -50,15 +48,12 @@ RUN apt-get update && \
    echo "deb [signed-by=/usr/share/keyrings/jellyfin.gpg arch=${TARGETARCH}] https://repo.jellyfin.org/debian bookworm main" \
      > /etc/apt/sources.list.d/jellyfin.list && \
    apt-get update && \
-    apt-get install -y --no-install-recommends jellyfin-ffmpeg7 git libvips42 fonts-noto-core fonts-noto-cjk && \
+    apt-get install -y --no-install-recommends jellyfin-ffmpeg7 libvips42 && \
    apt-get purge -y gnupg && apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*
-RUN mkdir -p /tmp/silo-transcode /var/lib/silo/compat/jellyfin-web
-COPY --from=frontend /usr/local/bin/node /usr/local/bin/node
-COPY --from=frontend /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
-RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-    ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+RUN mkdir -p /tmp/silo-transcode
 COPY --from=build /silo /usr/local/bin/silo
+COPY third_party/jellyfin-web/ /srv/jellyfin-web/
 EXPOSE 8080 8096 13378
 HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:${PORT:-8080}/api/v1/health || exit 1
@@ -5,7 +5,6 @@ FROM node:22-slim AS frontend
 RUN corepack enable && corepack prepare pnpm@10.32.1 --activate
 WORKDIR /app/web
 COPY web/package.json web/pnpm-lock.yaml ./
-COPY web/vendor/foliate-js ./vendor/foliate-js
 RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile
 COPY web/ .
@@ -20,7 +19,6 @@ ENV GONOSUMDB=github.com/Silo-Server/*
 RUN apt-get update && apt-get install -y --no-install-recommends libvips-dev && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY go.mod go.sum ./
-COPY internal/compat/zishang520-webtransport-go/ internal/compat/zishang520-webtransport-go/
 RUN --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=cache,target=/go/pkg/mod \
    go mod download
@@ -55,16 +53,13 @@ RUN apt-get update && \
    echo "deb [signed-by=/usr/share/keyrings/jellyfin.gpg arch=${TARGETARCH}] https://repo.jellyfin.org/debian bookworm main" \
      > /etc/apt/sources.list.d/jellyfin.list && \
    apt-get update && \
-    apt-get install -y --no-install-recommends jellyfin-ffmpeg7 git libvips42 fonts-noto-core fonts-noto-cjk && \
+    apt-get install -y --no-install-recommends jellyfin-ffmpeg7 libvips42 && \
    apt-get purge -y gnupg && apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*
-RUN mkdir -p /tmp/silo-transcode /var/lib/silo/compat/jellyfin-web
-COPY --from=frontend /usr/local/bin/node /usr/local/bin/node
-COPY --from=frontend /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
-RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-    ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+RUN mkdir -p /tmp/silo-transcode
 COPY --from=build /silo /usr/local/bin/silo
-EXPOSE 8080 8096 13378
+COPY third_party/jellyfin-web/ /srv/jellyfin-web/
+EXPOSE 8080 8080 8096
 HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:${PORT:-8080}/api/v1/health || exit 1
 ENTRYPOINT ["silo"]
@@ -1,13 +1,10 @@
-.PHONY: frontend build dev-frontend dev-backend dev-proxy dev-transcode lint clean jellyfin-web migrate-continuum-check verify-local-paths install-hooks migrate-create migrate-validate migrate-status migrate-up
+.PHONY: frontend build dev-frontend dev-backend dev-proxy dev-transcode lint clean jellyfin-web-bundle migrate-continuum-check verify-local-paths install-hooks

 GIT_COMMON_DIR := $(strip $(shell git rev-parse --git-common-dir 2>/dev/null))
 MAIN_CHECKOUT_ROOT := $(if $(GIT_COMMON_DIR),$(abspath $(GIT_COMMON_DIR)/..))
 SHARED_MAKEFILE_LOCAL := $(if $(GIT_COMMON_DIR),$(abspath $(GIT_COMMON_DIR)/../Makefile.local))
 DEFAULT_PLUGIN_SDK_DIR := $(abspath ../silo-plugin-sdk)
 SHARED_PLUGIN_SDK_DIR := $(if $(MAIN_CHECKOUT_ROOT),$(abspath $(MAIN_CHECKOUT_ROOT)/../silo-plugin-sdk))
-GOOSE := go run github.com/pressly/goose/v3/cmd/goose@v3.27.1
-GOOSE_DIR := migrations/sql
-ENV_FILE ?= .env

 ifneq ($(wildcard $(DEFAULT_PLUGIN_SDK_DIR)),)
 DEV_PLUGIN_SDK_DIR ?= $(DEFAULT_PLUGIN_SDK_DIR)
@@ -15,15 +12,7 @@ else ifneq ($(wildcard $(SHARED_PLUGIN_SDK_DIR)),)
 DEV_PLUGIN_SDK_DIR ?= $(SHARED_PLUGIN_SDK_DIR)
 endif

-JELLYFIN_WEB_INSTALL_DIR ?= .local/compat/jellyfin-web
-JELLYFIN_WEB_VERSION ?= 10.11.6
-
-# Build version stamping: inject the git revision so the admin Build panel shows a
-# version even when Go's VCS metadata isn't embedded (mirrors the Dockerfile ldflags).
-BUILDINFO_PKG := github.com/Silo-Server/silo-server/internal/buildinfo
-BUILD_REVISION ?= $(shell git rev-parse HEAD 2>/dev/null)
-BUILD_DIRTY ?= $(shell test -n "$$(git status --porcelain 2>/dev/null)" && echo true || echo false)
-GO_LDFLAGS := -X $(BUILDINFO_PKG).revisionOverride=$(BUILD_REVISION) -X $(BUILDINFO_PKG).dirtyOverride=$(BUILD_DIRTY)
+JELLYFIN_WEB_OUTPUT_DIR ?= third_party/jellyfin-web

 # Build the frontend (requires pnpm)
 frontend:
@@ -31,7 +20,7 @@ frontend:

 # Build the Go binary (depends on frontend)
 build: frontend
-	go build -ldflags "$(GO_LDFLAGS)" -o silo ./cmd/silo/
+	go build -o silo ./cmd/silo/

 # Run frontend dev server (proxies API to localhost:8080)
 dev-frontend:
@@ -58,23 +47,6 @@ lint:
 verify-local-paths:
 	scripts/check-local-path-leaks.sh

-# Create a timestamped Goose SQL migration. Usage: make migrate-create NAME=add_thing
-migrate-create:
-	@if [ -z "$(NAME)" ]; then echo "usage: make migrate-create NAME=add_thing"; exit 1; fi
-	$(GOOSE) -dir $(GOOSE_DIR) create "$(NAME)" sql
-
-# Validate Goose migration annotations and SQL parsing without touching a database.
-migrate-validate:
-	$(GOOSE) -dir $(GOOSE_DIR) validate
-
-# Show Goose migration status through Silo's bootstrapping runner.
-migrate-status:
-	go run ./cmd/silo/ --env "$(ENV_FILE)" --migrate-status
-
-# Apply pending Goose migrations through Silo's bootstrapping runner.
-migrate-up:
-	go run ./cmd/silo/ --env "$(ENV_FILE)" --migrate-only
-
 # Install repo-local git hooks for this checkout/worktree.
 install-hooks:
 	@existing="$$(git config --local core.hooksPath 2>/dev/null || true)"; \
@@ -83,9 +55,9 @@ install-hooks:
 	fi
 	git config core.hooksPath .githooks

-# Fetch and build the pinned Jellyfin Web component into a gitignored local cache.
-jellyfin-web:
-	go run ./cmd/silo/ compat-web install --dir "$(JELLYFIN_WEB_INSTALL_DIR)" --version "$(JELLYFIN_WEB_VERSION)"
+# Fetch and build the pinned Jellyfin Web bundle
+jellyfin-web-bundle:
+	JELLYFIN_WEB_OUTPUT_DIR=$(JELLYFIN_WEB_OUTPUT_DIR) scripts/fetch-jellyfin-web.sh

 # Read-only preflight for Continuum Docker installs moving to Silo.
 migrate-continuum-check:
@@ -1,8 +1,6 @@
 # Silo

-A self-hosted media streaming server with a React frontend and Go backend. Supports direct play, remuxing, and hardware-accelerated transcoding. Includes optional Jellyfin/Emby-compatible app support for clients such as VidHub and Findroid.
-
-Join the community on [Discord](https://discord.gg/4RxuUQAEnW).
+A self-hosted media streaming server with a React frontend and Go backend. Supports direct play, remuxing, and hardware-accelerated transcoding. Compatible with Jellyfin/Emby clients (VidHub, Findroid) via a built-in compatibility layer.

 ## Deploy with Docker (recommended)

@@ -30,33 +28,10 @@ The easiest way to run Silo is with Docker Compose. The default stack assumes yo
   docker compose up -d
   ```

-   This starts PostgreSQL, Redis, and the integrated Silo server. The app is available at `http://localhost:8090`. Jellyfin-compatible app support is disabled until an administrator enables it in onboarding or admin settings.
+   This starts PostgreSQL, Redis, and the integrated Silo server. The app is available at `http://localhost:8090` and the Jellyfin-compatible endpoint at `http://localhost:8096`.

   If you already have PostgreSQL and Redis available, omit those bundled service examples from compose and point Silo at your existing `DATABASE_URL` and `REDIS_URL` instead.

-   ### Optional NVIDIA/NVENC
-
-   GPU support is kept out of the default compose file so hosts without NVIDIA drivers work unchanged.
-
-   Install the NVIDIA Container Toolkit and use a Docker Compose version with GPU reservation support before enabling this override.
-
-   Use the optional override file when you want NVENC:
-
-   ```sh
-   docker compose -f docker-compose.yml -f docker-compose.nvidia.yml up -d
-   ```
-
-   If you want this controlled from `.env`, set `COMPOSE_FILE`:
-
-   ```dotenv
-   COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml
-   NVIDIA_GPU_COUNT=1
-   ```
-
-   Windows uses `;` instead of `:` between compose files.
-
-   Then `docker compose up -d` will include the NVIDIA override automatically.
-
 4. **Configure through the admin UI**

   Add libraries, users, metadata providers, and playback settings from the web interface.
@@ -201,36 +176,8 @@ Technical notes:
 | `make dev-backend` | Run Go backend (integrated mode) |
 | `make dev-proxy` | Run a standalone proxy node |
 | `make dev-transcode` | Run a standalone transcode node |
-| `make migrate-create NAME=add_thing` | Create a timestamped Goose SQL migration |
-| `make migrate-validate` | Validate Goose migration files without touching a database |
-| `make migrate-status` | Show Goose migration status using Silo's bootstrapping runner |
-| `make migrate-up` | Apply pending Goose migrations using Silo's bootstrapping runner |
 | `make clean` | Remove build artifacts |

-### Database Migrations
-
-PostgreSQL schema migrations are managed by Goose. Migration SQL files live in
-`migrations/sql/` and use Goose annotations. Converted legacy migrations keep
-their original numeric versions so existing `schema_versions` rows can bootstrap
-cleanly into Goose without replaying old SQL. New migrations should be created
-with timestamped filenames:
-
-```sh
-make migrate-create NAME=add_thing
-make migrate-validate
-```
-
-Do not run `goose fix`; timestamped migrations are the repository policy because
-they avoid version collisions across parallel PRs. The existing `001`-style
-files are historical compatibility records, not the naming pattern for new work.
-Runtime migrations are applied by the integrated/API server only. Proxy and
-transcode modes never mutate schema.
-For existing installs, use `make migrate-status` and `make migrate-up` rather
-than invoking the Goose CLI directly; those targets copy legacy
-`schema_versions` rows into `public.goose_db_version` under the migration lock
-before reading or applying migrations. Set `ENV_FILE=path/to/.env` when the
-database URL should be read from a non-default env file.
-
 ### Running Tests

 ```sh
@@ -269,57 +216,93 @@ Silo requires only a `DATABASE_URL` when running from source or against external
 | `proxy` | Stream proxy node that connects to the shared deployment database and Redis |
 | `transcode` | HLS transcode worker node that connects to the shared deployment database and Redis |

-## PostgreSQL Auto-Tuning
+## PostgreSQL Performance Tuning

-The default Docker Compose stack does not require a checked-in `postgresql.conf`.
-It enables Silo's [pgtune](https://github.com/le0pard/pgtune)-style OLTP tuning
-by default:
+The default PostgreSQL configuration is conservative and not optimized for any particular workload. For better performance, use [PGTune](https://pgtune.leopard.in.ua/) to generate settings tailored to your hardware.
+
+**Recommended PGTune settings:**
+
+| Setting | Value |
+|---|---|
+| DB Type | **Web application** |
+| Total Memory | Your server's RAM |
+| Number of CPUs | Your server's CPU count |
+| Number of Connections | 20 (Silo's default pool size) |
+| Data Storage | SSD or HDD depending on your setup |
+
+Silo's workload is predominantly read-heavy API queries (browse, search, metadata lookups) with the database small enough to fit in RAM for most libraries. The **Web application** profile optimizes for this: CPU-bound simple queries served from cached pages, high concurrent reads, and low write volume.
+
+If you have a very large library (50,000+ items) or heavy activity logging, consider switching to the **OLTP** profile instead.
+
+### Recommended Defaults for Modern Hardware
+
+Assuming you're using modern hardware with fast NVMe storage this is what I'm currently running.
+
+```ini
+# Connections
+max_connections = 100
+
+# Memory (tuned to keep PG under ~8GB total)
+shared_buffers = 4GB               # holds the entire DB in cache (typical DB is 1-4GB)
+effective_cache_size = 6GB         # planner hint only, not an allocation
+work_mem = 32MB                    # per-operation sort/hash memory
+maintenance_work_mem = 512MB       # VACUUM, CREATE INDEX, catalog imports
+
+# WAL / Write Performance
+wal_buffers = 64MB
+min_wal_size = 512MB
+max_wal_size = 2GB
+checkpoint_completion_target = 0.9
+
+# Storage (NVMe/Optane)
+random_page_cost = 1.1             # default 4.0; NVMe random ≈ sequential
+effective_io_concurrency = 200     # NVMe handles many concurrent requests
+
+# Parallelism
+max_worker_processes = 8
+max_parallel_workers_per_gather = 4
+max_parallel_workers = 8
+max_parallel_maintenance_workers = 4
+
+# Huge Pages
+huge_pages = try
+```
+
+These settings keep PostgreSQL under ~8GB of RAM while still caching the entire database. For HDD storage, change `random_page_cost` to `4.0` and `effective_io_concurrency` to `2`.
+
+### Applying Settings
+
+**Docker (recommended):** Save the settings above to a `postgresql.conf` file and mount it into your container:

 ```yaml
-POSTGRES_TUNE: auto
+# docker-compose.yml
+postgres:
+  image: pgvector/pgvector:pg18
+  volumes:
+    - ./postgresql.conf:/etc/postgresql/postgresql.conf:ro
+  command: postgres -c config_file=/etc/postgresql/postgresql.conf
 ```

-When enabled, Silo connects with `DATABASE_URL` and applies recommendations with
-`ALTER SYSTEM`, which writes to PostgreSQL's `postgresql.auto.conf` inside the
-database data directory. Reloadable settings are applied immediately with
-`pg_reload_conf()`. Settings that PostgreSQL marks as restart-only are written
-too, and Silo logs the setting names so you can restart PostgreSQL once:
+Then restart: `docker compose restart postgres`

-```sh
-docker compose restart postgres
+**Existing PostgreSQL:** You can apply settings without editing config files using `ALTER SYSTEM`, which writes to `postgresql.auto.conf` inside the data directory:
+
+```sql
+ALTER SYSTEM SET work_mem = '32MB';
+ALTER SYSTEM SET effective_cache_size = '6GB';
+ALTER SYSTEM SET random_page_cost = 1.1;
+ALTER SYSTEM SET effective_io_concurrency = 200;
+-- Apply without restart:
+SELECT pg_reload_conf();
+
+-- These require a full restart:
+ALTER SYSTEM SET shared_buffers = '4GB';
+ALTER SYSTEM SET max_connections = 100;
+ALTER SYSTEM SET max_worker_processes = 8;
+ALTER SYSTEM SET huge_pages = 'try';
 ```

-The default Compose database user has the required PostgreSQL permissions. If
-you use an external PostgreSQL server, make sure the configured `DATABASE_URL`
-user can run `ALTER SYSTEM`, or set `POSTGRES_TUNE=off` and manage
-PostgreSQL yourself.
-
-For `POSTGRES_TUNE_MEMORY=auto`, Silo uses the first trustworthy memory source:
-a finite Docker cgroup limit, the read-only `/host/proc/meminfo` mount supplied
-by the bundled Compose file, then `/proc/meminfo` with container safety guards.
-Auto-detected memory is treated as a PostgreSQL budget, defaulting to 75% of
-detected RAM so Silo, Redis, plugins, transcodes, and the OS retain headroom.
-`POSTGRES_TUNE_DB_SIZE=auto` queries `pg_database_size(current_database())` and
-classifies the workload by comparing the database size to that memory budget.
-
-Optional tuning overrides:
-
-| Variable | Default | Description |
-|---|---:|---|
-| `POSTGRES_TUNE_PROFILE` | `oltp` | Tuning profile. Only `oltp` is currently supported. |
-| `POSTGRES_TUNE_MEMORY` | `auto` | Server/container RAM, such as `8GB` or `32GB`; explicit values are used as-is. |
-| `POSTGRES_TUNE_MEMORY_BUDGET_PERCENT` | `75` | Percent of auto-detected RAM used for PostgreSQL recommendations. |
-| `POSTGRES_TUNE_CPUS` | `auto` | CPU count used for worker recommendations. |
-| `POSTGRES_TUNE_STORAGE` | `ssd` | One of `hdd`, `ssd`, `san`, or `nvme`. |
-| `POSTGRES_TUNE_DB_SIZE` | `auto` | Use `less_ram` when the database comfortably fits in RAM, `mid_ram`, or `greater_ram` for very large databases. |
-| `POSTGRES_TUNE_CONNECTIONS` | `100` | PostgreSQL `max_connections`; automatically raised if Silo's app pool is configured higher. |
-| `POSTGRES_SHM_SIZE` | `8gb` | Docker `/dev/shm` size for the bundled PostgreSQL container. |
-
-Advanced operators can still supply their own PostgreSQL configuration or
-override these env vars. Set `POSTGRES_TUNE=off` when you do not want Silo to
-change PostgreSQL server settings. Settings already written with `ALTER SYSTEM`
-remain in `postgresql.auto.conf`; reset those PostgreSQL parameters if you later
-move fully to a custom `postgresql.conf`.
+Settings like `shared_buffers`, `max_connections`, `max_worker_processes`, and `huge_pages` require a PostgreSQL restart. Memory/planner settings (`work_mem`, `effective_cache_size`, `random_page_cost`) can be reloaded live.

 ## Project Structure

@@ -336,5 +319,5 @@ internal/
  scanner/           Media file discovery and FFProbe
  worker/            Background jobs (scan, match, reconcile)
 web/                 React + TypeScript frontend (Vite, Tailwind, shadcn/ui)
-migrations/sql/      Goose-managed PostgreSQL schema migrations
+migrations/          PostgreSQL schema migrations
 ```
@@ -5,11 +5,11 @@ material needed for Silo server builds.

 ## Jellyfin Web

-Silo does not bundle Jellyfin Web in this repository or in the default runtime
-image. Administrators can explicitly install Jellyfin Web as a separate
-compatibility component with `silo compat-web install` or the admin settings UI.
-The installer records the upstream source URL, tag, commit SHA, checksum,
-license, and source/provenance metadata beside the installed assets.
+`third_party/jellyfin-web/10.11.6/` contains a vendored Jellyfin Web build used
+for Jellyfin compatibility surfaces. Upstream package notices generated by that
+build are preserved next to the corresponding bundles as `*.LICENSE.txt` files.
+Keep those notices with the vendored files when updating or redistributing this
+directory.

 ## Collection Template Posters

@@ -17,3 +17,4 @@ license, and source/provenance metadata beside the installed assets.
 poster artwork. The artwork is intended to use generic original scenes and
 avoid copyrighted movie/show posters, recognizable actors, franchise
 characters, provider logos, and readable in-image third-party branding.
+
@@ -132,9 +132,6 @@ func TestBuildLiveSessionSync_UsesTransportPlayMethod(t *testing.T) {
 				RequestedMediaFileID: 41,
 				PlayMethod:           playback.PlayTranscode,
 				BasePlayMethod:       playback.PlayRemux,
-				TranscodeHWAccel:     "qsv",
-				Position:             125.5,
-				IsPaused:             true,
 			},
 			want: "transcode",
 		},
@@ -167,18 +164,6 @@ func TestBuildLiveSessionSync_UsesTransportPlayMethod(t *testing.T) {
 			if got.SessionID != tc.session.ID {
 				t.Fatalf("SessionID = %q, want %q", got.SessionID, tc.session.ID)
 			}
-			if got.ProfileID != tc.session.ProfileID {
-				t.Fatalf("ProfileID = %q, want %q", got.ProfileID, tc.session.ProfileID)
-			}
-			if got.PositionSeconds != tc.session.Position {
-				t.Fatalf("PositionSeconds = %v, want %v", got.PositionSeconds, tc.session.Position)
-			}
-			if got.IsPaused != tc.session.IsPaused {
-				t.Fatalf("IsPaused = %v, want %v", got.IsPaused, tc.session.IsPaused)
-			}
-			if got.TranscodeHWAccel != tc.session.TranscodeHWAccel {
-				t.Fatalf("TranscodeHWAccel = %q, want %q", got.TranscodeHWAccel, tc.session.TranscodeHWAccel)
-			}
 		})
 	}
 }
@@ -1,85 +0,0 @@
-package main
-
-import (
-	"context"
-	"testing"
-
-	"github.com/Silo-Server/silo-server/internal/plugins"
-)
-
-type fakeMarkerRuntimeConfigs struct {
-	configs map[int][]*plugins.RuntimeConfig
-	puts    []plugins.RuntimeConfig
-}
-
-func (f *fakeMarkerRuntimeConfigs) ListGlobalConfigs(_ context.Context, installationID int) ([]*plugins.RuntimeConfig, error) {
-	return append([]*plugins.RuntimeConfig(nil), f.configs[installationID]...), nil
-}
-
-func (f *fakeMarkerRuntimeConfigs) PutGlobalConfig(_ context.Context, installationID int, key string, value map[string]any) error {
-	f.puts = append(f.puts, plugins.RuntimeConfig{InstallationID: installationID, Key: key, Value: value})
-	f.configs[installationID] = append(f.configs[installationID], &plugins.RuntimeConfig{
-		InstallationID: installationID,
-		Key:            key,
-		Value:          value,
-	})
-	return nil
-}
-
-type fakeMarkerLegacySettings map[string]string
-
-func (f fakeMarkerLegacySettings) Get(_ context.Context, key string) (string, error) {
-	return f[key], nil
-}
-
-func TestCopyLegacyIntroDBPluginConfigCopiesAPIKeyOnce(t *testing.T) {
-	runtimeConfigs := &fakeMarkerRuntimeConfigs{configs: map[int][]*plugins.RuntimeConfig{}}
-	installation := &plugins.Installation{ID: 42, PluginID: "silo.theintrodb"}
-	capability := &plugins.Capability{ID: "introdb"}
-
-	if err := copyLegacyIntroDBPluginConfig(
-		context.Background(),
-		runtimeConfigs,
-		fakeMarkerLegacySettings{"introdb.api_key": " legacy-key "},
-		installation,
-		capability,
-	); err != nil {
-		t.Fatalf("copyLegacyIntroDBPluginConfig: %v", err)
-	}
-	if len(runtimeConfigs.puts) != 1 {
-		t.Fatalf("puts = %d, want 1", len(runtimeConfigs.puts))
-	}
-	got := runtimeConfigs.puts[0]
-	if got.InstallationID != 42 || got.Key != "account" || got.Value["api_key"] != "legacy-key" {
-		t.Fatalf("put = %+v, want account api_key copy", got)
-	}
-
-	if err := copyLegacyIntroDBPluginConfig(
-		context.Background(),
-		runtimeConfigs,
-		fakeMarkerLegacySettings{"introdb.api_key": "new-key"},
-		installation,
-		capability,
-	); err != nil {
-		t.Fatalf("second copyLegacyIntroDBPluginConfig: %v", err)
-	}
-	if len(runtimeConfigs.puts) != 1 {
-		t.Fatalf("second copy overwrote config; puts = %d, want 1", len(runtimeConfigs.puts))
-	}
-}
-
-func TestCopyLegacyIntroDBPluginConfigIgnoresOtherPlugins(t *testing.T) {
-	runtimeConfigs := &fakeMarkerRuntimeConfigs{configs: map[int][]*plugins.RuntimeConfig{}}
-	if err := copyLegacyIntroDBPluginConfig(
-		context.Background(),
-		runtimeConfigs,
-		fakeMarkerLegacySettings{"introdb.api_key": "legacy-key"},
-		&plugins.Installation{ID: 7, PluginID: "silo.other"},
-		&plugins.Capability{ID: "introdb"},
-	); err != nil {
-		t.Fatalf("copyLegacyIntroDBPluginConfig: %v", err)
-	}
-	if len(runtimeConfigs.puts) != 0 {
-		t.Fatalf("puts = %d, want 0 for non-TheIntroDB plugin", len(runtimeConfigs.puts))
-	}
-}
@@ -31,10 +31,8 @@ func buildLiveSessionSync(s *playback.Session, reportingNode string) worker.Sess
 		TargetVideoCodec:     s.TargetVideoCodec,
 		TargetAudioCodec:     s.TargetAudioCodec,
 		TargetBitrateKbps:    s.TargetBitrateKbps,
-		TranscodeHWAccel:     s.TranscodeHWAccel,
 		StartedAt:            s.StartedAt,
 		UpdatedAt:            s.UpdatedAt,
-		PositionSeconds:      s.Position,
 		IsPaused:             s.IsPaused,
 		HasWebSocket:         s.HasWebSocket,
 	}
@@ -1,181 +0,0 @@
-# Development stack:
-#   docker compose -f docker-compose.dev.yml up --build
-#
-# Vite serves the UI at http://localhost:${PORT:-8090} and proxies API
-# requests to the Air-reloaded Go backend on the compose network.
-name: silo-dev
-
-services:
-  postgres:
-    image: pgvector/pgvector:pg18
-    restart: unless-stopped
-    shm_size: ${POSTGRES_SHM_SIZE:-2gb}
-    environment:
-      POSTGRES_USER: ${POSTGRES_USER:-silo}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-silo}
-      POSTGRES_DB: ${POSTGRES_DB:-silo}
-    ports:
-      - "${POSTGRES_PORT:-5432}:5432"
-    volumes:
-      - silo-dev-postgres:/var/lib/postgresql
-    command: ["postgres", "-c", "listen_addresses=*"]
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-silo}"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  redis:
-    image: redis:alpine
-    restart: unless-stopped
-    ports:
-      - "${REDIS_PORT:-6379}:6379"
-    volumes:
-      - silo-dev-redis:/data
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  silo:
-    build:
-      context: .
-      dockerfile_inline: |
-        FROM node:22-slim AS node_runtime
-
-        FROM golang:1.26
-
-        ENV CGO_ENABLED=1
-        ENV GOPROXY=direct
-        ENV GOPRIVATE=github.com/Silo-Server/*
-        ENV GONOSUMDB=github.com/Silo-Server/*
-
-        RUN apt-get update && apt-get install -y --no-install-recommends \
-            ca-certificates \
-            curl \
-            ffmpeg \
-            git \
-            libvips-dev \
-            pkg-config \
-          && rm -rf /var/lib/apt/lists/*
-
-        COPY --from=node_runtime /usr/local/bin/node /usr/local/bin/node
-        COPY --from=node_runtime /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
-        RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-            ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
-
-        RUN go install github.com/air-verse/air@latest
-
-        WORKDIR /app
-    restart: unless-stopped
-    working_dir: /app
-    command:
-      - sh
-      - -c
-      - |
-        mkdir -p tmp web/dist
-        if [ ! -f web/dist/index.html ]; then
-          printf '%s\n' '<!doctype html><html><body><div id="root"></div></body></html>' > web/dist/index.html
-        fi
-
-        cat >/tmp/air.docker.toml <<'AIR'
-        root = "."
-        tmp_dir = "tmp"
-
-        [build]
-          cmd = "go build -o ./tmp/silo ./cmd/silo/"
-          bin = "./tmp/silo"
-          args_bin = []
-          include_ext = ["go", "sql", "json"]
-          include_dir = ["cmd", "internal", "migrations"]
-          exclude_dir = ["tmp", "vendor", "third_party", "docs", "scripts", "web"]
-          exclude_regex = ["_test\\.go$"]
-          delay = 500
-          stop_on_error = true
-          kill_delay = 500
-          send_interrupt = true
-
-        [log]
-          time = true
-
-        [misc]
-          clean_on_exit = true
-        AIR
-
-        air -c /tmp/air.docker.toml
-    environment:
-      MODE: integrated
-      PORT: "8080"
-      DATABASE_URL: postgres://${POSTGRES_USER:-silo}:${POSTGRES_PASSWORD:-silo}@postgres:5432/${POSTGRES_DB:-silo}?sslmode=disable
-      REDIS_URL: redis://redis:6379
-      SILO_PLUGIN_CACHE_DIR: /var/lib/silo/plugins
-      POSTGRES_TUNE: "off"
-    ports:
-      - "${BACKEND_PORT:-18080}:8080"
-      - "${JF_PORT:-8096}:8096"
-      - "${ABS_PORT:-13378}:13378"
-    volumes:
-      - .:/app
-      - silo-dev-air-tmp:/app/tmp
-      - silo-dev-go-build:/root/.cache/go-build
-      - silo-dev-go-mod:/go/pkg/mod
-      - silo-dev-plugins:/var/lib/silo/plugins
-      - silo-dev-compat:/var/lib/silo/compat
-      - silo-dev-transcode:/tmp/silo-transcode
-      - silo-dev-audiobook-covers:/var/lib/silo/audiobook-covers
-      - ${MEDIA_ROOT:-/tmp/silo-dev-media}:${MEDIA_CONTAINER_ROOT:-/mnt/media}:ro
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-fsS", "http://localhost:8080/api/v1/health"]
-      interval: 5s
-      timeout: 3s
-      retries: 30
-      start_period: 10s
-    env_file:
-      - path: .env
-        required: false
-
-  web:
-    build:
-      context: .
-      dockerfile_inline: |
-        FROM node:22-slim
-
-        RUN corepack enable && corepack prepare pnpm@10.32.1 --activate
-
-        WORKDIR /app/web
-    restart: unless-stopped
-    working_dir: /app/web
-    command: sh -c "pnpm install --frozen-lockfile --store-dir /pnpm/store && pnpm run dev -- --host 0.0.0.0"
-    environment:
-      VITE_API_PROXY_TARGET: http://silo:8080
-      VITE_HMR_CLIENT_PORT: "${PORT:-8090}"
-      PNPM_STORE_DIR: /pnpm/store
-      CI: "true"
-    ports:
-      - "${PORT:-8090}:5173"
-    volumes:
-      - .:/app
-      - silo-dev-web-node-modules:/app/web/node_modules
-      - silo-dev-pnpm-store:/pnpm/store
-    depends_on:
-      silo:
-        condition: service_healthy
-
-volumes:
-  silo-dev-air-tmp:
-  silo-dev-audiobook-covers:
-  silo-dev-compat:
-  silo-dev-go-build:
-  silo-dev-go-mod:
-  silo-dev-plugins:
-  silo-dev-pnpm-store:
-  silo-dev-postgres:
-  silo-dev-redis:
-  silo-dev-transcode:
-  silo-dev-web-node-modules:
@@ -1,20 +0,0 @@
-services:
-  silo:
-    deploy:
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: ${NVIDIA_GPU_COUNT:-1}
-              capabilities: [gpu]
-
-  # Optional distributed-mode example. Most single-host installs should
-  # just use the integrated service above.
-  #  silo-transcode:
-  #  deploy:
-  #    resources:
-  #      reservations:
-  #        devices:
-  #          - driver: nvidia
-  #            count: ${NVIDIA_GPU_COUNT:-1}
-  #            capabilities: [gpu]
@@ -2,7 +2,7 @@ services:
  postgres:
    image: pgvector/pgvector:pg18
    restart: unless-stopped
-    shm_size: ${POSTGRES_SHM_SIZE:-8gb}
+    shm_size: 1gb
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-silo}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-silo}
@@ -11,7 +11,8 @@ services:
      - "5432:5432"
    volumes:
      - ${SILO_DATA_ROOT:-/opt/silo}/postgres:/var/lib/postgresql
-    command: ["postgres", "-c", "listen_addresses=*"]
+      - ./postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro
+    command: postgres -c config_file=/etc/postgresql/postgresql.conf
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-silo}"]
      interval: 5s
@@ -36,28 +37,20 @@ services:
    restart: unless-stopped
    environment:
      MODE: integrated
-      # Master key for at-rest credential encryption. Required — the server
-      # refuses to start without it. Generate with: openssl rand -base64 48
-      # Back it up SEPARATELY from your database dumps; losing it makes encrypted
-      # secrets unrecoverable. See docs/architecture/secret-encryption.md.
-      SECRET_KEY: ${SECRET_KEY:?Set SECRET_KEY in .env — generate one with openssl rand -base64 48}
      DATABASE_URL: postgres://${POSTGRES_USER:-silo}:${POSTGRES_PASSWORD:-silo}@postgres:5432/${POSTGRES_DB:-silo}?sslmode=disable
      REDIS_URL: redis://redis:6379
      SILO_PLUGIN_CACHE_DIR: /var/lib/silo/plugins
-      POSTGRES_TUNE: ${POSTGRES_TUNE:-auto}
    ports:
      - "${PORT:-8090}:8080"
      - "${JF_PORT:-8096}:8096"
      - "${ABS_PORT:-13378}:13378"
    volumes:
      - ${MEDIA_ROOT:?Set MEDIA_ROOT in .env to the host media path}:${MEDIA_CONTAINER_ROOT:-/mnt/media}:ro
-      - ${MEDIA_BOOKS_ROOT:-${MEDIA_ROOT}}:${MEDIA_BOOKS_CONTAINER_ROOT:-${MEDIA_CONTAINER_ROOT:-/mnt/media}/books}:ro
+      - ${MEDIA_BOOKS_ROOT:-${MEDIA_ROOT}}:${MEDIA_BOOKS_CONTAINER_ROOT:-${MEDIA_CONTAINER_ROOT:-/mnt/media}}:ro
      - ${SILO_DATA_ROOT:-/opt/silo}/plugins:/var/lib/silo/plugins
-      - ${SILO_DATA_ROOT:-/opt/silo}/compat:/var/lib/silo/compat
      - ${SILO_DATA_ROOT:-/opt/silo}/transcode:/tmp/silo-transcode
      - ${SILO_DATA_ROOT:-/opt/silo}/catalog-seeds:/catalog-seeds:ro
      - ${SILO_DATA_ROOT:-/opt/silo}/audiobook-covers:/var/lib/silo/audiobook-covers
-      - /proc/meminfo:/host/proc/meminfo:ro
    depends_on:
      postgres:
        condition: service_healthy
@@ -66,8 +59,6 @@ services:
    env_file:
      - path: .env
        required: false
-    devices:
-      - /dev/dri:/dev/dri

  # Optional distributed-mode example. Most single-host installs should
  # just use the integrated service above.
@@ -77,8 +68,6 @@ services:
  #   profiles: [proxy]
  #   environment:
  #     MODE: proxy
-  #     # Must be the SAME SECRET_KEY as the primary node (shared encrypted data).
-  #     SECRET_KEY: ${SECRET_KEY:?Set SECRET_KEY in .env — generate one with openssl rand -base64 48}
  #     DATABASE_URL: postgres://${POSTGRES_USER:-silo}:${POSTGRES_PASSWORD:-silo}@postgres:5432/${POSTGRES_DB:-silo}?sslmode=disable
  #     REDIS_URL: redis://redis:6379
  #     PORT: "8080"
@@ -103,8 +92,6 @@ services:
  #   profiles: [transcode]
  #   environment:
  #     MODE: transcode
-  #     # Must be the SAME SECRET_KEY as the primary node (shared encrypted data).
-  #     SECRET_KEY: ${SECRET_KEY:?Set SECRET_KEY in .env — generate one with openssl rand -base64 48}
  #     DATABASE_URL: postgres://${POSTGRES_USER:-silo}:${POSTGRES_PASSWORD:-silo}@postgres:5432/${POSTGRES_DB:-silo}?sslmode=disable
  #     REDIS_URL: redis://redis:6379
  #     SILO_PLUGIN_CACHE_DIR: /var/lib/silo/plugins
@@ -1,376 +0,0 @@
-# Deterministic, Cross-Server `content_id`
-
-**Status:** Implemented (branch `feat/deterministic-content-id`)
-**Scope:** catalog / scanner / metadata
-**Key code:** `internal/contentid`, `internal/metadata/service.go`,
-`internal/catalog/history_source.go`,
-`migrations/sql/20260612130000_deterministic_content_id.sql`,
-`migrations/sql/20260614120000_content_id_online_reid.sql`
-
-This is the dev-facing reference for *why* `content_id` is what it is and *how*
-it works. It merges the original design spec, the implementation notes, and the
-PR write-up into one place.
-
---
-
-## 1. The problem
-
-`content_id` is the anchor almost everything hangs off: artwork, metadata, watch
-history, progress, favorites, ratings, collections, credits. Historically it was
-a **Sonyflake** — a locally generated, time-ordered random number minted at scan
-time.
-
-That means the *same* movie matched on two servers (or re-imported into a fresh
-instance) gets a **different** id each time. Consequence: two servers holding the
-identical title share *none* of that state. Run more than one Silo, or try to
-sync a profile's history between servers, and the same film shows up as a
-stranger on the other side — no resume point, no watched flags, no ratings. There
-was no stable identity to build any cross-server feature on.
-
-We want: **the same logical title produces the same `content_id` on every server,
-every time**, derived from a globally stable anchor (the provider IDs already in
-the library), and **stable across file renames/re-encodes** so linked state
-survives.
-
---
-
-## 2. The decision
-
-Make `content_id` a **deterministic, provider-derived, structured natural key**,
-stored as **`text COLLATE "C"`**:
-
-| Item | `content_id` |
-| ---- | ------------ |
-| Movie | `movie-tmdb-228064` (fallback `movie-imdb-tt2413338`) |
-| Series | `series-tvdb-296762` |
-| Season | `season-tvdb-296762-1` |
-| Episode | `episode-tvdb-296762-1-5` |
-| Unmatched / local | `local-<128-bit path hash, hex>` |
-
-Why this shape:
-
- **Collision-free with no hashing.** Provider IDs are unique by construction, so
-  this is a natural key, not a surrogate — there is no "how many bits" question
-  and no birthday bound.
- **No column-type migration.** It stays `text`, so the wide soft-reference graph
-  keeps working; only the *values* are remapped, not the type.
- **Debuggable.** A row's identity is legible in logs and queries, and the
-  scanner's match step becomes a direct PK lookup ("do I already have
-  `movie-tmdb-228064`?") instead of a join through `media_item_provider_ids`.
- **Stable** across renames/re-encodes — a movie keeps its tmdb id.
-
-### Why `content_id`, not a file-level id
-
-Two distinct identities at different granularities, not to be conflated:
-
- **`content_id`** — the *logical* item (movie/series/season/episode). One id,
-  *many* files (1080p + 4K + cuts; a series owns thousands of episode files).
- **`media_files.id`** — one *physical* file; a per-server serial that only
-  answers "which file on disk."
-
-`content_id` is the high-value target (35 FKs + ~25 unconstrained soft references
-point at it). Its stability requirement is the *opposite* of a file id's: a file
-id *should* change on rename; a `content_id` must *not*, or every server would
-drop a title's watch history on a routine rename. That's why it's anchored on
-rename-invariant provider IDs, never a path or file hash. File-level dedup is a
-separate, deferred concern.
-
---
-
-## 3. How the id is derived
-
-### Format (SchemeVersion 1)
-
-```text
-movie-<provider>-<id>                  movie-tmdb-228064
-series-<provider>-<id>                 series-tvdb-296762
-season-<provider>-<seriesId>-<n>       season-tvdb-296762-1
-episode-<provider>-<seriesId>-<s>-<e>  episode-tvdb-296762-1-5
-local-<hex112>                         local-<sha256(path)[:14]>
-```
-
-The component separator is `-`, an [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3)
-*unreserved* character. Every component is `[a-z0-9]+` (or `tt` + digits for
-IMDb), so `-` is an unambiguous delimiter, and because it never needs
-percent-encoding the id doubles as its own tidy URL path segment
-(`/item/series-tvdb-296762`) — identical to what is stored in the database, so
-there is no encode/decode boundary and an operator can grep the value straight
-out of a URL or log. (`:` would be legal in a path too, but `encodeURIComponent`
-escapes it to `%3A`; an unreserved separator sidesteps that entirely.)
-
- The leading entity-type token domain-separates namespaces, so a movie and an
-  episode can never alias on a coincidental number.
- IDs are normalized: lowercase scheme tokens, whitespace trimmed, IMDb keeps its
-  `tt` prefix verbatim.
-
-### Frozen provider precedence
-
-Each item anchors on **one** canonical provider, chosen by fixed precedence so
-two servers that see the same tags pick the same anchor:
-
- **Movies:** `tmdb → imdb → tvdb`
- **Series / Season / Episode:** `tvdb → tmdb → imdb` (TVDB is episode-canonical)
-
-Precedence **and** exact string format are frozen behind a code constant
-(`contentid.SchemeVersion = 1`), *not* a DB column — any scheme change forces a
-full remap that normalizes every row at once, so there is never a mixed-version
-population. Staleness is recoverable by recomputing the expected id from the
-provider columns and comparing.
-
-### The load-bearing invariant: the show falls out of the episode id
-
-Season/episode ids compose from the **series anchor + season/episode numbers**
-(both present in filenames and universally available), *not* their own provider
-episode IDs (often missing). Because `episode-<provider>-<seriesId>-<s>-<e>`
-embeds the series anchor, the series id is a pure **string transform** of the
-episode id — no catalog lookup:
-
-```text
-episode-tvdb-296762-1-5   →   series-tvdb-296762
-movie-tmdb-228064         →   movie-tmdb-228064   (movies/series: unchanged)
-```
-
-This is relied on by the hot watch-history query (§5). The format must never
-break it. (`contentid.SeriesIDFromContentID` is the canonical transform.)
-
-### Where the anchor comes from
-
-For tagged libraries the IDs are in the folder/file name
-(`{imdb-tt2413338} {tmdb-228064}`), so both servers derive the same id **from the
-path string at scan time, with no API call**. The denormalized
-`media_items.{tmdb,imdb,tvdb}_id` columns and the `media_item_provider_ids` link
-table are the other sources. `content_id` is *derived from* the link table, not a
-replacement — keep the full provider-ID set indexed.
-
---
-
-## 4. What was built
-
-| Area | File(s) | Summary |
-| ---- | ------- | ------- |
-| Derivation core | `internal/contentid/contentid.go` | `ForMovie`/`ForSeries`/`ForSeason`/`ForEpisode`/`ForLocal`, `SeriesIDFromContentID`, `IsProviderAnchored`/`IsLocal`, `SchemeVersion`, frozen precedence, normalization. |
-| Generation wiring | `internal/metadata/service.go` | `deriveLogicalContentID`/`deriveSeasonContentID`/`deriveEpisodeContentID` replace `idgen.NextID()` at every mint site (skeleton, provider-match, explicit/implicit seasons, episodes, scanner fallback). |
-| Re-ID on match | `internal/metadata/canonicalize.go` | Promotes a `local-` placeholder to its deterministic id at first confirmed match. |
-| Hot query | `internal/catalog/history_source.go` | Watch-history `display_id` resolves the show via the string transform for anchored episodes; skips the `episodes_pkey` probe. |
-| Value-remap migration | `migrations/sql/20260612130000_deterministic_content_id.sql` | Collision-safe Sonyflake → structured remap across the whole reference graph + `COLLATE "C"`, with rollback. |
-| Online re-ID migration | `migrations/sql/20260614120000_content_id_online_reid.sql` | Adds `silo_rename_content_id` + `ON UPDATE CASCADE` to the content-id FK family. |
-
-### Generation: determinism at scan time
-
-The scanner already parses provider tags from names, so `createOrFindSkeleton`
-derives `movie-tmdb-…`/`series-tvdb-…` immediately — two servers seeing the same
-tags mint the same id with no provider API call. This is the primary target
-(Radarr/Sonarr/Plex-tagged libraries). Untagged new items get a path-derived
-`local-` id keyed on the **file path** (not the folder), so distinct pre-merge
-skeletons in a shared folder stay separate while being stable across rescans.
-
-Same-server convergence is preserved by the existing dedup
-(`findExistingByProviderIDs`) plus `UpsertTx`'s
-`ON CONFLICT (content_id) DO UPDATE` backstop.
-
-Non-movie/series items (audiobook/ebook/podcast) and anchorless items **stay on
-Sonyflake** — there's no stable cross-server anchor to derive from, so changing
-them gains nothing.
-
-### Re-ID on match: untagged items converge later
-
-A tagged file is born with the right id; an *untagged* file gets a `local-` id
-and only learns its provider IDs later when the match worker confirms a result. A
-single gate in `mergeAndPersist` (`canonicalizeLocalContentID`) promotes the
-placeholder at first confirmed match:
-
-```text
-SCAN a new file                          ← unchanged, still no network call
-      ▼
-createOrFindSkeleton ──► tag?  YES ► movie-tmdb-123   NO ► local-<hash>
-      ▼
-(later) match worker → mergeAndPersist → canonicalizeLocalContentID
-      │  Is the id still local- AND do we now have provider IDs?
-      │     no  → do nothing
-      │     yes → Does a row already sit at movie-tmdb-123?
-      │              yes → MERGE this row into it (rebindItemToExistingItem)
-      │              no  → RENAME local-<hash> → movie-tmdb-123
-      ▼                      └─ DB auto-moves child rows (ON UPDATE CASCADE)
-rest of mergeAndPersist runs with the corrected id
-```
-
-The guard is a single `IsLocal` prefix check, so tagged content and all refreshes
-pay nothing; the promotion is self-healing (a partial run re-runs on the next
-match). The rename primitive `silo_rename_content_id` reuses the migration's
-catalog-driven column enumeration so the two stay in lockstep.
-`ON UPDATE CASCADE` only fires when a `content_id` actually changes (essentially
-never outside this promotion), so there is no steady-state cost.
-
-### The migration
-
-The column **type does not change** (`text` → `text COLLATE "C"`); the **values**
-are remapped via add-then-swap, not in-place PK mutation. It dynamically
-enumerates the reference graph (the three PKs, every FK child from
-`pg_constraint`, and soft-reference columns by name — **65 columns** on the real
-schema), drops/recreates FKs and triggers, and retains a `content_id_migration_map`
-audit table for rollback.
-
-**Collisions are never merged.** If two items derive to the same key, or a key is
-already taken, those rows keep their Sonyflake id and are flagged `collision` in
-the map — the migration can never violate a PK or silently drop a row. Collision
-status **cascades** from a series to its seasons/episodes (otherwise a uniquely
-numbered episode under a colliding series would get an `episode-…` key whose
-embedded series anchor points at a non-existent row).
-
-`COLLATE "C"` is applied to every referencing column in the same migration so
-join keys match on both type and collation.
-
---
-
-## 5. Why `COLLATE "C"` is mandatory
-
-Provider-derived IDs are pure ASCII, but `content_id` inherits the DB default
-`en_US.utf8` collation. The design **regresses without `COLLATE "C"`**:
-
- For **equality / hash joins** (the watch-history join), `en_US.utf8` is
-  deterministic so PostgreSQL already compares raw bytes — collation is
-  irrelevant.
- For **ordering** comparisons (B-tree descent on PK probes, `ORDER BY`, range
-  scans), `en_US.utf8` invokes libc `strcoll` while `C` is a plain `memcmp`.
- Structured keys share long prefixes (`episode-tvdb-296762-…`), which makes
-  `strcoll` *worse* than on 18-digit Sonyflake strings — so a structured key
-  under `en_US.utf8` is *slower* than the status quo. Under `C` it's ~3–5×
-  faster.
-
-So `COLLATE "C"` is load-bearing, not a free upgrade.
-
-### The hot query
-
-The watch-history page query (`history_source.go`) resolves each history row's
-episode key to its series, then inner-joins `media_items`, deduped over the
-profile's *entire* history. Two facts:
-
- `DISTINCT ON` can't short-circuit on `LIMIT` — cost is **O(history size)** with
-  PK probes per row, not O(page).
- The structured id lets us **delete the `LEFT JOIN episodes`** that existed only
-  to fetch `series_id`: for anchored episode ids the show is a string transform.
-  The join is null-poisoned for anchored ids (`= NULL` is an unsatisfiable b-tree
-  scan key) so the planner never descends `episodes_pkey` for them. Legacy/`local-`
-  ids still fall through the join.
-
-The remaining `JOIN media_items` stays — it's for access/library filtering, not
-the show id. Reducing full-history scans to O(page) for the heaviest profiles is
-follow-up work (a per-`(profile, display_id)` summary table), not part of this
-change.
-
---
-
-## 6. Performance — measured at production scale
-
-Measured on an isolated, prod-tuned PostgreSQL 18 instance (`shared_buffers=4GB`)
-loaded with an **exact-cardinality copy of production**: 184k items, 1.93M
-episodes, 775k watch-history rows / 1,622 profiles. "Before" reproduces
-production today (Sonyflake, `en_US.utf8`); "after" applies the structured-key
-remap + `COLLATE "C"`. **Every metric improves.**
-
-**`content_id` index-probe cost** — 300k forced point lookups over 1.9M keys:
-
-The last three columns are *why* the faster schemes were rejected: speed alone
-isn't the goal — the scheme has to carry the properties the whole feature exists
-for. ✓ = has the property, ✗ = lacks it.
-
-| Key scheme | Index size | µs / probe | vs today | Cross-server deterministic | Zero-join show transform | Human-readable |
-| ---------- | ---------- | ---------- | -------- | :------------------------: | :----------------------: | :------------: |
-| Sonyflake text, `en_US.utf8` *(today)* | 74 MB | 5.05 | 1.00× | ✗ | ✗ | ✗ |
-| 128-bit hash `bytea(16)` | 74 MB | 1.80 | 2.81× | ✓ | ✗ | ✗ |
-| `bigint` surrogate | 41 MB | 1.23 | 4.11× | ✗ | ✗ | ✗ |
-| **Structured + `COLLATE "C"` (this PR)** | 84 MB | **1.86** | **2.71×** | ✓ | ✓ | ✓ |
-
-The structured key lands within 3% of a 128-bit hash and is the **only all-✓
-row**. The two faster schemes each give up something load-bearing:
-
- **128-bit hash** is cross-server deterministic (it hashes the same natural
-  key), but an opaque digest can't be string-transformed, so episode→series
-  needs a catalog join (no zero-join hot path), and it isn't legible in logs,
-  URLs, or `psql`.
- **`bigint` surrogate** is just the status quo's narrow integer: fast because
-  it's 8 bytes, but per-server (not reproducible elsewhere), no embedded anchor
-  to transform, and not meaningful to a human.
-
-Index grows ~14% (84 vs 74 MB), immaterial.
-
-**Real history-page query** — heaviest profile (25,384 rows):
-
-| State | Latency | `episodes_pkey` probes | Speedup |
-| ----- | ------- | ---------------------- | ------- |
-| Before | 385 ms | 25,348 | 1.00× |
-| **This PR** | **150 ms** | **2,775** | **2.57×** |
-
-**Concurrency** (`pgbench`, 150 real profiles): at 100 concurrent users,
-**311 ms / 321 tps → 181 ms / 551 tps** — 1.7× throughput, 42% lower tail
-latency. Comparison cost is pure CPU, so cheaper `COLLATE "C"` comparisons raise
-the throughput ceiling under load.
-
-*Caveat: warmed (dataset fits in `shared_buffers`); the before/after **ratios**
-are the robust result, not absolute tps.*
-
---
-
-## 7. Known limitations / follow-ups
-
- **Untagged series children.** A series that accumulated season/episode rows
-  *before* it matched keeps those children on Sonyflake until a follow-up
-  `recomposeSeriesChildIDs` pass re-derives them. Rare at first match (children
-  usually don't exist yet); not yet wired.
- **Cross-provider reconciliation.** A series tagged tmdb-only on one server and
-  tvdb-only on another still diverges — both paths derive from the denormalized
-  provider columns. Proper fix: consult `media_item_provider_ids` before walking
-  the precedence list.
- **O(history) query shape.** The watch-history `DISTINCT ON` over full history is
-  the real liability at concurrency; the string transform removes a probe but not
-  the full scan. The O(page) summary table is the fix, deferred.
- **Migration at scale.** Runs in one transaction holding `AccessExclusive` locks
-  for the COLLATE rewrite + remap — run off-peak; very large installs (10–50M
-  rows) should use the batched procedure noted in the migration header.
- **`local-` uses the absolute path,** so a same-server remount re-IDs local
-  items. Acceptable for the best-effort local namespace. The hash is 112 bits
-  (`sha256(path)[:14]`) so a `local-` id packs losslessly into a compat UUID
-  (see below).
- **Client-visible id churn.** `jellycompat` encodes `content_id` into the
-  client-facing UUID, so item ids seen by Android/Apple/Jellyfin clients change at
-  migration (caches/resume keyed on item id reset once). **silo-android** and
-  **silo-apple** should be made aware; server-side state is fully remapped. The
-  encoding is *reversible* — a structured or local `content_id` is bit-packed
-  into the UUID (`contentid.Pack`/`Unpack`), not hashed into a lookup table — so
-  a compat item id decodes by pure computation and is stable across server
-  restarts and across instances. Only arbitrary names (genres, studios) and the
-  rare `content_id` too large to pack still use the in-memory hash map.
-
---
-
-## 8. Prior art
-
- **Plex:** logical identity is a provider-namespaced GUID (`plex://movie/…`,
-  `com.plexapp.agents.imdb://tt…`) — exactly this shape. (Its per-server integer
-  `ratingKey` is the non-portable counterexample we avoid.)
- **Jellyfin / Emby:** store namespaced provider IDs and match on them; item GUIDs
-  are deterministic. Same principle — anchor identity on the provider, not a
-  per-server sequence.
-
---
-
-## Appendix — alternatives rejected
-
-Retained so the decision isn't re-litigated:
-
- **Keep Sonyflake.** Non-deterministic per server — the entire problem.
- **Hash provider tuple → `uuid` (128-bit).** Collision resistance is unnecessary
-  (input is already unique), the id becomes opaque, and it forces a `text → uuid`
-  migration across 35 FKs + ~25 soft refs whose failure mode is a seq-scan cliff
-  (miss one column → `uuid = text` per-row cast → index disabled). Pays a large
-  migration cost for an ~8-byte width win that only matters at a 50M-row ceiling.
- **Hash provider tuple → `text` hex.** Opaque like the uuid, large like the
-  natural key — no reason to pick it over the legible structured key.
- **Path or content hash.** A title spans many files at many paths (no single path
-  to hash), and the hash changes on rename — the opposite of the stability
-  requirement. Only appropriate for *file-level* identity.
- **Pack provider + numeric id into `bigint`.** Variable-width provider numbers
-  and S/E packing make the encoding brittle; not worth it over a legible key.
- **File-level deterministic id (`media_files`).** Deferred, not rejected — lower
-  value (no metadata/watch state hangs off it), with open problems (server-local
-  mount anchors, same-file-in-two-libraries). A complement, out of scope here.
@@ -1,49 +0,0 @@
-# Outbound Email (`internal/mail`)
-
-**Status:** Implemented 2026-06-11
-
-Silo's shared outbound email facility. It is deliberately feature-agnostic: any
-feature that sends mail (notification emails, account flows, invites) composes
-a `mail.Message` and hands it to the shared `mail.Sender`, so SMTP
-configuration, security policy, and diagnostics live in exactly one place.
-
-## Abstraction
-
-```go
-type Sender interface {
-    Enabled(ctx context.Context) bool
-    Send(ctx context.Context, msg Message) error
-}
-```
-
-`Message` carries recipients, subject, and text and/or HTML bodies (both set →
-multipart/alternative). `Send` returns `mail.ErrNotConfigured` when email is
-disabled or incomplete, so features treat email as an optional transport and
-degrade gracefully. The SMTP implementation (`mail.NewSMTPSender`) is backed by
-`github.com/wneessen/go-mail`.
-
-## Configuration
-
-Live server settings (no restart required; read on every send — volume is
-low):
-
-| Key | Default | Notes |
-|---|---|---|
-| `email.enabled` | `false` | master switch |
-| `email.smtp_host` | — | required |
-| `email.smtp_port` | `587` | |
-| `email.smtp_security` | `starttls` | `starttls` \| `tls` (implicit, port 465) \| `none` |
-| `email.smtp_username` | — | empty = no auth |
-| `email.smtp_password` | — | encrypted at rest (`SensitiveSettingKeys`) |
-| `email.from_address` | — | required |
-| `email.from_name` | `Silo` | |
-
-Admin UI: Admin Settings → Connections → Email, including a synchronous test
-send (`POST /api/v1/admin/email/test`).
-
-## Adding a consumer
-
-Construct messages in the feature package and send through a `mail.Sender`
-dependency. Do not read `email.*` settings from feature code, and check
-`Enabled` (or branch on `ErrNotConfigured`) rather than treating a missing
-SMTP configuration as an error.
@@ -1,142 +0,0 @@
-# At-rest credential encryption
-
-Silo encrypts third-party integration credentials and other server-owned secrets
-at rest. Sonarr/Radarr API keys, S3 keys, watch-sync OAuth tokens, the
-Audiobookshelf-compat signing key, and the sensitive `server_settings` entries
-are stored as ciphertext in PostgreSQL and decrypted only in memory. The key that
-protects them lives **outside** the database, so a full DB dump or compromise
-does not expose the secrets.
-
-## How it works
-
- **Cipher:** AES-256-GCM with a random 12-byte nonce per value. Implemented in
-  `internal/secret`.
- **Key derivation:** the data key is HKDF-SHA256–derived from the `SECRET_KEY`
-  environment variable with a versioned domain label. `SECRET_KEY` is the
-  encryption root; it is never stored in the database.
- **Envelope:** every ciphertext is stored as `enc:v1:<base64url(nonce‖sealed)>`.
-  The `enc:v1:` prefix is the version marker (see *Key rotation* below).
- **Row binding (AAD):** each ciphertext is GCM-bound to its logical row via
-  additional-authenticated data — `table:column:<pk>` for per-row columns,
-  `server_settings:<key>` for settings. A DB-write attacker therefore cannot move
-  a credential blob from one row/column to another: decrypting under a different
-  binding fails authentication.
- **Read path:** an empty value stays empty; a non-`enc:v1:` value is treated as
-  legacy plaintext and passed through unchanged (so a not-yet-migrated row keeps
-  working); an `enc:v1:` value is decrypted and **any** failure (wrong key,
-  tampering, truncation) is surfaced as an error — it is never silently used as a
-  credential.
-
-## SECRET_KEY
-
-`SECRET_KEY` is **required**. The server refuses to start without it (it fatals
-in `config.LoadBootstrap`), and it must be at least 32 characters.
-
-Generate one with:
-
-```bash
-openssl rand -base64 48
-```
-
-Set it in the deployment environment (or in `.env` for source/dev runs, which
-`godotenv` loads at startup). See `.env.example`.
-
-### Back it up — separately from the database
-
-Treat `SECRET_KEY` like a CA private key:
-
- **Store it outside your database backups.** A DB dump contains only ciphertext;
-  the value of at-rest encryption is entirely lost if the key travels with the
-  dump.
- Keep it in a secrets manager / sealed secret / password manager, not in the
-  repo or in the same bucket as your Postgres backups.
- Rotating the *deployment* (new host, restored DB) requires the **same**
-  `SECRET_KEY`. Restoring a database backup onto a node with a different
-  `SECRET_KEY` makes every encrypted secret unreadable.
-
-### Key loss
-
-If `SECRET_KEY` is lost, the encrypted secrets are **unrecoverable** — that is the
-point of keeping the key out of the database. Recovery means re-entering the
-affected credentials:
-
- Re-enter Sonarr/Radarr and Autoscan API keys, S3 keys, watch-sync connections,
-  history-import tokens, and subtitle provider credentials.
- `auth.jwt_secret` becomes unreadable, so all existing sessions are invalid and
-  users must log in again (a new secret is generated on next boot if the row is
-  cleared — see below).
-
-## Rollout (automatic backfill)
-
-On the first boot after deploying this change, the primary (migration-running)
-node runs an idempotent, best-effort startup backfill that encrypts any
-remaining plaintext in place:
-
-1. sensitive `server_settings` keys,
-2. the per-table credential columns (subtitles, watch-sync, webhook-sync,
-   history-import, including temporary server-list credentials stored in
-   session JSON),
-3. the two arr `api_key_ref` columns — these are **resolved-then-encrypted**: a
-   legacy row that held a `server_settings` reference (e.g.
-   `requests.radarr.api_key`) is collapsed to the real credential before being
-   encrypted.
-
-The backfill is safe to run repeatedly: already-encrypted values are skipped, and
-a per-row guard makes concurrent multi-node boots converge without
-double-encrypting. A failed row is logged and left as plaintext (no new exposure)
-rather than blocking boot. Proxy/transcode nodes skip the backfill; they read
-whatever the primary encrypted. No manual steps are required.
-
-## Rollback / downgrade hazard
-
-Downgrading to a binary that predates this change is **not** safe while secrets
-are encrypted, because the old binary has no read path: it would read
-`enc:v1:auth.jwt_secret` as a literal JWT secret (invalidating all sessions) and
-read `enc:v1:`-prefixed integration keys as garbage credentials.
-
-To downgrade safely you must first return the affected values to plaintext, for
-example:
-
- Decrypt the sensitive `server_settings` back to plaintext (run a one-off that
-  reads each via the encrypting repo and writes the plaintext via the raw repo),
-  **or**
- At minimum, clear `auth.jwt_secret` so the older binary regenerates a fresh
-  plaintext one (this still logs everyone out), and re-enter any integration
-  credentials as plaintext.
-
-There is no automatic "decrypt everything" downgrade path in this release; plan
-downgrades accordingly.
-
-## Key rotation (future)
-
-The `enc:v1:` envelope and the HKDF domain label are versioned. A future rotation
-would introduce `enc:v2:` with a new derived key (and `Decrypt` already dispatches
-on the version, returning an explicit error for an unknown version). Rotation is
-out of scope for this release; the versioning exists so it can be added without a
-data migration of the envelope format.
-
-## Scope and known gaps
-
-Covered: arr (Requests + Autoscan) API keys, S3 keys, all sensitive
-`server_settings`, watch-sync tokens, webhook-sync `access_token`,
-history-import admin/session tokens and temporary server-list credentials,
-subtitle provider `api_key`/`password`,
-the Jellyfin-compat session's bridged Silo access/refresh tokens
-(`jellycompat_sessions.streamapp_access_token` / `streamapp_refresh_token`), and
-the ABS signing key.
-
-Deliberately **not** encrypted (tracked as follow-ups):
-
- **Equality-looked-up secrets** — these are matched by exact value
-  (`WHERE … = $1`), and AES-GCM is randomized, so encrypting them would break the
-  lookup. They need a deterministic **blind-index hash** column instead:
-  `api_keys.api_key`, `webhook_sync_connections.webhook_secret`,
-  `jellycompat_sessions.token`, and `watch_together_rooms.join_token`.
- **Plugin runtime config** — `plugin_runtime_configs.config_value` is opaque
-  plugin-defined JSONB whose secret fields are manifest-declared and whose runtime
-  lives in a separate repo; encrypting it correctly needs a coordinated,
-  manifest-aware design.
-
-Excluded (not a gap): `plex_sync_connections.*` is a dead table (zero Go
-references); `oauth_completion.token_ciphertext` is already AES-GCM;
-`users.password_hash` and the `*_hash` columns are already hashed.
@@ -1,19 +0,0 @@
-# Silo v1 Scope
-
-**Status: NOT LOCKED — proposal window open.**
-
-Propose capabilities with the **v1 capability proposal** issue template; triage happens on the
-[Silo v1 project](https://github.com/orgs/Silo-Server/projects/5).
-
-When the scope locks, this file becomes the source of truth and will contain:
-
-1. **Locked capabilities** — a table of capability epics (issue links) with one-line scope statements.
-2. **API policy** — additive-only within `/api/v1` (no field renames/removals, no type changes,
-   no status-code repurposing; removals only via the Deprecation/Sunset header flow; capability
-   endpoints for feature detection). Contract tooling: #135.
-3. **Amendment rules** — after lock, this file changes only via PR with code-owner review.
-   An amendment PR is the exception process: it must say what changes, why it cannot wait
-   for v1.1, and what it displaces.
-
-Until lock: treat any capability not tracked as `Proposed`/`Locked` on the project as out of scope
-for feature PRs (see the scope gate in `CLAUDE.md`).
@@ -1,98 +0,0 @@
-# Wholphin → jellycompat Endpoint Coverage Report
-
-Date: 2026-06-09
-Scope: every Jellyfin server endpoint the Wholphin Android TV client (jellyfin-sdk-kotlin based) can call, cross-referenced against the routes registered in `internal/jellycompat/router.go`. Wholphin source analyzed from a local clone of `damontecres/Wholphin` (`app/src/main`). Commands assume the repository root is the cwd.
-
-Wholphin's Seerr integration (`/api/v1/...` discover/request endpoints) targets a separate Seerr server, not Jellyfin, and is out of scope here.
-
-## Methodology
-
-1. Grepped Wholphin for every `*Api.method()` SDK call (`itemsApi`, `playStateApi`, etc.), websocket subscriptions, and raw URL construction; mapped each to its HTTP endpoint per the Jellyfin OpenAPI spec.
-2. Inventoried every route registered in `internal/jellycompat/router.go`, including path normalization (`path_normalization.go` handles casing and `/emby`//`jellyfin` prefixes).
-3. For each endpoint Wholphin uses but silo does not serve, checked whether a server-side gate (user policy flag, DTO field) prevents the client from ever calling it.
-
-## Summary
-
- **Covered (full):** 22 endpoint families — everything on the core path: auth, browse, item detail, episodes/next-up, resume, playback info, direct/HLS streaming, subtitles, progress reporting, favorites/played, images, genres, persons, suggestions, media segments (skip intro), display preferences.
- **Covered (partial/stub):** 4 — websocket (keep-alive only, no remote control), `/Studios`, `/Users/Public`, `/QuickConnect/Enabled` (deliberate `false`).
- **Missing but safely gated:** 8 — the client never calls them because we don't advertise the capability (delete, subtitle download, trickplay, local trailers, additional parts, quick connect auth, live TV, playlists).
- **Missing and reachable:** 4 — theme songs, universal audio stream, item download, client log upload. These return 404 when the client calls them. None block video playback.
-
-**Bottom line: the entire core video path is covered.** The reachable gaps are quality-of-life features (theme songs, photo screensaver, debug log upload) plus one advertised-but-broken inconsistency (`CanDownload=true` with no `/Items/{id}/Download` route).
-
-## Coverage matrix
-
-### Fully covered
-
-| Wholphin call | Endpoint | silo handler |
-|---|---|---|
-| `userApi.authenticateUserByName` | `POST /Users/AuthenticateByName` | `handlers_auth.go` |
-| `userApi.getCurrentUser` | `GET /Users/Me` | `handlers_auth.go` |
-| `userApi.getUserById` | `GET /Users/{id}` | `handlers_auth.go` |
-| `systemApi.getPublicSystemInfo` | `GET /System/Info/Public` | `handlers_system.go` |
-| `sessionApi.postCapabilities` | `POST /Sessions/Capabilities` | `handlers_playback.go` |
-| `itemsApi.getItems` | `GET /Items` | `handlers_items.go` |
-| `itemsApi.getResumeItems` | `GET /UserItems/Resume` (+ legacy `/Users/{id}/Items/Resume`) | `handlers_items.go` |
-| `userLibraryApi.getItem` | `GET /Items/{id}` (+ legacy user-scoped form) | `handlers_items.go` |
-| `tvShowsApi.getEpisodes` | `GET /Shows/{id}/Episodes` | `handlers_items.go` |
-| `tvShowsApi.getNextUp` | `GET /Shows/NextUp` | `handlers_items.go` |
-| `suggestionsApi.getSuggestions` | `GET /Items/Suggestions` | `handlers_items.go` |
-| `genresApi.getGenres` | `GET /Genres` | `handlers_items.go` |
-| `personsApi.getPersons` | `GET /Persons` | `handlers_persons.go` (full when PersonRepo is wired; empty stub otherwise) |
-| `searchApi.getSearchHints` | `GET /Search/Hints` | `handlers_items.go` (Wholphin's call is currently commented out upstream) |
-| `mediaInfoApi.getPostedPlaybackInfo` | `POST /Items/{id}/PlaybackInfo` | `handlers_playback.go` |
-| `videosApi.getVideoStreamUrl` | `GET/HEAD /Videos/{id}/stream(.{container})` | `streams.go` |
-| (transcode path from PlaybackInfo) | `GET /Videos/{id}/master.m3u8` + HLS playlist/segments | `streams.go` |
-| (subtitle delivery URLs) | `GET /Videos/{id}/{source}/Subtitles/{idx}/stream.{fmt}` | `streams.go` |
-| `playStateApi.reportPlaybackStart/Progress/Stopped` | `POST /Sessions/Playing[/Progress|/Stopped]` | `streams.go` |
-| `playStateApi.markPlayedItem/markUnplayedItem` | `POST/DELETE /UserPlayedItems/{id}` (+ legacy) | `handlers_userdata.go` |
-| `userLibraryApi.markFavoriteItem/unmarkFavoriteItem` | `POST/DELETE /UserFavoriteItems/{id}` (+ legacy) | `handlers_userdata.go` |
-| `mediaSegmentsApi.getItemSegments` | `GET /MediaSegments/{id}` | `handlers_items.go` (skip intro/credits) |
-| `displayPreferencesApi.updateDisplayPreferences` | `GET/POST /DisplayPreferences/{id}` | `handlers_displayprefs.go` |
-| `imageApi.getItemImageUrl` | `GET /Items/{id}/Images/{type}[/{index}]` | `handlers_images.go` |
-| `imageApi.getUserImageUrl` | `GET /Users/{id}/Images/Primary` | `handlers_images.go` (placeholder avatar) |
-
-### Partial / stub (graceful degradation)
-
-| Endpoint | Status | Client impact |
-|---|---|---|
-| `GET /socket` (websocket) | Accepts upgrade, answers KeepAlive only (`handlers_websocket.go`) | Wholphin subscribes to `GeneralCommandMessage` and `PlaystateMessage` for server-initiated remote control. Connection stays healthy; remote-control commands are simply never delivered. No errors, feature inert. |
-| `GET /Studios` | Empty-array stub | Studio browse rows render empty. |
-| `GET /Users/Public` | Empty-array stub | No user tiles on the login screen; manual login works. |
-| `GET /QuickConnect/Enabled` | Hardcoded `false` | Deliberate: Wholphin hides Quick Connect UI, so the unimplemented `POST /QuickConnect/Authorize` and `POST /Users/AuthenticateWithQuickConnect` are never called. |
-
-### Missing but safely gated (client never calls them)
-
-| Endpoint | Why it's unreachable |
-|---|---|
-| `DELETE /Items/{id}` | We return `CanDelete=false` per item (`mapping.go`) and `EnableContentDeletion=false` in user policy (`handlers_auth.go`), so Wholphin hides delete UI. |
-| `POST /Items/{id}/RemoteSearch/Subtitles/{subtitleId}` | `EnableSubtitleManagement=false` in user policy hides subtitle search/download. |
-| `GET /Videos/{id}/Trickplay/...` | We never emit trickplay metadata on item DTOs, so the scrubber never requests tiles. |
-| `GET /Items/{id}/LocalTrailers` | Wholphin gates on `localTrailerCount > 0` (`TrailerService.kt`); we never set `LocalTrailerCount`. |
-| `GET /Videos/{id}/AdditionalParts` | Gated on `partCount > 1` (`PlaylistCreator.kt`); we never set `PartCount`. |
-| Quick Connect auth endpoints | Gated by `/QuickConnect/Enabled` = false. |
-| Live TV suite (`/LiveTv/Channels`, `/Programs`, `/Recordings`, timers) | We expose no live-TV views or channels, so the feature never activates. |
-| Playlists (`GET/POST/DELETE /Playlists/{id}/Items`) | We expose no playlist items in the catalog, so playlist screens are unreachable. Becomes a real gap the day silo grows playlists. |
-
-### Missing and reachable (return 404 today)
-
-| Endpoint | Wholphin caller | Impact | Severity |
-|---|---|---|---|
-| `GET /Items/{id}/ThemeSongs` | `ThemeSongPlayer.kt` | ~~404 → feature silently dead.~~ **Resolved 2026-06-09:** now stubbed with an empty `ThemeMediaResult` (including the `OwnerId` field jellyfin-sdk-kotlin requires). | Resolved |
-| `GET /Audio/{id}/universal` | `ThemeSongPlayer.kt`, `MusicService.kt` | Audio streaming for theme songs and music playback. No music libraries are exposed today, but this is the second half of the theme-song path and the blocker for any future audio support in jellycompat. | Low (today) |
-| `GET /Items/{id}/Download` | `SlideshowViewModel.kt`, `ScreensaverService.kt` | ~~Inconsistency: `CanDownload=true` while the route 404s.~~ **Resolved 2026-06-09:** a real `/Items/{id}/Download` route now serves the original file (`streams.go`), and `CanDownload=true` again. The earlier `CanDownload=false` workaround broke Infuse, which requires the flag for Direct Play. | Resolved |
-| `POST /ClientLog/Document` | `MediaReportService.kt`, `DebugPage.kt` | "Upload logs to server" debug action fails. | Low |
-| `GET /Audio/{id}/Lyrics` | `NowPlayingViewModel.kt` | Music-only; unreachable until audio libraries exist. | Low |
-
-## Recommendations (priority order)
-
-1. **Merge the repeated-`Fields` fix** (PR #110). `parseItemsQuery` still reads `q.Get("Fields")` (`internal/jellycompat/query.go`), which truncates jellyfin-sdk-kotlin's repeated query params and breaks Wholphin episode auto-advance. This is the only *covered* endpoint with a known correctness bug for this client. Follow up by sweeping the remaining single-value reads (`Ids`, `GenreIds`, `PersonIds`, `Filters`, `SortBy`, `SortOrder`) to `q.Values`, matching how `IncludeItemTypes`/`MediaTypes`/`ImageTypes` are already handled.
-2. ~~Resolve the `CanDownload` inconsistency~~ — **done 2026-06-09**: real `/Items/{id}/Download` route added; `CanDownload` stays `true` (Infuse requires it for Direct Play).
-3. ~~Stub `GET /Items/{id}/ThemeSongs`~~ — **done 2026-06-09**: empty `ThemeMediaResult` stub registered.
-4. **Websocket server-push** (remote control: server-initiated pause/stop, display messages) — tracked in issue #122.
-5. **Optional, later:** `POST /ClientLog/Document` accept-and-discard stub and real `/Studios` data. Playlists, lyrics, and universal audio only matter once silo exposes those content types through jellycompat.
-
-## Notes
-
- Path normalization (`path_normalization.go`) already handles Wholphin's casing and any `/emby`//`jellyfin` prefixes, so none of the covered routes are at risk from URL-shape differences.
- Unmatched jellycompat paths fall through to chi's default 404 with no body; jellyfin-sdk-kotlin surfaces these as `InvalidStatusException`, which Wholphin generally catches per-feature.
@@ -1,82 +0,0 @@
-# PR #124 (ebooks) — Review & Hardening Pass
-
-Date: 2026-06-10
-Scope: full review of the ebook feature branch (`work/ebooks-reader-base`) followed by
-fixes for every finding. Two review rounds were performed (a full-PR review, then an
-adversarial edge-case/security pass over both the original code and the first round of
-fixes), with all changes verified against the full Go test suite, the full web test
-suite, production frontend build, ESLint/Prettier, and `make verify-local-paths`.
-Commands assume the repository root is the cwd.
-
-## Security fixes
-
- **Stored XSS via book content (high):** book sections render in same-origin blob
-  iframes with `allow-scripts` (WebKit requirement). A Content-Security-Policy is now
-  served with all SPA HTML responses (`internal/server/frontend.go`) — blob/srcdoc
-  documents inherit it, so `script-src 'self' 'wasm-unsafe-eval'` blocks script
-  execution from book content on all browsers. Threat model documented on the policy
-  constant. `X-Content-Type-Options: nosniff` added to frontend, jellycompat, and
-  ebook file responses.
- Ebook file serving can no longer fall through to `application/octet-stream` for an
-  admitted file (extension/container whitelist and MIME resolution share one resolver),
-  closing a browser-sniff escape combined with the `?token=` query-auth fallback.
- External links in books are intercepted app-side: http(s) only, opened with
-  `noopener,noreferrer` (blocks reverse tabnabbing and `javascript:` URLs).
- Request size caps (`http.MaxBytesReader`, 413) on progress/config/annotation writes;
-  `Content-Disposition` built with `mime.FormatMediaType` (RFC 5987, no header
-  injection); annotation PATCH is atomic (`SELECT ... FOR UPDATE`) with
-  presence-aware field semantics and invariant re-validation.
- Verified safe under adversarial review: no IDOR (all reader-state SQL scoped to
-  user+profile+content), no path traversal, range serving via stdlib, progress input
-  validation. Accepted residual: CSS-only loads inside book iframes can leak the
-  book's own content but cannot reach tokens, DOM, or navigation.
-
-## Reliability fixes
-
- **Scanner missing-file reconciliation (critical class):** ebook scans now mark
-  missing files like video/audio, with real walk-failure tracking (failed roots are
-  excluded from deletion), symlinked-root support via the shared logical walker, and
-  the empty-root cleanup allowance — an unmounted share can no longer wipe a library.
- **Enrichment:** provider errors record failures (dedicated `ebook_enrichment_state`
-  backoff table, capped retries) instead of permanently stamping items done;
-  unconfigured chains and scan-window races skip without stamping. No longer shares
-  `media_items.refresh_failures` with the metadata refresh-debt system.
- Ebook items are created `pending` and promoted to `matched` on enrichment (backfill
-  migration included), making curated-metadata protection real: matched items keep
-  provider titles/people/series on re-scan (fill-empty only).
- PDF metadata: head+tail window scan (non-linearized PDFs keep the Info dict at the
-  end), delimiter-aware key matching, head-wins merge. `.md` dropped as an ebook
-  format; plain `.fb2` reads capped like `.fbz`.
- FK-cascade indexes added for the reader-state tables.
-
-## Consistency & correctness fixes
-
- Hidden-history (`user_history_hidden_items`) gating applied to every ebook progress
-  surface (watched/in-progress filters, all sort plans, Continue Reading, sort
-  metrics, `Played` state, recommendation signals) with the exact video semantics.
- `GetItemWatchers` counts distinct watchers (no binge inflation) and the
-  `minWatchers` floor counts distinct accounts, not profiles; ebook reading now feeds
-  implicit taste signals and taste-seed candidates; Continue Reading pages past
-  dismissals and dedupes across pages.
- The 0.9 finished threshold is centralized (`models.EbookFinishedProgressThreshold`).
- Reader frontend: open-flow race teardown (no wrong-file progress saves), ordered
-  progress writes with `pagehide`/`visibilitychange` flush, settings no longer
-  clobbered by late server config, TTS stop actually stops, Media Session cleanup,
-  512 MiB download guard, fraction bookmarks navigable.
-
-## Feature completion
-
- Native read-state endpoints: `POST/DELETE /watched/{id}` and `/history/remove`
-  accept ebook content IDs (mark read = progress 1.0 preserving location; mark unread
-  mirrors video unwatch and clears position; history removal hides without losing
-  position). Web UI exposes Mark Read/Unread on the item page and card menus, with
-  Continue Reading dismiss copy and dismissal-path ID encoding fixed.
-
-## Client follow-ups (Android / Apple)
-
- Ebook leaf user data encodes the reading ratio as `position_seconds` (0..1) with
-  `duration_seconds = 1`; do not render absolute times for ebooks.
- `/watched/{id}` returns `{type: "ebook", affected_count: 1, played: bool}` and the
-  existing watched SSE event fires.
- Reading progress is deliberately per-book (cross-format): one position per content
-  ID.
@@ -17,14 +17,14 @@
 | Path | Created/Modified | Purpose |
 |---|---|---|
 | `docs/superpowers/plans/artifacts/2026-05-24-audiobooks-discovery-findings.md` | Create | Findings doc produced by Task 1. Locks the remaining schema/code decisions. |
-| `migrations/147_abs_sessions.up.sql` | Create | New table parallel to `jellycompat_sessions`. |
-| `migrations/147_abs_sessions.down.sql` | Create | Drop the table. |
-| `migrations/157_podcast_feeds.up.sql` | Create | New table for RSS-subscribed podcast metadata. |
-| `migrations/157_podcast_feeds.down.sql` | Create | Drop the table. |
-| `migrations/159_media_folders_kind_noop.up.sql` | Create (conditional — see Task 4 step 1) | Document `media_folders.type='audiobooks'`; no column change needed. |
-| `migrations/159_media_folders_kind_noop.down.sql` | Create (same condition) | No-op rollback. |
-| `migrations/160_audiobooks_feature_flag.up.sql` | Create | Insert `audiobooks.enabled='false'` into `server_settings`. |
-| `migrations/160_audiobooks_feature_flag.down.sql` | Create | Delete the setting row. |
+| `migrations/139_abs_sessions.up.sql` | Create | New table parallel to `jellycompat_sessions`. |
+| `migrations/139_abs_sessions.down.sql` | Create | Drop the table. |
+| `migrations/140_podcast_feeds.up.sql` | Create | New table for RSS-subscribed podcast metadata. |
+| `migrations/140_podcast_feeds.down.sql` | Create | Drop the table. |
+| `migrations/141_media_libraries_kind.up.sql` | Create (conditional — see Task 4 step 1) | Add `kind` column to `media_libraries`. |
+| `migrations/141_media_libraries_kind.down.sql` | Create (same condition) | Drop the column. |
+| `migrations/142_audiobooks_feature_flag.up.sql` | Create | Insert `audiobooks.enabled='false'` into `server_settings`. |
+| `migrations/142_audiobooks_feature_flag.down.sql` | Create | Delete the setting row. |
 | `internal/audiobooks/doc.go` | Create | Package comment + intent. |
 | `internal/audiobooks/service.go` | Create | Empty `Service` struct, `New` constructor, `Enabled()` reader. |
 | `internal/audiobooks/service_test.go` | Create | One unit test proving the package compiles and `Enabled()` returns the setting value. |
@@ -240,15 +240,15 @@ EOF

 ---

-## Task 2: Migration 147 — `abs_sessions`
+## Task 2: Migration 139 — `abs_sessions`

 Parallel of `jellycompat_sessions` for Audiobookshelf clients. Lets ABS
 mobile/desktop apps reconnect without re-authenticating against silo's
 main `auth_sessions`.

 **Files:**
- Create: `migrations/147_abs_sessions.up.sql`
- Create: `migrations/147_abs_sessions.down.sql`
+- Create: `migrations/139_abs_sessions.up.sql`
+- Create: `migrations/139_abs_sessions.down.sql`

 > **Note:** If Task 1, Step 1.2 found the next number is not 139, rename
 > both filenames to match. All other tasks downstream of 139 shift by the
@@ -266,7 +266,7 @@ main `auth_sessions`.

 ### Step 2.2: Create the up migration

- [ ] **Create** `migrations/147_abs_sessions.up.sql` with:
+- [ ] **Create** `migrations/139_abs_sessions.up.sql` with:

  ```sql
  -- Audiobookshelf-compatible client sessions. Parallel to
@@ -277,7 +277,7 @@ main `auth_sessions`.
  CREATE TABLE IF NOT EXISTS public.abs_sessions (
      id           BIGSERIAL PRIMARY KEY,
      user_id      INTEGER NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
-      token_hash   TEXT NOT NULL,
+      token        TEXT NOT NULL,
      device_id    TEXT NOT NULL,
      device_name  TEXT,
      client_name  TEXT,
@@ -287,8 +287,8 @@ main `auth_sessions`.
      revoked_at   TIMESTAMP WITH TIME ZONE
  );

-  CREATE UNIQUE INDEX IF NOT EXISTS idx_abs_sessions_token_hash
-      ON public.abs_sessions (token_hash);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_abs_sessions_token
+      ON public.abs_sessions (token);

  CREATE INDEX IF NOT EXISTS idx_abs_sessions_user_device
      ON public.abs_sessions (user_id, device_id);
@@ -299,12 +299,12 @@ main `auth_sessions`.

 ### Step 2.3: Create the down migration

- [ ] **Create** `migrations/147_abs_sessions.down.sql` with:
+- [ ] **Create** `migrations/139_abs_sessions.down.sql` with:

  ```sql
  DROP INDEX IF EXISTS public.idx_abs_sessions_last_seen;
  DROP INDEX IF EXISTS public.idx_abs_sessions_user_device;
-  DROP INDEX IF EXISTS public.idx_abs_sessions_token_hash;
+  DROP INDEX IF EXISTS public.idx_abs_sessions_token;
  DROP TABLE IF EXISTS public.abs_sessions;
  ```

@@ -328,27 +328,27 @@ main `auth_sessions`.
 - [ ] **Run** (each command should now succeed):
  ```bash
  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "\d public.abs_sessions"
-  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "SELECT version FROM schema_versions WHERE version = 147;"
+  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "SELECT version FROM schema_versions WHERE version = 139;"
  ```
-  Expected: `\d` prints the full column list; the `SELECT` returns one row with `version=147`.
+  Expected: `\d` prints the full column list; the `SELECT` returns one row with `version=139`.

 - [ ] **Run** a sample insert/delete to prove constraints work:
  ```bash
  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "
-  INSERT INTO abs_sessions (user_id, token_hash, device_id, device_name, client_name, client_version)
-  VALUES ((SELECT id FROM users ORDER BY id LIMIT 1), 'test-token-hash-001', 'test-device-001', 'Test Device', 'AbsTestClient', '1.0.0');
-  DELETE FROM abs_sessions WHERE token_hash = 'test-token-hash-001';
+  INSERT INTO abs_sessions (user_id, token, device_id, device_name, client_name, client_version)
+  VALUES (1, 'test-token-001', 'test-device-001', 'Test Device', 'AbsTestClient', '1.0.0');
+  DELETE FROM abs_sessions WHERE token = 'test-token-001';
  "
  ```
-  Expected: `INSERT 0 1` then `DELETE 1`. (At least one user must exist.)
+  Expected: `INSERT 0 1` then `DELETE 1`. (User id 1 must exist — silo's first user.)

 ### Step 2.6: Commit

 - [ ] **Run:**
  ```bash
-  git add migrations/147_abs_sessions.up.sql migrations/147_abs_sessions.down.sql
+  git add migrations/139_abs_sessions.up.sql migrations/139_abs_sessions.down.sql
  git commit -m "$(cat <<'EOF'
-feat(audiobooks): migration 147 add abs_sessions table
+feat(audiobooks): migration 139 add abs_sessions table

 Parallel of jellycompat_sessions for Audiobookshelf-compatible clients.
 Lets ABS mobile/desktop apps maintain a device-bound session that
@@ -361,15 +361,15 @@ EOF

 ---

-## Task 3: Migration 157 — `podcast_feeds`
+## Task 3: Migration 140 — `podcast_feeds`

 One row per subscribed podcast. The podcast itself lives in `media_items`
 (`type='podcast'`); this side table carries the RSS-specific metadata the
 feed refresher needs.

 **Files:**
- Create: `migrations/157_podcast_feeds.up.sql`
- Create: `migrations/157_podcast_feeds.down.sql`
+- Create: `migrations/140_podcast_feeds.up.sql`
+- Create: `migrations/140_podcast_feeds.down.sql`

 ### Step 3.1: Write the failing assertion

@@ -381,7 +381,7 @@ feed refresher needs.

 ### Step 3.2: Create the up migration

- [ ] **Create** `migrations/157_podcast_feeds.up.sql` with:
+- [ ] **Create** `migrations/140_podcast_feeds.up.sql` with:

  ```sql
  -- RSS-feed metadata for subscribed podcasts. One row per podcast
@@ -416,7 +416,7 @@ feed refresher needs.

 ### Step 3.3: Create the down migration

- [ ] **Create** `migrations/157_podcast_feeds.down.sql` with:
+- [ ] **Create** `migrations/140_podcast_feeds.down.sql` with:

  ```sql
  DROP INDEX IF EXISTS public.idx_podcast_feeds_due_for_refresh;
@@ -438,17 +438,17 @@ feed refresher needs.
 - [ ] **Run:**
  ```bash
  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "\d public.podcast_feeds"
-  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "SELECT version FROM schema_versions WHERE version = 157;"
+  sudo docker exec silo-prod-postgres-1 psql -U silo -d silo -c "SELECT version FROM schema_versions WHERE version = 140;"
  ```
-  Expected: column list printed; one row with `version=157`.
+  Expected: column list printed; one row with `version=140`.

 ### Step 3.6: Commit

 - [ ] **Run:**
  ```bash
-  git add migrations/157_podcast_feeds.up.sql migrations/157_podcast_feeds.down.sql
+  git add migrations/140_podcast_feeds.up.sql migrations/140_podcast_feeds.down.sql
  git commit -m "$(cat <<'EOF'
-feat(audiobooks): migration 157 add podcast_feeds table
+feat(audiobooks): migration 140 add podcast_feeds table

 Side table on media_items for RSS-subscribed podcasts. Holds feed URL,
 ETag/Last-Modified for conditional fetches, last-refresh timestamp, and
@@ -462,7 +462,7 @@ EOF

 ---

-## Task 4: Migration 159 — `media_libraries.kind` audiobook value (no-op)
+## Task 4: Migration 141 — `media_libraries.kind` (conditional)

 Adds a discriminator column so the scanner can branch on
 `audiobooks`/`podcasts` libraries without filename heuristics.
@@ -474,8 +474,8 @@ Adds a discriminator column so the scanner can branch on
 > Otherwise, proceed with the steps below.

 **Files:**
- Create: `migrations/159_media_folders_kind_noop.up.sql`
- Create: `migrations/159_media_folders_kind_noop.down.sql`
+- Create: `migrations/141_media_libraries_kind.up.sql`
+- Create: `migrations/141_media_libraries_kind.down.sql`

 ### Step 4.1: Write the failing assertion

@@ -487,7 +487,7 @@ Adds a discriminator column so the scanner can branch on

 ### Step 4.2: Create the up migration

- [ ] **Create** `migrations/159_media_folders_kind_noop.up.sql` with:
+- [ ] **Create** `migrations/141_media_libraries_kind.up.sql` with:

  ```sql
  -- Per-library content discriminator. Lets the scanner choose the right
@@ -509,7 +509,7 @@ Adds a discriminator column so the scanner can branch on

 ### Step 4.3: Create the down migration

- [ ] **Create** `migrations/159_media_folders_kind_noop.down.sql` with:
+- [ ] **Create** `migrations/141_media_libraries_kind.down.sql` with:

  ```sql
  DROP INDEX IF EXISTS public.idx_media_libraries_kind;
@@ -551,9 +551,9 @@ Adds a discriminator column so the scanner can branch on

 - [ ] **Run:**
  ```bash
-  git add migrations/159_media_folders_kind_noop.up.sql migrations/159_media_folders_kind_noop.down.sql
+  git add migrations/141_media_libraries_kind.up.sql migrations/141_media_libraries_kind.down.sql
  git commit -m "$(cat <<'EOF'
-feat(audiobooks): migration 159 document audiobooks media folder type
+feat(audiobooks): migration 141 add media_libraries.kind

 Per-library discriminator that lets the scanner pick the right parser
 ('movies', 'tv', 'audiobooks', 'podcasts') instead of inferring from
@@ -567,15 +567,15 @@ EOF

 ---

-## Task 5: Migration 160 — `audiobooks.enabled` feature flag
+## Task 5: Migration 142 — `audiobooks.enabled` feature flag

 Adds a `server_settings` row so subsequent sub-plans can branch on
 "audiobooks compiled in but turned off" vs "fully live". Default is
 `false` so this sub-plan's landing is a strict no-op for users.

 **Files:**
- Create: `migrations/160_audiobooks_feature_flag.up.sql`
- Create: `migrations/160_audiobooks_feature_flag.down.sql`
+- Create: `migrations/142_audiobooks_feature_flag.up.sql`
+- Create: `migrations/142_audiobooks_feature_flag.down.sql`

 ### Step 5.1: Write the failing assertion

@@ -589,11 +589,11 @@ Adds a `server_settings` row so subsequent sub-plans can branch on

 ### Step 5.2: Create the up migration

- [ ] **Create** `migrations/160_audiobooks_feature_flag.up.sql` with:
+- [ ] **Create** `migrations/142_audiobooks_feature_flag.up.sql` with:

  ```sql
  -- Master kill-switch for the absorbed audiobooks feature. Defaults to
-  -- 'false' so landing migrations 147/157/159/160 is a no-op for users; operators
+  -- 'false' so landing migrations 139-142 is a no-op for users; operators
  -- flip this to 'true' at cutover.

  INSERT INTO server_settings (key, value) VALUES ('audiobooks.enabled', 'false')
@@ -602,7 +602,7 @@ Adds a `server_settings` row so subsequent sub-plans can branch on

 ### Step 5.3: Create the down migration

- [ ] **Create** `migrations/160_audiobooks_feature_flag.down.sql` with:
+- [ ] **Create** `migrations/142_audiobooks_feature_flag.down.sql` with:

  ```sql
  DELETE FROM server_settings WHERE key = 'audiobooks.enabled';
@@ -625,9 +625,9 @@ Adds a `server_settings` row so subsequent sub-plans can branch on

 - [ ] **Run:**
  ```bash
-  git add migrations/160_audiobooks_feature_flag.up.sql migrations/160_audiobooks_feature_flag.down.sql
+  git add migrations/142_audiobooks_feature_flag.up.sql migrations/142_audiobooks_feature_flag.down.sql
  git commit -m "$(cat <<'EOF'
-feat(audiobooks): migration 160 add audiobooks.enabled flag
+feat(audiobooks): migration 142 add audiobooks.enabled flag

 Server-settings row that gates the absorbed audiobooks feature.
 Defaults to 'false' so sub-plan 1 lands as a strict no-op; subsequent
@@ -646,7 +646,7 @@ EOF
 Creates an empty but compiling Go package, wires its constructor into
 `cmd/silo/main.go` so the package is referenced from the binary, and
 ships a unit test that proves the `Enabled()` reader returns the flag
-value seeded by migration 160.
+value seeded by migration 142.

 This task proves the package compiles inside the rest of silo without
 changing any runtime behavior. No routes are mounted. No scheduled
@@ -721,7 +721,7 @@ tasks are registered. No DB writes happen.

 ### Step 6.2: Run the test to verify it fails

- [ ] **Run:** `go test ./internal/audiobooks/...`
+- [ ] **Run:** `cd /opt/silo-server && go test ./internal/audiobooks/...`

  Expected: build failure with messages like `undefined: New` and
  `package audiobooks not found`.
@@ -777,9 +777,9 @@ tasks are registered. No DB writes happen.
  	return &Service{settings: settings}
  }

-  // Enabled reports whether the audiobooks feature flag (set by
-  // 160_audiobooks_feature_flag and toggled by operators) is currently true.
-  // Any value other than the literal string "true" reads as false; this matches how silo
+  // Enabled reports whether the audiobooks feature flag (set by migration
+  // 142 and toggled by operators) is currently true. Any value other than
+  // the literal string "true" reads as false; this matches how silo
  // treats other boolean server_settings rows.
  func (s *Service) Enabled(ctx context.Context) (bool, error) {
  	if s == nil || s.settings == nil {
@@ -795,7 +795,7 @@ tasks are registered. No DB writes happen.

 ### Step 6.5: Run the test to verify it passes

- [ ] **Run:** `go test ./internal/audiobooks/...`
+- [ ] **Run:** `cd /opt/silo-server && go test ./internal/audiobooks/...`
  Expected: `ok  github.com/Silo-Server/silo-server/internal/audiobooks ...`

 ### Step 6.6: Wire the constructor into `cmd/silo/main.go`
@@ -831,13 +831,13 @@ are constructed and pass a settings store to.

 ### Step 6.7: Verify everything still compiles and tests pass

- [ ] **Run:** `go build ./...`
+- [ ] **Run:** `cd /opt/silo-server && go build ./...`
  Expected: exit 0, no output.

- [ ] **Run:** `go test ./internal/audiobooks/... ./cmd/...`
+- [ ] **Run:** `cd /opt/silo-server && go test ./internal/audiobooks/... ./cmd/...`
  Expected: all passes.

- [ ] **Run:** `make lint`
+- [ ] **Run:** `cd /opt/silo-server && make lint`
  Expected: no new lint findings introduced by this task.

 ### Step 6.8: Smoke-test the running binary
@@ -883,9 +883,9 @@ EOF
 | Spec section | Task(s) that cover it |
 |---|---|
 | Data model: reused tables | Task 1 (verification only) |
-| Data model: `abs_sessions` (migration 147) | Task 2 |
-| Data model: `podcast_feeds` (migration 157) | Task 3 |
-| Data model: `media_folders.type` audiobook value (migration 159 no-op) | Task 4 |
+| Data model: `abs_sessions` (mig 134→139) | Task 2 |
+| Data model: `podcast_feeds` (mig 135→140) | Task 3 |
+| Data model: `media_libraries.kind` (mig 136→141) | Task 4 |
 | Data model: data migration = none | n/a — confirmed in spec |
 | Feature flag (`audiobooks.enabled`) | Task 5 |
 | Architecture: `internal/audiobooks/` package | Task 6 |
@@ -909,8 +909,9 @@ fires).
 test matches the production interface defined in `service.go`. Method
 name `GetString`, signature `(ctx context.Context, key string) (string, error)` — consistent across both files.

-**Note on migration numbering:** Tasks 2–5 originally used numbers `139..142`
-based on a snapshot showing `138_search_number_word_normalization.up.sql` as
-the highest existing migration. The landed implementation was renumbered to
-`147_abs_sessions`, `157_podcast_feeds`, `159_media_folders_kind_noop`, and
-`160_audiobooks_feature_flag`.
+**Note on migration numbering:** Tasks 2–5 use numbers `139..142` based
+on a snapshot showing `138_search_number_word_normalization.up.sql` as
+the highest existing migration. Task 1 Step 1.2 re-verifies this; if
+the executing agent finds the highest existing number has moved, it
+must shift filenames in Tasks 2–5 by the same delta and update the
+matching task headings and commit-message references.
@@ -2,9 +2,9 @@

 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

-**Goal:** Make silo's existing scanner recognize audiobook + podcast libraries (`media_folders.type='audiobooks'` or `'podcasts'`), walk them to find audio files, and write `media_items.type='audiobook'` / `media_items.type='podcast'` rows with chapter metadata and author/narrator role links. No external metadata enrichment runs in this sub-plan; the scanner extracts local tags and identity hints, and the audiobook metadata plugin/provider enriches canonical metadata later.
+**Goal:** Make silo's existing scanner recognize audiobook + podcast libraries (`media_folders.type='audiobooks'` or `'podcasts'`), walk them to find audio files, and write `media_items.type='audiobook'` / `media_items.type='podcast'` rows with chapter metadata and author/narrator role links. No external metadata enrichment in this sub-plan — file tags only.

-**Architecture:** New constants (`PersonKindAuthor=7`, `PersonKindNarrator=8`, `audioExtensions`). New helpers (`isAudiobookLibraryType`, `isPodcastLibraryType`, `SupportsAudioFile`). New parser file `internal/scanner/audiobook.go` for the folder-to-media-items mapping. The chapter extraction reuses the existing `probe.go` ffprobe helper. Author/narrator names are upserted into the existing `people` and `item_people` tables via the same code paths used for movie actors. Matching/enrichment queue integration for the audiobook metadata plugin/provider is deferred.
+**Architecture:** New constants (`PersonKindAuthor=7`, `PersonKindNarrator=8`, `audioExtensions`). New helpers (`isAudiobookLibraryType`, `isPodcastLibraryType`, `SupportsAudioFile`). New parser file `internal/scanner/audiobook.go` for the folder-to-media-items mapping. The chapter extraction reuses the existing `probe.go` ffprobe helper. Author/narrator names are upserted into the existing `people` and `item_people` tables via the same code paths used for movie actors. No changes to the matching/enrichment metadata queues — those are deferred.

 **Tech Stack:** Go 1.26 + pgx; ffprobe via `os/exec` (already vendored as `internal/scanner/probe.go`); ID3/MP4 tag parsing — verify what silo already vendors before introducing a new library (acceptable: `github.com/dhowden/tag` if not already present, OR shell out to ffprobe which exposes tag dictionaries).

@@ -408,8 +408,8 @@ ffmpeg -y -f lavfi -i "anullsrc=r=22050:cl=mono" -t 10 -metadata title="Test Aud
  -metadata artist="Test Author" -metadata album="Test Series" \
  -metadata:s:a:0 language=eng \
  internal/scanner/testdata/audiobook_fixtures/single_book/raw.m4a
-# Add chapters via a repo-local metadata fixture
-cat > internal/scanner/testdata/audiobook_fixtures/single_book/chapters.ffmeta <<'EOF'
+# Add chapters via a temporary metadata file
+cat > /tmp/chapters.ffmeta <<'EOF'
 ;FFMETADATA1
 [CHAPTER]
 TIMEBASE=1/1000
@@ -423,9 +423,9 @@ END=10000
 title=Outro
 EOF
 ffmpeg -y -i internal/scanner/testdata/audiobook_fixtures/single_book/raw.m4a \
-  -i internal/scanner/testdata/audiobook_fixtures/single_book/chapters.ffmeta -map_metadata 1 -codec copy \
+  -i /tmp/chapters.ffmeta -map_metadata 1 -codec copy \
  internal/scanner/testdata/audiobook_fixtures/single_book/book.m4b
-rm internal/scanner/testdata/audiobook_fixtures/single_book/raw.m4a internal/scanner/testdata/audiobook_fixtures/single_book/chapters.ffmeta
+rm internal/scanner/testdata/audiobook_fixtures/single_book/raw.m4a /tmp/chapters.ffmeta
 ```

 Add a test that calls the chapter-extraction function on `book.m4b` and asserts:
@@ -1008,6 +1008,7 @@ Verify the full sub-plan landed cleanly.
 ### Step 10.1: Full tests + build

 ```bash
+cd /opt/silo-server
 go build ./...
 go test ./internal/scanner/... ./internal/models/... ./internal/audiobooks/...
 go vet ./...
@@ -1018,7 +1019,7 @@ All green.
 ### Step 10.2: Rebuild + recreate silo container

 ```bash
-sudo docker build -t silo:latest .
+sudo docker build -t silo:latest /opt/silo-server
 sudo docker compose -p silo-prod up -d --force-recreate silo
 until [ "$(sudo docker inspect -f '{{.State.Health.Status}}' silo-prod-silo-1 2>/dev/null)" = "healthy" ]; do sleep 2; done; echo healthy
 ```
@@ -1064,7 +1065,7 @@ Otherwise: no commit needed.
 | Multi-file audiobooks | T7 |
 | Filesystem podcasts | T9 |
 | RSS podcasts | deferred to sub-plan 5 |
-| External enrichment through audiobook metadata plugin/provider | deferred per spec |
+| External enrichment (OpenLibrary/Google Books) | dropped per spec |

 **Placeholder scan:** Task 8 has language like "grep for upsertMediaItem or similar in scanner.go to find it" — this is intentional. The scanner's write helpers are too deeply embedded for me to enumerate without reading more code; the implementer subagent will discover them. If a subagent reports BLOCKED on Task 8 because the write helpers aren't shaped how this plan assumes, the controller dispatches a discovery sub-task.

@@ -2,12 +2,12 @@

 **Goal:** Port the plugin's `podcastfeed` package as a first-party scheduled task in silo, so RSS-subscribed podcasts get their episode lists kept up to date.

-**Source plugin:** `../silo-plugin-audiobooks/internal/podcastfeed/refresher.go` (353 LOC) + `refresher_test.go` (295 LOC)
+**Source plugin:** `/opt/silo_plugins/silo-plugin-audiobooks/internal/podcastfeed/refresher.go` (353 LOC) + `refresher_test.go` (295 LOC)

 ## Tasks

 ### Task 1: Port the refresher package
- Copy `refresher.go` + `refresher_test.go` from plugin to `internal/audiobooks/podcastfeed/`
+- Copy `refresher.go` + `refresher_test.go` from plugin to `/opt/silo-server/internal/audiobooks/podcastfeed/`
 - Update imports (drop plugin SDK; use silo's `pgxpool` + `log/slog`)
 - Rewrite SQL queries against silo's `podcast_feeds` table (created in sub-plan 1 migration 140), `media_items` (type='podcast'), and `episodes`
 - Drop the plugin's `presentation_libraries` reference; subscriptions are tracked by `podcast_feeds.media_item_id`
@@ -1,724 +0,0 @@
-# Resilient Library Deletion Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Rewrite `delete_library` so it deletes a library in small, autocommitted, deadlock-retrying batches instead of one multi-minute transaction that deadlocks and rolls back on large libraries.
-
-**Architecture:** `FolderRepository.DeleteWithStats` becomes a phased, batched operation (orphan items → folder media_files → remaining shared junctions → folder row). Each batch is one autocommit statement wrapped in a `retryOnDeadlock` helper, so locks are held briefly and the job is resumable. Two small helpers (`retryOnDeadlock`, `deleteInBatches`) are unit-tested in pure Go; the full path is verified against the live dev database.
-
-**Tech Stack:** Go, pgx v5 (`pgxpool`, `pgconn`), PostgreSQL. Spec: `docs/superpowers/specs/2026-05-28-library-delete-resilience-design.md`.
-
-All commands assume the repository root is the cwd.
-
---
-
-## File Structure
-
- **Modify** `internal/catalog/folder_repo.go`
-  - Add constants `orphanDeleteBatch`, `folderChildDeleteBatch`.
-  - Add package vars `deadlockMaxAttempts`, `deadlockBaseBackoff` and func `retryOnDeadlock`.
-  - Add func `deleteInBatches`.
-  - Add interface `rowQuerier`; change `collectImageDirs` and `filterUnreferencedImageDirs` to take `rowQuerier` instead of `pgx.Tx`; extract `collectRawImageDirs`.
-  - Rewrite `DeleteWithStats`; add helpers `collectOrphanBatch`, `dirSetToSlice`.
-  - Leave `collectOrphanIDs` and `Delete` unchanged.
- **Create** `internal/catalog/folder_delete_test.go` — pure-Go unit tests for `retryOnDeadlock` and `deleteInBatches`.
- **Do not modify** `internal/catalog/library_repo.go` — its `collectImageDirs`/`collectOrphanIDs` calls keep compiling because `pgx.Tx` satisfies `rowQuerier`. (Verified by build.)
- **Unchanged behavior** in `internal/adminjob/library_delete.go` (executor), `internal/adminjob/runner.go` (heartbeat).
-
---
-
-## Task 1: Deadlock-retry helper
-
-**Files:**
- Modify: `internal/catalog/folder_repo.go`
- Test: `internal/catalog/folder_delete_test.go` (create)
-
- [ ] **Step 1: Write the failing tests**
-
-Create `internal/catalog/folder_delete_test.go`:
-
-```go
-package catalog
-
-import (
-	"context"
-	"errors"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgconn"
-)
-
-// withFastDeadlockRetry shrinks retry timing/attempts for tests and restores
-// the originals on cleanup. Tests using it must not call t.Parallel().
-func withFastDeadlockRetry(t *testing.T, maxAttempts int) {
-	t.Helper()
-	oldMax, oldBackoff := deadlockMaxAttempts, deadlockBaseBackoff
-	deadlockMaxAttempts = maxAttempts
-	deadlockBaseBackoff = time.Millisecond
-	t.Cleanup(func() {
-		deadlockMaxAttempts = oldMax
-		deadlockBaseBackoff = oldBackoff
-	})
-}
-
-func TestRetryOnDeadlockRetriesThenSucceeds(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	calls := 0
-	err := retryOnDeadlock(context.Background(), func() error {
-		calls++
-		if calls < 3 {
-			return &pgconn.PgError{Code: "40P01"}
-		}
-		return nil
-	})
-	if err != nil {
-		t.Fatalf("expected success, got %v", err)
-	}
-	if calls != 3 {
-		t.Fatalf("expected 3 calls, got %d", calls)
-	}
-}
-
-func TestRetryOnDeadlockReturnsNonRetryableImmediately(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	sentinel := errors.New("boom")
-	calls := 0
-	err := retryOnDeadlock(context.Background(), func() error {
-		calls++
-		return sentinel
-	})
-	if !errors.Is(err, sentinel) {
-		t.Fatalf("expected sentinel, got %v", err)
-	}
-	if calls != 1 {
-		t.Fatalf("expected 1 call, got %d", calls)
-	}
-}
-
-func TestRetryOnDeadlockGivesUpAfterMaxAttempts(t *testing.T) {
-	withFastDeadlockRetry(t, 4)
-	calls := 0
-	err := retryOnDeadlock(context.Background(), func() error {
-		calls++
-		return &pgconn.PgError{Code: "40P01"}
-	})
-	var pgErr *pgconn.PgError
-	if !errors.As(err, &pgErr) || pgErr.Code != "40P01" {
-		t.Fatalf("expected 40P01 pg error, got %v", err)
-	}
-	if calls != 4 {
-		t.Fatalf("expected 4 calls, got %d", calls)
-	}
-}
-
-func TestRetryOnDeadlockStopsOnCanceledContext(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-	calls := 0
-	err := retryOnDeadlock(ctx, func() error {
-		calls++
-		return &pgconn.PgError{Code: "40P01"}
-	})
-	if !errors.Is(err, context.Canceled) {
-		t.Fatalf("expected context.Canceled, got %v", err)
-	}
-	if calls != 1 {
-		t.Fatalf("expected 1 call before cancel, got %d", calls)
-	}
-}
-```
-
- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `go test ./internal/catalog/ -run TestRetryOnDeadlock -v`
-Expected: compile failure / FAIL — `undefined: retryOnDeadlock`, `deadlockMaxAttempts`, `deadlockBaseBackoff`.
-
- [ ] **Step 3: Implement the helper**
-
-In `internal/catalog/folder_repo.go`, add near the top of the file (after the `import` block, before the sentinel errors var is fine):
-
-```go
-// Retry parameters for transient serialization/deadlock failures. They are
-// package vars (not consts) only so tests can shrink them; production code
-// never mutates them.
-var (
-	deadlockMaxAttempts = 5
-	deadlockBaseBackoff = 50 * time.Millisecond
-)
-
-// retryOnDeadlock runs op, retrying when Postgres reports a deadlock (40P01) or
-// serialization failure (40001), with exponential backoff. It returns
-// immediately for any other error, and honors context cancellation between
-// attempts.
-func retryOnDeadlock(ctx context.Context, op func() error) error {
-	backoff := deadlockBaseBackoff
-	for attempt := 1; ; attempt++ {
-		err := op()
-		if err == nil {
-			return nil
-		}
-		var pgErr *pgconn.PgError
-		if attempt < deadlockMaxAttempts && errors.As(err, &pgErr) &&
-			(pgErr.Code == "40P01" || pgErr.Code == "40001") {
-			select {
-			case <-ctx.Done():
-				return ctx.Err()
-			case <-time.After(backoff):
-			}
-			backoff *= 2
-			continue
-		}
-		return err
-	}
-}
-```
-
-(`context`, `errors`, `time`, and `github.com/jackc/pgx/v5/pgconn` are already imported in this file.)
-
- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `go test ./internal/catalog/ -run TestRetryOnDeadlock -v`
-Expected: PASS (4 tests).
-
- [ ] **Step 5: Format and commit**
-
-```bash
-gofmt -w internal/catalog/folder_repo.go internal/catalog/folder_delete_test.go
-git add internal/catalog/folder_repo.go internal/catalog/folder_delete_test.go
-git commit -m "feat(catalog): add deadlock-retry helper for batched deletes"
-```
-
---
-
-## Task 2: Batched-delete loop helper
-
-**Files:**
- Modify: `internal/catalog/folder_repo.go`
- Test: `internal/catalog/folder_delete_test.go`
-
- [ ] **Step 1: Write the failing tests**
-
-Append to `internal/catalog/folder_delete_test.go`:
-
-```go
-func TestDeleteInBatchesLoopsUntilUnderBatchSize(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	counts := []int64{5, 5, 2}
-	idx := 0
-	total, err := deleteInBatches(context.Background(), 5, func(context.Context) (int64, error) {
-		n := counts[idx]
-		idx++
-		return n, nil
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if total != 12 {
-		t.Fatalf("expected total 12, got %d", total)
-	}
-	if idx != 3 {
-		t.Fatalf("expected 3 batches, got %d", idx)
-	}
-}
-
-func TestDeleteInBatchesStopsImmediatelyWhenFirstBatchUnderSize(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	calls := 0
-	total, err := deleteInBatches(context.Background(), 5, func(context.Context) (int64, error) {
-		calls++
-		return 0, nil
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if total != 0 || calls != 1 {
-		t.Fatalf("expected total 0 and 1 call, got total=%d calls=%d", total, calls)
-	}
-}
-
-func TestDeleteInBatchesReturnsError(t *testing.T) {
-	withFastDeadlockRetry(t, 5)
-	sentinel := errors.New("delete failed")
-	_, err := deleteInBatches(context.Background(), 5, func(context.Context) (int64, error) {
-		return 0, sentinel
-	})
-	if !errors.Is(err, sentinel) {
-		t.Fatalf("expected sentinel, got %v", err)
-	}
-}
-```
-
- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `go test ./internal/catalog/ -run TestDeleteInBatches -v`
-Expected: FAIL — `undefined: deleteInBatches`.
-
- [ ] **Step 3: Implement the helper**
-
-In `internal/catalog/folder_repo.go`, add after `retryOnDeadlock`:
-
-```go
-// deleteInBatches repeatedly runs deleteBatch (each a single autocommit
-// statement) until a batch removes fewer than batchSize rows. Each batch is
-// retried on deadlock. It returns the total number of rows deleted.
-func deleteInBatches(
-	ctx context.Context,
-	batchSize int,
-	deleteBatch func(ctx context.Context) (int64, error),
-) (int64, error) {
-	var total int64
-	for {
-		var affected int64
-		if err := retryOnDeadlock(ctx, func() error {
-			n, e := deleteBatch(ctx)
-			affected = n
-			return e
-		}); err != nil {
-			return total, err
-		}
-		total += affected
-		if affected < int64(batchSize) {
-			return total, nil
-		}
-	}
-}
-```
-
- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `go test ./internal/catalog/ -run TestDeleteInBatches -v`
-Expected: PASS (3 tests).
-
- [ ] **Step 5: Format and commit**
-
-```bash
-gofmt -w internal/catalog/folder_repo.go internal/catalog/folder_delete_test.go
-git add internal/catalog/folder_repo.go internal/catalog/folder_delete_test.go
-git commit -m "feat(catalog): add deleteInBatches loop helper"
-```
-
---
-
-## Task 3: Generalize image-dir helpers to a querier interface
-
-This lets the image-dir helpers run on either a `*pgxpool.Pool` (new batched path) or a `pgx.Tx` (existing `library_repo.go` path), and splits raw collection from filtering so the batched path can collect cheaply per batch and filter once.
-
-**Files:**
- Modify: `internal/catalog/folder_repo.go:547-635` (the `collectImageDirs` / `filterUnreferencedImageDirs` block)
-
- [ ] **Step 1: Add the `rowQuerier` interface**
-
-In `internal/catalog/folder_repo.go`, add (near the other type declarations, e.g. just above `collectOrphanIDs`):
-
-```go
-// rowQuerier is satisfied by both *pgxpool.Pool and pgx.Tx, letting read
-// helpers run inside or outside an explicit transaction.
-type rowQuerier interface {
-	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
-}
-```
-
- [ ] **Step 2: Split `collectImageDirs` into raw collection + filtering**
-
-Replace the existing `collectImageDirs` function (currently `internal/catalog/folder_repo.go:549-584`) with these two functions:
-
-```go
-// collectImageDirs returns S3 directory prefixes for images belonging to the
-// given content IDs that are not still referenced by other surviving content.
-func collectImageDirs(ctx context.Context, q rowQuerier, contentIDs []string) ([]string, error) {
-	dirs, err := collectRawImageDirs(ctx, q, contentIDs)
-	if err != nil {
-		return nil, err
-	}
-	return filterUnreferencedImageDirs(ctx, q, dirs, contentIDs)
-}
-
-// collectRawImageDirs returns the deduped S3 directory prefixes referenced by
-// the given content IDs (items, their seasons, and their episodes), without
-// filtering out dirs still used by other content.
-func collectRawImageDirs(ctx context.Context, q rowQuerier, contentIDs []string) ([]string, error) {
-	imgRows, err := q.Query(ctx, `
-		SELECT poster_path, backdrop_path, logo_path FROM media_items WHERE content_id = ANY($1)
-		UNION ALL
-		SELECT poster_path, '', '' FROM seasons WHERE series_id = ANY($1)
-		UNION ALL
-		SELECT still_path, '', '' FROM episodes WHERE series_id = ANY($1)
-	`, contentIDs)
-	if err != nil {
-		return nil, fmt.Errorf("collecting image paths: %w", err)
-	}
-	defer imgRows.Close()
-	dirSet := make(map[string]struct{})
-	for imgRows.Next() {
-		var p1, p2, p3 string
-		if err := imgRows.Scan(&p1, &p2, &p3); err != nil {
-			return nil, fmt.Errorf("scanning image path: %w", err)
-		}
-		for _, p := range []string{p1, p2, p3} {
-			if p != "" && !strings.Contains(p, "://") {
-				if dir := pathDir(p); dir != "" {
-					dirSet[dir] = struct{}{}
-				}
-			}
-		}
-	}
-	if err := imgRows.Err(); err != nil {
-		return nil, fmt.Errorf("iterating image paths: %w", err)
-	}
-	dirs := make([]string, 0, len(dirSet))
-	for dir := range dirSet {
-		dirs = append(dirs, dir)
-	}
-	return dirs, nil
-}
-```
-
- [ ] **Step 3: Change `filterUnreferencedImageDirs` to take `rowQuerier`**
-
-In `internal/catalog/folder_repo.go`, change the signature (currently `internal/catalog/folder_repo.go:586`) from:
-
-```go
-func filterUnreferencedImageDirs(ctx context.Context, tx pgx.Tx, dirs, deletingContentIDs []string) ([]string, error) {
-```
-
-to:
-
-```go
-func filterUnreferencedImageDirs(ctx context.Context, q rowQuerier, dirs, deletingContentIDs []string) ([]string, error) {
-```
-
-and change the single `tx.Query(ctx, ...)` call inside it to `q.Query(ctx, ...)`. Leave the SQL and the rest of the body unchanged.
-
- [ ] **Step 4: Verify the build (proves `library_repo.go` still compiles with `pgx.Tx`)**
-
-Run: `go build ./... && go vet ./internal/catalog/`
-Expected: no errors. (`library_repo.go` passes a `pgx.Tx` to `collectImageDirs`, which now accepts `rowQuerier`; `pgx.Tx` satisfies it.)
-
- [ ] **Step 5: Run the catalog tests**
-
-Run: `go test ./internal/catalog/...`
-Expected: PASS (existing tests plus Tasks 1–2 helpers).
-
- [ ] **Step 6: Format and commit**
-
-```bash
-gofmt -w internal/catalog/folder_repo.go
-git add internal/catalog/folder_repo.go
-git commit -m "refactor(catalog): make image-dir helpers querier-agnostic"
-```
-
---
-
-## Task 4: Rewrite `DeleteWithStats` as a batched, phased operation
-
-**Files:**
- Modify: `internal/catalog/folder_repo.go:415-511` (the `DeleteWithStats` body) and add two helpers + two constants.
-
- [ ] **Step 1: Add the batch-size constants**
-
-In `internal/catalog/folder_repo.go`, add near the retry vars from Task 1:
-
-```go
-const (
-	// orphanDeleteBatch is small because each media_items row cascades across
-	// ~15 child tables.
-	orphanDeleteBatch = 1000
-	// folderChildDeleteBatch covers the lighter folder-scoped media_files and
-	// junction deletes.
-	folderChildDeleteBatch = 5000
-)
-```
-
- [ ] **Step 2: Replace the `DeleteWithStats` body**
-
-Replace the entire existing `DeleteWithStats` function (`internal/catalog/folder_repo.go:415-511`) with:
-
-```go
-func (r *FolderRepository) DeleteWithStats(
-	ctx context.Context,
-	id int,
-	progress func(current, total int, message string),
-) (*DeleteFolderStats, error) {
-	stats := &DeleteFolderStats{}
-
-	// Phase 0: preflight reads (no long-lived transaction).
-	if err := r.pool.QueryRow(ctx, `SELECT name FROM media_folders WHERE id = $1`, id).Scan(&stats.LibraryName); err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, ErrFolderNotFound
-		}
-		return nil, fmt.Errorf("loading folder before delete: %w", err)
-	}
-	if err := r.pool.QueryRow(ctx, `SELECT COUNT(*) FROM media_files WHERE media_folder_id = $1`, id).Scan(&stats.MediaFiles); err != nil {
-		return nil, fmt.Errorf("counting media files: %w", err)
-	}
-	if err := r.pool.QueryRow(ctx, `SELECT COUNT(*) FROM media_item_libraries WHERE media_folder_id = $1`, id).Scan(&stats.MediaItemLinks); err != nil {
-		return nil, fmt.Errorf("counting media item links: %w", err)
-	}
-	var orphanTotal int
-	if err := r.pool.QueryRow(ctx, `
-		SELECT COUNT(*)
-		FROM media_item_libraries mil
-		WHERE mil.media_folder_id = $1
-		AND NOT EXISTS (
-			SELECT 1 FROM media_item_libraries other
-			WHERE other.content_id = mil.content_id
-			AND other.media_folder_id <> $1
-		)`, id).Scan(&orphanTotal); err != nil {
-		return nil, fmt.Errorf("counting orphaned items: %w", err)
-	}
-
-	// Phase 1: delete orphaned media_items in detect-then-delete batches.
-	// Cascade removes their junctions, provider IDs, episodes, seasons, etc.
-	if progress != nil {
-		progress(0, orphanTotal, "Deleting orphaned items")
-	}
-	rawDirs := make(map[string]struct{})
-	for {
-		ids, err := r.collectOrphanBatch(ctx, id, orphanDeleteBatch)
-		if err != nil {
-			return nil, err
-		}
-		if len(ids) == 0 {
-			break
-		}
-		dirs, err := collectRawImageDirs(ctx, r.pool, ids)
-		if err != nil {
-			return nil, err
-		}
-		for _, d := range dirs {
-			rawDirs[d] = struct{}{}
-		}
-		if err := retryOnDeadlock(ctx, func() error {
-			_, e := r.pool.Exec(ctx, `DELETE FROM media_items WHERE content_id = ANY($1)`, ids)
-			return e
-		}); err != nil {
-			return nil, fmt.Errorf("deleting orphaned items: %w", err)
-		}
-		stats.OrphanedItems += len(ids)
-		if progress != nil {
-			progress(stats.OrphanedItems, orphanTotal, "Deleting orphaned items")
-		}
-	}
-
-	// Filter accumulated image dirs once, now that orphans are gone, against
-	// any surviving content. Empty deleting-set means "exclude nothing".
-	if len(rawDirs) > 0 {
-		filtered, err := filterUnreferencedImageDirs(ctx, r.pool, dirSetToSlice(rawDirs), []string{})
-		if err != nil {
-			return nil, err
-		}
-		stats.OrphanedImageDirs = filtered
-	}
-
-	// Phase 2: delete this folder's media_files (folder-tied, not item-tied).
-	if progress != nil {
-		progress(orphanTotal, orphanTotal, "Deleting media files")
-	}
-	if _, err := deleteInBatches(ctx, folderChildDeleteBatch, func(ctx context.Context) (int64, error) {
-		tag, e := r.pool.Exec(ctx, `
-			DELETE FROM media_files
-			WHERE id IN (
-				SELECT id FROM media_files WHERE media_folder_id = $1 LIMIT $2
-			)`, id, folderChildDeleteBatch)
-		if e != nil {
-			return 0, e
-		}
-		return tag.RowsAffected(), nil
-	}); err != nil {
-		return nil, fmt.Errorf("deleting media files: %w", err)
-	}
-
-	// Phase 3: delete remaining folder memberships (shared items kept; only the
-	// membership in this folder is removed).
-	if progress != nil {
-		progress(orphanTotal, orphanTotal, "Removing library memberships")
-	}
-	if _, err := deleteInBatches(ctx, folderChildDeleteBatch, func(ctx context.Context) (int64, error) {
-		tag, e := r.pool.Exec(ctx, `
-			DELETE FROM media_item_libraries
-			WHERE ctid IN (
-				SELECT ctid FROM media_item_libraries WHERE media_folder_id = $1 LIMIT $2
-			)`, id, folderChildDeleteBatch)
-		if e != nil {
-			return 0, e
-		}
-		return tag.RowsAffected(), nil
-	}); err != nil {
-		return nil, fmt.Errorf("deleting media item links: %w", err)
-	}
-
-	// Phase 4: delete the now-lightweight folder row. Tolerate 0 rows so a
-	// resumed run that already removed it still succeeds.
-	if err := retryOnDeadlock(ctx, func() error {
-		_, e := r.pool.Exec(ctx, `DELETE FROM media_folders WHERE id = $1`, id)
-		return e
-	}); err != nil {
-		return nil, fmt.Errorf("deleting folder: %w", err)
-	}
-
-	if progress != nil {
-		progress(orphanTotal, orphanTotal, "Library deletion completed")
-	}
-	return stats, nil
-}
-
-// collectOrphanBatch returns up to limit content IDs whose only library
-// membership is the given folder.
-func (r *FolderRepository) collectOrphanBatch(ctx context.Context, folderID, limit int) ([]string, error) {
-	rows, err := r.pool.Query(ctx, `
-		SELECT mil.content_id
-		FROM media_item_libraries mil
-		WHERE mil.media_folder_id = $1
-		AND NOT EXISTS (
-			SELECT 1 FROM media_item_libraries other
-			WHERE other.content_id = mil.content_id
-			AND other.media_folder_id <> $1
-		)
-		LIMIT $2`, folderID, limit)
-	if err != nil {
-		return nil, fmt.Errorf("finding orphaned items: %w", err)
-	}
-	defer rows.Close()
-	var ids []string
-	for rows.Next() {
-		var contentID string
-		if err := rows.Scan(&contentID); err != nil {
-			return nil, fmt.Errorf("scanning orphan content_id: %w", err)
-		}
-		ids = append(ids, contentID)
-	}
-	return ids, rows.Err()
-}
-
-// dirSetToSlice returns the keys of set as a slice (nil if empty).
-func dirSetToSlice(set map[string]struct{}) []string {
-	if len(set) == 0 {
-		return nil
-	}
-	dirs := make([]string, 0, len(set))
-	for d := range set {
-		dirs = append(dirs, d)
-	}
-	return dirs
-}
-```
-
-Note: this removes the old single-transaction body (`tx, err := r.pool.Begin(...)`, the inline orphan-collection loop, the `collectImageDirs` call, the CASCADE folder drop, and `tx.Commit`). `collectOrphanIDs` and `Delete` are untouched. `collectImageDirs` remains (still used by `library_repo.go`).
-
- [ ] **Step 3: Verify the build and vet**
-
-Run: `go build ./... && go vet ./internal/catalog/`
-Expected: no errors. If `go vet` flags an unused function, confirm it is genuinely unused before removing — `collectImageDirs`, `collectOrphanIDs`, and `pathDir` must all remain (still referenced).
-
- [ ] **Step 4: Run the full catalog + adminjob test suites**
-
-Run: `go test ./internal/catalog/... ./internal/adminjob/...`
-Expected: PASS. (No DB-backed test exercises `DeleteWithStats`; the helper unit tests and existing tests must stay green.)
-
- [ ] **Step 5: Lint**
-
-Run: `golangci-lint run ./internal/catalog/...`
-Expected: no findings. (If `golangci-lint` is unavailable, run `gofmt -l internal/catalog/` and ensure it prints nothing.)
-
- [ ] **Step 6: Format and commit**
-
-```bash
-gofmt -w internal/catalog/folder_repo.go
-git add internal/catalog/folder_repo.go
-git commit -m "fix(catalog): delete libraries in deadlock-retrying batches
-
-Replaces the single multi-minute delete transaction with phased, batched
-autocommit deletes (orphan items, media files, memberships, folder row),
-each retried on deadlock. Holds only short locks, survives concurrent
-writers, and is resumable on failure."
-```
-
---
-
-## Task 5: Verify on the dev server
-
-This is the integration test (no catalog DB harness exists). Follow the deployment-debugging runbook. The Audiobooks library (folder id 8) is currently stuck with ~249K items / ~339K files.
-
- [ ] **Step 1: Deploy the branch to dev**
-
-Run: `make dev-deploy`
-Expected: builds `silo:dev-local`, recreates the `silo` service. Then confirm health:
-`ssh "$DEV_HOST" 'curl -s http://localhost:8090/api/v1/ready'`
-
- [ ] **Step 2: Capture the starting counts**
-
-Run (psql via the dev compose `postgres` service, user/db `continuum`):
-
-```sql
-SELECT
-  (SELECT COUNT(*) FROM media_files WHERE media_folder_id = 8) AS files,
-  (SELECT COUNT(*) FROM media_item_libraries WHERE media_folder_id = 8) AS links,
-  (SELECT EXISTS (SELECT 1 FROM media_folders WHERE id = 8)) AS folder_exists;
-```
-
-Expected: non-zero files/links, `folder_exists = t`.
-
- [ ] **Step 3: Trigger the deletion**
-
-Re-trigger the library deletion through the normal path (admin UI "delete library" for Audiobooks, or the admin delete endpoint). Confirm a new job is queued:
-
-```sql
-SELECT id, job_type, status, requested_at
-FROM admin_jobs WHERE job_type = 'delete_library'
-ORDER BY requested_at DESC LIMIT 3;
-```
-
- [ ] **Step 4: Monitor to completion**
-
-Watch the job and the draining counts (re-run periodically):
-
-```sql
-SELECT id, status, progress_current, progress_total, error_message, heartbeat_at
-FROM admin_jobs WHERE job_type = 'delete_library'
-ORDER BY requested_at DESC LIMIT 1;
-```
-
-```sql
-SELECT COUNT(*) FROM media_item_libraries WHERE media_folder_id = 8;
-```
-
-Also confirm deadlock retries (if any) are recovered rather than fatal:
-`ssh "$DEV_HOST" "$DEV_COMPOSE_CMD logs postgres 2>&1 | grep -i deadlock | tail -20"`
-Expected: the job reaches `status = completed`; counts trend to 0; any deadlocks are transient (the job does not fail).
-
- [ ] **Step 5: Confirm full removal**
-
-```sql
-SELECT
-  (SELECT COUNT(*) FROM media_files WHERE media_folder_id = 8) AS files,
-  (SELECT COUNT(*) FROM media_item_libraries WHERE media_folder_id = 8) AS links,
-  (SELECT EXISTS (SELECT 1 FROM media_folders WHERE id = 8)) AS folder_exists;
-```
-
-Expected: `files = 0`, `links = 0`, `folder_exists = f`.
-
- [ ] **Step 6: Report**
-
-Summarize: starting counts, time to completion, number of batches/retries observed, and final state. No commit (verification only).
-
---
-
-## Self-Review
-
-**Spec coverage:**
- Phased batched deletion (Phases 0–4) → Task 4. ✔
- `retryOnDeadlock` (40P01/40001, 5 attempts, backoff, ctx-aware) → Task 1. ✔
- Batch sizes `orphanDeleteBatch=1000`, `folderChildDeleteBatch=5000` → Task 4 Step 1. ✔
- Autocommit per batch / no long transaction → Task 4 Step 2 (uses `r.pool.Exec`, no `Begin`). ✔
- Stats + progress + heartbeat reliance → Task 4 Step 2; runner heartbeat unchanged. ✔
- Resumability (folder row last, tolerate 0 rows) → Task 4 Phase 4. ✔
- Unit tests for retry + batch loop → Tasks 1–2. ✔
- `collectImageDirs` shared with `library_repo.go` preserved → Task 3 (interface widening), Task 4 Step 3 build check. ✔
- Dev integration verification → Task 5. ✔
- Out of scope (writer coordination, runner/executor changes, schema changes) → not present in any task. ✔
-
-**Placeholder scan:** No TBD/TODO; every code step has complete code; every command has expected output. ✔
-
-**Type consistency:** `retryOnDeadlock(ctx, func() error) error`, `deleteInBatches(ctx, int, func(ctx) (int64,error)) (int64,error)`, `rowQuerier{ Query(ctx,string,...any)(pgx.Rows,error) }`, `collectRawImageDirs`/`collectImageDirs`/`filterUnreferencedImageDirs(ctx, rowQuerier, ...)`, `collectOrphanBatch(ctx,int,int)([]string,error)`, `dirSetToSlice(map[string]struct{})[]string`, consts `orphanDeleteBatch`/`folderChildDeleteBatch`, vars `deadlockMaxAttempts`/`deadlockBaseBackoff` — names used consistently across tasks. ✔
@@ -1,779 +0,0 @@
-# Autoscan Host Backend Implementation Plan (Part 1 of 2)
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build the silo-server backend for the standalone Autoscan category: poll `scan_source.v1` plugins on a timer, resolve their Silo-native paths to library folders, and enqueue rescans — with connections decoupled from Requests.
-
-**Architecture:** Mirror the existing `scheduled_task.v1` host dispatch (`pluginhost.Client` capability wrapper + `plugins.Service` resolver + a `taskmanager` task). Generalize the closed PR #43 autoscan engine (resolve → suppress → enqueue) so its input is "Silo-native paths from a scan-source plugin" instead of "arr history." Replace the old `request_integrations`-coupled schema with `autoscan_connections` + `autoscan_sources`.
-
-**Tech Stack:** Go, pgx/v5, the `internal/plugins`/`internal/pluginhost` runtime, `internal/scantrigger`/`internal/scanqueue`, `internal/taskmanager`, numbered SQL migrations, `github.com/Silo-Server/silo-plugin-sdk` (the new `scan_source.v1` capability).
-
-Commands assume the silo-server repository root is the cwd. This is **Part 1 (backend)**; the Autoscan admin UI is Part 2.
-
---
-
-## Prerequisites
-
-1. **SDK dependency.** This plan needs the SDK's `scan_source.v1` symbols (`runtime.Client.ScanSource()`, `pluginv1.ScanSourceClient`, `pluginv1.PollChangesRequest/Response`, `capability.ScanSource`). They are in `silo-plugin-sdk` PR #2 but **not yet released**. Until `v0.5.0` is tagged, add a local replace directive so the host builds against the working checkout:
-
-   ```bash
-   # from the repository root (cwd)
-   go mod edit -replace github.com/Silo-Server/silo-plugin-sdk=../silo-plugin-sdk
-   go mod tidy
-   ```
-
-   This points the replace at the `silo-plugin-sdk` checkout (a sibling of this repo).
-
-   The final task removes the replace and bumps to the tagged version.
-
-2. **Closed PR #43 is on `main`.** The in-process arr autoscan (`internal/autoscan/*`, `internal/api/handlers/autoscan.go`, `internal/taskmanager/tasks/autoscan_poll.go`, router routes, migration `171_autoscan`, the `AdminRequests.tsx` tab) is the salvage source. This plan **generalizes the engine and replaces the schema/wiring**; it does not preserve the arr-specific history client (that moves to the arr plugin in a separate plan).
-
-3. **Tests that touch `internal/api/handlers` or `internal/api` link libvips via CGO.** Run the suite in the libvips-equipped container (see project memory `silo-test-libvips-gotcha`), not the bare host, or those packages report `[build failed]` and skip silently.
-
---
-
-## Pattern references (read before starting)
-
- Host capability client wrapper: `internal/pluginhost/client.go` — `ScheduledTaskClient` type (l.42), `Client.ScheduledTask` accessor (l.111), `requireCapability` (l.157), `Run` (l.226).
- Host resolver: `internal/plugins/service.go:413` `ScheduledTaskClient(ctx, installationID, capabilityID)` → `ensureClient` → `client.ScheduledTask(capabilityID)`.
- Timer task over plugin capabilities: `internal/plugins/task_registry.go` (iterate enabled installations, filter capability type, build a `taskmanager.Task`).
- Salvageable engine (generalize, don't rewrite): `internal/autoscan/service.go` (resolve/suppress/enqueue loop), `dedupe.go` (`uniqueParentDirs`), `suppress.go` (`Suppressor`). Discard `history.go`, `rewrite.go`, `suggest*.go` (arr-specific → arr plugin).
- Migration mechanics: paired `migrations/NNN_*.up.sql`/`.down.sql`, embedded via `migrations/embed.go`, auto-applied on boot.
- Credential decryption for the reuse-from-Requests case: `internal/requests/repository.go` (`integrationColumns` has `base_url, api_key_ref`); Fernet resolution via `catalog.ServerSettingsRepo.Get` (the same path PR #43's `SecretResolver` used).
-
---
-
-## File Structure
-
-| File | Responsibility | Action |
-|---|---|---|
-| `internal/pluginhost/client.go` | `ScanSourceClient` wrapper + `Client.ScanSource()` accessor | Modify |
-| `internal/pluginhost/client_test.go` | `requireCapability` gate for `scan_source.v1` | Modify |
-| `internal/plugins/service.go` | `ScanSourceClient(ctx, installationID, capabilityID)` resolver | Modify |
-| `migrations/172_autoscan_v2.up.sql` / `.down.sql` | `autoscan_connections` + `autoscan_sources`; drop the `171` tables | Create |
-| `internal/autoscan/types.go` | `Source`, `Connection`, `Settings`, `PollChanges` provider seam | Rewrite |
-| `internal/autoscan/repository.go` | CRUD for connections + sources; `AdvanceMarker` | Rewrite |
-| `internal/autoscan/provider.go` | `ScanSourceProvider` interface + adapter over the plugins resolver | Create |
-| `internal/autoscan/connection.go` | Resolve a `Connection` (own or Requests-linked) → `{base_url, api_key}` | Create |
-| `internal/autoscan/service.go` | Generic engine: per source → `PollChanges(marker)` → resolve → suppress → enqueue → store marker | Rewrite |
-| `internal/autoscan/dedupe.go`, `suppress.go` | Unchanged salvage | Keep |
-| `internal/autoscan/history.go`, `rewrite.go`, `suggest*.go` | Arr-specific | Delete |
-| `internal/taskmanager/tasks/autoscan_poll.go` | Poll task → `Service.PollOnce` | Keep (retarget) |
-| `internal/api/handlers/autoscan.go` | Admin API (settings/connections/sources/trigger/status) | Rewrite |
-| `internal/api/router.go`, `cmd/silo/main.go` | Wire the rebuilt service + connection resolver; drop request-coupled wiring | Modify |
-| `go.mod` | SDK replace (dev) → `v0.5.0` (final) | Modify |
-
---
-
-## Task 1: Host `pluginhost` client wrapper for `scan_source.v1`
-
-**Files:**
- Modify: `internal/pluginhost/client.go`
- Modify: `internal/pluginhost/client_test.go`
-
- [ ] **Step 1: Write the failing test**
-
-In `internal/pluginhost/client_test.go`, add a test mirroring the existing `scheduled_task` capability-gate test (find it first; it constructs a `Client` with a manifest declaring a capability and asserts the accessor errors when the capability is absent and succeeds when present):
-
-```go
-func TestClientScanSourceRequiresCapability(t *testing.T) {
-	// Client whose manifest does NOT declare scan_source.v1
-	c := newTestClientWithCapabilities(t, "metadata_provider.v1")
-	if _, err := c.ScanSource("missing"); err == nil {
-		t.Fatal("ScanSource: expected error when capability absent")
-	}
-	// Client WHOSE manifest declares scan_source.v1 with id "arr"
-	c2 := newTestClientWithCapabilities(t, "scan_source.v1:arr")
-	if _, err := c2.ScanSource("arr"); err != nil {
-		t.Fatalf("ScanSource: unexpected error when capability present: %v", err)
-	}
-}
-```
-
-Use whatever helper the sibling `scheduled_task` test uses to construct a `Client` with declared capabilities; mirror it exactly (do not invent a helper that does not exist — read `client_test.go` and copy the construction).
-
- [ ] **Step 2: Run test to verify it fails**
-
-Run: `go test ./internal/pluginhost/ -run TestClientScanSourceRequiresCapability`
-Expected: FAIL — `c.ScanSource undefined`.
-
- [ ] **Step 3: Add the wrapper type and accessor**
-
-In `internal/pluginhost/client.go`, after the `ScheduledTaskClient` type (l.42), add:
-
-```go
-type ScanSourceClient struct {
-	client  pluginv1.ScanSourceClient
-	timeout time.Duration
-}
-```
-
-After the `Client.ScheduledTask` accessor (l.117), add:
-
-```go
-func (c *Client) ScanSource(capabilityID string) (*ScanSourceClient, error) {
-	if err := c.requireCapability("scan_source.v1", capabilityID); err != nil {
-		return nil, err
-	}
-	return &ScanSourceClient{
-		client:  c.rpc.ScanSource(),
-		timeout: DefaultControlTimeout,
-	}, nil
-}
-
-func (c *ScanSourceClient) PollChanges(ctx context.Context, req *pluginv1.PollChangesRequest) (*pluginv1.PollChangesResponse, error) {
-	callCtx, cancel := ensureDeadline(ctx, c.timeout)
-	defer cancel()
-	return c.client.PollChanges(callCtx, req)
-}
-```
-
- [ ] **Step 4: Run test to verify it passes**
-
-Run: `go test ./internal/pluginhost/ -run TestClientScanSourceRequiresCapability`
-Expected: PASS.
-
- [ ] **Step 5: Commit**
-
-```bash
-git add internal/pluginhost/client.go internal/pluginhost/client_test.go
-git commit -m "feat(pluginhost): scan_source.v1 capability client wrapper"
-```
-
---
-
-## Task 2: `plugins.Service` resolver for `scan_source.v1`
-
-**Files:**
- Modify: `internal/plugins/service.go`
-
- [ ] **Step 1: Add the resolver method**
-
-After `ScheduledTaskClient` (l.413–423), add the identical shape for scan source:
-
-```go
-func (s *Service) ScanSourceClient(
-	ctx context.Context,
-	installationID int,
-	capabilityID string,
-) (*pluginhost.ScanSourceClient, error) {
-	client, err := s.ensureClient(ctx, installationID)
-	if err != nil {
-		return nil, err
-	}
-	return client.ScanSource(capabilityID)
-}
-```
-
- [ ] **Step 2: Build to verify it compiles**
-
-Run: `go build ./internal/plugins/`
-Expected: exits 0.
-
- [ ] **Step 3: Commit**
-
-```bash
-git add internal/plugins/service.go
-git commit -m "feat(plugins): expose scan_source.v1 client resolver"
-```
-
---
-
-## Task 3: Schema — `autoscan_connections` + `autoscan_sources`
-
-**Files:**
- Create: `migrations/172_autoscan_v2.up.sql`, `migrations/172_autoscan_v2.down.sql`
-
- [ ] **Step 1: Write the up migration**
-
-Create `migrations/172_autoscan_v2.up.sql`. It drops PR #43's `171` tables and creates the decoupled schema (no FK into `request_integrations`; the optional reuse link is `ON DELETE SET NULL`):
-
-```sql
-DROP TABLE IF EXISTS public.autoscan_sources;
-DROP TABLE IF EXISTS public.autoscan_settings;
-
-CREATE TABLE public.autoscan_settings (
-    id boolean PRIMARY KEY DEFAULT true,
-    enabled boolean NOT NULL DEFAULT false,
-    default_poll_interval_seconds integer NOT NULL DEFAULT 600,
-    debounce_seconds integer NOT NULL DEFAULT 60,
-    created_at timestamptz NOT NULL DEFAULT now(),
-    updated_at timestamptz NOT NULL DEFAULT now(),
-    CONSTRAINT autoscan_settings_singleton CHECK (id),
-    CONSTRAINT autoscan_settings_interval_pos CHECK (default_poll_interval_seconds > 0),
-    CONSTRAINT autoscan_settings_debounce_nonneg CHECK (debounce_seconds >= 0)
-);
-INSERT INTO public.autoscan_settings (id) VALUES (true) ON CONFLICT (id) DO NOTHING;
-
-CREATE TABLE public.autoscan_connections (
-    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-    name text NOT NULL,
-    kind text NOT NULL,
-    -- Own credentials (used when request_integration_id IS NULL):
-    base_url text,
-    api_key_ref text,
-    -- Optional soft reuse of a Requests arr server (live link; SET NULL on delete):
-    request_integration_id text REFERENCES public.request_integrations(id) ON DELETE SET NULL,
-    created_at timestamptz NOT NULL DEFAULT now(),
-    updated_at timestamptz NOT NULL DEFAULT now(),
-    CONSTRAINT autoscan_connections_source_present
-        CHECK (request_integration_id IS NOT NULL OR base_url IS NOT NULL)
-);
-
-CREATE TABLE public.autoscan_sources (
-    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-    installation_id integer NOT NULL,
-    capability_id text NOT NULL,
-    connection_id uuid NOT NULL REFERENCES public.autoscan_connections(id) ON DELETE RESTRICT,
-    enabled boolean NOT NULL DEFAULT false,
-    poll_interval_seconds integer,
-    marker text,
-    last_run_at timestamptz,
-    last_error text,
-    created_at timestamptz NOT NULL DEFAULT now(),
-    updated_at timestamptz NOT NULL DEFAULT now(),
-    CONSTRAINT autoscan_sources_interval_pos CHECK (poll_interval_seconds IS NULL OR poll_interval_seconds > 0),
-    CONSTRAINT autoscan_sources_capability_unique UNIQUE (installation_id, capability_id)
-);
-```
-
- [ ] **Step 2: Write the down migration**
-
-Create `migrations/172_autoscan_v2.down.sql`:
-
-```sql
-DROP TABLE IF EXISTS public.autoscan_sources;
-DROP TABLE IF EXISTS public.autoscan_connections;
-DROP TABLE IF EXISTS public.autoscan_settings;
-```
-
-(Recreating the `171` tables on down-migration is unnecessary: `171` is unreleased and superseded; the down simply removes `172`'s tables.)
-
- [ ] **Step 3: Apply and verify against a disposable DB**
-
-Run the migrations against a throwaway Postgres (the project's disposable-DB pattern) and confirm boot applies cleanly:
-```bash
-docker compose up -d postgres
-go run ./cmd/silo --migrate-only 2>&1 | grep -i "migrations applied" || echo "check migration output"
-```
-Expected: migrations apply without error; `\d autoscan_connections` shows the soft FK `request_integration_id`.
-
- [ ] **Step 4: Commit**
-
-```bash
-git add migrations/172_autoscan_v2.up.sql migrations/172_autoscan_v2.down.sql
-git commit -m "feat(migrations): autoscan v2 schema (connections + sources, no requests FK)"
-```
-
---
-
-## Task 4: Types and repository
-
-**Files:**
- Rewrite: `internal/autoscan/types.go`
- Rewrite: `internal/autoscan/repository.go`
-
- [ ] **Step 1: Define the types**
-
-Replace `internal/autoscan/types.go` with the v2 model:
-
-```go
-package autoscan
-
-import "time"
-
-type Settings struct {
-	Enabled                    bool
-	DefaultPollIntervalSeconds int
-	DebounceSeconds            int
-}
-
-// Connection is an arr server the host can reach: either own credentials, or a
-// live reference to a Requests integration (RequestIntegrationID set).
-type Connection struct {
-	ID                   string
-	Name                 string
-	Kind                 string
-	BaseURL              string // own; empty when linked
-	APIKeyRef            string // own; empty when linked
-	RequestIntegrationID *string
-}
-
-// Source ties a scan_source plugin capability instance to a connection plus the
-// host-owned scheduling/bookkeeping state.
-type Source struct {
-	ID                  string
-	InstallationID      int
-	CapabilityID        string
-	ConnectionID        string
-	Enabled             bool
-	PollIntervalSeconds *int    // nil => use settings default
-	Marker              *string // opaque; nil on first run
-	LastRunAt           *time.Time
-	LastError           *string
-}
-```
-
- [ ] **Step 2: Write a failing repository test**
-
-Add `internal/autoscan/repository_test.go` exercising round-trip + `AdvanceMarker` against a disposable DB (gate with the project's DB-test build tag/helper if one exists; otherwise a `//go:build integration` tag matching sibling DB tests). Minimal:
-
-```go
-func TestRepositoryMarkerRoundTrip(t *testing.T) {
-	repo := newTestRepo(t) // disposable-DB helper used by sibling repo tests
-	connID := repo.mustCreateConnection(t, Connection{Name: "Sonarr", Kind: "sonarr", BaseURL: "http://x", APIKeyRef: "k"})
-	srcID := repo.mustCreateSource(t, Source{InstallationID: 1, CapabilityID: "arr", ConnectionID: connID, Enabled: true})
-
-	if err := repo.AdvanceMarker(ctx, srcID, "2026-06-02T14:10:00Z"); err != nil {
-		t.Fatalf("AdvanceMarker: %v", err)
-	}
-	got, _ := repo.ListEnabledSources(ctx)
-	if len(got) != 1 || got[0].Marker == nil || *got[0].Marker != "2026-06-02T14:10:00Z" {
-		t.Fatalf("marker not persisted: %+v", got)
-	}
-}
-```
-
- [ ] **Step 3: Run to verify it fails**
-
-Run: `go test ./internal/autoscan/ -run TestRepositoryMarkerRoundTrip` (with the DB helper available)
-Expected: FAIL — undefined repository methods.
-
- [ ] **Step 4: Implement the repository**
-
-Rewrite `internal/autoscan/repository.go` with: `GetSettings`, `UpdateSettings`, connection CRUD (`CreateConnection`, `UpdateConnection`, `DeleteConnection`, `ListConnections`, `GetConnection`), source CRUD (`UpsertSource`, `ListEnabledSources`, `ListSources`, `GetSource`), and `AdvanceMarker(ctx, sourceID, marker string)` (sets `marker`, `last_run_at = now()`, clears `last_error`). Use pgx; follow the column/scan style of the existing (pre-rewrite) `repository.go` and `internal/requests/repository.go`.
-
- [ ] **Step 5: Run to verify it passes**
-
-Run: `go test ./internal/autoscan/ -run TestRepositoryMarkerRoundTrip`
-Expected: PASS.
-
- [ ] **Step 6: Commit**
-
-```bash
-git add internal/autoscan/types.go internal/autoscan/repository.go internal/autoscan/repository_test.go
-git commit -m "feat(autoscan): v2 types and repository (connections, sources, markers)"
-```
-
---
-
-## Task 5: Connection resolution (own or Requests-linked)
-
-**Files:**
- Create: `internal/autoscan/connection.go`
- Create: `internal/autoscan/connection_test.go`
-
- [ ] **Step 1: Write the failing test**
-
-```go
-func TestResolveConnectionOwnVsLinked(t *testing.T) {
-	reqLookup := fakeRequestIntegrationLookup{"req-1": creds{BaseURL: "http://req:7878", APIKeyRef: "rk"}}
-	secrets := fakeSecrets{"rk": "REQKEY", "ownref": "OWNKEY"}
-	r := NewConnectionResolver(reqLookup, secrets)
-
-	own, err := r.Resolve(ctx, Connection{BaseURL: "http://own:8989", APIKeyRef: "ownref"})
-	if err != nil || own.BaseURL != "http://own:8989" || own.APIKey != "OWNKEY" {
-		t.Fatalf("own resolve = %+v, err=%v", own, err)
-	}
-	id := "req-1"
-	linked, err := r.Resolve(ctx, Connection{RequestIntegrationID: &id})
-	if err != nil || linked.BaseURL != "http://req:7878" || linked.APIKey != "REQKEY" {
-		t.Fatalf("linked resolve = %+v, err=%v", linked, err)
-	}
-}
-
-func TestResolveConnectionLinkedMissingFallsBack(t *testing.T) {
-	r := NewConnectionResolver(fakeRequestIntegrationLookup{}, fakeSecrets{})
-	id := "gone"
-	if _, err := r.Resolve(ctx, Connection{RequestIntegrationID: &id}); err == nil {
-		t.Fatal("expected error when linked Requests integration is missing")
-	}
-}
-```
-
- [ ] **Step 2: Run to verify it fails**
-
-Run: `go test ./internal/autoscan/ -run TestResolveConnection`
-Expected: FAIL — undefined `NewConnectionResolver`.
-
- [ ] **Step 3: Implement**
-
-Create `internal/autoscan/connection.go`:
-
-```go
-package autoscan
-
-import (
-	"context"
-	"fmt"
-)
-
-// ResolvedConnection is concrete credentials handed to the plugin.
-type ResolvedConnection struct {
-	BaseURL string
-	APIKey  string
-}
-
-type RequestIntegrationLookup interface {
-	// Returns base URL + encrypted api key ref for a Requests integration.
-	Get(ctx context.Context, integrationID string) (baseURL, apiKeyRef string, err error)
-}
-
-type SecretResolver interface {
-	Get(ctx context.Context, ref string) (string, error)
-}
-
-type ConnectionResolver struct {
-	requests RequestIntegrationLookup
-	secrets  SecretResolver
-}
-
-func NewConnectionResolver(r RequestIntegrationLookup, s SecretResolver) *ConnectionResolver {
-	return &ConnectionResolver{requests: r, secrets: s}
-}
-
-func (cr *ConnectionResolver) Resolve(ctx context.Context, c Connection) (ResolvedConnection, error) {
-	baseURL, apiKeyRef := c.BaseURL, c.APIKeyRef
-	if c.RequestIntegrationID != nil {
-		u, ref, err := cr.requests.Get(ctx, *c.RequestIntegrationID)
-		if err != nil {
-			return ResolvedConnection{}, fmt.Errorf("autoscan: linked requests integration %q: %w", *c.RequestIntegrationID, err)
-		}
-		baseURL, apiKeyRef = u, ref
-	}
-	apiKey := apiKeyRef
-	if cr.secrets != nil && apiKeyRef != "" {
-		resolved, err := cr.secrets.Get(ctx, apiKeyRef)
-		if err != nil {
-			return ResolvedConnection{}, fmt.Errorf("autoscan: resolve api key: %w", err)
-		}
-		if resolved != "" {
-			apiKey = resolved
-		}
-	}
-	return ResolvedConnection{BaseURL: baseURL, APIKey: apiKey}, nil
-}
-```
-
- [ ] **Step 4: Run to verify it passes**
-
-Run: `go test ./internal/autoscan/ -run TestResolveConnection`
-Expected: PASS.
-
- [ ] **Step 5: Commit**
-
-```bash
-git add internal/autoscan/connection.go internal/autoscan/connection_test.go
-git commit -m "feat(autoscan): resolve connections (own credentials or Requests-linked)"
-```
-
---
-
-## Task 6: Provider seam over the plugin resolver
-
-**Files:**
- Create: `internal/autoscan/provider.go`
-
- [ ] **Step 1: Define the seam and adapter**
-
-The engine must be testable without a live plugin, so it depends on a narrow interface, with a production adapter over `plugins.Service.ScanSourceClient`. Create `internal/autoscan/provider.go`:
-
-```go
-package autoscan
-
-import (
-	"context"
-
-	pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1"
-)
-
-// ScanSourceProvider yields changed paths for one source. The engine calls
-// PollChanges; production wraps the plugins.Service scan_source resolver.
-type ScanSourceProvider interface {
-	PollChanges(ctx context.Context, installationID int, capabilityID, marker string, conn ResolvedConnection) (paths []string, nextMarker string, err error)
-}
-
-// pluginScanSourceClient is the slice of *pluginhost.ScanSourceClient used here.
-type pluginScanSourceClient interface {
-	PollChanges(ctx context.Context, req *pluginv1.PollChangesRequest) (*pluginv1.PollChangesResponse, error)
-}
-
-type scanSourceResolver interface {
-	ScanSourceClient(ctx context.Context, installationID int, capabilityID string) (pluginScanSourceClient, error)
-}
-
-type pluginProvider struct{ resolver scanSourceResolver }
-
-func NewPluginProvider(resolver scanSourceResolver) ScanSourceProvider {
-	return &pluginProvider{resolver: resolver}
-}
-
-func (p *pluginProvider) PollChanges(ctx context.Context, installationID int, capabilityID, marker string, conn ResolvedConnection) ([]string, string, error) {
-	client, err := p.resolver.ScanSourceClient(ctx, installationID, capabilityID)
-	if err != nil {
-		return nil, "", err
-	}
-	resp, err := client.PollChanges(ctx, &pluginv1.PollChangesRequest{CapabilityId: capabilityID, Marker: marker})
-	if err != nil {
-		return nil, "", err
-	}
-	return resp.GetChangedPaths(), resp.GetNextMarker(), nil
-}
-```
-
-Note: the connection (`conn`) is delivered to the plugin out-of-band as runtime config when the source is configured (the plugin reads its own `{base_url, api_key}`); it is passed here so a future provider variant could inject per-call. For v1 the production path configures the plugin instance with the resolved connection at upsert time; document this in `NewPluginProvider`'s comment.
-
- [ ] **Step 2: Build**
-
-Run: `go build ./internal/autoscan/`
-Expected: exits 0.
-
- [ ] **Step 3: Commit**
-
-```bash
-git add internal/autoscan/provider.go
-git commit -m "feat(autoscan): scan-source provider seam over the plugin resolver"
-```
-
---
-
-## Task 7: Generalize the engine (`Service.PollOnce`)
-
-**Files:**
- Rewrite: `internal/autoscan/service.go`
- Modify: `internal/autoscan/service_test.go` (generalize the salvaged tests)
-
- [ ] **Step 1: Adapt the salvaged tests to the provider seam**
-
-The PR #43 `service_test.go` used a `fakeHistory`; replace it with a `fakeProvider` implementing `ScanSourceProvider`, keeping the same assertions (dedupe to one folder; distinct paths same folder → two scans; disabled no-op; provider error keeps marker; enqueue failure releases claims + keeps marker). Add an opaque-marker assertion: the provider's returned `nextMarker` is stored verbatim via `AdvanceMarker`.
-
-```go
-type fakeProvider struct {
-	paths      map[string][]string // key: capabilityID
-	nextMarker string
-	err        error
-}
-
-func (f *fakeProvider) PollChanges(_ context.Context, _ int, capabilityID, _ string, _ ResolvedConnection) ([]string, string, error) {
-	if f.err != nil {
-		return nil, "", f.err
-	}
-	return f.paths[capabilityID], f.nextMarker, nil
-}
-```
-
- [ ] **Step 2: Run to verify the tests fail**
-
-Run: `go test ./internal/autoscan/ -run TestPollOnce`
-Expected: FAIL — `Service` signature/`fakeProvider` not yet wired.
-
- [ ] **Step 3: Rewrite the engine**
-
-Rewrite `internal/autoscan/service.go`. Keep the salvaged resolve→suppress→enqueue loop verbatim (it is provider-agnostic already), but drive it from sources + the provider seam:
-
-```go
-func (s *Service) PollOnce(ctx context.Context) error {
-	settings, err := s.store.GetSettings(ctx)
-	if err != nil {
-		return err
-	}
-	if !settings.Enabled {
-		return nil
-	}
-	sources, err := s.store.ListEnabledSources(ctx)
-	if err != nil {
-		return err
-	}
-	ttl := time.Duration(settings.DebounceSeconds) * time.Second
-
-	for _, src := range sources {
-		conn, cerr := s.resolveConnection(ctx, src.ConnectionID)
-		if cerr != nil {
-			slog.WarnContext(ctx, "autoscan: resolve connection failed", "source_id", src.ID, "err", cerr)
-			continue
-		}
-		marker := ""
-		if src.Marker != nil {
-			marker = *src.Marker
-		}
-		paths, next, perr := s.provider.PollChanges(ctx, src.InstallationID, src.CapabilityID, marker, conn)
-		if perr != nil {
-			slog.WarnContext(ctx, "autoscan: poll changes failed", "source_id", src.ID, "err", perr)
-			_ = s.store.RecordError(ctx, src.ID, perr.Error())
-			continue
-		}
-
-		targets, claimed := s.resolveAndClaim(ctx, paths, ttl) // salvaged dedupe→resolve→suppress
-		if len(targets) > 0 {
-			if eerr := s.queue.EnqueueScans(ctx, targets); eerr != nil {
-				s.releaseClaims(ctx, claimed)
-				slog.WarnContext(ctx, "autoscan: enqueue failed", "source_id", src.ID, "err", eerr)
-				continue // do NOT advance marker
-			}
-		}
-		if aerr := s.store.AdvanceMarker(ctx, src.ID, next); aerr != nil {
-			slog.WarnContext(ctx, "autoscan: advance marker failed", "source_id", src.ID, "err", aerr)
-		}
-	}
-	return nil
-}
-```
-
-Extract the salvaged loop body into `resolveAndClaim`/`releaseClaims` helpers (lifted verbatim from PR #43's `service.go` lines that build `targets`/`claimed`). Keep `uniqueParentDirs`, `Suppressor`, the `fmt.Sprintf("%d|%s", folderID, target.Path)` suppression key, and the `scantrigger.RequestError` quiet-skip.
-
- [ ] **Step 4: Run to verify the tests pass**
-
-Run: `go test ./internal/autoscan/ -run TestPollOnce`
-Expected: PASS.
-
- [ ] **Step 5: Commit**
-
-```bash
-git add internal/autoscan/service.go internal/autoscan/service_test.go
-git commit -m "feat(autoscan): generic engine drives sources via scan_source provider"
-```
-
---
-
-## Task 8: Delete arr-specific salvage residue
-
-**Files:**
- Delete: `internal/autoscan/history.go`, `history_test.go`, `rewrite.go`, `rewrite_test.go`, `suggest.go`, `suggest_deps.go`, `suggest_test.go`
-
- [ ] **Step 1: Remove the files**
-
-```bash
-git rm internal/autoscan/history.go internal/autoscan/history_test.go \
-       internal/autoscan/rewrite.go internal/autoscan/rewrite_test.go \
-       internal/autoscan/suggest.go internal/autoscan/suggest_deps.go internal/autoscan/suggest_test.go
-```
-
- [ ] **Step 2: Build to confirm no remaining references**
-
-Run: `go build ./internal/autoscan/...`
-Expected: exits 0 (the engine no longer references the deleted arr logic). If it fails, a reference was missed — remove it.
-
- [ ] **Step 3: Commit**
-
-```bash
-git commit -m "refactor(autoscan): drop arr-specific history/rewrite/suggest (moved to plugin)"
-```
-
---
-
-## Task 9: Admin API rewrite
-
-**Files:**
- Rewrite: `internal/api/handlers/autoscan.go`
- Modify: `internal/api/handlers/autoscan_test.go`
-
- [ ] **Step 1: Define the endpoints**
-
-Rewrite the handler to back the new model. Endpoints (admin-gated, mounted in Task 10):
- `GET/PUT /admin/autoscan/settings`
- `GET/POST /admin/autoscan/connections`, `PUT/DELETE /admin/autoscan/connections/{id}`
- `GET /admin/autoscan/sources`, `PUT /admin/autoscan/sources/{id}` (enable, interval, connection binding)
- `POST /admin/autoscan/trigger` (async `PollOnce`, 202 — keep the detached-goroutine + channel-tested pattern from the closed PR's `autoscan_test.go`)
- `GET /admin/autoscan/status`
-
-Strip credentials from responses (never emit `api_key_ref`/resolved keys), matching the `_SENSITIVE_METADATA_KEYS` defense-in-depth posture.
-
- [ ] **Step 2: Port + extend the handler tests**
-
-Carry over the trigger test (the `done`-channel synchronization fix from `d3ee373`), the FK→404 test (now: unknown source/connection → 404), and a secrets-not-leaked test for the connections list.
-
- [ ] **Step 3: Run the handler tests (libvips container)**
-
-Run (in the libvips-equipped container per Prerequisites #3):
-`go test ./internal/api/handlers/ -run Autoscan`
-Expected: PASS.
-
- [ ] **Step 4: Commit**
-
-```bash
-git add internal/api/handlers/autoscan.go internal/api/handlers/autoscan_test.go
-git commit -m "feat(api): autoscan v2 admin endpoints (settings, connections, sources)"
-```
-
---
-
-## Task 10: Wiring + rate limits + retire old coupling
-
-**Files:**
- Modify: `internal/api/router.go`
- Modify: `cmd/silo/main.go`
-
- [ ] **Step 1: Rebuild the service wiring**
-
-In `internal/api/router.go` and `cmd/silo/main.go`, construct the v2 service:
-
-```go
-autoscanRepo := autoscan.NewRepository(deps.DB)
-provider := autoscan.NewPluginProvider(pluginServiceScanSourceAdapter{pluginService})
-connResolver := autoscan.NewConnectionResolver(requestIntegrationLookup{requestsRepo}, serverSettingsSecretResolver{settingsRepo})
-autoscanSvc := autoscan.NewService(autoscanRepo, provider, connResolver, deps.Resolver, deps.ScanQueue, autoscan.NewRedisSuppressor(deps.RedisClient))
-autoscanHandler = handlers.NewAutoscanHandler(autoscanRepo, autoscanSvc)
-```
-
-Replace the old route block with the Task 9 routes. Keep the `catalog_*`/admin rate-limit conventions consistent with the security standards (per-user/admin caps on the new endpoints; mirror the request-integrations admin tier).
-
- [ ] **Step 2: Retarget the poll task**
-
-`internal/taskmanager/tasks/autoscan_poll.go` calls `Service.PollOnce` — unchanged behavior; confirm it compiles against the rebuilt service and uses `Settings.DefaultPollIntervalSeconds` for the interval (per-source overrides are honored inside `PollOnce`).
-
- [ ] **Step 3: Build the whole tree**
-
-Run (libvips container): `go build ./...`
-Expected: exits 0.
-
- [ ] **Step 4: Commit**
-
-```bash
-git add internal/api/router.go cmd/silo/main.go internal/taskmanager/tasks/autoscan_poll.go
-git commit -m "feat(autoscan): wire v2 service, routes, and poll task"
-```
-
---
-
-## Task 11: Full sweep + finalize SDK dependency
-
-**Files:**
- Modify: `go.mod`, `go.sum`
-
- [ ] **Step 1: Full build + test (libvips container)**
-
-Run in the libvips-equipped container (Prerequisites #3):
-```bash
-go build ./... && go test ./... && go vet ./...
-```
-Expected: build OK; all packages `ok`; vet clean. `gofmt -l internal migrations` prints nothing.
-
- [ ] **Step 2: Finalize the SDK version (after `v0.5.0` is tagged upstream)**
-
-Once `silo-plugin-sdk` PR #2 is merged and `v0.5.0` tagged:
-```bash
-go mod edit -dropreplace github.com/Silo-Server/silo-plugin-sdk
-go get github.com/Silo-Server/silo-plugin-sdk@v0.5.0
-go mod tidy
-go build ./...
-```
-Expected: builds against the released tag with no replace directive.
-
-If `v0.5.0` is not yet tagged when this plan is otherwise complete, leave the replace directive in place, commit it, and note in the PR that the dependency must be finalized before merge (do not merge a `replace` pointing at a local path).
-
- [ ] **Step 3: Commit**
-
-```bash
-git add go.mod go.sum
-git commit -m "build: depend on silo-plugin-sdk v0.5.0 (scan_source.v1)"
-```
-
---
-
-## Self-Review notes
-
- **Spec coverage:** §7 engine (Tasks 6–7), §8 connections incl. reuse-or-own + soft Requests link (Tasks 3,5), §9 data model decoupled from Requests + Autoscan-owned state (Tasks 3–4,9–10), §5/§11 host consumes `scan_source.v1` (Tasks 1–2). §10 (arr plugin) and §9 UI are separate plans.
- **Salvage map honored (§13):** engine/dedupe/suppress kept and generalized (Tasks 6–8); arr history/rewrite/suggest deleted (Task 8); `last_poll_at` → opaque `marker` (Tasks 3–4,7).
- **Out of scope here:** the Autoscan admin **UI** category (Part 2 plan) and the **arr plugin** (separate repo plan). This backend is testable on its own via the repository/engine/handler tests.
- **Risk carried from spec §14:** plugin multiplicity (one installation per arr server vs. many connections per installation) is modeled as one `autoscan_sources` row per `(installation_id, capability_id)`; if the runtime supports multiple capability instances per installation this maps cleanly, otherwise it implies one installation per server. Confirm during Task 1–2 by inspecting `ensureClient`/installation handling.
- **Type consistency:** `ResolvedConnection{BaseURL,APIKey}`, `Connection{BaseURL,APIKeyRef,RequestIntegrationID}`, `Source{InstallationID,CapabilityID,ConnectionID,Marker}`, `ScanSourceProvider.PollChanges(...)`, `Service.PollOnce` used consistently across Tasks 4–10.
@@ -1,694 +0,0 @@
-# Autoscan Rewrite-Sync Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** A "Sync rewrites from arr" action that suggests autoscan `path_rewrites` for an instance by matching its arr root folders to Silo media folders on shared trailing path segments, previewed and committed by the admin.
-
-**Architecture:** A pure `suggestRewrites` matcher in `internal/autoscan`, a `Service.SuggestRewrites` method backed by two new injected deps (an arr root-folder client and a Silo folder lister), one read-only admin endpoint returning a preview, and a "Sync from arr" button in the existing Autoscan tab that merges proposals into the editor (admin saves via the existing per-source PUT). Manual rewrites stay the source of truth.
-
-**Tech Stack:** Go (standard `testing`), React/TypeScript.
-
-**Spec:** `docs/superpowers/specs/2026-06-02-autoscan-rewrite-sync-design.md`
-
-**Commands assume the repository root is the cwd.** Go tests: `go test ./internal/autoscan/...`. Frontend: `cd web && pnpm exec tsc -b && pnpm run lint`. Ensure the Go toolchain is on `PATH` (prepend its `bin` directory if `go` is missing). `internal/api`/`internal/api/handlers` cannot be compiled without libvips; verify those via `gofmt` + the Docker build.
-
---
-
-## Phase 0 — Branch
-
- [ ] **Step 0.1: Confirm branch**
-
-```bash
-git rev-parse --abbrev-ref HEAD   # expect: feat/autoscan-arr-polling
-```
-This feature extends the autoscan branch. If you're elsewhere: `git checkout feat/autoscan-arr-polling`.
-
---
-
-## Phase 1 — Core matcher (pure, TDD)
-
-### Task 1: suggestRewrites + types
-
-**Files:**
- Create: `internal/autoscan/suggest.go`
- Create: `internal/autoscan/suggest_test.go`
-
- [ ] **Step 1.1: Write the failing test**
-
-`internal/autoscan/suggest_test.go`:
-```go
-package autoscan
-
-import (
-	"reflect"
-	"testing"
-)
-
-func TestSuggestRewrites(t *testing.T) {
-	silo := []string{
-		"/mnt/media/happy/storage2/tvshows1",
-		"/mnt/media/happy4k/4ktv7",
-		"/mnt/media/storage/Anime/Subs",
-		"/mnt/media/storage/Anime2/Subs",
-		"/library/Films",
-		"/tank/television/Show",
-	}
-
-	t.Run("multi-segment unique match", func(t *testing.T) {
-		got := suggestRewrites([]string{"/mnt/happy/storage2/tvshows1"}, silo, nil)
-		if len(got.Proposed) != 1 || got.Proposed[0].To != "/mnt/media/happy/storage2/tvshows1" || got.Proposed[0].MatchDepth != 2 {
-			t.Fatalf("proposed=%+v", got.Proposed)
-		}
-	})
-
-	t.Run("single-segment unique match (different parents)", func(t *testing.T) {
-		got := suggestRewrites([]string{"/mnt/kodama/storage2/4ktv7"}, silo, nil)
-		if len(got.Proposed) != 1 || got.Proposed[0].To != "/mnt/media/happy4k/4ktv7" || got.Proposed[0].MatchDepth != 1 {
-			t.Fatalf("proposed=%+v", got.Proposed)
-		}
-	})
-
-	t.Run("longest-suffix disambiguation", func(t *testing.T) {
-		got := suggestRewrites([]string{"/mnt/kodama/storage1/Anime/Subs"}, silo, nil)
-		if len(got.Proposed) != 1 || got.Proposed[0].To != "/mnt/media/storage/Anime/Subs" || got.Proposed[0].MatchDepth != 2 {
-			t.Fatalf("expected Anime/Subs (depth 2), got %+v", got.Proposed)
-		}
-		if len(got.Ambiguous) != 0 {
-			t.Fatalf("should not be ambiguous: %+v", got.Ambiguous)
-		}
-	})
-
-	t.Run("unmatched when no shared segment", func(t *testing.T) {
-		got := suggestRewrites([]string{"/data/Movies"}, silo, nil)
-		if len(got.Unmatched) != 1 || got.Unmatched[0] != "/data/Movies" || len(got.Proposed) != 0 {
-			t.Fatalf("got=%+v", got)
-		}
-	})
-
-	t.Run("leaf match across unlike layouts", func(t *testing.T) {
-		got := suggestRewrites([]string{"/srv/tv/Show"}, silo, nil)
-		if len(got.Proposed) != 1 || got.Proposed[0].To != "/tank/television/Show" {
-			t.Fatalf("got=%+v", got)
-		}
-	})
-
-	t.Run("ambiguous tie", func(t *testing.T) {
-		// a root whose only shared segment is "Subs" ties two folders
-		got := suggestRewrites([]string{"/foo/bar/Subs"}, silo, nil)
-		if len(got.Ambiguous) != 1 || len(got.Ambiguous[0].Candidates) != 2 {
-			t.Fatalf("expected ambiguous with 2 candidates, got %+v", got.Ambiguous)
-		}
-	})
-
-	t.Run("covered by existing rule", func(t *testing.T) {
-		existing := []PathRewrite{{From: "/mnt/happy", To: "/mnt/media/happy"}}
-		got := suggestRewrites([]string{"/mnt/happy/storage2/tvshows1"}, silo, existing)
-		if len(got.Covered) != 1 || len(got.Proposed) != 0 {
-			t.Fatalf("expected covered, got %+v", got)
-		}
-	})
-
-	t.Run("normalization: trailing slash, backslashes, dup slashes", func(t *testing.T) {
-		got := suggestRewrites([]string{`\mnt\happy\\storage2\tvshows1\`}, silo, nil)
-		if len(got.Proposed) != 1 || got.Proposed[0].From != "/mnt/happy/storage2/tvshows1" || got.Proposed[0].To != "/mnt/media/happy/storage2/tvshows1" {
-			t.Fatalf("normalization failed: %+v", got.Proposed)
-		}
-	})
-}
-
-func TestCommonSuffixLen(t *testing.T) {
-	cases := []struct {
-		a, b []string
-		want int
-	}{
-		{[]string{"a", "b", "c"}, []string{"x", "b", "c"}, 2},
-		{[]string{"4ktv7"}, []string{"happy4k", "4ktv7"}, 1},
-		{[]string{"4ktv7"}, []string{"4ktv70"}, 0}, // full-segment, not substring
-		{[]string{"a"}, []string{"b"}, 0},
-	}
-	for _, tc := range cases {
-		if got := commonSuffixLen(tc.a, tc.b); got != tc.want {
-			t.Fatalf("commonSuffixLen(%v,%v)=%d want %d", tc.a, tc.b, got, tc.want)
-		}
-	}
-}
-```
-
- [ ] **Step 1.2: Run it — expect failure**
-
-```bash
-go test ./internal/autoscan/ -run 'TestSuggestRewrites|TestCommonSuffixLen' -v
-```
-Expected: FAIL (`suggestRewrites` undefined).
-
- [ ] **Step 1.3: Implement** `internal/autoscan/suggest.go`:
-```go
-package autoscan
-
-import "strings"
-
-// RewriteSuggestions is the result of matching arr root folders to Silo folders.
-type RewriteSuggestions struct {
-	Proposed  []ProposedRewrite `json:"proposed"`
-	Unmatched []string          `json:"unmatched"`
-	Ambiguous []AmbiguousRoot   `json:"ambiguous"`
-	Covered   []string          `json:"covered"`
-}
-
-// ProposedRewrite is a suggested rewrite plus its confidence (shared trailing segments).
-type ProposedRewrite struct {
-	From       string `json:"from"`
-	To         string `json:"to"`
-	MatchDepth int    `json:"match_depth"`
-}
-
-// AmbiguousRoot is an arr root that tied across multiple Silo folders.
-type AmbiguousRoot struct {
-	Root       string   `json:"root"`
-	Candidates []string `json:"candidates"`
-}
-
-// normalizePath makes a path comparable: backslashes -> '/', collapse duplicate
-// slashes, strip a trailing slash (but keep a bare "/").
-func normalizePath(p string) string {
-	p = normalizeSeparators(strings.TrimSpace(p))
-	for strings.Contains(p, "//") {
-		p = strings.ReplaceAll(p, "//", "/")
-	}
-	if len(p) > 1 {
-		p = strings.TrimRight(p, "/")
-	}
-	return p
-}
-
-func segments(p string) []string {
-	p = strings.Trim(p, "/")
-	if p == "" {
-		return nil
-	}
-	return strings.Split(p, "/")
-}
-
-// commonSuffixLen counts equal trailing segments (full-segment equality).
-func commonSuffixLen(a, b []string) int {
-	i, j, n := len(a)-1, len(b)-1, 0
-	for i >= 0 && j >= 0 && a[i] == b[j] {
-		n++
-		i--
-		j--
-	}
-	return n
-}
-
-// coveredBy reports whether an existing rewrite already matches root (same
-// boundary rule as applyRewrites).
-func coveredBy(root string, existing []PathRewrite) bool {
-	for _, rw := range existing {
-		from := strings.TrimRight(strings.TrimSpace(rw.From), "/")
-		if from == "" {
-			continue
-		}
-		if root == from || strings.HasPrefix(root, from+"/") {
-			return true
-		}
-	}
-	return false
-}
-
-// suggestRewrites matches each arr root to the Silo folder sharing the most
-// trailing path segments (unique winner). Roots already handled by an existing
-// rewrite are reported as Covered; roots with no shared segment as Unmatched;
-// ties as Ambiguous. Pure: no I/O, no deployment constants.
-func suggestRewrites(arrRoots, siloFolderPaths []string, existing []PathRewrite) RewriteSuggestions {
-	siloNorm := make([]string, 0, len(siloFolderPaths))
-	siloSegs := make([][]string, 0, len(siloFolderPaths))
-	for _, p := range siloFolderPaths {
-		n := normalizePath(p)
-		if n == "" {
-			continue
-		}
-		siloNorm = append(siloNorm, n)
-		siloSegs = append(siloSegs, segments(n))
-	}
-
-	var out RewriteSuggestions
-	for _, raw := range arrRoots {
-		root := normalizePath(raw)
-		if root == "" {
-			continue
-		}
-		if coveredBy(root, existing) {
-			out.Covered = append(out.Covered, root)
-			continue
-		}
-		rootSegs := segments(root)
-		best := 0
-		var winners []string
-		for i, segs := range siloSegs {
-			n := commonSuffixLen(rootSegs, segs)
-			if n == 0 {
-				continue
-			}
-			if n > best {
-				best, winners = n, []string{siloNorm[i]}
-			} else if n == best {
-				winners = append(winners, siloNorm[i])
-			}
-		}
-		switch {
-		case best == 0:
-			out.Unmatched = append(out.Unmatched, root)
-		case len(winners) == 1:
-			out.Proposed = append(out.Proposed, ProposedRewrite{From: root, To: winners[0], MatchDepth: best})
-		default:
-			out.Ambiguous = append(out.Ambiguous, AmbiguousRoot{Root: root, Candidates: winners})
-		}
-	}
-	return out
-}
-```
-
- [ ] **Step 1.4: Run it — expect pass; commit**
-
-```bash
-go test ./internal/autoscan/ -run 'TestSuggestRewrites|TestCommonSuffixLen' -v
-gofmt -l internal/autoscan/suggest.go internal/autoscan/suggest_test.go
-git add internal/autoscan/suggest.go internal/autoscan/suggest_test.go
-git commit -m "feat(autoscan): suffix-match rewrite suggester"
-```
-
---
-
-## Phase 2 — Service support
-
-### Task 2: Repository.GetSource
-
-**Files:**
- Modify: `internal/autoscan/repository.go`
-
- [ ] **Step 2.1: Implement** `GetSource` (single-source join, includes disabled). Add after `ListEnabledSources`:
-```go
-// GetSource returns one instance's autoscan state joined with its
-// request_integrations row (kind/base_url/api_key_ref), regardless of enabled.
-func (r *Repository) GetSource(ctx context.Context, integrationID string) (*Source, error) {
-	row := r.pool.QueryRow(ctx, sourceSelect+` WHERE ri.id = $1`, integrationID)
-	src, err := scanSource(row)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, fmt.Errorf("%w: %s", ErrIntegrationNotFound, integrationID)
-		}
-		return nil, fmt.Errorf("get autoscan source: %w", err)
-	}
-	return &src, nil
-}
-```
-(`errors`, `pgx`, `fmt`, `ErrIntegrationNotFound`, and `sourceSelect`/`scanSource` already exist in the file.)
-
- [ ] **Step 2.2: Build + commit**
-
-```bash
-go build ./internal/autoscan/... && go test ./internal/autoscan/...
-git add internal/autoscan/repository.go
-git commit -m "feat(autoscan): GetSource single-source lookup"
-```
-
-### Task 3: RootFolderClient + FolderLister adapters
-
-**Files:**
- Create: `internal/autoscan/suggest_deps.go`
-
- [ ] **Step 3.1: Implement the two adapters + interfaces**
-```go
-package autoscan
-
-import (
-	"context"
-	"net/http"
-
-	"github.com/Silo-Server/silo-server/internal/catalog"
-	"github.com/Silo-Server/silo-server/internal/requests/arrclient"
-)
-
-// RootFolderClient lists a Radarr/Sonarr instance's configured root folder paths.
-type RootFolderClient interface {
-	RootFolders(ctx context.Context, baseURL, apiKey string) ([]string, error)
-}
-
-// FolderLister lists every Silo media-folder path.
-type FolderLister interface {
-	ListFolderPaths(ctx context.Context) ([]string, error)
-}
-
-type arrRootFolderClient struct{ httpClient *http.Client }
-
-// NewArrRootFolderClient returns a RootFolderClient backed by the shared arrclient.
-func NewArrRootFolderClient(httpClient *http.Client) RootFolderClient {
-	return &arrRootFolderClient{httpClient: httpClient}
-}
-
-func (c *arrRootFolderClient) RootFolders(ctx context.Context, baseURL, apiKey string) ([]string, error) {
-	client := arrclient.New(baseURL, apiKey, c.httpClient)
-	folders, err := arrclient.ListRootFolders(ctx, client)
-	if err != nil {
-		return nil, err
-	}
-	paths := make([]string, 0, len(folders))
-	for _, f := range folders {
-		if f.Path != "" {
-			paths = append(paths, f.Path)
-		}
-	}
-	return paths, nil
-}
-
-type catalogFolderLister struct{ repo *catalog.FolderRepository }
-
-// NewCatalogFolderLister adapts catalog.FolderRepository to FolderLister.
-func NewCatalogFolderLister(repo *catalog.FolderRepository) FolderLister {
-	return &catalogFolderLister{repo: repo}
-}
-
-func (l *catalogFolderLister) ListFolderPaths(ctx context.Context) ([]string, error) {
-	folders, err := l.repo.List(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var paths []string
-	for _, f := range folders {
-		paths = append(paths, f.Paths...)
-	}
-	return paths, nil
-}
-```
-Note: `autoscan` already depends on `catalog` (via `scantrigger`) and on `requests/arrclient` (via `history.go`), so these imports add no new module-level coupling and no cycle (`catalog` does not import `autoscan`).
-
- [ ] **Step 3.2: Build + commit**
-
-```bash
-go build ./internal/autoscan/...
-git add internal/autoscan/suggest_deps.go
-git commit -m "feat(autoscan): arr root-folder client + Silo folder lister"
-```
-
-### Task 4: Service.SuggestRewrites
-
-**Files:**
- Modify: `internal/autoscan/service.go`
- Modify: `internal/autoscan/service_test.go`
-
- [ ] **Step 4.1: Write the failing test** (append to `service_test.go`):
-```go
-type fakeRootFolders struct {
-	paths []string
-	err   error
-}
-
-func (f fakeRootFolders) RootFolders(context.Context, string, string) ([]string, error) {
-	return f.paths, f.err
-}
-
-type fakeFolderLister struct{ paths []string }
-
-func (f fakeFolderLister) ListFolderPaths(context.Context) ([]string, error) { return f.paths, nil }
-
-type sourceGetterStore struct {
-	fakeStore
-	src *Source
-}
-
-func (s *sourceGetterStore) GetSource(context.Context, string) (*Source, error) { return s.src, nil }
-
-func TestSuggestRewritesService(t *testing.T) {
-	store := &sourceGetterStore{src: &Source{IntegrationID: "i1", Kind: "sonarr", BaseURL: "http://x", APIKeyRef: "k"}}
-	svc := NewService(store, &fakeHistory{}, fakeResolver{}, &recordingQueuer{}, allowSuppressor{}, nil)
-	svc.SetRewriteResolvers(
-		fakeRootFolders{paths: []string{"/mnt/happy/storage2/tvshows1", "/data/Movies"}},
-		fakeFolderLister{paths: []string{"/mnt/media/happy/storage2/tvshows1"}},
-	)
-	got, err := svc.SuggestRewrites(context.Background(), "i1")
-	if err != nil {
-		t.Fatalf("SuggestRewrites: %v", err)
-	}
-	if len(got.Proposed) != 1 || got.Proposed[0].To != "/mnt/media/happy/storage2/tvshows1" {
-		t.Fatalf("proposed=%+v", got.Proposed)
-	}
-	if len(got.Unmatched) != 1 || got.Unmatched[0] != "/data/Movies" {
-		t.Fatalf("unmatched=%+v", got.Unmatched)
-	}
-}
-```
-> The `Store` interface needs a `GetSource` method so the service can call it. Add `GetSource(ctx context.Context, integrationID string) (*Source, error)` to the `Store` interface in `service.go`. `*Repository` already implements it (Task 2). The test's `sourceGetterStore` embeds the existing `fakeStore` and adds `GetSource`. If `fakeStore` does not satisfy the widened interface on its own, that's fine — only `sourceGetterStore` is used here; but ensure the package still compiles (other tests construct `fakeStore` directly and pass it where `Store` is required — add a `GetSource` method to `fakeStore` returning `(nil, nil)` so it still satisfies `Store`).
-
- [ ] **Step 4.2: Run it — expect failure**
-
-```bash
-go test ./internal/autoscan/ -run TestSuggestRewritesService -v
-```
-Expected: FAIL (`SetRewriteResolvers`/`SuggestRewrites` undefined).
-
- [ ] **Step 4.3: Implement** in `service.go`. Add fields + setter + method, and add `GetSource` to `Store`:
-```go
-// add to the Store interface:
-//   GetSource(ctx context.Context, integrationID string) (*Source, error)
-
-// add fields to Service struct:
-//   rootFolders RootFolderClient
-//   folders     FolderLister
-
-// SetRewriteResolvers wires the deps used by SuggestRewrites (optional; only the
-// admin-facing service needs them).
-func (s *Service) SetRewriteResolvers(rootFolders RootFolderClient, folders FolderLister) {
-	s.rootFolders = rootFolders
-	s.folders = folders
-}
-
-// SuggestRewrites matches an instance's arr root folders to Silo media folders.
-func (s *Service) SuggestRewrites(ctx context.Context, integrationID string) (RewriteSuggestions, error) {
-	if s.rootFolders == nil || s.folders == nil {
-		return RewriteSuggestions{}, fmt.Errorf("autoscan: rewrite suggestion not configured")
-	}
-	src, err := s.store.GetSource(ctx, integrationID)
-	if err != nil {
-		return RewriteSuggestions{}, err
-	}
-	apiKey := src.APIKeyRef
-	if s.secrets != nil && apiKey != "" {
-		if resolved, rerr := s.secrets.Get(ctx, apiKey); rerr == nil && resolved != "" {
-			apiKey = resolved
-		}
-	}
-	arrRoots, err := s.rootFolders.RootFolders(ctx, src.BaseURL, apiKey)
-	if err != nil {
-		return RewriteSuggestions{}, fmt.Errorf("autoscan: list arr root folders: %w", err)
-	}
-	siloPaths, err := s.folders.ListFolderPaths(ctx)
-	if err != nil {
-		return RewriteSuggestions{}, fmt.Errorf("autoscan: list silo folders: %w", err)
-	}
-	return suggestRewrites(arrRoots, siloPaths, src.PathRewrites), nil
-}
-```
-Add `GetSource` to `fakeStore` in `service_test.go` (`func (f *fakeStore) GetSource(context.Context, string) (*Source, error) { return nil, nil }`).
-
- [ ] **Step 4.4: Run tests — expect pass; commit**
-
-```bash
-go test ./internal/autoscan/...
-gofmt -l internal/autoscan/service.go internal/autoscan/service_test.go
-git add internal/autoscan/service.go internal/autoscan/service_test.go
-git commit -m "feat(autoscan): Service.SuggestRewrites"
-```
-
---
-
-## Phase 3 — API endpoint
-
-### Task 5: Handler + route
-
-**Files:**
- Modify: `internal/api/handlers/autoscan.go`
- Modify: `internal/api/router.go`
- Modify: `internal/api/handlers/autoscan_test.go`
-
- [ ] **Step 5.1: Extend the handler's service interface + add the handler method**
-
-In `autoscan.go`, add `SuggestRewrites` to the `autoscanTriggerer` interface:
-```go
-type autoscanTriggerer interface {
-	PollOnce(ctx context.Context) error
-	SuggestRewrites(ctx context.Context, integrationID string) (autoscan.RewriteSuggestions, error)
-}
-```
-Add the handler:
-```go
-func (h *AutoscanHandler) HandleRewriteSuggestions(w http.ResponseWriter, r *http.Request) {
-	id := strings.TrimSpace(chi.URLParam(r, "id"))
-	suggestions, err := h.svc.SuggestRewrites(r.Context(), id)
-	if err != nil {
-		if errors.Is(err, autoscan.ErrIntegrationNotFound) {
-			writeError(w, http.StatusNotFound, "not_found", "Autoscan source not found")
-			return
-		}
-		// arr unreachable / bad key / folder list failure
-		writeError(w, http.StatusBadGateway, "arr_unreachable", "Could not load root folders from the arr instance")
-		return
-	}
-	writeJSON(w, http.StatusOK, suggestions)
-}
-```
-(`errors`, `autoscan`, `chi`, `strings`, `writeError`, `writeJSON` already imported.)
-
- [ ] **Step 5.2: Mount the route** in `router.go`, inside the autoscan route block:
-```go
-r.Get("/autoscan/sources/{id}/rewrite-suggestions", autoscanHandler.HandleRewriteSuggestions)
-```
-
- [ ] **Step 5.3: Wire the service deps** in `router.go` where `autoscanSvc` is built (after `autoscan.NewService(...)`):
-```go
-autoscanSvc.SetRewriteResolvers(
-	autoscan.NewArrRootFolderClient(nil),
-	autoscan.NewCatalogFolderLister(deps.FolderRepo),
-)
-```
-(This is inside the existing `if deps.FolderRepo != nil && deps.LibraryScanQueue != nil` block, so `deps.FolderRepo` is non-nil here.)
-
- [ ] **Step 5.4: Update the handler test fake**
-
-In `autoscan_test.go`, the fake satisfying `autoscanTriggerer` (e.g. `fakeAutoscanTriggerer`) gains:
-```go
-func (f *fakeAutoscanTriggerer) SuggestRewrites(context.Context, string) (autoscan.RewriteSuggestions, error) {
-	return autoscan.RewriteSuggestions{}, nil
-}
-```
-Add a test asserting `HandleRewriteSuggestions` returns 200 with JSON for a known id (mirror the existing handler tests).
-
- [ ] **Step 5.5: Verify (limited) + commit**
-
-```bash
-# ensure the Go toolchain is on PATH
-go vet ./internal/autoscan/...
-gofmt -l internal/api/handlers/autoscan.go internal/api/router.go internal/api/handlers/autoscan_test.go
-# internal/api cannot compile here (libvips) — Docker verifies later.
-git add internal/api/handlers/autoscan.go internal/api/router.go internal/api/handlers/autoscan_test.go
-git commit -m "feat(autoscan): rewrite-suggestions endpoint"
-```
-
---
-
-## Phase 4 — Frontend
-
-### Task 6: Types + hook
-
-**Files:**
- Modify: `web/src/api/types.ts`
- Modify: `web/src/hooks/queries/useAutoscan.ts`
-
- [ ] **Step 6.1: Types** — add to `types.ts`:
-```ts
-export interface AutoscanProposedRewrite {
-  from: string;
-  to: string;
-  match_depth: number;
-}
-export interface AutoscanAmbiguousRoot {
-  root: string;
-  candidates: string[];
-}
-export interface AutoscanRewriteSuggestions {
-  proposed: AutoscanProposedRewrite[];
-  unmatched: string[];
-  ambiguous: AutoscanAmbiguousRoot[];
-  covered: string[];
-}
-```
-
- [ ] **Step 6.2: Hook** — add to `useAutoscan.ts` a mutation that fetches suggestions for an id:
-```ts
-export function useAutoscanRewriteSuggestions() {
-  return useMutation({
-    mutationFn: (id: string) =>
-      api<AutoscanRewriteSuggestions>(`/admin/autoscan/sources/${id}/rewrite-suggestions`),
-    onError: (err) =>
-      toast.error(err instanceof Error ? err.message : "Could not sync rewrites from the arr instance"),
-  });
-}
-```
-Match the import/`api`/`toast`/`useMutation` conventions already in the file (it imports `api` and `toast` already; reuse them; import the new type).
-
- [ ] **Step 6.3: Lint + commit**
-
-```bash
-cd web && pnpm exec tsc -b && pnpm run lint && pnpm exec prettier --check src/api/types.ts src/hooks/queries/useAutoscan.ts
-git add web/src/api/types.ts web/src/hooks/queries/useAutoscan.ts
-git commit -m "feat(web): autoscan rewrite-suggestions types and hook"
-```
-
-### Task 7: Sync button + preview in AutoscanSourceEditor
-
-**Files:**
- Modify: `web/src/pages/AdminRequests.tsx`
-
- [ ] **Step 7.1: Add the button + preview**
-
-In `AutoscanSourceEditor`:
- Call `const suggest = useAutoscanRewriteSuggestions();` and add local state `const [preview, setPreview] = useState<AutoscanRewriteSuggestions | null>(null);` and `const [selected, setSelected] = useState<Set<string>>(new Set());`.
- Add a **"Sync from arr"** `Button` beside Save: `onClick={async () => { const s = await suggest.mutateAsync(source.integration_id); setPreview(s); setSelected(new Set(s.proposed.map((p) => p.from))); }}` (disabled while `suggest.isPending`).
- When `preview` is set, render a panel (reuse the file's `Dialog` or an inline bordered panel) with three sections:
-  - **Proposed:** each `proposed[]` row — a checkbox bound to `selected.has(p.from)` (toggle updates the set), `from → to`, and a `Badge` showing confidence: `match_depth >= 2 ? "${match_depth} segments" : "1 segment — weak"` (destructive/secondary variant for weak).
-  - **Unmatched:** muted list of `unmatched[]` ("no Silo match — add manually if needed").
-  - **Ambiguous:** list of `ambiguous[]` (`root` + its `candidates` joined) — info only.
-  - An **"Add selected to rewrites"** button that merges the checked proposals into the editor's existing rewrites state, deduped by `from` (skip any whose `from` already exists), then `setPreview(null)`. Do NOT auto-save — the admin then clicks the existing **Save**.
- Keep the existing manual path-rewrite editor unchanged; sync only appends rows to it.
-
-Reuse existing `Button`/`Badge`/`Field`/`Dialog` primitives and the editor's existing rewrites-state setter.
-
- [ ] **Step 7.2: Lint + commit**
-
-```bash
-cd web && pnpm exec tsc -b && pnpm run lint && pnpm exec prettier --check src/pages/AdminRequests.tsx
-git add web/src/pages/AdminRequests.tsx
-git commit -m "feat(web): autoscan sync-rewrites preview"
-```
-
---
-
-## Phase 5 — Verification
-
-### Task 8: Full verification
-
- [ ] **Step 8.1: Go**
-
-```bash
-# ensure the Go toolchain is on PATH
-go test ./internal/autoscan/... 2>&1 | tail
-go vet ./internal/autoscan/...
-gofmt -l internal/autoscan internal/api/handlers/autoscan.go internal/api/router.go
-```
-Expected: all pass; vet/gofmt clean.
-
- [ ] **Step 8.2: Frontend**
-
-```bash
-cd web && pnpm exec tsc -b && pnpm run lint && pnpm run format:check
-```
-
- [ ] **Step 8.3: Docker build (closes the libvips gap)**
-
-```bash
-docker build --build-arg BUILD_REVISION=$(git rev-parse HEAD) --build-arg BUILD_DIRTY=false -t silo-server:autoscan .
-```
-Expected: exit 0 (handlers + router + frontend compile).
-
- [ ] **Step 8.4: Smoke (optional)**
-
-On a deploy with arr instances configured: open an instance in the Autoscan tab, click **Sync from arr**, confirm the preview shows proposed (with confidence) + unmatched + ambiguous, "Add selected" appends deduped rows, and Save persists them.
-
---
-
-## Self-review notes (resolved)
-
- **Spec §1 matcher** → Task 1 (incl. normalization, covered-first, suffix depth, unlike-deployment fixtures). **§2 endpoint/service** → Tasks 2–5 (`GetSource`, `RootFolderClient`/`FolderLister`, `SuggestRewrites`, endpoint, 404/502 mapping). **§3 frontend** → Tasks 6–7. **§4 testing** → Tasks 1,4,5 + Task 8.
- **Manual-preserving**: sync only *appends* deduped rows to the editor; the admin saves via the existing `PUT` (Task 7). Never auto-writes.
- **Generic**: `suggestRewrites` takes plain string slices, no deployment constants; tests include `/data/Movies` and `/srv/tv` fixtures (Task 1).
- **Optional deps**: `SetRewriteResolvers` keeps `main.go`'s poll service untouched; `SuggestRewrites` errors if unset (Task 4).
- **Type consistency**: `RewriteSuggestions`/`ProposedRewrite`/`AmbiguousRoot` (Go) ↔ `AutoscanRewriteSuggestions`/`AutoscanProposedRewrite`/`AutoscanAmbiguousRoot` (TS); `match_depth` JSON tag matches.
@@ -1,375 +0,0 @@
-# `scan_source.v1` SDK Capability — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a new, additive `scan_source.v1` plugin capability to `silo-plugin-sdk` so the Silo host can pull changed paths from a scan-source plugin on a timer.
-
-**Architecture:** Mirror the existing `scheduled_task.v1` capability exactly — a single-RPC, request/response gRPC service defined in a `.proto`, generated into `pkg/pluginproto`, then registered in three Go helper sites (`capability.KnownTypes`, the `runtime.CapabilityServers` struct, and the `runtime.GRPCPlugin` server registration). Nothing existing is modified in shape; only new symbols are added. Tag a new SDK release so the host and the arr plugin can build against it.
-
-**Tech Stack:** Go, Protocol Buffers (proto3), `buf` codegen (`buf.gen.yaml`), `google.golang.org/protobuf`, `google.golang.org/grpc`, the `hashicorp/go-plugin` runtime the SDK wraps.
-
---
-
-## Prerequisites (read before starting)
-
-This plan targets the **`silo-plugin-sdk`** repository (Go module `github.com/Silo-Server/silo-plugin-sdk`), which is **not currently checked out** in this workspace — only `silo-server` and `silo-plugin-tmdb` are. Before executing:
-
-1. Clone `silo-plugin-sdk` as a writable working copy beside the other repos. Commands below assume **the silo-plugin-sdk repository root is the cwd**.
-2. Ensure the proto toolchain is available: the `make proto` target auto-installs `buf`, `protoc-gen-go@v1.36.11`, and `protoc-gen-go-grpc@v1.6.1` into `$(GO_BIN)`, but it requires the **`protoc`** binary to already be on `PATH` (it errors `protoc is required` otherwise). Install `protoc` if absent.
-3. This SDK is the **long pole**: the silo-server host plan and the arr-plugin plan both depend on the version tagged at the end of this plan (Task 6). Do not start those until this is tagged.
-
-**Pattern reference (current `scheduled_task.v1`, the template this mirrors):**
- Proto: `proto/silo/plugin/v1/scheduled_task.proto`
- Generated: `pkg/pluginproto/silo/plugin/v1/scheduled_task.pb.go` + `scheduled_task_grpc.pb.go`
- Capability const + allowlist: `pkg/pluginsdk/capability/capability.go`
- Runtime wiring: `pkg/pluginsdk/runtime/runtime.go` (struct field, `Client` accessor, `GRPCServer` registration)
- Manifest acceptance test pattern: `pkg/pluginsdk/manifest/manifest_test.go`
-
---
-
-## File Structure
-
-| File | Responsibility | Action |
-|---|---|---|
-| `proto/silo/plugin/v1/scan_source.proto` | The `ScanSource` service + `PollChanges` request/response messages | Create |
-| `pkg/pluginproto/silo/plugin/v1/scan_source.pb.go` | Generated message types | Create (codegen) |
-| `pkg/pluginproto/silo/plugin/v1/scan_source_grpc.pb.go` | Generated client/server stubs | Create (codegen) |
-| `pkg/pluginsdk/capability/capability.go` | `ScanSource` const + add to `KnownTypes` allowlist | Modify |
-| `pkg/pluginsdk/capability/capability_test.go` | Assert `ScanSource` is a known type | Create or Modify |
-| `pkg/pluginsdk/runtime/runtime.go` | `CapabilityServers.ScanSource` field, `Client.ScanSource()` accessor, `GRPCServer` registration | Modify |
-| `pkg/pluginsdk/runtime/runtime_test.go` | Assert a `ScanSource` server registers without error | Create or Modify |
-| `pkg/pluginsdk/manifest/manifest_test.go` | Assert a manifest declaring `scan_source.v1` loads | Modify |
-
---
-
-## Task 1: Define and generate the `scan_source.v1` proto
-
-**Files:**
- Create: `proto/silo/plugin/v1/scan_source.proto`
- Create (via codegen): `pkg/pluginproto/silo/plugin/v1/scan_source.pb.go`, `pkg/pluginproto/silo/plugin/v1/scan_source_grpc.pb.go`
-
- [ ] **Step 1: Write the proto**
-
-Create `proto/silo/plugin/v1/scan_source.proto` (the `go_package` option must match the sibling protos exactly so generated code lands in package `pluginv1`):
-
-```proto
-syntax = "proto3";
-
-package silo.plugin.v1;
-
-option go_package = "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1;pluginv1";
-
-// ScanSource lets the host pull changed filesystem paths from a provider
-// (e.g. Sonarr/Radarr, inotify, Ceph). Pull only: the host owns the timer and
-// calls PollChanges; the plugin never initiates.
-service ScanSource {
-  rpc PollChanges(PollChangesRequest) returns (PollChangesResponse);
-}
-
-message PollChangesRequest {
-  // Which configured scan_source capability instance is being polled.
-  string capability_id = 1;
-  // Opaque continuation token from the previous PollChanges. Empty on first
-  // run, which the provider treats as "start from now" (do not replay history).
-  string marker = 2;
-}
-
-message PollChangesResponse {
-  // Absolute paths already translated into Silo's filesystem namespace (the
-  // plugin has applied its own path rewrites). Files or directories.
-  repeated string changed_paths = 1;
-  // Opaque continuation token. The host stores it verbatim and echoes it back
-  // on the next PollChanges; the host never parses it.
-  string next_marker = 2;
-}
-```
-
- [ ] **Step 2: Generate the Go code**
-
-Run: `make proto`
-Expected: exits 0; creates `pkg/pluginproto/silo/plugin/v1/scan_source.pb.go` and `scan_source_grpc.pb.go`. (If it prints `protoc is required`, install `protoc` and re-run.)
-
- [ ] **Step 3: Verify the generated symbols exist and compile**
-
-Run: `go build ./... && grep -l "func NewScanSourceClient" pkg/pluginproto/silo/plugin/v1/scan_source_grpc.pb.go && grep -l "RegisterScanSourceServer" pkg/pluginproto/silo/plugin/v1/scan_source_grpc.pb.go`
-Expected: build succeeds; both `grep`s print the filename (confirming `ScanSourceClient`, `ScanSourceServer`, `NewScanSourceClient`, `RegisterScanSourceServer` were generated — `require_unimplemented_servers=false` in `buf.gen.yaml` means no forced `UnimplementedScanSourceServer` embedding).
-
- [ ] **Step 4: Commit**
-
-```bash
-git add proto/silo/plugin/v1/scan_source.proto pkg/pluginproto/silo/plugin/v1/scan_source.pb.go pkg/pluginproto/silo/plugin/v1/scan_source_grpc.pb.go
-git commit -m "feat(proto): add scan_source.v1 capability service"
-```
-
---
-
-## Task 2: Register the capability type in the allowlist
-
-The manifest loader rejects capability types not in `capability.KnownTypes` (see `TestLoadRejectsUnknownCapabilityType`). A manifest declaring `scan_source.v1` cannot load until the type is registered here.
-
-**Files:**
- Modify: `pkg/pluginsdk/capability/capability.go`
- Create or Modify: `pkg/pluginsdk/capability/capability_test.go`
-
- [ ] **Step 1: Write the failing test**
-
-Append to `pkg/pluginsdk/capability/capability_test.go` (create the file with this `package capability` header if it does not exist):
-
-```go
-package capability
-
-import "testing"
-
-func TestScanSourceIsKnownType(t *testing.T) {
-	if ScanSource != "scan_source.v1" {
-		t.Fatalf("ScanSource const = %q, want %q", ScanSource, "scan_source.v1")
-	}
-	found := false
-	for _, k := range KnownTypes {
-		if k == ScanSource {
-			found = true
-			break
-		}
-	}
-	if !found {
-		t.Fatalf("ScanSource (%q) missing from KnownTypes %v", ScanSource, KnownTypes)
-	}
-}
-```
-
- [ ] **Step 2: Run test to verify it fails**
-
-Run: `go test ./pkg/pluginsdk/capability/ -run TestScanSourceIsKnownType -v`
-Expected: FAIL — `undefined: ScanSource` (the const does not exist yet).
-
- [ ] **Step 3: Add the const and allowlist entry**
-
-In `pkg/pluginsdk/capability/capability.go`, add the const inside the existing `const (...)` block (after `EbookBackend`):
-
-```go
-	EbookBackend     = "ebook_backend.v1"
-	ScanSource       = "scan_source.v1"
-```
-
-and add it to the `KnownTypes` slice (append `ScanSource` to the existing list):
-
-```go
-	ScanSource,
-```
-
- [ ] **Step 4: Run test to verify it passes**
-
-Run: `go test ./pkg/pluginsdk/capability/ -run TestScanSourceIsKnownType -v`
-Expected: PASS.
-
- [ ] **Step 5: Commit**
-
-```bash
-git add pkg/pluginsdk/capability/capability.go pkg/pluginsdk/capability/capability_test.go
-git commit -m "feat(capability): register scan_source.v1 as a known capability type"
-```
-
---
-
-## Task 3: Wire the capability into the runtime
-
-Add the `ScanSource` server to `CapabilityServers`, a `Client.ScanSource()` accessor, and the conditional registration in `GRPCServer` — mirroring `ScheduledTask` in `pkg/pluginsdk/runtime/runtime.go`.
-
-**Files:**
- Modify: `pkg/pluginsdk/runtime/runtime.go`
- Create or Modify: `pkg/pluginsdk/runtime/runtime_test.go`
-
- [ ] **Step 1: Write the failing test**
-
-Append to `pkg/pluginsdk/runtime/runtime_test.go` (create with the `package runtime` header if absent). This test constructs a real `*grpc.Server`, supplies a minimal `ScanSource` server, and asserts `GRPCServer` registers it without error:
-
-```go
-package runtime
-
-import (
-	"context"
-	"testing"
-
-	pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1"
-	"google.golang.org/grpc"
-)
-
-type stubScanSource struct{}
-
-func (stubScanSource) PollChanges(context.Context, *pluginv1.PollChangesRequest) (*pluginv1.PollChangesResponse, error) {
-	return &pluginv1.PollChangesResponse{}, nil
-}
-
-func TestGRPCServerRegistersScanSource(t *testing.T) {
-	p := &GRPCPlugin{Servers: CapabilityServers{
-		Runtime:    stubRuntime{},   // existing stub used by sibling runtime tests
-		ScanSource: stubScanSource{},
-	}}
-	srv := grpc.NewServer()
-	if err := p.GRPCServer(nil, srv); err != nil {
-		t.Fatalf("GRPCServer with ScanSource = %v, want nil", err)
-	}
-	if _, ok := srv.GetServiceInfo()["silo.plugin.v1.ScanSource"]; !ok {
-		t.Fatalf("ScanSource service not registered; got %v", srv.GetServiceInfo())
-	}
-}
-```
-
-Note: `GRPCServer` requires `Servers.Runtime` to be non-nil (it errors otherwise). Reuse the existing runtime stub the sibling tests use. If no such stub exists in `runtime_test.go`, add a minimal one:
-
-```go
-type stubRuntime struct{ pluginv1.RuntimeServer }
-```
-
- [ ] **Step 2: Run test to verify it fails**
-
-Run: `go test ./pkg/pluginsdk/runtime/ -run TestGRPCServerRegistersScanSource -v`
-Expected: FAIL — `unknown field 'ScanSource' in struct literal of type CapabilityServers` (the field does not exist yet).
-
- [ ] **Step 3: Add the struct field**
-
-In `pkg/pluginsdk/runtime/runtime.go`, add to the `CapabilityServers` struct (after the `ScheduledTask` field):
-
-```go
-	ScheduledTask    pluginv1.ScheduledTaskServer
-	ScanSource       pluginv1.ScanSourceServer
-```
-
- [ ] **Step 4: Add the `Client` accessor**
-
-After the existing `func (c *Client) ScheduledTask() ...` method, add:
-
-```go
-func (c *Client) ScanSource() pluginv1.ScanSourceClient {
-	return pluginv1.NewScanSourceClient(c.conn)
-}
-```
-
- [ ] **Step 5: Add the conditional registration in `GRPCServer`**
-
-In `func (p *GRPCPlugin) GRPCServer(...)`, after the `ScheduledTask` registration block, add:
-
-```go
-	if p.Servers.ScheduledTask != nil {
-		pluginv1.RegisterScheduledTaskServer(server, p.Servers.ScheduledTask)
-	}
-	if p.Servers.ScanSource != nil {
-		pluginv1.RegisterScanSourceServer(server, p.Servers.ScanSource)
-	}
-```
-
- [ ] **Step 6: Run test to verify it passes**
-
-Run: `go test ./pkg/pluginsdk/runtime/ -run TestGRPCServerRegistersScanSource -v`
-Expected: PASS.
-
- [ ] **Step 7: Commit**
-
-```bash
-git add pkg/pluginsdk/runtime/runtime.go pkg/pluginsdk/runtime/runtime_test.go
-git commit -m "feat(runtime): serve and dial scan_source.v1 capability"
-```
-
---
-
-## Task 4: Prove a `scan_source.v1` manifest loads
-
-Guards the end-to-end path: a plugin manifest declaring the new capability must pass the loader (it would not before Task 2's allowlist entry).
-
-**Files:**
- Modify: `pkg/pluginsdk/manifest/manifest_test.go`
-
- [ ] **Step 1: Write the failing test**
-
-The test file is package `manifest_test` (external) and loads from a JSON literal via `manifest.Load([]byte)`. Append this test, mirroring `TestLoadAcceptsRequestRouterCapability` exactly with the type swapped to `scan_source.v1`:
-
-```go
-func TestLoadAcceptsScanSourceCapability(t *testing.T) {
-	raw := []byte(`{
-	  "plugin_id": "silo.example",
-	  "version": "1.0.0",
-	  "silo_api_version": "v1",
-	  "capabilities": [
-	    {"type": "scan_source.v1", "id": "arr", "display_name": "X", "description": "Y"}
-	  ]
-	}`)
-	m, err := manifest.Load(raw)
-	if err != nil {
-		t.Fatalf("Load returned unexpected error: %v", err)
-	}
-	if len(m.GetCapabilities()) != 1 {
-		t.Fatalf("expected 1 capability, got %d", len(m.GetCapabilities()))
-	}
-	if got := m.GetCapabilities()[0].GetType(); got != "scan_source.v1" {
-		t.Fatalf("capability type = %q, want scan_source.v1", got)
-	}
-}
-```
-
- [ ] **Step 2: Run test to verify it fails (before this task's dependency was in place) / passes now**
-
-Run: `go test ./pkg/pluginsdk/manifest/ -run TestLoadAcceptsScanSourceCapability -v`
-Expected: PASS (Task 2 already added `scan_source.v1` to `KnownTypes`). If it FAILS with an unknown-capability-type error, Task 2 was not completed correctly — fix that first.
-
- [ ] **Step 3: Commit**
-
-```bash
-git add pkg/pluginsdk/manifest/manifest_test.go
-git commit -m "test(manifest): accept scan_source.v1 capability in manifests"
-```
-
---
-
-## Task 5: Full build + test sweep
-
-**Files:** none (verification only)
-
- [ ] **Step 1: Build everything**
-
-Run: `go build ./...`
-Expected: exits 0.
-
- [ ] **Step 2: Run the full SDK test suite**
-
-Run: `go test ./...`
-Expected: all packages `ok`. Confirms the additive change broke no existing capability, manifest, or runtime test.
-
- [ ] **Step 3: Vet + format**
-
-Run: `go vet ./... && gofmt -l pkg proto 2>/dev/null; test -z "$(gofmt -l pkg)"`
-Expected: vet clean; `gofmt -l pkg` prints nothing.
-
---
-
-## Task 6: Tag the release
-
-Downstream repos (silo-server host, arr plugin) consume the SDK as a tagged module version.
-
-**Files:** none (release action)
-
- [ ] **Step 1: Confirm the version to tag**
-
-Check the latest tag: `git tag --list 'v*' | sort -V | tail -3`. The current consumed version is `v0.4.0`; this additive feature warrants a minor bump to **`v0.5.0`** (no breaking changes).
-
- [ ] **Step 2: Tag and push**
-
-```bash
-git tag v0.5.0
-git push origin v0.5.0
-```
-
- [ ] **Step 3: Record the contract for downstream plans**
-
-Note in the host and arr-plugin plans that they must require `github.com/Silo-Server/silo-plugin-sdk v0.5.0` and use:
- `capability.ScanSource` (`"scan_source.v1"`)
- `runtime.CapabilityServers{ ScanSource: <impl> }` (plugin side)
- `client.ScanSource()` → `pluginv1.ScanSourceClient.PollChanges(ctx, &pluginv1.PollChangesRequest{CapabilityId, Marker})` (host side)
- response fields `PollChangesResponse.ChangedPaths []string`, `PollChangesResponse.NextMarker string`
-
---
-
-## Self-Review notes
-
- **Spec coverage:** Implements spec §5 (the `scan_source.v1` contract: `PollChanges`, opaque marker, Silo-native paths) and §11 (additive-only; registered in `KnownTypes`; no existing capability modified). Spec §12 build-order step 1 (tag the SDK) is Task 6.
- **Out of scope here:** the host engine (spec §7), connections (§8), the Autoscan category (§9), and the arr plugin (§10) are separate per-repo plans built against the `v0.5.0` tag produced by Task 6.
- **Marker is opaque end-to-end:** the proto carries `marker`/`next_marker` as plain strings with no server-side interpretation, satisfying the "any provider's bookmark" requirement.
@@ -1,265 +0,0 @@
-# Sonarr/Radarr Scan-Source Plugin Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build a new installable Silo plugin that implements `scan_source.v1` for Sonarr/Radarr: when the host pulls, it polls arr `/history`, extracts imported + renamed paths, applies its own path rewrites, and returns Silo-native paths + a marker.
-
-**Architecture:** A standalone Go module structured like `silo-plugin-tmdb` — a `manifest.json` declaring `scan_source.v1`, a `main.go` serving `runtime.CapabilityServers{Runtime, ScanSource}` via `runtime.Serve`, and the arr-specific logic ported from the closed silo-server PR #43 (`internal/autoscan/history.go`, `rewrite.go`, `suggest.go`).
-
-**Tech Stack:** Go, `github.com/Silo-Server/silo-plugin-sdk` (`v0.5.0`, the `scan_source.v1` capability), `hashicorp/go-plugin` runtime (via the SDK), arr HTTP API (`X-Api-Key`).
-
-Commands assume the **new plugin repository root** is the cwd (the `silo-plugin-autoscan-arr` checkout, a sibling of this repo like the `silo-plugin-sdk` checkout).
-
---
-
-## Prerequisites
-
-1. **SDK `v0.5.0`.** Needs `scan_source.v1` from `silo-plugin-sdk` PR #2. Until tagged, depend on the local checkout via replace:
-   ```bash
-   go mod edit -replace github.com/Silo-Server/silo-plugin-sdk=../silo-plugin-sdk
-   ```
-   This points at the `silo-plugin-sdk` checkout (a sibling of this repo). Task 8 finalizes to `v0.5.0`.
-2. **Template:** the `silo-plugin-tmdb` checkout (a sibling of this repo) — copy its `main.go` runtime scaffold, `Makefile`, and `manifest.json` shape.
-3. **Salvage source:** the arr logic is on silo-server `main` at `internal/autoscan/history.go` (imports + renames extraction, bounded window), `rewrite.go` (`applyRewrites`, `normalizeSeparators`), `suggest.go`/`suggest_deps.go` (root-folder suffix-match suggester). Port these verbatim where possible.
-4. **New repo:** create `Silo-Server/silo-plugin-autoscan-arr` (or fork pattern). The plugin is registered in the `silo-plugins` catalog in a separate follow-up (Task 9 notes it).
-
---
-
-## File Structure
-
-| File | Responsibility | Action |
-|---|---|---|
-| `go.mod` | module `github.com/Silo-Server/silo-plugin-autoscan-arr`; SDK dep | Create |
-| `manifest.json` | declares `scan_source.v1` capability + `global_config_schema` (path rewrites only; connection arrives per request) | Create |
-| `main.go` | `runtimeServer` (GetManifest/Configure) + `scanSourceServer` (PollChanges); `runtime.Serve` | Create |
-| `internal/arr/history.go` | poll `/history`, imports + renames, bounded window | Create (port) |
-| `internal/arr/rewrite.go` | `applyRewrites`, `normalizeSeparators` | Create (port) |
-| `internal/arr/client.go` | arr HTTP client (`X-Api-Key`, response cap, timeout) | Create |
-| `internal/config/config.go` | parse Configure payload → `{rewrites}` (connection comes per request, not config) | Create |
-| `Makefile` | build (cross-platform), like tmdb | Create |
-
---
-
-## Task 1: Scaffold the plugin (serves an empty `scan_source.v1`)
-
-**Files:** Create `go.mod`, `manifest.json`, `main.go`, `Makefile`.
-
- [ ] **Step 1: Module + SDK dep**
-
-```bash
-go mod init github.com/Silo-Server/silo-plugin-autoscan-arr
-go mod edit -replace github.com/Silo-Server/silo-plugin-sdk=../silo-plugin-sdk   # the silo-plugin-sdk checkout, a sibling of this repo
-go get github.com/Silo-Server/silo-plugin-sdk@v0.4.0   # replace points at the scan_source branch checkout
-```
-
- [ ] **Step 2: manifest.json**
-
-Mirror tmdb's shape, declaring the scan source:
-
-```json
-{
-  "plugin_id": "silo.autoscan.arr",
-  "version": "0.1.0",
-  "checksum": "__CHECKSUM__",
-  "silo_api_version": "v1",
-  "supported_platforms": [
-    {"os": "linux", "arch": "amd64"},
-    {"os": "linux", "arch": "arm64"},
-    {"os": "darwin", "arch": "arm64"}
-  ],
-  "capabilities": [
-    {
-      "type": "scan_source.v1",
-      "id": "arr",
-      "display_name": "Sonarr / Radarr",
-      "description": "Triggers Silo rescans from Sonarr/Radarr import and rename history."
-    }
-  ],
-  "global_config_schema": [
-    {"key": "path_rewrites", "type": "json", "required": false, "display_name": "Path rewrites"}
-  ]
-}
-```
-
-> **Connection is NOT plugin config.** The arr base URL + API key are delivered by the host in each `PollChangesRequest.connection` (resolved from the operator's Autoscan connection — own creds or a reused Requests link). The plugin reads them from the request and stores no credentials. Only path rewrites (and other provider-specific behaviour) live in plugin config.
-
-(Confirm the exact `global_config_schema` entry shape against `silo-plugin-sdk` `pkg/pluginsdk/config` — adapt field names to the SDK's config schema type.)
-
- [ ] **Step 3: main.go scaffold**
-
-Copy tmdb's `runtimeServer` (GetManifest from embedded manifest; Configure stores config) and add a `scanSourceServer` returning empty for now:
-
-```go
-type scanSourceServer struct{ cfg *config.Config }
-
-func (s *scanSourceServer) PollChanges(ctx context.Context, req *pluginv1.PollChangesRequest) (*pluginv1.PollChangesResponse, error) {
-	return &pluginv1.PollChangesResponse{}, nil
-}
-
-func main() {
-	manifest := mustLoadManifest()
-	rt := &runtimeServer{manifest: manifest}
-	runtime.Serve(runtime.ServeConfig{
-		Servers: runtime.CapabilityServers{
-			Runtime:    rt,
-			ScanSource: &scanSourceServer{cfg: rt.cfg},
-		},
-	})
-}
-```
-
- [ ] **Step 4: Build**
-
-Run: `go build ./...`
-Expected: exits 0.
-
- [ ] **Step 5: Commit**
-
-```bash
-git init && git add -A
-git commit -m "feat: scaffold autoscan-arr scan_source.v1 plugin"
-```
-
---
-
-## Task 2: Config parsing (Configure → path rewrites only)
-
-**Files:** Create `internal/config/config.go`, `internal/config/config_test.go`.
-
-> Connection (base_url/api_key) is NOT config — it arrives per poll in `PollChangesRequest.connection` (Task 5). Plugin config carries only path rewrites.
-
- [ ] **Step 1: Failing test**
-
-```go
-func TestParseConfig(t *testing.T) {
-	cfg, err := Parse(map[string]string{
-		"path_rewrites": `[{"from":"/mnt/arr/tv","to":"/mnt/media/tv"}]`,
-	})
-	if err != nil { t.Fatalf("Parse: %v", err) }
-	if len(cfg.Rewrites) != 1 || cfg.Rewrites[0].From != "/mnt/arr/tv" { t.Fatalf("bad rewrites: %+v", cfg.Rewrites) }
-}
-```
-
- [ ] **Step 2: Run → fail.** `go test ./internal/config/` → undefined `Parse`.
-
- [ ] **Step 3: Implement** `Parse(map[string]string) (*Config, error)` with `Config{Rewrites []Rewrite}` where `Rewrite{From, To string}`; unmarshal `path_rewrites` JSON. Wire `runtimeServer.Configure` to store the parsed config so `scanSourceServer` reads the rewrites.
-
- [ ] **Step 4: Run → pass.**
-
- [ ] **Step 5: Commit** `feat(config): parse arr connection and path rewrites`.
-
---
-
-## Task 3: arr history client (imports + renames, bounded window)
-
-**Files:** Create `internal/arr/client.go`, `internal/arr/history.go`, `internal/arr/history_test.go`.
-
-Port from silo-server `main:internal/autoscan/history.go` (the `ChangedPaths` logic: `downloadFolderImported.importedPath`; `episodeFileRenamed`/`movieFileRenamed` → `path` + `sourcePath`; deletes ignored) and the client (`X-Api-Key`, 1 MiB cap, timeout). The marker is an RFC3339 timestamp; empty marker ⇒ "now".
-
- [ ] **Step 1: Failing test** — copy the salvaged `history_test.go` (`TestArrHistoryChangedPaths`: imports + both rename paths returned, `grabbed`/`episodeFileDeleted` ignored), renamed to this package, asserting the returned `(paths, nextMarker)`.
-
- [ ] **Step 2: Run → fail.**
-
- [ ] **Step 3: Implement** `ChangedPaths(ctx, baseURL, apiKey, since time.Time) (paths []string, newest time.Time, err error)` — port `history.go`, additionally returning the newest history timestamp as the next marker. Apply the bounded window (24h max-lookback floor + overlap buffer) here.
-
- [ ] **Step 4: Run → pass.**
-
- [ ] **Step 5: Commit** `feat(arr): poll history for imports and renames`.
-
---
-
-## Task 4: Path rewrites (→ Silo-native paths)
-
-**Files:** Create `internal/arr/rewrite.go`, `internal/arr/rewrite_test.go`.
-
-Port `applyRewrites` (boundary-safe prefix: `path==trimmed || HasPrefix(path, trimmed+"/")`) and `normalizeSeparators` from silo-server `main:internal/autoscan/rewrite.go`.
-
- [ ] **Step 1: Failing test** — copy salvaged `rewrite_test.go` cases.
- [ ] **Step 2: Run → fail.**
- [ ] **Step 3: Implement** the port.
- [ ] **Step 4: Run → pass.**
- [ ] **Step 5: Commit** `feat(arr): boundary-safe path rewrites`.
-
---
-
-## Task 5: Wire `PollChanges` end-to-end
-
-**Files:** Modify `main.go` (`scanSourceServer.PollChanges`), add `main_test.go`.
-
- [ ] **Step 1: Failing test** — a `scanSourceServer` (rewrites configured) called with a `PollChangesRequest` whose `Connection` points at a stub arr server (httptest); assert `PollChanges` with empty marker returns rewritten Silo-native paths and a non-empty `next_marker`, and that the request actually hit the stub at `connection.base_url` with `X-Api-Key: connection.api_key`. A second call with the returned marker queries arr with the right `since`. Also assert a request with a nil/empty `Connection` returns an error (no credentials to poll with).
-
- [ ] **Step 2: Run → fail.**
-
- [ ] **Step 3: Implement** — read the connection from the request, not from config:
-
-```go
-func (s *scanSourceServer) PollChanges(ctx context.Context, req *pluginv1.PollChangesRequest) (*pluginv1.PollChangesResponse, error) {
-	conn := req.GetConnection()
-	if conn == nil || conn.GetBaseUrl() == "" {
-		return nil, fmt.Errorf("scan_source: no connection supplied")
-	}
-	since := time.Time{} // empty marker => now (history client floors to now)
-	if m := req.GetMarker(); m != "" {
-		if t, err := time.Parse(time.RFC3339, m); err == nil { since = t }
-	}
-	raw, newest, err := arr.ChangedPaths(ctx, conn.GetBaseUrl(), conn.GetApiKey(), since)
-	if err != nil { return nil, err }
-	out := make([]string, 0, len(raw))
-	for _, p := range raw {
-		out = append(out, arr.ApplyRewrites(arr.NormalizeSeparators(p), s.cfg.Rewrites))
-	}
-	return &pluginv1.PollChangesResponse{ChangedPaths: out, NextMarker: newest.UTC().Format(time.RFC3339)}, nil
-}
-```
-
- [ ] **Step 4: Run → pass.**
-
- [ ] **Step 5: Commit** `feat: PollChanges returns Silo-native paths from arr history`.
-
---
-
-## Task 6: Rewrite suggester ("Sync from arr") — root folders
-
-**Files:** Create `internal/arr/suggest.go`, `suggest_test.go`.
-
-Port `suggestRewrites` (suffix-match arr root folders → Silo folders) from `main:internal/autoscan/suggest.go`. **Open question (spec §14 risk #2):** how the operator triggers "Sync" and how the plugin reaches Silo's media-folder list.
-
- [ ] **Step 1:** Decide the delivery mechanism — recommended: the plugin reads Silo's folder list via the host library-listing service (`pluginhost` library lister, reachable through the SDK `runtime.Host()` client). Confirm that path exists in `v0.5.0`; if not, scope "Sync" to a follow-up and ship Tasks 1–5 (manual rewrites only) first.
- [ ] **Step 2:** Port the suffix-match suggester + its tests (unique/ambiguous/covered/no-op/normalization cases from `suggest_test.go`).
- [ ] **Step 3:** Expose it — either via an `http_routes.v1` capability the admin UI calls, or as part of the plugin config flow. Document the chosen mechanism.
- [ ] **Step 4:** Tests pass; commit `feat(arr): suffix-match rewrite suggester`.
-
-> If §14 risk #2 is unresolved at execution time, **skip this task**, ship manual rewrites (Tasks 1–5), and file the suggester as a follow-up. The plugin is fully functional without it.
-
---
-
-## Task 7: Cross-repo smoke test against the host
-
-**Files:** none (verification).
-
- [ ] **Step 1:** Build the plugin binary; install it into a dev silo-server (with the Part-1 backend) via the plugin installer.
- [ ] **Step 2:** Configure a source pointing at a real/stub arr; trigger an autoscan poll; confirm the host enqueues a scan for an imported path. (This exercises the full SDK contract end-to-end.)
- [ ] **Step 3:** Note results; no commit unless fixes are needed.
-
---
-
-## Task 8: Finalize SDK dependency
-
- [ ] After `silo-plugin-sdk v0.5.0` is tagged: `go mod edit -dropreplace ...; go get .../silo-plugin-sdk@v0.5.0; go mod tidy; go build ./...`.
- [ ] Commit `build: depend on silo-plugin-sdk v0.5.0`.
- [ ] Do not publish/tag the plugin with a `replace` directive in `go.mod`.
-
---
-
-## Task 9: Catalog registration (follow-up, separate repo)
-
- [ ] Add `silo.autoscan.arr` to the `silo-plugins` catalog manifest so it is installable. This is a separate PR in the `silo-plugins` repo (not this module) — note it; out of scope for this plan's repo.
-
---
-
-## Self-Review notes
-
- **Spec coverage:** §10 (arr plugin: history imports + renames, bounded window, rewrites, Silo-native paths) Tasks 3–5; §5 contract (`PollChanges`, opaque marker = RFC3339 timestamp, first-run "now") Task 5; "Sync from arr" §10/§14-risk-2 Task 6 (with an explicit skip path).
- **Salvage:** history/rewrite/suggest ported from the closed PR (Tasks 3,4,6) — exactly the files the host backend plan deletes (Part-1 Task 8).
- **Risk:** §14 risk #1 (one plugin installation per arr server vs. many) — this plugin holds one connection per installation/config; multiple arr servers ⇒ multiple installs unless the runtime supports multiple capability instances. §14 risk #2 (Sync UI) gated in Task 6 with a clean skip.
- **Type consistency:** `Config{Rewrites}` (no creds — connection arrives in `PollChangesRequest.connection`), `Rewrite{From,To}`, `arr.ChangedPaths(ctx, baseURL, apiKey, since) ([]string, time.Time, error)`, `arr.ApplyRewrites`/`NormalizeSeparators`, `scanSourceServer.PollChanges` consistent across Tasks 2–6.
@@ -1,209 +0,0 @@
-# Autoscan Admin UI Implementation Plan (Part 2 of 2)
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Give Autoscan its own admin category (page + sidebar nav), separate from Requests: manage Connections (reuse a Requests arr server or enter own), Sources (per scan-source plugin: enable, interval, connection), and global settings — backed by the Part-1 v2 API.
-
-**Architecture:** Extract the Autoscan tab out of `AdminRequests.tsx` into a standalone `AdminAutoscan.tsx` page; register a route and a sidebar item; rebuild `useAutoscan.ts` hooks + `types.ts` against the v2 endpoints (`/admin/autoscan/{settings,connections,sources,trigger,status}`).
-
-**Tech Stack:** React + TypeScript, React Query (`@tanstack/react-query`), the project's `ui/` component library (`Tabs`, `Table`, `Card`, etc.), `react-router` routes in `App.tsx`, 2-space indent / double quotes / 100-col (`web/.prettierrc`).
-
-Commands assume the silo-server repository root is the cwd. **Depends on Part 1 (backend)** being implemented (the v2 endpoints must exist).
-
---
-
-## Prerequisites
-
-1. **Part-1 backend merged/available** — the v2 endpoints and response shapes (connections with `request_integration_id`, sources with `marker`/`last_error`, settings with `default_poll_interval_seconds`).
-2. **Reference the existing autoscan tab** at `web/src/pages/AdminRequests.tsx` (the `autoscan` `TabsContent`, the `AutoscanTab`/`AutoscanSourceEditor` components) and hooks at `web/src/hooks/queries/useAutoscan.ts` — these are the starting material; they are reshaped, not discarded.
-3. **Run before MR:** `cd web && pnpm run lint && pnpm run format:check`. Note the 20 pre-existing failing frontend tests are unrelated (project memory); do not be alarmed if they appear — only newly-introduced failures matter.
-
---
-
-## File Structure
-
-| File | Responsibility | Action |
-|---|---|---|
-| `web/src/api/types.ts` | `AutoscanConnection`, `AutoscanSource`, `AutoscanSettings` (v2 shapes) | Modify |
-| `web/src/hooks/queries/useAutoscan.ts` | hooks for settings/connections/sources/trigger/status | Rewrite |
-| `web/src/hooks/queries/keys.ts` | query keys for connections/sources | Modify |
-| `web/src/pages/AdminAutoscan.tsx` | the new standalone Autoscan page (Connections + Sources + Settings tabs) | Create |
-| `web/src/pages/admin/autoscan/ConnectionsPanel.tsx` | list/add/edit/delete connections (own or Requests-linked) | Create |
-| `web/src/pages/admin/autoscan/SourcesPanel.tsx` | per-source enable, interval, connection binding, status | Create |
-| `web/src/pages/AdminRequests.tsx` | remove the Autoscan tab | Modify |
-| `web/src/App.tsx` | add `<Route path="autoscan" element={<AdminAutoscan />} />` | Modify |
-| `web/src/components/AdminSidebar.tsx` | add the Autoscan nav item under "Content" | Modify |
-
---
-
-## Task 1: v2 types + hooks
-
-**Files:** Modify `web/src/api/types.ts`, `web/src/hooks/queries/keys.ts`; rewrite `web/src/hooks/queries/useAutoscan.ts`.
-
- [ ] **Step 1: Types**
-
-Add to `web/src/api/types.ts`:
-
-```ts
-export interface AutoscanSettings {
-  enabled: boolean;
-  default_poll_interval_seconds: number;
-  debounce_seconds: number;
-}
-
-export interface AutoscanConnection {
-  id: string;
-  name: string;
-  kind: string;
-  // present when the connection has its own credentials:
-  base_url?: string;
-  // present when linked to a Requests integration (live reuse):
-  request_integration_id?: string | null;
-  // NOTE: api_key_ref / resolved keys are never sent by the backend.
-}
-
-export interface AutoscanSource {
-  id: string;
-  installation_id: number;
-  capability_id: string;
-  connection_id: string;
-  enabled: boolean;
-  poll_interval_seconds: number | null;
-  last_run_at: string | null;
-  last_error: string | null;
-}
-```
-
- [ ] **Step 2: Hooks**
-
-Rewrite `useAutoscan.ts` with: `useAutoscanSettings`/`useUpdateAutoscanSettings`, `useAutoscanConnections`/`useCreateAutoscanConnection`/`useUpdateAutoscanConnection`/`useDeleteAutoscanConnection`, `useAutoscanSources`/`useUpdateAutoscanSource`, `useAutoscanStatus`, `useTriggerAutoscan`. Follow the existing hook style (the current `useAutoscan.ts` is the template for query/mutation + invalidation). Add query keys in `keys.ts`.
-
- [ ] **Step 3: Typecheck**
-
-Run: `cd web && pnpm exec tsc --noEmit`
-Expected: no type errors in the autoscan files.
-
- [ ] **Step 4: Commit**
-
-```bash
-git add web/src/api/types.ts web/src/hooks/queries/useAutoscan.ts web/src/hooks/queries/keys.ts
-git commit -m "feat(web): autoscan v2 types and query hooks"
-```
-
---
-
-## Task 2: Connections panel
-
-**Files:** Create `web/src/pages/admin/autoscan/ConnectionsPanel.tsx`.
-
- [ ] **Step 1: Build the panel**
-
-A `Card` + `Table` listing connections (name, kind, and a "Reused from Requests" / "Own" badge derived from `request_integration_id`). An "Add connection" dialog offers two modes:
- **Reuse from Requests** — a select populated from the existing request-integrations hook (filter to arr kinds), storing `request_integration_id`.
- **Enter own** — name + URL + API key fields, posting own credentials.
-
-Edit + delete actions per row. Never render any key material (the backend doesn't send it).
-
- [ ] **Step 2: Lint/format/typecheck**
-
-Run: `cd web && pnpm run lint && pnpm exec tsc --noEmit`
-Expected: clean.
-
- [ ] **Step 3: Commit** `feat(web): autoscan connections panel (reuse or own)`.
-
---
-
-## Task 3: Sources panel
-
-**Files:** Create `web/src/pages/admin/autoscan/SourcesPanel.tsx`.
-
- [ ] **Step 1: Build the panel**
-
-A `Table` of sources, one row per installed `scan_source` capability instance: plugin/capability label, a connection `<select>` (bound to `connection_id`), an enable toggle, a poll-interval input (blank = settings default), and a status column (`last_run_at`, `last_error`). Reuse the spinner/"Syncing…" affordances from the old `AutoscanSourceEditor` where relevant. Wire to `useAutoscanSources`/`useUpdateAutoscanSource`.
-
- [ ] **Step 2: Lint/format/typecheck** — clean.
- [ ] **Step 3: Commit** `feat(web): autoscan sources panel`.
-
---
-
-## Task 4: The Autoscan page + global settings + manual trigger
-
-**Files:** Create `web/src/pages/AdminAutoscan.tsx`.
-
- [ ] **Step 1: Compose the page**
-
-A page with a `Tabs` (or sections): **Sources**, **Connections**, **Settings**. Settings = global enable toggle, default poll interval, debounce. A "Run now" button calling `useTriggerAutoscan` (202 → toast "Autoscan triggered"). Mirror the header/layout of `AdminRequests.tsx` for visual consistency.
-
- [ ] **Step 2: Lint/format/typecheck** — clean.
- [ ] **Step 3: Commit** `feat(web): standalone Autoscan admin page`.
-
---
-
-## Task 5: Route + sidebar nav
-
-**Files:** Modify `web/src/App.tsx`, `web/src/components/AdminSidebar.tsx`.
-
- [ ] **Step 1: Route**
-
-In `web/src/App.tsx`, next to `<Route path="requests" element={<AdminRequests />} />` (l.374), add:
-
-```tsx
-<Route path="autoscan" element={<AdminAutoscan />} />
-```
-
-with the matching `import AdminAutoscan from "@/pages/AdminAutoscan";`.
-
- [ ] **Step 2: Sidebar item**
-
-In `web/src/components/AdminSidebar.tsx`, under the **Content** group (after the Requests item, ~l.112), add:
-
-```tsx
-{
-  label: "Autoscan",
-  icon: <RefreshCw className="h-[18px] w-[18px]" />,
-  href: "/admin/autoscan",
-},
-```
-
-(Import an appropriate icon from the icon set already used in the file.)
-
- [ ] **Step 3: Verify navigation**
-
-Run: `cd web && pnpm run build`
-Expected: build succeeds. Manually confirm `/admin/autoscan` renders and the sidebar item highlights.
-
- [ ] **Step 4: Commit** `feat(web): route and sidebar nav for Autoscan category`.
-
---
-
-## Task 6: Remove the Autoscan tab from Requests
-
-**Files:** Modify `web/src/pages/AdminRequests.tsx`.
-
- [ ] **Step 1: Excise the tab**
-
-Remove the `<TabsTrigger value="autoscan">` (l.146) and its `<TabsContent value="autoscan">`, the `AutoscanTab`/`AutoscanSourceEditor` definitions (now superseded by the new panels), and `autoscan` from `ADMIN_REQUEST_TABS`. Remove now-unused imports.
-
- [ ] **Step 2: Lint/format/typecheck/build**
-
-Run: `cd web && pnpm run lint && pnpm run format:check && pnpm run build`
-Expected: clean; build succeeds; no dangling references to removed components.
-
- [ ] **Step 3: Commit** `refactor(web): move Autoscan out of Requests into its own category`.
-
---
-
-## Task 7: Final sweep
-
- [ ] **Step 1:** `cd web && pnpm run lint && pnpm run format:check && pnpm run build` — all clean.
- [ ] **Step 2:** `cd web && pnpm test` — confirm no **newly** failing tests (the 20 pre-existing failures, per project memory, are unrelated; compare against baseline).
- [ ] **Step 3:** Manual pass: add a connection (both modes), bind a source, toggle enable, "Run now", confirm status updates.
-
---
-
-## Self-Review notes
-
- **Spec coverage:** §9 (Autoscan as its own category, decoupled from Requests; Connections reuse-or-own; per-source enable/interval/status) — Tasks 1–6. The reuse-from-Requests UI (Task 2) surfaces the soft link from spec §8.
- **Salvage:** the old `AutoscanTab`/`AutoscanSourceEditor` and `useAutoscan.ts` are reshaped (Tasks 1–3), then the Requests tab is removed (Task 6).
- **Out of scope:** plugin-side config UI (the path-rewrite table lives on the plugin's own settings screen per spec §10 — that is the arr-plugin plan / spec §14 risk #2, not this page).
- **Type consistency:** `AutoscanConnection{request_integration_id?}`, `AutoscanSource{connection_id,poll_interval_seconds,last_error}`, `AutoscanSettings{default_poll_interval_seconds}` used consistently across hooks (Task 1) and panels (Tasks 2–4).
@@ -1,174 +0,0 @@
-# Audiobooks Stacked PR Split Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace the oversized audiobook PR with a stacked series of smaller, reviewable PRs.
-
-**Architecture:** Preserve the existing `feat/audiobooks` work as the source branch, then create branch cut points that expose one logical layer at a time. Each PR targets the previous branch so reviewers see only the incremental diff.
-
-**Tech Stack:** Git, GitHub CLI, Go, pnpm/Vite, PostgreSQL migrations.
-
---
-
-### Task 1: Close The Oversized PR
-
-**Files:**
- Modify: GitHub PR #17 only.
-
- [ ] **Step 1: Post a replacement note**
-
-Run:
-
-```bash
-gh pr comment 17 --repo Silo-Server/silo-server --body 'Closing this oversized PR in favor of a stacked series of smaller PRs. The existing branch is preserved as the source-of-truth while the stack is rebuilt into logical review units.'
-```
-
-Expected: GitHub prints the created comment URL.
-
- [ ] **Step 2: Close PR #17 without deleting the branch**
-
-Run:
-
-```bash
-gh pr close 17 --repo Silo-Server/silo-server
-```
-
-Expected: PR #17 state becomes `CLOSED`; branch `feat/audiobooks` remains available.
-
-### Task 2: Create Stacked Branches
-
-**Files:**
- Modify: remote Git branches only.
-
- [ ] **Step 1: Create branch 1, foundation**
-
-Branch name: `stack/audiobooks-foundation`
-
-Scope:
- audiobook feature flag/settings
- audiobook and podcast schema foundations
- scanner support
- audiobook media item write path
- no native UI
- no ABS listener
-
- [ ] **Step 2: Create branch 2, native UI MVP**
-
-Branch name: `stack/audiobooks-native-ui`
-
-Base: `stack/audiobooks-foundation`
-
-Scope:
- `/api/v1/audiobooks`
- audiobook detail/progress endpoints
- audiobook frontend route/sidebar/player MVP
-
- [ ] **Step 3: Create branch 3, ABS core**
-
-Branch name: `stack/audiobooks-abs-core`
-
-Base: `stack/audiobooks-native-ui`
-
-Scope:
- ABS auth/login/refresh/logout
- ABS listener and feature-flag listener gating
- ABS library/items/play/progress
- ABS access control and security hardening
-
- [ ] **Step 4: Create branch 4, ABS collections**
-
-Branch name: `stack/audiobooks-abs-collections`
-
-Base: `stack/audiobooks-abs-core`
-
-Scope:
- ABS bookmarks
- ABS collections
- ABS playlists
- ABS smart collections
- unified collection migration
-
- [ ] **Step 5: Create branch 5, extras and polish**
-
-Branch name: `stack/audiobooks-extras`
-
-Base: `stack/audiobooks-abs-collections`
-
-Scope:
- podcasts/RSS
- stats
- author/series extras
- catalog audiobook filters/typeahead
- performance and enrichment cleanup
-
-### Task 3: Open The Stacked PRs
-
-**Files:**
- Modify: GitHub PRs only.
-
- [ ] **Step 1: Open PR 1**
-
-Run:
-
-```bash
-gh pr create --repo Silo-Server/silo-server --base main --head stack/audiobooks-foundation --title 'feat(audiobooks): foundation and scanner support' --body 'First PR in the audiobook stack. Adds the schema/settings/scanner foundation without native UI or ABS compatibility.'
-```
-
- [ ] **Step 2: Open PR 2**
-
-Run:
-
-```bash
-gh pr create --repo Silo-Server/silo-server --base stack/audiobooks-foundation --head stack/audiobooks-native-ui --title 'feat(audiobooks): native API and player MVP' --body 'Second PR in the audiobook stack. Adds native Silo audiobook endpoints and the MVP web player UI.'
-```
-
- [ ] **Step 3: Open PR 3**
-
-Run:
-
-```bash
-gh pr create --repo Silo-Server/silo-server --base stack/audiobooks-native-ui --head stack/audiobooks-abs-core --title 'feat(audiobooks): Audiobookshelf compatibility core' --body 'Third PR in the audiobook stack. Adds ABS auth, listener, library/items/play/progress, and security hardening.'
-```
-
- [ ] **Step 4: Open PR 4**
-
-Run:
-
-```bash
-gh pr create --repo Silo-Server/silo-server --base stack/audiobooks-abs-core --head stack/audiobooks-abs-collections --title 'feat(audiobooks): ABS collections, playlists, and smart collections' --body 'Fourth PR in the audiobook stack. Adds ABS bookmarks, collections, playlists, smart collections, and unified collection storage.'
-```
-
- [ ] **Step 5: Open PR 5**
-
-Run:
-
-```bash
-gh pr create --repo Silo-Server/silo-server --base stack/audiobooks-abs-collections --head stack/audiobooks-extras --title 'feat(audiobooks): podcasts, catalog filters, and enrichment polish' --body 'Final PR in the audiobook stack. Adds podcast/RSS extras, audiobook catalog filters/typeahead, and scan/enrichment performance polish.'
-```
-
-### Task 4: Verify And Report
-
-**Files:**
- Modify: none.
-
- [ ] **Step 1: Verify PR states**
-
-Run:
-
-```bash
-gh pr list --repo Silo-Server/silo-server --state open --search 'audiobooks in:title' --json number,title,headRefName,baseRefName,url
-```
-
-Expected: five open stacked PRs with the base/head chain shown above.
-
- [ ] **Step 2: Run branch verification where feasible**
-
-Run:
-
-```bash
-go test ./...
-cd web && pnpm run build
-```
-
-Expected: both commands pass on the final stack tip.
-
@@ -1,617 +0,0 @@
-# TheIntroDB read-path correctness (Phase 1 / Layer A) — implementation plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Fix the three read-path correctness gaps in the TheIntroDB provider so it matches the
-real v3 API contract: (1) honor **TVDB** ids in lookups (today they are silently dropped),
-(2) capture and use the **real per-segment `confidence`** instead of a hardcoded `0.9`, and
-(3) when the API returns multiple candidate segments, **pick the most-submitted / highest-confidence**
-one instead of the first usable. This is Phase 1 of
-[the marker sources & contribution design](../specs/2026-06-06-marker-sources-and-contribution-design.md);
-it stands alone, ships value immediately (anime / TheTVDB-first libraries start getting markers),
-and unblocks the "query-all / best-wins" merge in later phases.
-
-**Architecture:** All changes are contained within `internal/markers/introdb` plus one added
-field on `markers.Marker`. The resolver already populates the TVDB id into
-`Request.ExternalIDs` — only the provider and HTTP client drop it. The HTTP `Client` gains a
-`tvdbID` argument on `FetchEpisode`/`FetchMovie` (query preference `tmdb → tvdb → imdb`, cache
-keys extended); the provider reads `ExternalIDKeyTVDB`; `segmentTimestamps` gains `confidence`
-and `submission_count`; `pickMarker` uses real confidence (with a named default) and ranks
-candidates. The write path (`BuildUpdatePayload` / `UpsertMarkers`) is **not** touched here.
-
-**Out of scope (deferred to Phase 2):** threading *per-segment* confidence through
-`MarkerUpdatePayload` and `UpsertMarkers`. That refactor only becomes observable once
-`Registry.FetchMerged` can combine segments from different providers; with a single provider
-today the existing "max confidence across segments" collapse is equivalent, and changing it now
-would break `TestBuildUpdatePayloadAggregatesConfidence` for no functional gain. It lands with
-the merge dispatch in Phase 2.
-
-**Tech Stack:** Go (the `internal/markers/introdb` package is pure Go — no libvips/CGO),
-PostgreSQL is not involved (no migration), no frontend changes. Tests run in a throwaway Go
-container (the host has no Go toolchain); a named volume caches module downloads.
-
-Commands assume the repository root is the cwd.
-
---
-
-## Running tests (host has no Go toolchain)
-
-`internal/markers` and `internal/markers/introdb` are pure Go, so no libvips is needed:
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/... -v
-```
-
-To run a single test, append `-run TestName` and narrow the package path, e.g.
-`go test ./internal/markers/introdb/ -run TestFetchEpisodeSendsTVDBWhenNoTMDB -v`.
-
---
-
-## File structure
-
- `internal/markers/introdb/types.go` — **modify**. Add `Confidence` + `SubmissionCount` to `segmentTimestamps`; add the `defaultConfidence` const.
- `internal/markers/types.go` — **modify**. Add `SubmissionCount` to `markers.Marker`.
- `internal/markers/introdb/client.go` — **modify**. `tvdbID` arg on `FetchEpisode`/`FetchMovie`; query preference `tmdb → tvdb → imdb`; cache keys include tvdb.
- `internal/markers/introdb/provider.go` — **modify**. Read `ExternalIDKeyTVDB` and pass it through; rewrite `pickMarker` for real confidence + best-candidate.
- `internal/markers/introdb/client_test.go` — **create**. httptest-based client tests (TVDB query, TMDB preference, caching).
- `internal/markers/introdb/provider_test.go` — **create**. End-to-end provider tests (TVDB-only resolves, real/default confidence, best-candidate).
-
-No migration, no wiring change (`cmd/silo/main.go` constructs the provider but never calls the
-client directly), no frontend change.
-
---
-
-## Task 1: Type plumbing — capture confidence + submission_count
-
-**Files:**
- Modify: `internal/markers/introdb/types.go`
- Modify: `internal/markers/types.go`
-
-This task is pure struct plumbing (no behavior yet); later tasks' tests exercise it. Verify by
-compilation.
-
- [ ] **Step 1: Add the response fields + default constant in `introdb/types.go`**
-
-Replace the `Algorithm` const block to add `defaultConfidence` after it:
-
-```go
-// Algorithm is the algorithm tag written alongside markers. The version
-// suffix lets us invalidate or refresh markers if the upstream contract
-// changes.
-const Algorithm = "introdb:v3"
-
-// defaultConfidence is applied when TheIntroDB omits a per-segment confidence
-// in the /media response. Real per-segment confidence is preferred when present.
-const defaultConfidence = 0.9
-```
-
-Replace the `segmentTimestamps` struct with the version that decodes the two extra fields the
-v3 `/media` response carries:
-
-```go
-// segmentTimestamps is the per-occurrence shape returned by TheIntroDB.
-// Either bound may be nil — for intro/recap, start may be omitted (segment
-// begins at file start); for credits/preview, end may be omitted (segment
-// runs to file end). Confidence and SubmissionCount are optional per-segment
-// quality signals used to pick among multiple candidates.
-type segmentTimestamps struct {
-	StartMs         *int64   `json:"start_ms,omitempty"`
-	EndMs           *int64   `json:"end_ms,omitempty"`
-	Confidence      *float64 `json:"confidence,omitempty"`
-	SubmissionCount *int     `json:"submission_count,omitempty"`
-}
-```
-
- [ ] **Step 2: Add `SubmissionCount` to `markers.Marker`**
-
-In `internal/markers/types.go`, replace the `Marker` struct:
-
-```go
-type Marker struct {
-	Kind            MarkerKind
-	Start           time.Duration
-	End             time.Duration
-	Confidence      float64
-	SubmissionCount int
-}
-```
-
- [ ] **Step 3: Verify the packages still compile**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go build ./internal/markers/...
-```
-
-Expected: no output, exit 0. (Existing `write_test.go` / `types_test.go` use field-keyed
-literals, so the added field does not break them.)
-
- [ ] **Step 4: Commit**
-
-```bash
-git add internal/markers/introdb/types.go internal/markers/types.go
-git commit -m "feat(markers): decode introdb per-segment confidence + submission_count"
-```
-
---
-
-## Task 2: TVDB lookups (gap #1)
-
-**Files:**
- Modify: `internal/markers/introdb/client.go`
- Modify: `internal/markers/introdb/provider.go`
- Create: `internal/markers/introdb/client_test.go`
-
- [ ] **Step 1: Write the failing client tests**
-
-Create `internal/markers/introdb/client_test.go`:
-
-```go
-package introdb
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-	"net/url"
-	"sync/atomic"
-	"testing"
-)
-
-func TestFetchEpisodeSendsTVDBWhenNoTMDB(t *testing.T) {
-	var gotQuery url.Values
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotQuery = r.URL.Query()
-		_, _ = w.Write([]byte(`{"type":"episode"}`))
-	}))
-	defer srv.Close()
-
-	c := NewClient("")
-	c.SetBaseURL(srv.URL)
-	if _, err := c.FetchEpisode(context.Background(), "", "55555", "tt1234567", 2, 3, 0); err != nil {
-		t.Fatalf("FetchEpisode: %v", err)
-	}
-	if gotQuery.Get("tvdb_id") != "55555" {
-		t.Errorf("tvdb_id = %q, want 55555", gotQuery.Get("tvdb_id"))
-	}
-	if gotQuery.Get("tmdb_id") != "" {
-		t.Errorf("tmdb_id = %q, want empty", gotQuery.Get("tmdb_id"))
-	}
-	if gotQuery.Get("imdb_id") != "" {
-		t.Errorf("imdb_id should be omitted when tvdb present, got %q", gotQuery.Get("imdb_id"))
-	}
-}
-
-func TestFetchEpisodePrefersTMDBOverTVDBAndIMDB(t *testing.T) {
-	var gotQuery url.Values
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotQuery = r.URL.Query()
-		_, _ = w.Write([]byte(`{"type":"episode"}`))
-	}))
-	defer srv.Close()
-
-	c := NewClient("")
-	c.SetBaseURL(srv.URL)
-	if _, err := c.FetchEpisode(context.Background(), "111", "222", "tt333", 1, 1, 0); err != nil {
-		t.Fatalf("FetchEpisode: %v", err)
-	}
-	if gotQuery.Get("tmdb_id") != "111" {
-		t.Errorf("tmdb_id = %q, want 111", gotQuery.Get("tmdb_id"))
-	}
-	if gotQuery.Get("tvdb_id") != "" || gotQuery.Get("imdb_id") != "" {
-		t.Errorf("only tmdb_id expected, got tvdb=%q imdb=%q", gotQuery.Get("tvdb_id"), gotQuery.Get("imdb_id"))
-	}
-}
-
-func TestFetchMovieSendsTVDB(t *testing.T) {
-	var gotQuery url.Values
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotQuery = r.URL.Query()
-		_, _ = w.Write([]byte(`{"type":"movie"}`))
-	}))
-	defer srv.Close()
-
-	c := NewClient("")
-	c.SetBaseURL(srv.URL)
-	if _, err := c.FetchMovie(context.Background(), "", "888", "", 0); err != nil {
-		t.Fatalf("FetchMovie: %v", err)
-	}
-	if gotQuery.Get("tvdb_id") != "888" {
-		t.Errorf("tvdb_id = %q, want 888", gotQuery.Get("tvdb_id"))
-	}
-}
-
-func TestFetchEpisodeCachesByID(t *testing.T) {
-	var hits int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		atomic.AddInt32(&hits, 1)
-		_, _ = w.Write([]byte(`{"type":"episode"}`))
-	}))
-	defer srv.Close()
-
-	c := NewClient("")
-	c.SetBaseURL(srv.URL)
-	for i := 0; i < 3; i++ {
-		if _, err := c.FetchEpisode(context.Background(), "", "999", "", 1, 1, 0); err != nil {
-			t.Fatalf("FetchEpisode: %v", err)
-		}
-	}
-	if hits != 1 {
-		t.Fatalf("server hits = %d, want 1 (cached after first)", hits)
-	}
-}
-```
-
- [ ] **Step 2: Run the tests to verify they fail**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/introdb/ -run 'TestFetch' -v
-```
-
-Expected: FAIL — compile error (`FetchEpisode`/`FetchMovie` still take the old 6/4-arg
-signatures without `tvdbID`).
-
- [ ] **Step 3: Add `tvdbID` to `FetchEpisode` in `client.go`**
-
-Replace the whole `FetchEpisode` method:
-
-```go
-// FetchEpisode looks up segment timestamps for a TV episode.
-// At least one of tmdbID, tvdbID, or imdbID must be non-empty.
-func (c *Client) FetchEpisode(ctx context.Context, tmdbID, tvdbID, imdbID string, season, episode int, durationMS int64) (*mediaResponse, error) {
-	if tmdbID == "" && tvdbID == "" && imdbID == "" {
-		return nil, fmt.Errorf("introdb: tmdb_id, tvdb_id, or imdb_id required")
-	}
-	if season <= 0 || episode <= 0 {
-		return nil, fmt.Errorf("introdb: episode lookup requires season and episode > 0 (got %d/%d)", season, episode)
-	}
-	q := url.Values{}
-	switch {
-	case tmdbID != "":
-		q.Set("tmdb_id", tmdbID)
-	case tvdbID != "":
-		q.Set("tvdb_id", tvdbID)
-	default:
-		q.Set("imdb_id", imdbID)
-	}
-	q.Set("season", strconv.Itoa(season))
-	q.Set("episode", strconv.Itoa(episode))
-	if durationMS > 0 {
-		q.Set("duration_ms", strconv.FormatInt(durationMS, 10))
-	}
-	return c.fetch(ctx, q, cacheKeyEpisode(tmdbID, tvdbID, imdbID, season, episode, durationMS))
-}
-```
-
- [ ] **Step 4: Add `tvdbID` to `FetchMovie` in `client.go`**
-
-Replace the whole `FetchMovie` method:
-
-```go
-// FetchMovie looks up segment timestamps for a movie.
-// At least one of tmdbID, tvdbID, or imdbID must be non-empty.
-func (c *Client) FetchMovie(ctx context.Context, tmdbID, tvdbID, imdbID string, durationMS int64) (*mediaResponse, error) {
-	if tmdbID == "" && tvdbID == "" && imdbID == "" {
-		return nil, fmt.Errorf("introdb: tmdb_id, tvdb_id, or imdb_id required")
-	}
-	q := url.Values{}
-	switch {
-	case tmdbID != "":
-		q.Set("tmdb_id", tmdbID)
-	case tvdbID != "":
-		q.Set("tvdb_id", tvdbID)
-	default:
-		q.Set("imdb_id", imdbID)
-	}
-	if durationMS > 0 {
-		q.Set("duration_ms", strconv.FormatInt(durationMS, 10))
-	}
-	return c.fetch(ctx, q, cacheKeyMovie(tmdbID, tvdbID, imdbID, durationMS))
-}
-```
-
- [ ] **Step 5: Extend the cache-key helpers in `client.go`**
-
-Replace both `cacheKeyEpisode` and `cacheKeyMovie`:
-
-```go
-func cacheKeyEpisode(tmdbID, tvdbID, imdbID string, season, episode int, durationMS int64) string {
-	switch {
-	case tmdbID != "":
-		return fmt.Sprintf("tmdb:%s:s%de%d:d%d", tmdbID, season, episode, durationMS)
-	case tvdbID != "":
-		return fmt.Sprintf("tvdb:%s:s%de%d:d%d", tvdbID, season, episode, durationMS)
-	default:
-		return fmt.Sprintf("imdb:%s:s%de%d:d%d", imdbID, season, episode, durationMS)
-	}
-}
-
-func cacheKeyMovie(tmdbID, tvdbID, imdbID string, durationMS int64) string {
-	switch {
-	case tmdbID != "":
-		return fmt.Sprintf("tmdb:movie:%s:d%d", tmdbID, durationMS)
-	case tvdbID != "":
-		return fmt.Sprintf("tvdb:movie:%s:d%d", tvdbID, durationMS)
-	default:
-		return fmt.Sprintf("imdb:movie:%s:d%d", imdbID, durationMS)
-	}
-}
-```
-
- [ ] **Step 6: Read TVDB in the provider and pass it through (`provider.go`)**
-
-Replace the id-extraction block in `FetchMarkers` (the `tmdbID`/`imdbID` lines and the empty
-guard):
-
-```go
-	tmdbID := strings.TrimSpace(req.ExternalIDs[markers.ExternalIDKeyTMDB])
-	tvdbID := strings.TrimSpace(req.ExternalIDs[markers.ExternalIDKeyTVDB])
-	imdbID := strings.TrimSpace(req.ExternalIDs[markers.ExternalIDKeyIMDB])
-	if tmdbID == "" && tvdbID == "" && imdbID == "" {
-		return markers.Result{}, nil
-	}
-```
-
-Then update the two client calls in the `switch req.Kind` block to pass `tvdbID`:
-
-```go
-		resp, err = p.client.FetchEpisode(ctx, tmdbID, tvdbID, imdbID, req.SeasonNumber, req.EpisodeNumber, durationMS)
-```
-```go
-		resp, err = p.client.FetchMovie(ctx, tmdbID, tvdbID, imdbID, durationMS)
-```
-
- [ ] **Step 7: Run the client tests to verify they pass**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/introdb/ -run 'TestFetch' -v
-```
-
-Expected: PASS (all four `TestFetch*` tests).
-
- [ ] **Step 8: Commit**
-
-```bash
-git add internal/markers/introdb/client.go internal/markers/introdb/provider.go internal/markers/introdb/client_test.go
-git commit -m "fix(markers): honor TVDB ids in TheIntroDB lookups"
-```
-
---
-
-## Task 3: Real confidence + best-candidate selection (gaps #2, #3)
-
-**Files:**
- Modify: `internal/markers/introdb/provider.go` (`pickMarker`)
- Create: `internal/markers/introdb/provider_test.go`
-
- [ ] **Step 1: Write the failing provider tests**
-
-Create `internal/markers/introdb/provider_test.go`:
-
-```go
-package introdb
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-	"time"
-
-	"github.com/Silo-Server/silo-server/internal/markers"
-)
-
-func newProvider(t *testing.T, body string) *Provider {
-	t.Helper()
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		_, _ = w.Write([]byte(body))
-	}))
-	t.Cleanup(srv.Close)
-	c := NewClient("")
-	c.SetBaseURL(srv.URL)
-	return NewProvider(c)
-}
-
-func episodeReq(ids map[string]string) markers.Request {
-	return markers.Request{
-		Kind:          markers.ItemKindEpisode,
-		ExternalIDs:   ids,
-		SeasonNumber:  1,
-		EpisodeNumber: 1,
-		Duration:      30 * time.Minute,
-	}
-}
-
-func TestProviderResolvesTVDBOnly(t *testing.T) {
-	p := newProvider(t, `{"type":"episode","intro":[{"end_ms":60000}]}`)
-	res, err := p.FetchMarkers(context.Background(), episodeReq(map[string]string{markers.ExternalIDKeyTVDB: "777"}))
-	if err != nil {
-		t.Fatalf("FetchMarkers: %v", err)
-	}
-	if len(res.Markers) != 1 || res.Markers[0].Kind != markers.MarkerKindIntro {
-		t.Fatalf("expected one intro marker, got %+v", res.Markers)
-	}
-}
-
-func TestProviderUsesRealConfidence(t *testing.T) {
-	p := newProvider(t, `{"type":"episode","intro":[{"end_ms":60000,"confidence":0.42}]}`)
-	res, _ := p.FetchMarkers(context.Background(), episodeReq(map[string]string{markers.ExternalIDKeyTMDB: "1"}))
-	if len(res.Markers) != 1 {
-		t.Fatalf("want 1 marker, got %d", len(res.Markers))
-	}
-	if res.Markers[0].Confidence != 0.42 {
-		t.Errorf("confidence = %v, want 0.42 (real value, not hardcoded)", res.Markers[0].Confidence)
-	}
-}
-
-func TestProviderDefaultsConfidenceWhenAbsent(t *testing.T) {
-	p := newProvider(t, `{"type":"episode","intro":[{"end_ms":60000}]}`)
-	res, _ := p.FetchMarkers(context.Background(), episodeReq(map[string]string{markers.ExternalIDKeyTMDB: "1"}))
-	if res.Markers[0].Confidence != defaultConfidence {
-		t.Errorf("confidence = %v, want default %v", res.Markers[0].Confidence, defaultConfidence)
-	}
-}
-
-func TestProviderPicksMostSubmittedCandidate(t *testing.T) {
-	body := `{"type":"episode","intro":[
-		{"end_ms":50000,"confidence":0.6,"submission_count":2},
-		{"end_ms":61000,"confidence":0.5,"submission_count":9}
-	]}`
-	p := newProvider(t, body)
-	res, _ := p.FetchMarkers(context.Background(), episodeReq(map[string]string{markers.ExternalIDKeyTMDB: "1"}))
-	if len(res.Markers) != 1 {
-		t.Fatalf("want 1 marker, got %d", len(res.Markers))
-	}
-	if got := res.Markers[0].End; got != 61*time.Second {
-		t.Errorf("picked end = %v, want 61s (the submission_count=9 candidate)", got)
-	}
-	if res.Markers[0].SubmissionCount != 9 {
-		t.Errorf("submission_count = %d, want 9", res.Markers[0].SubmissionCount)
-	}
-}
-```
-
- [ ] **Step 2: Run the tests to verify they fail**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/introdb/ -run TestProvider -v
-```
-
-Expected: FAIL — `TestProviderUsesRealConfidence` sees `0.9` (hardcoded), `TestProviderPicksMostSubmittedCandidate`
-gets the first usable (`end=50s`, `SubmissionCount=0`). (`TestProviderResolvesTVDBOnly` already
-passes from Task 2 — it guards against regression.)
-
- [ ] **Step 3: Rewrite `pickMarker` in `provider.go`**
-
-Replace the entire `pickMarker` function:
-
-```go
-// pickMarker selects the best usable segment from a TheIntroDB response array.
-// `requireEnd` is true for segments where the end timestamp is the load-bearing
-// field (intro, recap) — they're allowed to start at 0 if `start_ms` is omitted.
-// For trailing segments (credits, preview) the start is required but the end
-// defaults to the file duration. When several candidates are usable (e.g. no
-// duration match narrowed the set), the most-submitted one wins, with higher
-// confidence breaking ties; with a single candidate this is the previous
-// first-usable behavior. Real per-segment confidence is used when present,
-// falling back to defaultConfidence only when the API omits it.
-func pickMarker(stamps []segmentTimestamps, kind markers.MarkerKind, totalDuration time.Duration, requireEnd bool) (markers.Marker, bool) {
-	best := markers.Marker{}
-	bestSubs := -1
-	found := false
-	for _, s := range stamps {
-		start := time.Duration(0)
-		end := totalDuration
-		if s.StartMs != nil {
-			start = time.Duration(*s.StartMs) * time.Millisecond
-		}
-		if s.EndMs != nil {
-			end = time.Duration(*s.EndMs) * time.Millisecond
-		}
-		if requireEnd && s.EndMs == nil {
-			continue
-		}
-		if !requireEnd && s.StartMs == nil {
-			continue
-		}
-		if end <= start {
-			continue
-		}
-		confidence := defaultConfidence
-		if s.Confidence != nil {
-			confidence = *s.Confidence
-		}
-		subs := 0
-		if s.SubmissionCount != nil {
-			subs = *s.SubmissionCount
-		}
-		if !found || subs > bestSubs || (subs == bestSubs && confidence > best.Confidence) {
-			best = markers.Marker{Kind: kind, Start: start, End: end, Confidence: confidence, SubmissionCount: subs}
-			bestSubs = subs
-			found = true
-		}
-	}
-	return best, found
-}
-```
-
- [ ] **Step 4: Run the tests to verify they pass**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/introdb/ -run TestProvider -v
-```
-
-Expected: PASS (all four `TestProvider*` tests).
-
- [ ] **Step 5: Commit**
-
-```bash
-git add internal/markers/introdb/provider.go internal/markers/introdb/provider_test.go
-git commit -m "feat(markers): use real introdb confidence and pick best candidate"
-```
-
---
-
-## Task 4: Full-package regression + integration build
-
-**Files:** none (verification only)
-
- [ ] **Step 1: Run the entire markers test suite**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/... -v
-```
-
-Expected: PASS — the new `introdb` tests plus the existing `write_test.go` /
-`types_test.go` (unchanged behavior: `BuildUpdatePayload` still aggregates max confidence,
-`FetchFirstHit` still uses registration order).
-
- [ ] **Step 2: Build the binary to confirm nothing downstream broke**
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go build ./...
-```
-
-Expected: exit 0. (The only callers of the changed client methods are in `provider.go`, updated
-in Task 2; `cmd/silo/main.go` constructs the provider but never calls the client directly.)
-
- [ ] **Step 3: Confirm the working tree is clean**
-
-```bash
-git status
-```
-
-Expected: clean (all changes committed in Tasks 1–3; this task adds no files).
-
---
-
-## Self-review notes
-
- **Gap coverage:** TVDB lookups (Task 2, `TestFetch*` + `TestProviderResolvesTVDBOnly`), real
-  confidence (Task 3, `TestProviderUsesRealConfidence` + `…DefaultsConfidenceWhenAbsent`),
-  best-candidate (Task 3, `TestProviderPicksMostSubmittedCandidate`). Maps to design gaps #1–#3.
- **Containment:** the client signature change touches exactly one production caller
-  (`provider.go`); `markers.Marker` is constructed only in `provider.go`. Verified by grep before
-  planning, re-verified by the Task 4 `go build ./...`.
- **No behavior regressions:** the write path is untouched, so `BuildUpdatePayload`'s
-  max-confidence aggregation and its test remain valid; per-segment confidence is deferred to
-  Phase 2 where the merge actually consumes it.
- **No placeholders:** every code step shows the complete replacement; every run step shows the
-  command and the expected result. No migration, no frontend, no wiring changes.
- **Default confidence:** `defaultConfidence = 0.9` preserves today's effective value for
-  responses that omit confidence, so existing stored markers keep equivalent provenance.
@@ -1,482 +0,0 @@
-# Marker sources & TheIntroDB contribution — implementation plan (all phases)
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Implement phases in order; each phase is independently shippable.
-
-**Goal:** Implement the design in
-[2026-06-06-marker-sources-and-contribution-design.md](../specs/2026-06-06-marker-sources-and-contribution-design.md):
-fix the TheIntroDB read-path correctness gaps, formalize a multi-source provider model
-(query-all / best-wins), and add the ability to contribute Silo's own markers back to
-TheIntroDB — configured **per provider, off by default**. Server-side API + data model only;
-web UI is a separate follow-up.
-
-**Architecture:** Five sequential phases. Phase 1 fixes the existing provider (TVDB, real
-confidence, best-candidate). Phase 2 adds a per-provider config table, per-segment marker
-provenance, and `Registry.FetchMerged`. Phase 3 adds the submission client, the contribution
-audit table, and the `ContributionService` engine. Phase 4 exposes the full admin API (manual
-markers, provider config, contribute, history). Phase 5 adds the daily auto-contribution task.
-
-**Tech Stack:** Go (chi handlers, pgx repositories), PostgreSQL (paired numbered migrations),
-no frontend in this plan. Most touched packages (`internal/markers`, `internal/markers/introdb`,
-`internal/taskmanager/tasks`) are pure Go; `internal/api/handlers` needs libvips (CGO image
-deps). Tests run in a throwaway Go container (host has no Go toolchain).
-
-Commands assume the repository root is the cwd.
-
---
-
-## Phase overview & dependencies
-
-| Phase | Delivers | Depends on | New migrations |
-|------|----------|-----------|----------------|
-| 1 | TheIntroDB read-path correctness (TVDB, real confidence, best-candidate) | — | none |
-| 2 | `marker_provider_config` + per-segment provenance + `FetchMerged` | 1 (real confidence) | `marker_provider_config` |
-| 3 | Submission client + `marker_contributions` + `ContributionService` | 2 (`Submitter`, provider config) | `marker_contributions` |
-| 4 | Admin API: manual markers, provider config, contribute, history | 3 (service) | none |
-| 5 | Daily auto-contribution task | 3 (service), 4 (optional) | none |
-
-Phase 1's line-level steps are also captured standalone in
-[2026-06-06-marker-introdb-readpath-correctness.md](2026-06-06-marker-introdb-readpath-correctness.md);
-they are summarized here so this document is self-contained.
-
---
-
-## Running tests (host has no Go toolchain)
-
-Pure-Go packages (`internal/markers`, `internal/markers/introdb`, `internal/taskmanager/...`):
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/markers/... -v
-```
-
-`internal/api/handlers` (Phase 4) needs libvips:
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  sh -c 'apt-get update >/dev/null && apt-get install -y --no-install-recommends libvips-dev >/dev/null && go test ./internal/api/handlers/ -run TestAdminMarkers -v'
-```
-
-Whole-project compile: `go build ./...` (same container).
-
---
-
-## Phase 1 — TheIntroDB read-path correctness
-
-**Goal:** Honor TVDB ids, capture/use real per-segment confidence + submission_count, and pick
-the best candidate among multiple. Contained to `internal/markers/introdb` plus one field on
-`markers.Marker`. No migration, no write-path change.
-
-**Files:** `internal/markers/introdb/{types.go,client.go,provider.go}` (modify),
-`internal/markers/types.go` (modify, add `Marker.SubmissionCount`),
-`internal/markers/introdb/{client_test.go,provider_test.go}` (create).
-
-### Task 1.1 — Type plumbing
- [ ] Add `Confidence *float64` and `SubmissionCount *int` to `segmentTimestamps`
-  (`introdb/types.go`); add `const defaultConfidence = 0.9`.
- [ ] Add `SubmissionCount int` to `markers.Marker` (`markers/types.go`).
- [ ] `go build ./internal/markers/...` → exit 0. Commit.
-
-### Task 1.2 — TVDB lookups (gap #1)
- [ ] Create `introdb/client_test.go` (httptest): asserts `tvdb_id` sent when only tvdb given,
-  tmdb preferred over tvdb/imdb, movie tvdb, and cache collapses repeat calls. Run → FAIL (compile).
- [ ] `client.go`: `FetchEpisode`/`FetchMovie` gain a `tvdbID` arg; query preference
-  `tmdb → tvdb → imdb` via a `switch`; the empty-id guard includes tvdb; `cacheKeyEpisode`/
-  `cacheKeyMovie` include a `tvdb:` branch.
- [ ] `provider.go` `FetchMarkers`: read `req.ExternalIDs[markers.ExternalIDKeyTVDB]`, include it
-  in the empty guard, pass it to both client calls.
- [ ] Run client tests → PASS. Commit.
-
-### Task 1.3 — Real confidence + best-candidate (gaps #2, #3)
- [ ] Create `introdb/provider_test.go`: TVDB-only resolves; real confidence used; default when
-  absent; most-submitted candidate wins (ties broken by confidence). Run → FAIL.
- [ ] Rewrite `pickMarker` to use real confidence (fallback `defaultConfidence`), set
-  `SubmissionCount`, and select the candidate with the highest `(submission_count, confidence)`.
- [ ] Run → PASS. Commit.
-
-### Task 1.4 — Regression
- [ ] `go test ./internal/markers/... && go build ./...` → all green (existing `write_test.go`/
-  `types_test.go` unaffected; write path untouched). Commit if needed.
-
-(Full code for every step is in the standalone Phase 1 plan linked above.)
-
---
-
-# Phase 2 — Per-provider config, per-segment provenance, FetchMerged
-
-**Goal:** Add the `marker_provider_config` table that drives which providers are queried (and,
-later, submitted to); make the marker write path carry **per-segment** provider/confidence/
-algorithm so a merged multi-provider result writes correct provenance; add
-`Registry.FetchMerged` (query all enabled providers, keep the best candidate per segment) and
-switch the lazy-playback path to it. With only TheIntroDB enabled, behavior is unchanged.
-
-**Files:**
- Create: `migrations/<next>_marker_provider_config.{up,down}.sql`
- Create: `internal/markers/provider_config.go`, `internal/markers/provider_config_test.go`
- Modify: `internal/markers/types.go` (`Marker.ProviderID`/`Algorithm`; `Registry.FetchMerged`)
- Modify: `internal/markers/write.go` (per-segment provenance in `MarkerUpdatePayload`/`BuildUpdatePayload`)
- Modify: `internal/scanner/file_repo.go` (`MarkerUpdate` + `applySegmentPatch` per-segment provenance)
- Modify: the `markers.MarkerUpdatePayload` → `scanner.MarkerUpdate` conversion (in the lazy-markers handler/adapter)
- Modify: `internal/api/handlers/playback_lazy_markers.go` (call `FetchMerged`)
- Modify: `cmd/silo/main.go` (construct the config store; pass to the registry)
-
-### Task 2.1 — Migration: `marker_provider_config`
- [ ] Write `migrations/<next>_marker_provider_config.up.sql` (use the next free number; latest is 180):
-
-```sql
-CREATE TABLE public.marker_provider_config (
-    provider                  text PRIMARY KEY,
-    fetch_enabled             boolean NOT NULL DEFAULT true,
-    fetch_priority            integer NOT NULL DEFAULT 100,
-    contribute_enabled        boolean NOT NULL DEFAULT false,
-    contribute_auto_local     boolean NOT NULL DEFAULT false,
-    contribute_min_confidence double precision NOT NULL DEFAULT 0.95,
-    updated_at                timestamptz NOT NULL DEFAULT now()
-);
-INSERT INTO public.marker_provider_config (provider, fetch_enabled) VALUES ('introdb', true);
-```
-
- [ ] `.down.sql`: `DROP TABLE public.marker_provider_config;`
- [ ] Commit.
-
-### Task 2.2 — Provider config store
- [ ] Create `internal/markers/provider_config.go`:
-
-```go
-type ProviderConfig struct {
-    Provider                string
-    FetchEnabled            bool
-    FetchPriority           int
-    ContributeEnabled       bool
-    ContributeAutoLocal     bool
-    ContributeMinConfidence float64
-}
-
-// ProviderConfigStore is a cached read/write façade over marker_provider_config.
-// Reads serve from an in-memory snapshot; Update writes through and refreshes.
-type ProviderConfigStore struct { /* pool, mu, cache map[string]ProviderConfig */ }
-
-func NewProviderConfigStore(pool *pgxpool.Pool) *ProviderConfigStore
-func (s *ProviderConfigStore) Reload(ctx context.Context) error            // load all rows into cache
-func (s *ProviderConfigStore) List() []ProviderConfig                       // snapshot copy
-func (s *ProviderConfigStore) Get(provider string) (ProviderConfig, bool)
-func (s *ProviderConfigStore) Update(ctx context.Context, p ProviderConfig) error // upsert + refresh
-// EnabledForFetch returns fetch_enabled providers sorted by (fetch_priority asc, provider asc).
-func (s *ProviderConfigStore) EnabledForFetch() []ProviderConfig
-```
-
- [ ] Hot-reload: subscribe the store's `Reload` to the existing `cache.EventSettingsChanged`
-  Redis channel (mirror the `introdb.api_key` reload wiring in `cmd/silo/main.go`), or add a
-  dedicated `marker_provider_config_changed` event published by `Update`. Either is acceptable;
-  document which.
- [ ] `provider_config_test.go`: with a real/pgxmock pool or an injected fake, assert
-  `EnabledForFetch` filters disabled rows and sorts by priority. Commit.
-
-### Task 2.3 — Per-segment marker provenance (write path)
-
-This makes a merged result (intro from provider A, credits from provider B) persist the correct
-per-segment `*_markers_provider` / `*_markers_confidence` / `*_markers_algorithm`. The DB columns
-already exist; today `applySegmentPatch` applies one shared triple.
-
- [ ] Add to `markers.Marker`: `ProviderID string`, `Algorithm string` (so each segment carries
-  its origin). `provider.go` (Phase 1) sets these from `ProviderID`/`Algorithm` per marker.
- [ ] Rework `markers.MarkerUpdatePayload` (`write.go`) from one shared `Confidence`/`Provider`/
-  `Algorithm` to a per-segment struct, e.g.:
-
-```go
-type SegmentPayload struct { Start, End *float64; Provider *string; Confidence *float64; Algorithm string }
-type MarkerUpdatePayload struct {
-    Intro, Credits, Recap, Preview SegmentPayload
-    Source string // shared source class (e.g. "online"); per-kind provider differs
-}
-```
-
- [ ] Update `BuildUpdatePayload` to fill each `SegmentPayload` from the matching `Marker`
-  (provider/confidence/algorithm per segment). Update `write_test.go`
-  (`TestBuildUpdatePayloadAggregatesConfidence` → assert per-segment confidence: intro 0.7,
-  credits 0.9, recap 0.5).
- [ ] Read `applySegmentPatch` and the `MarkerUpdatePayload → scanner.MarkerUpdate` conversion
-  first, then extend `scanner.MarkerUpdate` + `applySegmentPatch` so each segment's
-  provider/confidence/algorithm come from that segment (not a shared field). `nextSharedMarkerAttribution`
-  keeps populating the legacy shared `markers_source`/`markers_confidence` columns from the
-  highest-confidence applied segment.
- [ ] `go test ./internal/markers/... ./internal/scanner/...` → green. Commit.
-
-### Task 2.4 — `Registry.FetchMerged`
- [ ] Give `Registry` access to the enabled set (constructor takes a `ProviderConfigStore`, or
-  `FetchMerged` takes an `[]ProviderConfig` snapshot). Add:
-
-```go
-// FetchMerged queries every fetch-enabled provider concurrently and keeps, per
-// segment kind, the candidate with the highest (SubmissionCount, Confidence),
-// breaking ties by the provider's fetch_priority. Per-segment ProviderID/
-// Algorithm are preserved so the write path records correct provenance.
-func (r *Registry) FetchMerged(ctx context.Context, req Request) (Result, bool, error)
-```
-
-Algorithm: fan out via goroutines (bounded) to enabled providers; collect `(ProviderConfig,
-Result, error)`; for each `MarkerKind`, choose the best `Marker` across results; assemble a
-`Result` whose `Markers` carry their winning provider's `ProviderID`/`Algorithm`. Log and skip
-provider errors (like `FetchFirstHit`). Return `ok=false` if no segment found.
-
- [ ] `types_test.go`: add a merge test — two fake providers, one wins intro, the other wins
-  credits by submission_count; assert the merged result has both with correct per-segment
-  ProviderID. Keep the existing `FetchFirstHit` tests. Commit.
-
-### Task 2.5 — Switch lazy path + wire store
- [ ] In `internal/api/handlers/playback_lazy_markers.go`, replace the `FetchFirstHit` call in
-  `fetchOnlineMarkersForPlayback` with `FetchMerged`.
- [ ] In `cmd/silo/main.go`, construct `NewProviderConfigStore`, `Reload` it at startup, wire its
-  hot-reload, and pass it to the registry. (TheIntroDB stays registered as today.)
- [ ] `go build ./... && go test ./internal/markers/...` → green. With only `introdb` enabled,
-  `FetchMerged` returns the same result `FetchFirstHit` did — verify a provider test asserting
-  single-provider parity. Commit.
-
---
-
-# Phase 3 — Submission client, contribution tracking, service engine
-
-**Goal:** Build the machinery to submit a marker to a provider, idempotently and audited —
-without yet wiring a trigger. Adds the `Submitter` capability, the introdb submission/stats
-client methods, the `marker_contributions` table, and the `ContributionService`.
-
-**Files:**
- Modify: `internal/markers/types.go` (`Submitter`, `SubmissionRequest`/`SubmissionResult`/`UserStats`)
- Modify: `internal/markers/introdb/{types.go,client.go,provider.go}` (submit + stats; implement `Submitter`)
- Create: `migrations/<next>_marker_contributions.{up,down}.sql`
- Create: `internal/markers/contribution_repo.go`, `internal/markers/contribute.go` (+ tests)
- Modify: `cmd/silo/main.go` (construct the service)
-
-### Task 3.1 — `Submitter` capability + DTOs
- [ ] Add to `internal/markers/types.go`:
-
-```go
-type SubmissionRequest struct {
-    Kind          ItemKind
-    ExternalIDs   map[string]string // tmdb/imdb (tvdb not accepted by /submit; tmdb required)
-    SeasonNumber  int
-    EpisodeNumber int
-    Segment       MarkerKind
-    Start, End    *time.Duration // nil start ok for intro/recap; nil end ok for credits/preview
-    Duration      time.Duration
-}
-type SubmissionResult struct { ID string; Status string; Weight float64 } // status: pending|accepted|rejected
-type UserStats struct { Total, Accepted, Pending, Rejected int; AcceptanceRate float64; CurrentStreak, BestStreak int }
-
-type Submitter interface {
-    Provider
-    SubmitMarker(ctx context.Context, req SubmissionRequest) (SubmissionResult, error)
-    FetchUserStats(ctx context.Context) (UserStats, error)
-}
-```
-
- [ ] Commit (compiles; no implementer yet).
-
-### Task 3.2 — introdb submission client
- [ ] `introdb/types.go`: add the request/response shapes for `POST /v3/submit`
-  (`tmdb_id`,`imdb_id`,`type`,`segment`,`season`,`episode`,`video_duration_ms`,`start_ms`,`end_ms`;
-  response `{submissions:[{id,status,weight,...}]}`) and `GET /v3/user/stats`. Remove the
-  "Submissions are intentionally not supported" package note.
- [ ] `introdb/client.go`: add `SubmitSegment(ctx, ...) (*submitResponse, error)` (POST,
-  `Authorization: Bearer` **required** — return an error if `apiKey == ""`; honor
-  `X-UsageLimit-Reset` on 429) and `FetchUserStats(ctx) (*userStats, error)` (GET).
- [ ] `introdb/provider.go`: implement `markers.Submitter` — map `SubmissionRequest` to the
-  client call (apply the v3 null rules: intro/recap drop a zero start to `null`; credits/preview
-  send `null` end when absent), translate `SubmissionResult`/`UserStats`.
- [ ] `client_test.go`/`provider_test.go`: httptest asserts the submit body shape, bearer header,
-  and that an empty key errors before any HTTP call; stats parse. Commit.
-
-### Task 3.3 — `marker_contributions` table + repo
- [ ] Migration `<next>_marker_contributions.up.sql` (per design §C4):
-
-```sql
-CREATE TABLE public.marker_contributions (
-    id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-    media_file_id      integer NOT NULL REFERENCES media_files(id) ON DELETE CASCADE,
-    provider           text    NOT NULL,
-    segment_kind       text    NOT NULL,
-    source             text    NOT NULL,
-    submitted_start_ms bigint,
-    submitted_end_ms   bigint,
-    video_duration_ms  bigint,
-    content_hash       text    NOT NULL,
-    submission_id      uuid,
-    status             text    NOT NULL,
-    http_status        integer,
-    error              text,
-    submitted_at       timestamptz NOT NULL DEFAULT now(),
-    updated_at         timestamptz NOT NULL DEFAULT now(),
-    UNIQUE (media_file_id, provider, segment_kind, content_hash)
-);
-CREATE INDEX marker_contributions_file_idx ON public.marker_contributions(media_file_id);
-```
-
- [ ] `.down.sql`: drop the table.
- [ ] `internal/markers/contribution_repo.go`: `ContributionStore` with `AlreadySubmitted(ctx,
-  fileID, provider, kind, contentHash) (bool, error)`, `Record(ctx, ContributionRow) error`
-  (upsert on the unique key), `ListByFile(ctx, fileID) ([]ContributionRow, error)`. Add a
-  `ContentHash(kind string, startMs, endMs, durationMs *int64) string` helper (stable SHA-256).
- [ ] Repo test (value-hash idempotency, list). Commit.
-
-### Task 3.4 — `ContributionService`
- [ ] `internal/markers/contribute.go`:
-
-```go
-type ContributionService struct { /* registry, resolver, cfg *ProviderConfigStore, store *ContributionStore, log */ }
-
-// ContributeFile submits the file's eligible markers to enabled submitter providers.
-// opts may scope to one provider and/or specific segment kinds. Auto callers pass
-// requireAutoLocal=true so only providers with contribute_auto_local participate.
-func (s *ContributionService) ContributeFile(ctx context.Context, file *models.MediaFile, opts ContributeOptions) ([]ContributionOutcome, error)
-```
-
-Per provider (from `cfg.List()` filtered to `Submitter` + `contribute_enabled`, and
-`contribute_auto_local` when `opts.Auto`):
-1. **Eligibility (C2):** for each requested segment present on the file, require
-   `source ∈ {scanner, manual}` (skip `online` — circular); resolve external IDs via the existing
-   resolver (skip if none / tmdb required by `/submit`); for auto require `source=scanner`,
-   `kind=intro`, `confidence ≥ contribute_min_confidence`.
-2. **Idempotency:** compute `ContentHash`; skip if `AlreadySubmitted`.
-3. **Submit:** `provider.(Submitter).SubmitMarker(...)`.
-4. **Persist:** `store.Record(...)` with returned status/submission_id (or `status="error"`).
-
- [ ] `contribute_test.go` with a fake `Submitter` + in-memory store: asserts online-sourced
-  markers are skipped, sub-threshold auto markers skipped, duplicates skipped, a fresh manual
-  marker submitted and recorded. Commit.
-
-### Task 3.5 — Wire
- [ ] `cmd/silo/main.go`: construct `ContributionService` (registry, resolver, config store,
-  contribution store). Not yet called by any handler/task. `go build ./...` + tests green. Commit.
-
---
-
-# Phase 4 — Admin API (manual markers, provider config, contribute, history)
-
-**Goal:** Expose the full backend contract under `RequireAdmin`. Mirror the structure of
-`internal/api/handlers/admin_intro.go` (interface-typed deps, `chi.URLParam`, `writeError`/
-`writeJSON`, `MarkerUpdateNotifier` after writes).
-
-**Files:**
- Create: `internal/api/handlers/admin_markers.go` (+ test), `internal/api/handlers/admin_marker_providers.go` (+ test)
- Modify: `internal/api/router.go` (register routes in the `RequireAdmin` group)
- Modify: `cmd/silo/main.go` (construct + inject the handlers)
-
-### Task 4.1 — Manual marker endpoints (design §C3)
- [ ] `admin_markers.go`:
-  - `GET /admin/files/{fileId}/markers` → current per-segment values + provenance
-    (`source`,`provider`,`confidence`,`algorithm`,`detected_at`) for intro/recap/credits/preview.
-  - `PUT /admin/files/{fileId}/markers` → body per segment `{start,end}` (seconds) or `null` to
-    clear; write `source = "manual"` via `scanner.FileRepository.UpsertMarkers` (priority 4);
-    then `MarkerUpdateNotifier.MarkersUpdated(file)`. Validation: `end>start`; intro/recap may
-    omit start; credits/preview may omit end; within `[0, duration]`.
-  - `DELETE /admin/files/{fileId}/markers/{segment}` → clear one segment.
-  - `GET|PUT /admin/items/{id}/markers` → resolve to the item's primary file (convenience).
- [ ] Handler test (libvips container): PUT writes manual markers and returns provenance;
-  invalid range → 400; clear nulls the segment. Commit.
-
-### Task 4.2 — Provider config + validate endpoints (design §C7)
- [ ] `admin_marker_providers.go`:
-  - `GET /admin/markers/providers` → for each registered provider: id, `isSubmitter`, its
-    `marker_provider_config` row, and (best-effort cached) `UserStats` for submitters with a key.
-  - `PUT /admin/markers/providers/{provider}` → update the config row (validated; unknown → 404).
-  - `POST /admin/markers/providers/{provider}/validate` → `Submitter.FetchUserStats`; non-submitter → 400.
- [ ] Test: list returns introdb with its config; update flips `contribute_enabled`; validate on
-  a non-submitter → 400. Commit.
-
-### Task 4.3 — Contribution endpoints (design §C7)
- [ ] In `admin_markers.go` (or a small `admin_contributions.go`):
-  - `POST /admin/files/{fileId}/contribute` (optional body `{provider?, segments?[]}`) →
-    `ContributionService.ContributeFile(...)`; returns per (provider, segment) outcome.
-  - `GET /admin/files/{fileId}/contributions` → `ContributionStore.ListByFile`.
- [ ] Test with a fake service/store. Commit.
-
-### Task 4.4 — Routing + wiring
- [ ] Register all new routes inside the existing `RequireAdmin` group in `internal/api/router.go`
-  (mirror the `redetect-intro` registration). Inject the handlers in `cmd/silo/main.go`.
- [ ] `go build ./... && go test ./internal/api/handlers/ -run 'TestAdminMarkers|TestAdminMarkerProviders'`
-  (libvips container) → green. Commit.
-
---
-
-# Phase 5 — Daily auto-contribution task
-
-**Goal:** A scheduled task that, for each provider with `contribute_enabled &&
-contribute_auto_local`, submits high-confidence local intro detections that haven't been
-contributed. Mirror `internal/taskmanager/tasks/detect_intro_markers.go`.
-
-**Files:** Create `internal/taskmanager/tasks/contribute_markers.go` (+ test); modify
-`cmd/silo/main.go` (register the task).
-
-### Task 5.1 — `ContributeMarkersTask`
- [ ] Implement the `taskmanager.Task` interface (`Key="contribute_markers"`, `Name`,
-  `Description`, `Category=TaskCategoryLibrary`, `IsHidden() bool`, `DefaultTriggers()` daily e.g.
-  `"04:00"` — after the 03:30 detection task, `Execute`).
- [ ] `Execute`: short-circuit if no provider has `contribute_enabled && contribute_auto_local`
-  (read `ProviderConfigStore`). Otherwise page through episode files with
-  `intro_markers_source='scanner'` and `intro_markers_confidence ≥` the provider's
-  `contribute_min_confidence` (a new `ContributionStore`/repo query, batched), and call
-  `ContributionService.ContributeFile(file, ContributeOptions{Auto:true})`. Report progress; obey
-  the introdb usage limit (the client already backs off on `X-UsageLimit-Reset`); idempotency
-  makes interrupted runs resumable.
- [ ] Test with fakes: enabled+auto submits eligible files; disabled → no-op; sub-threshold
-  skipped. Commit.
-
-### Task 5.2 — Register
- [ ] Register the task where `DetectIntroMarkersTask` is registered in `cmd/silo/main.go`.
- [ ] `go build ./... && go test ./internal/taskmanager/...` → green. Commit.
-
---
-
-## Final integration verification
-
-**Files:** none (build + runtime).
-
- [ ] **Build the image** (compiles backend + frontend):
-  ```bash
-  docker build --build-arg BUILD_REVISION=$(git rev-parse --short HEAD) --build-arg BUILD_DIRTY=false -t silo-server:markers-test .
-  ```
- [ ] **Recreate the container** (applies the new migrations on startup) and wait for health:
-  ```bash
-  docker compose up -d silo
-  for i in $(seq 1 24); do s=$(docker inspect -f '{{.State.Health.Status}}' silo-silo-1); echo "$s"; [ "$s" = healthy ] && break; sleep 5; done
-  ```
- [ ] **Verify migrations applied + tables exist:**
-  ```bash
-  docker compose exec -T postgres psql -U silo -d silo -c \
-    "SELECT to_regclass('public.marker_provider_config'), to_regclass('public.marker_contributions');"
-  docker compose exec -T postgres psql -U silo -d silo -c "SELECT * FROM marker_provider_config;"
-  ```
-  Expected: both tables present; an `introdb` row with `fetch_enabled=t, contribute_enabled=f`.
- [ ] **Smoke the read path (TVDB):** trigger playback (or call the marker fetch) for a
-  TVDB-only-matched episode and confirm markers now populate where they previously did not.
- [ ] **Smoke contribution (manual, dry):** enable contribution for introdb against a **test/staging**
-  TheIntroDB key, `PUT` a manual marker on a file, `POST /admin/files/{id}/contribute`, then
-  `GET /admin/files/{id}/contributions` shows a `pending` row; a second contribute is idempotent
-  (no new row). Use a non-production key so test data isn't submitted to the real database.
- [ ] `git status` → clean (all changes committed per phase).
-
---
-
-## Self-review notes
-
- **Phase independence:** each phase compiles, tests, and ships alone; with only `introdb`
-  enabled and contribution off (defaults), Phases 2–5 are observationally inert until an operator
-  enables a provider — so they can land ahead of any behavior change.
- **Per-provider, off by default:** `contribute_enabled`/`contribute_auto_local` default `false`
-  in the migration; the service refuses to submit otherwise; auto additionally gated on
-  `contribute_auto_local`. The `provider` column on `marker_contributions` and the per-provider
-  loop make multi-target submission first-class.
- **Circular-contribution guard:** `source='online'` is never contributed (C2 eligibility) — has
-  a dedicated unit test in Task 3.4.
- **Idempotency:** value `content_hash` + the unique constraint mean repeat/interrupted runs
-  don't double-submit, while a corrected value (new hash) does submit — matching TheIntroDB's
-  weighted-average model.
- **Write-path accuracy:** Task 2.3 requires reading `applySegmentPatch` and the
-  `MarkerUpdatePayload → scanner.MarkerUpdate` conversion before editing; the per-segment columns
-  already exist in `media_files`, so this is a plumbing change, not a schema change.
- **Migration numbers:** `marker_provider_config` and `marker_contributions` take the next two
-  free numbers at implementation time (181+; latest on disk is 180). Re-check for collisions
-  before writing.
- **Out of scope (tracked in the design doc):** all web UI; per-user TheIntroDB accounts; a
-  `marker_provider.v1` plugin capability. Clean seams left for each.
@@ -1,301 +0,0 @@
-# Ebook Reader Full Parity Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Bring the core ebook reader up to the personal reader feature set with server-persisted config, annotations/bookmarks, selection tools, reading aids, and advanced settings.
-
-**Architecture:** Keep ebook reading in core, matching audiobooks: core owns the ebook media type and reader behavior; metadata remains plugin-provided. Extend the existing `/ebooks/{content_id}` reader API and `EbookReaderHandler` rather than creating a separate plugin-style reader subsystem. Persist per-user/per-profile/per-book state in Postgres so settings, annotations, and bookmarks roam across devices.
-
-**Tech Stack:** Go/Chi handlers, pgx/Postgres migrations, React 19, TanStack Query, Foliate/readest reader wrapper, Vitest, Go unit tests.
-
---
-
-## File Structure
-
- `migrations/sql/20260608000300_ebook_reader_state.sql`
-  - Creates `ebook_reader_config` and `ebook_reader_annotations`.
- `internal/api/handlers/ebook_reader.go`
-  - Adds reader config and annotation types, store interfaces, handlers, validation, and Postgres store methods.
- `internal/api/handlers/ebook_reader_test.go`
-  - Adds handler tests for config, annotation CRUD, access scoping, and validation.
- `internal/api/router.go`
-  - Wires config/annotation stores and routes under `/ebooks/{content_id}`.
- `web/src/reader/FoliateBookReader.tsx`
-  - Adds selection/annotation/readable-text/content-popup reader handles and applies saved config.
- `web/src/pages/EbookReader.tsx`
-  - Adds server-backed settings, annotation/bookmark UI, selection tools, TTS controls, wake-lock/e-ink controls, and advanced reader controls.
- `web/src/hooks/useTTS.ts`, `web/src/hooks/useScreenWakeLock.ts`, `web/src/hooks/useEinkMode.ts`
-  - Port focused personal-reader hooks into core web.
- `web/src/reader/ebookReaderApi.ts`
-  - Centralizes reader config and annotation API calls for tests and page usage.
- `web/src/pages/EbookReader.test.tsx`, `web/src/reader/FoliateBookReader.test.ts`
-  - Adds UI and wrapper tests.
-
-## Task 1: Server-Persisted Reader Config
-
-**Files:**
- Create: `migrations/sql/20260608000300_ebook_reader_state.sql`
- Modify: `internal/api/handlers/ebook_reader.go`
- Modify: `internal/api/handlers/ebook_reader_test.go`
- Modify: `internal/api/router.go`
- Create: `web/src/reader/ebookReaderApi.ts`
- Modify: `web/src/pages/EbookReader.tsx`
- Modify: `web/src/pages/EbookReader.test.tsx`
-
- [ ] **Step 1: Write failing Go handler tests**
-
-Add tests that:
- `GET /ebooks/{content_id}/reader-config` returns `{ "config": {} }` when no row exists.
- `PUT /ebooks/{content_id}/reader-config` saves JSON config for the authenticated user/profile/content.
- inaccessible content returns 404 through the existing `ItemAccess` path.
- invalid non-object config returns 400.
-
-Run:
-
-```bash
-go test ./internal/api/handlers -run 'TestEbookReader.*Config' -count=1
-```
-
-Expected: fail because config store/handlers do not exist.
-
- [ ] **Step 2: Add migration**
-
-Create `ebook_reader_config`:
-
-```sql
-CREATE TABLE ebook_reader_config (
-    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    profile_id TEXT NOT NULL,
-    content_id TEXT NOT NULL REFERENCES media_items(content_id) ON DELETE CASCADE,
-    config JSONB NOT NULL DEFAULT '{}'::jsonb,
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, profile_id, content_id)
-);
-
-CREATE INDEX ebook_reader_config_profile_updated
-    ON ebook_reader_config (user_id, profile_id, updated_at DESC);
-```
-
- [ ] **Step 3: Implement config store and handlers**
-
-Add `EbookReaderConfig`, `EbookReaderConfigStore`, `HandleGetConfig`, `HandleSaveConfig`, and `PGEbookReaderConfigStore` methods in `ebook_reader.go`.
-
-Validation:
- authenticated user required
- `content_id` required
- `config` must decode to a JSON object
- content access checked with `FileAuthorizer.ItemAccess.EnsureAccessible`
-
- [ ] **Step 4: Wire routes and store**
-
-In `internal/api/router.go`, create the store when `deps.DB != nil`, assign it to `ebookReaderHandler`, and add:
-
-```go
-r.Get("/{content_id}/reader-config", ebookReaderHandler.HandleGetConfig)
-r.Put("/{content_id}/reader-config", ebookReaderHandler.HandleSaveConfig)
-```
-
- [ ] **Step 5: Add web API wrapper**
-
-Create `web/src/reader/ebookReaderApi.ts` with:
-
-```ts
-export function ebookReaderConfigPath(contentID: string): string
-export async function fetchEbookReaderConfig(contentID: string): Promise<Record<string, unknown>>
-export async function saveEbookReaderConfig(contentID: string, config: Record<string, unknown>): Promise<Record<string, unknown>>
-```
-
- [ ] **Step 6: Move settings persistence from localStorage to server**
-
-Update `EbookReader.tsx` to fetch reader config on load and save settings through the config endpoint. Keep a local fallback only until the server value arrives.
-
- [ ] **Step 7: Verify and commit**
-
-Run:
-
-```bash
-go test ./internal/api/handlers -run 'TestEbookReader.*Config' -count=1
-cd web && pnpm test src/pages/EbookReader.test.tsx src/reader/FoliateBookReader.test.ts --run
-cd web && pnpm build
-```
-
-Commit:
-
-```bash
-git add migrations/sql/20260608000300_ebook_reader_state.sql internal/api/handlers/ebook_reader.go internal/api/handlers/ebook_reader_test.go internal/api/router.go web/src/reader/ebookReaderApi.ts web/src/pages/EbookReader.tsx web/src/pages/EbookReader.test.tsx
-git commit -m "feat: persist ebook reader config"
-```
-
-## Task 2: Server-Persisted Annotations And Bookmarks
-
-**Files:**
- Modify: `migrations/sql/20260608000300_ebook_reader_state.sql`
- Modify: `internal/api/handlers/ebook_reader.go`
- Modify: `internal/api/handlers/ebook_reader_test.go`
- Modify: `internal/api/router.go`
- Modify: `web/src/reader/ebookReaderApi.ts`
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Modify: `web/src/pages/EbookReader.tsx`
-
- [ ] **Step 1: Write failing annotation handler tests**
-
-Cover list, create, update, delete. Test annotation fields:
-
-```json
-{
-  "kind": "highlight",
-  "cfi_range": "epubcfi(/6/4,/1:0,/1:12)",
-  "selected_text": "sample text",
-  "note": "note text",
-  "style": "highlight",
-  "color": "#facc15"
-}
-```
-
-Run:
-
-```bash
-go test ./internal/api/handlers -run 'TestEbookReader.*Annotation|TestEbookReader.*Bookmark' -count=1
-```
-
-Expected: fail because annotation APIs do not exist.
-
- [ ] **Step 2: Add annotation table**
-
-Extend migration with:
-
-```sql
-CREATE TABLE ebook_reader_annotations (
-    id TEXT PRIMARY KEY,
-    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    profile_id TEXT NOT NULL,
-    content_id TEXT NOT NULL REFERENCES media_items(content_id) ON DELETE CASCADE,
-    kind TEXT NOT NULL CHECK (kind IN ('highlight', 'note', 'bookmark')),
-    cfi_range TEXT,
-    location TEXT,
-    selected_text TEXT NOT NULL DEFAULT '',
-    note TEXT NOT NULL DEFAULT '',
-    style TEXT NOT NULL DEFAULT 'highlight',
-    color TEXT NOT NULL DEFAULT '#facc15',
-    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    CHECK ((kind = 'bookmark' AND location IS NOT NULL) OR (kind <> 'bookmark' AND cfi_range IS NOT NULL))
-);
-
-CREATE INDEX ebook_reader_annotations_book
-    ON ebook_reader_annotations (user_id, profile_id, content_id, updated_at DESC);
-```
-
- [ ] **Step 3: Implement annotation store and handlers**
-
-Add handlers:
- `GET /ebooks/{content_id}/annotations`
- `POST /ebooks/{content_id}/annotations`
- `PATCH /ebooks/{content_id}/annotations/{annotation_id}`
- `DELETE /ebooks/{content_id}/annotations/{annotation_id}`
-
- [ ] **Step 4: Wire Foliate annotation drawing and selection**
-
-Extend `FoliateBookReaderHandle` with:
- `createSelectionAnnotation()`
- `clearSelection()`
-
-Draw stored annotations using Foliate `addAnnotation`.
-
- [ ] **Step 5: Add reader UI**
-
-Add:
- selection popover
- highlight button
- note button
- bookmark button
- annotation list in the side panel
- delete/update note controls
-
- [ ] **Step 6: Verify and commit**
-
-Run handler tests, web tests, and build. Commit:
-
-```bash
-git commit -m "feat: add ebook annotations and bookmarks"
-```
-
-## Task 3: Reader Tools, TTS, And Reading Aids
-
-**Files:**
- Create: `web/src/hooks/useTTS.ts`
- Create: `web/src/hooks/useScreenWakeLock.ts`
- Create: `web/src/hooks/useEinkMode.ts`
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Modify: `web/src/pages/EbookReader.tsx`
- Modify: `web/src/pages/EbookReader.test.tsx`
-
- [ ] **Step 1: Port focused hooks from personal reader**
-
-Bring over:
- Web Speech TTS controller
- screen wake lock hook
- e-ink body-class hook
-
- [ ] **Step 2: Add readable text handle**
-
-Expose `getReadableText()` from `FoliateBookReader` for TTS.
-
- [ ] **Step 3: Add UI controls**
-
-Add side-panel controls for:
- Speak current text
- Pause/resume/stop
- voice/rate/pitch
- wake lock
- e-ink mode
-
- [ ] **Step 4: Add content popups and helpers**
-
-Add selection popover actions:
- define
- translate
-
-Add reader content popup handling for footnotes/images/tables when Foliate emits them.
-
- [ ] **Step 5: Verify and commit**
-
-Run focused web tests and build. Commit:
-
-```bash
-git commit -m "feat: add ebook reader tools and aids"
-```
-
-## Task 4: Advanced Reader Settings
-
-**Files:**
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Modify: `web/src/pages/EbookReader.tsx`
- Modify: `web/src/pages/EbookReader.test.tsx`
-
- [ ] **Step 1: Add advanced reader settings**
-
-Add server-persisted settings for:
- RTL
- writing mode
- zoom/scale
- brightness
- hyphenation toggle
- custom font selection/upload if API support is added in a later task
-
- [ ] **Step 2: Verify and commit**
-
-Run focused tests and build. Commit:
-
-```bash
-git commit -m "feat: add ebook advanced reader settings"
-```
-
-## Self-Review
-
- The plan covers server persistence first, matching the user's explicit preference.
- The plan keeps ebook features in core and metadata in plugins, matching the audiobook pattern.
- The plan avoids extra ebook catalog tables; added tables are reader-user-state only.
- The biggest implementation risk is annotation rendering against Foliate selection APIs; Task 2 isolates it after backend persistence exists.
- The migration filename is intentionally after existing ebook migrations and can be adjusted if another migration is added before implementation.
@@ -1,68 +0,0 @@
-# Ebook Reader Shell Parity Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Bring the core ebook reader up to the first useful parity slice from `personal/silo-plugin-ebooks`: TOC, search, progress scrub, reader settings, and keyboard navigation.
-
-**Architecture:** Keep the current core reader API and persistence model. Extend `FoliateBookReader` with imperative methods for TOC, search, href/fraction navigation, and runtime style updates; keep `EbookReader` responsible for the chrome/panels/settings state. Store reader preferences in localStorage for this first local slice so no backend schema is added.
-
-**Tech Stack:** React 19, React Router, TanStack Query, foliate-js custom element, existing Silo UI components, Vitest.
-
---
-
-### Task 1: Reader Handle Capabilities
-
-**Files:**
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Test: `web/src/reader/FoliateBookReader.test.ts`
-
- [ ] Add exported types `ReaderSettings`, `ReaderSearchOptions`, `ReaderSearchResult`, and `ReaderReadyState`.
- [ ] Extend `FoliateBookReaderHandle` with `goToFraction`, `goTo`, `search`, `clearSearch`, and `applySettings`.
- [ ] Add a `settings?: ReaderSettings` prop and convert `readerStyles()` to accept settings.
- [ ] Preserve existing progress save/restore behavior.
- [ ] Verify with `pnpm vitest run src/reader/FoliateBookReader.test.ts`.
-
-### Task 2: TOC and Search Panel
-
-**Files:**
- Modify: `web/src/pages/EbookReader.tsx`
- Test: `web/src/pages/EbookReader.test.tsx`
-
- [ ] Add panel state for `toc`, `searchResults`, `searchTerm`, and current tab.
- [ ] Render side panel tabs for Contents, Search, and Settings.
- [ ] Wire TOC items to `readerRef.current.goTo(href)`.
- [ ] Wire search form to `readerRef.current.search(term)` and result clicks to `goTo(cfi)`.
- [ ] Verify with `pnpm vitest run src/pages/EbookReader.test.tsx`.
-
-### Task 3: Reader Settings
-
-**Files:**
- Modify: `web/src/pages/EbookReader.tsx`
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Test: `web/src/pages/EbookReader.test.tsx`
-
- [ ] Add localStorage-backed settings for theme, font size, font family, line height, margin, max width, spread, and flow.
- [ ] Render compact controls in the Settings tab.
- [ ] Apply settings live through `FoliateBookReader`.
- [ ] Verify settings persist across remount in tests.
-
-### Task 4: Progress Scrub and Keyboard Navigation
-
-**Files:**
- Modify: `web/src/pages/EbookReader.tsx`
- Modify: `web/src/reader/FoliateBookReader.tsx`
- Test: `web/src/pages/EbookReader.test.tsx`
-
- [ ] Add a progress range input in the header.
- [ ] Call `goToFraction` on commit/change and update display from relocate events.
- [ ] Add ArrowLeft/ArrowRight keyboard navigation on the reader page.
- [ ] Verify with page-level tests.
-
-### Task 5: Local Verification
-
-**Files:**
- No source changes.
-
- [ ] Run `cd web && pnpm run build`.
- [ ] Run `GOWORK=off go test ./internal/api/handlers ./internal/scanner`.
- [ ] Keep changes local; do not push.
@@ -1,518 +0,0 @@
-# Encrypt integration credentials at rest (issue #45) — implementation plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Do not edit this plan file while implementing.
-
-**Issue:** [#45 — Encrypt arr integration credentials at rest (Requests + Autoscan)](https://github.com/Silo-Server/silo-server/issues/45)
-
-> **Revision note (post-review):** This plan was revised after a code review. Key corrections baked in:
-> the arr backfill now **resolves the legacy `server_settings` reference before encrypting** (otherwise
-> rows holding a setting-name like `requests.radarr.api_key` would be encrypted as the *name*, not the
-> credential); the sensitive-settings allowlist is **audited from the config loader's real inputs**
-> (incl. `redis.sentinel_password` and legacy `s3.operational_*` aliases) rather than copied from the
-> admin redaction map; AAD binds to **row identity** (`table:column:pk`); read paths **pass through
-> legacy plaintext** and hard-fail only on corrupt ciphertext; `settingsRepo` is **re-wrapped after the
-> max-connections pool recreation**; history-import session tokens are **included**; and
-> `plugin_runtime_configs.config_value` is an **explicit, documented gap** (see Out of scope).
-
-**Goal:** Stop storing third-party integration credentials in plaintext at rest. Today Sonarr/Radarr
-API keys, S3 keys, and a dozen other secrets sit in the database as naked `text` — `request_integrations.api_key_ref`
-and `autoscan_connections.api_key_ref` are resolved through a plaintext `server_settings` key/value
-store, and both resolvers contain a **ref-vs-literal fallback**: when the secret lookup returns empty,
-the stored string is used verbatim as the API key. This plan introduces a real symmetric-encryption
-layer (AES-256-GCM, `SECRET_KEY`-derived via HKDF), encrypts every recoverable server-owned credential
-**inline** in its owning row, deletes the ambiguous resolver fallback, and backfills existing rows
-automatically on startup.
-
-**Decisions (locked with the requester):**
- **Master key:** a **required** `SECRET_KEY` environment variable. The server fatals at startup if it
-  is missing. The key lives outside Postgres, so encrypted secrets survive a full DB compromise/dump.
- **Scope:** **all silo-server-owned credential storage** (was framed "full sweep"). Every recoverable
-  server-owned secret — arr keys, S3 keys, all sensitive `server_settings`, and the per-table token
-  columns — is covered. Two categories are deliberately *not* in this PR because they are a different
-  *shape* of problem, not because they are unimportant: equality-looked-up secrets (need **hashing**,
-  not encryption) and plugin runtime config JSONB (cross-repo + manifest-driven). Both are called out in
-  Out of scope with follow-ups.
- **Data model (best practice):** **inline-encrypted**. Store the ciphertext directly in the owning
-  column and decrypt on read. Drop the `server_settings` "ref" indirection and the `SecretResolver`
-  literal fallback entirely — this kills the ambiguity at its root and matches the repo's one existing
-  good example (`oauth_completion.token_ciphertext` lives inline in its own row).
- **Rollout:** idempotent Go startup **backfill** encrypts any plaintext (no-envelope-prefix) value in
-  place on first boot after deploy. No manual steps.
-
-**Architecture:** A new `internal/secret` package owns the one cryptographic primitive everything reuses:
-AES-256-GCM with a random 12-byte nonce, `base64.RawURLEncoding`, and a versioned `enc:v1:` envelope
-prefix; the data key is HKDF-SHA256–derived from `SECRET_KEY` with a domain label. Each ciphertext is
-GCM-bound to its logical **row** via additional-authenticated-data (`"table:column:<pk>"`, or
-`"server_settings:<key>"`) so a DB-write attacker cannot transplant a credential blob into another row
-or column. Three wiring seams consume the cipher: (1) an `EncryptedSettingsRepo` **decorator** around
-`catalog.ServerSettingsRepo` that transparently encrypts/decrypts the sensitive `server_settings` keys,
-so `config.LoadFromDB` and every downstream consumer keep seeing plaintext; (2) the two `api_key_ref`
-columns become inline ciphertext and the entire `SecretResolver` indirection is deleted from
-`internal/requests` and `internal/autoscan`; (3) a handful of per-table repos gain a `*secret.Cipher`
-and encrypt-on-write / decrypt-on-read. A startup backfill sweeps all groups idempotently — with a
-**special resolve-then-encrypt path for the two arr columns** so legacy `server_settings` references are
-collapsed to the real credential before encryption.
-
-**Out of scope (each a deliberate, documented decision — not an oversight):**
- **Equality-looked-up secrets → need hashing, not encryption.** `api_keys.api_key`
-  (`WHERE api_key = $1`) and `webhook_sync_connections.webhook_secret` (`WHERE webhook_secret = $1`,
-  [repo.go:101](internal/webhooksync/repo.go:101)) are matched by exact value. AES-GCM uses a fresh
-  random nonce, so the same plaintext encrypts differently each time — encrypting these would silently
-  break API-key auth and inbound-webhook routing. The correct fix is a deterministic **hash** column +
-  lookup-by-hash, a distinct lookup-semantics + migration change. **Follow-up issue.**
- **`plugin_runtime_configs.config_value` → cross-repo + manifest-driven.** This is opaque plugin-defined
-  JSONB ([runtime_config.go:55](internal/plugins/runtime_config.go:55)); some plugins store secrets in it
-  (e.g. the legacy one-time copy of `introdb.api_key` at [main.go:2341](cmd/silo/main.go:2341)). It is
-  read/written only through `RuntimeConfigStore` *in this repo*, so whole-blob encrypt-on-write /
-  decrypt-on-read at that store is technically feasible — **but** host-side plugin runtime lives in the
-  separate **`Silo`** repo (per CLAUDE.md) and may read this table directly, and which fields are secret
-  is declared in each plugin's manifest. Doing this correctly needs a coordinated, manifest-aware design
-  across repos. **Explicitly deferred — known gap.** Note: while deferred, the legacy `introdb.api_key`
-  copy means that secret still exists in plaintext inside plugin config even after the `server_settings`
-  copy is encrypted; the follow-up must re-encrypt or purge it.
- **`plex_sync_connections`** — dead table, zero Go references (superseded by `webhook_sync_connections`
-  in migration `060`). Not touched.
- **Already-protected / non-secret:** `users.password_hash` (bcrypt), `oauth_completion.token_ciphertext`
-  (already AES-GCM), `abs_sessions.token_hash` / `oauth_completion.code_hash` (hashed), `oauth_session.state`
-  (equality CSRF), `subtitle_provider_config.username` (a username, not a secret),
-  `history_import_plex_sessions.pin_id`/`pin_code` (transient OAuth pairing handshake, not a stored
-  access credential).
- `internal/auth/oauth_store.go` is left as-is (its key is jwt-derived and its data is ephemeral).
-  Optionally a shared low-level seal/open helper can be extracted later; not required here.
-
-**Tech Stack:** Go 1.26.3 (module declares `go 1.26.3`; stdlib `crypto/hkdf` is available — no new
-dependency). PostgreSQL via `pgxpool`. **No schema migration** — every target column is already `text`
-(or `jsonb` left untouched) and now simply holds ciphertext; the backfill is pure Go. No frontend or
-client (silo-android / silo-apple) changes — API responses already mask these values to `has_api_key` /
-`has_credentials` booleans, so no contract changes.
-
-Commands assume the repository root is the cwd.
-
---
-
-## Running tests
-
-The `internal/secret` package is pure Go (no libvips/CGO). If a Go toolchain is on the host:
-
-```bash
-GOWORK=off go test ./internal/secret/... -v
-```
-
-`GOWORK=off` is required when running from a `.claude/worktrees/` checkout — the parent `go.work`
-otherwise pins the module to `main` and the build fails with "main module does not contain package".
-
-If the host has no Go toolchain, run in a throwaway container (a named volume caches module downloads):
-
-```bash
-docker run --rm -v "$PWD":/app -w /app -v silo-gomod:/go/pkg/mod \
-  -e GOFLAGS=-mod=mod golang:1.26 \
-  go test ./internal/secret/... -v
-```
-
-Full backend build/vet before opening the MR: `GOWORK=off go build ./...` then `make lint` and
-`make verify-local-paths`.
-
---
-
-## File structure
-
-**New files:**
- `internal/secret/cipher.go` — **create**. `Cipher` type; `New`, `Encrypt`, `Decrypt`, `IsEncrypted`,
-  `EncryptIfPlaintext`; envelope + HKDF + version dispatch. Row-bound AAD passed by callers.
- `internal/secret/cipher_test.go` — **create**. Round-trip, tamper/AAD-mismatch rejection, wrong-key,
-  `IsEncrypted` edge cases, version dispatch, idempotency.
- `internal/secret/backfill.go` — **create**. Generic in-place backfill for literal-credential columns +
-  the special resolve-then-encrypt backfill for the two arr columns.
- `internal/secret/backfill_test.go` — **create**. Idempotency, mixed plaintext/ciphertext rows, empty
-  values skipped, failure isolation, arr resolve-then-encrypt.
-
-**Modified files:**
- `internal/config/bootstrap.go` — add `SecretKey []byte` to `BootstrapConfig`; read `SECRET_KEY`; fatal
-  if missing or `< 32` chars.
- `cmd/silo/main.go` — construct `*secret.Cipher` after bootstrap; build the `EncryptedSettingsRepo`;
-  run the settings + column backfills after migrations and before settings are read; **re-wrap
-  `settingsRepo` after the max-connections pool recreation (line ~399)**; thread the cipher into the
-  affected repo constructors; delete the `SetSecretResolver` wiring.
- `internal/catalog/encrypted_settings_repo.go` — **create**. `EncryptedSettingsRepo` decorator +
-  exported, **audited** `SensitiveSettingKeys` (single source of truth) + `BackfillSensitiveSettings`.
- `internal/catalog/server_settings_repo.go` — unchanged behavior; remains the raw inner store.
- `internal/api/handlers/admin.go` — replace the local `sensitiveSettingKeys` map with
-  `catalog.SensitiveSettingKeys` (redaction now shares the audited allowlist; closes the prior gap where
-  `redis.sentinel_password` and `s3.operational_*` were returned in plaintext).
- `internal/requests/repository.go` — `Repository` gains `*secret.Cipher`; encrypt `api_key_ref` on
-  insert/update (AAD bound to integration id); decrypt (pass-through legacy plaintext) in `scanIntegration`.
- `internal/requests/service.go` — delete `SecretResolver` interface, `secrets` field,
-  `SetSecretResolver`, and `resolveAPIKey`; call sites use the already-decrypted `Integration.APIKeyRef`.
- `internal/autoscan/repository.go` — `Repository` gains `*secret.Cipher`; encrypt `api_key_ref` on
-  create/update (AAD bound to connection id); decrypt (pass-through legacy) in `scanConnection`.
- `internal/autoscan/connection.go` — delete `SecretResolver` interface, `secrets` field, and the
-  secret-resolution branch in `Resolve`; linked-integration path uses the requests repo's decrypted key.
- `internal/api/autoscan_wiring.go` — drop the `AutoscanSecretResolver` param from `BuildAutoscanService`.
- `internal/api/router.go` — drop the `SetSecretResolver(settingsRepo)` calls; pass the
-  `EncryptedSettingsRepo` where `settingsRepo` is used; thread the cipher into repo constructors.
- `internal/subtitles/pgrepo.go` — `*secret.Cipher`; encrypt `api_key` + `password` on upsert; decrypt on
-  read. PK for AAD = `provider_name`.
- `internal/watchsync/repository.go` — `*secret.Cipher`; encrypt `access_token` + `refresh_token` on
-  upsert; decrypt in a `decryptConnection` helper called after every scan. PK for AAD = connection `id`.
- `internal/webhooksync/repo.go` — `*secret.Cipher`; encrypt `access_token` on create; decrypt on scan.
-  **`webhook_secret` is NOT encrypted** (equality lookup — carved out). PK for AAD = connection `id`.
- `internal/historyimport/repo_admin.go` — `*secret.Cipher`; encrypt in `SetSourceAdminToken`; decrypt in
-  `GetSourceWithAdminToken`. PK for AAD = source `id`.
- `internal/historyimport/repo.go` — `*secret.Cipher`; encrypt `connect_access_token`
-  (`history_import_connect_sessions`) + `auth_token` (`history_import_plex_sessions`) on insert/update;
-  decrypt on scan. PK for AAD = session `id`.
- `docs/architecture/secret-encryption.md` — **create**. Operator runbook (SECRET_KEY generation, backup,
-  key-loss, rollback/downgrade).
-
-**No migration files.** All target columns are already `text`; the backfill is Go-side.
-
---
-
-## Reference tables
-
-### What is encrypted vs hashed vs excluded
-
-AAD column shows the GCM additional-authenticated-data string; `<pk>` is the row's stable primary key.
-
-| Group | Table.column | AAD binding | Action |
-| --- | --- | --- | --- |
-| Arr keys | `request_integrations.api_key_ref` | `request_integrations:api_key_ref:<id>` | **Resolve-then-encrypt** (backfill) / encrypt inline (writes) |
-| Arr keys | `autoscan_connections.api_key_ref` | `autoscan_connections:api_key_ref:<id>` | **Resolve-then-encrypt** (backfill) / encrypt inline (writes) |
-| Settings | every key in `SensitiveSettingKeys` (see audited list below) | `server_settings:<key>` | **Encrypt via decorator** |
-| Subtitles | `subtitle_provider_config.api_key`, `.password` | `subtitle_provider_config:<col>:<provider_name>` | **Encrypt inline** |
-| Watch sync | `watch_provider_connections.access_token`, `.refresh_token` | `watch_provider_connections:<col>:<id>` | **Encrypt inline** |
-| Webhook sync | `webhook_sync_connections.access_token` | `webhook_sync_connections:access_token:<id>` | **Encrypt inline** |
-| History import | `history_import_sources.admin_token` | `history_import_sources:admin_token:<id>` | **Encrypt inline** |
-| History import | `history_import_connect_sessions.connect_access_token` | `history_import_connect_sessions:connect_access_token:<id>` | **Encrypt inline** |
-| History import | `history_import_plex_sessions.auth_token` | `history_import_plex_sessions:auth_token:<id>` | **Encrypt inline** |
-| — | `api_keys.api_key` | — | **Carved out → hash** (follow-up) |
-| — | `webhook_sync_connections.webhook_secret` | — | **Carved out → hash** (follow-up) |
-| — | `plugin_runtime_configs.config_value` | — | **Deferred → cross-repo/manifest design** (follow-up) |
-| — | `plex_sync_connections.*` | — | **Excluded** (dead table) |
-
-### Audited `SensitiveSettingKeys` (single source of truth)
-
-Built from the config loader's actual secret inputs ([internal/config/db_loader.go](internal/config/db_loader.go))
-plus the admin redaction map plus other known consumers — **not** just the current redaction map. The
-union is intentional and also fixes a pre-existing redaction leak. Implementers must re-audit
-`db_loader.go` and `grep` for any `*secret*`/`*token*`/`*password*`/`*api_key*` settings keys before
-finalizing.
-
-```
-auth.jwt_secret
-s3.public_access_key   s3.public_secret_key   s3.public_token_secret
-s3.private_access_key  s3.private_secret_key
-s3.user_db_access_key  s3.user_db_secret_key
-s3.operational_access_key  s3.operational_secret_key  s3.operational_token_secret   # legacy aliases still read as fallbacks (db_loader L165-192); migration 086 copied but did not delete them
-redis.url                    # may embed credentials (redis://:pass@host)
-redis.sentinel_password      # read at db_loader L334 — MISSING from the old redaction map
-tmdb.api_key
-mdblist.api_key
-introdb.api_key              # read in main.go (legacy → plugin copy)
-subtitle_ai.api_key
-recommendations.embedding_auth_token   recommendations.openai_api_key   # legacy alias (db_loader L409)
-watchsync.trakt.client_id   watchsync.trakt.client_secret
-watchsync.simkl.client_id   watchsync.simkl.client_secret
-requests.radarr.api_key     requests.sonarr.api_key                     # legacy single-instance arr keys
-```
-
-`auth.jwt_secret` IS encrypted at rest under `SECRET_KEY` (it is no longer the encryption root — `SECRET_KEY`
-is). `redis.url`/client-id entries are not high-value secrets but are kept in the set as a harmless safe
-superset and to match existing redaction.
-
-### Envelope format
-
-```
-enc:v1:<base64.RawURLEncoding( nonce[12] ‖ gcm.Seal(...) )>
-```
-
- `enc:v1:` — exactly 7 ASCII chars; not valid base64url, not a UUID/JWT/URL/integer prefix. Collision-proof
-  against any real plaintext credential in practice.
- `IsEncrypted(s)` ≡ `strings.HasPrefix(s, "enc:v1:")`.
- Decrypt parses the version (`strings.SplitN(s, ":", 3)`), dispatches to the v1 opener; an unknown
-  version returns an explicit `ErrUnknownVersion`. This is the forward-compat hook for a future `enc:v2:`
-  key rotation — implement the dispatch now even though only `v1` exists.
-
-### Read-path contract (applies to every decrypt site — decorator and repos)
-
-1. `value == ""` → return `""`.
-2. `!IsEncrypted(value)` → **return the value unchanged** (legacy plaintext pass-through during the
-   backfill window; the value is no worse than today). This is unambiguous — there is no longer any
-   "ref vs literal" question because the `_ref` indirection is gone.
-3. `IsEncrypted(value)` → `Decrypt`; **any error (wrong key, tamper, truncation) is propagated, never
-   swallowed and never returned as the ciphertext string.** A corrupt ciphertext fails the operation.
-
-This reconciles the best-effort backfill (a skipped/failed row stays readable as plaintext) with the
-hard guarantee that a real `enc:v1:` value never silently degrades to using ciphertext as a credential.
-
---
-
-## Task 1: The `internal/secret` cipher package
-
-**Files:** Create `internal/secret/cipher.go`, `internal/secret/cipher_test.go`.
-
-This is the foundation; it has no dependencies on `catalog`/`config` and is independently testable.
-
- [ ] **Step 1: `Cipher` type + `New`.** Derive a 32-byte AES key with stdlib
-  `hkdf.Key(sha256.New, masterKey, nil /*salt*/, "silo/data-encryption/v1", 32)`. Return an error if
-  `len(masterKey) < 32`. Store the derived key as `[32]byte`. The type is safe for concurrent use.
- [ ] **Step 2: `Encrypt(plaintext, aad string) (string, error)`.** Empty plaintext returns `"", nil`
-  (do not produce an `enc:v1:` blob for an empty secret). Otherwise: `aes.NewCipher` → `cipher.NewGCM` →
-  12-byte `rand` nonce → `gcm.Seal(nonce, nonce, []byte(plaintext), []byte(aad))` →
-  `envelopePrefix + base64.RawURLEncoding.EncodeToString(sealed)`. `aad` is the row-bound context string.
- [ ] **Step 3: `Decrypt(ciphertext, aad string) (string, error)`.** Strip + validate the version prefix;
-  unknown version → `ErrUnknownVersion`. base64-decode; reject if shorter than the nonce size; split
-  nonce/body; `gcm.Open(nil, nonce, body, []byte(aad))`. **Any failure returns an error — never fall back
-  to returning the ciphertext or an empty string.** (Pass-through of *non-prefixed* plaintext is the
-  caller's job per the read-path contract, not `Decrypt`'s.)
- [ ] **Step 4: `IsEncrypted(s string) bool`** and `EncryptIfPlaintext(s, aad string) (string, bool, error)`.
-  `EncryptIfPlaintext` returns `(s, false, nil)` when already encrypted or empty; otherwise encrypts and
-  returns `(ct, true, nil)`. This is the idempotent primitive the backfill uses.
- [ ] **Step 5: Tests** (`cipher_test.go`):
-  - round-trip with AAD recovers plaintext; ciphertext has the `enc:v1:` prefix.
-  - two encryptions of the same plaintext+AAD differ (random nonce works).
-  - tamper: flip one byte of the decoded body → `Decrypt` errors.
-  - AAD mismatch: encrypt with `"t:c:1"`, decrypt with `"t:c:2"` → errors (proves row binding).
-  - wrong key: encrypt with key A, decrypt with key B → errors.
-  - `New` with a `< 32`-byte key → error.
-  - `IsEncrypted`: `"enc:v1:x"`→true, `"sa_abc"`→false, `""`→false, `"ENC:V1:x"`→false.
-  - unknown version `"enc:v99:..."` → `ErrUnknownVersion`.
-  - `EncryptIfPlaintext` is idempotent (second call is a no-op, `changed=false`).
- [ ] **Step 6:** `GOWORK=off go test ./internal/secret/... -v` passes.
-
---
-
-## Task 2: `SECRET_KEY` bootstrap + cipher construction
-
-**Files:** Modify `internal/config/bootstrap.go`, `cmd/silo/main.go`.
-
- [ ] **Step 1:** Add `SecretKey []byte` to `BootstrapConfig`. In `LoadBootstrap`, after the
-  `DATABASE_URL` check, read `os.Getenv("SECRET_KEY")`; return an error (which the existing
-  `log.Fatalf` path surfaces) if it is empty or `< 32` characters. Message must be actionable, e.g.
-  `SECRET_KEY is required (>=32 chars); generate one with: openssl rand -base64 48`. `godotenv` already
-  loads `.env`, so dev sets it there.
- [ ] **Step 2:** In `cmd/silo/main.go`, immediately after `LoadBootstrap` returns, construct the cipher:
-  `dataCipher, err := secret.New(bc.SecretKey)` and `log.Fatalf` on error. The cipher is threaded
-  explicitly as a dependency — **never** a package-level global.
- [ ] **Step 3:** Add `SECRET_KEY=...` to `.env.example` (or the documented dev env) and note it in the
-  operator runbook (Task 7).
- [ ] **Step 4:** `GOWORK=off go build ./cmd/silo` compiles; starting without `SECRET_KEY` fatals with the
-  actionable message.
-
---
-
-## Task 3: `server_settings` encryption decorator
-
-**Files:** Create `internal/catalog/encrypted_settings_repo.go`; modify `internal/api/handlers/admin.go`,
-`cmd/silo/main.go`, `internal/api/router.go`.
-
- [ ] **Step 1: Build the audited allowlist.** Create exported `var SensitiveSettingKeys map[string]bool`
-  in `internal/catalog` populated from the "Audited `SensitiveSettingKeys`" list above. **Do not** simply
-  move the admin redaction map — re-audit `internal/config/db_loader.go` (and other `server_settings`
-  consumers) for every secret-bearing key, and include the legacy aliases (`s3.operational_*`,
-  `recommendations.openai_api_key`) and `redis.sentinel_password`. Update `admin.go`
-  (`HandleGetSettings` redaction, `HandleGetSensitiveStatus`, the `PUT` response branch) to reference
-  `catalog.SensitiveSettingKeys`. One allowlist now drives **both** redaction and encryption.
- [ ] **Step 2:** Implement `EncryptedSettingsRepo` wrapping `*ServerSettingsRepo` + `*secret.Cipher`:
-  - `Set(key, value)`: if `SensitiveSettingKeys[key]` and `value != ""`, encrypt with AAD
-    `"server_settings:"+key` before delegating; else delegate raw.
-  - `Get(key)` / `GetAll()`: delegate, then apply the **read-path contract** to each sensitive key
-    (pass through legacy plaintext; decrypt prefixed values; propagate decrypt errors).
- [ ] **Step 3:** Add `BackfillSensitiveSettings(ctx)` on the decorator: for each key in
-  `SensitiveSettingKeys`, read the raw inner value; if non-empty and not `IsEncrypted`, `inner.Set` the
-  encrypted value (AAD `"server_settings:"+key`). Idempotent. Returns a count + aggregated errors.
- [ ] **Step 4:** In `cmd/silo/main.go`, build `settingsRepo` as the `EncryptedSettingsRepo` wrapping the
-  raw `catalog.NewServerSettingsRepo(pool)`. Confirm the auto-generate-`jwt_secret` step still works: the
-  `GetAll` map carries plaintext, the `== ""` check is unchanged, and `Set("auth.jwt_secret", encoded)`
-  now writes **encrypted** while the in-memory map keeps the plaintext for `LoadFromDB`. Any function
-  currently typed to the concrete `*catalog.ServerSettingsRepo` changes to the `ServerSettingsStore`
-  interface that both already satisfy.
- [ ] **Step 5 (re-wrap after pool recreation):** `cmd/silo/main.go` rebuilds a **raw**
-  `catalog.NewServerSettingsRepo(pool)` after recreating the pool for `max_connections` (line ~399).
-  Re-wrap it there too (`settingsRepo = catalog.NewEncryptedSettingsRepo(catalog.NewServerSettingsRepo(pool), dataCipher)`)
-  so every later consumer gets the encrypting repo, not a raw one. Audit for any other raw construction
-  of the settings repo and wrap each.
- [ ] **Step 6:** Tests: decorator round-trip (raw store holds `enc:v1:`, decorator `Get` returns
-  plaintext); non-sensitive keys pass through unencrypted; legacy-plaintext pass-through on read;
-  `BackfillSensitiveSettings` idempotency.
- [ ] **Step 7:** `GOWORK=off go build ./...` compiles; admin settings GET still redacts (now including
-  `redis.sentinel_password`); a sensitive key written via the admin API lands as `enc:v1:` in the DB.
-
---
-
-## Task 4: Inline-encrypt arr keys + delete the `SecretResolver` indirection
-
-**Files:** Modify `internal/requests/repository.go`, `internal/requests/service.go`,
-`internal/autoscan/repository.go`, `internal/autoscan/connection.go`,
-`internal/api/autoscan_wiring.go`, `internal/api/router.go`, `cmd/silo/main.go`.
-
-> The legacy-data resolution for these two columns is handled by the **resolve-then-encrypt backfill** in
-> Task 6 (a row may currently hold a `server_settings` key name, not a literal key). The repo write path
-> below only ever encrypts the literal credential an admin submits going forward.
-
- [ ] **Step 1:** `requests.NewRepository` gains a `*secret.Cipher` parameter. In `insertIntegration` and
-  `updateIntegration`, encrypt `i.APIKeyRef` (AAD `"request_integrations:api_key_ref:"+i.ID`) before
-  binding — preserve the existing `CASE WHEN $5 = '' THEN api_key_ref ELSE $5 END` keep-existing
-  semantics (encrypt only the non-empty incoming value). In `scanIntegration`, apply the read-path
-  contract to the scanned `api_key_ref`.
- [ ] **Step 2:** Delete `requests.SecretResolver` (interface), the `Service.secrets` field,
-  `Service.SetSecretResolver`, and `Service.resolveAPIKey`. Every former `resolveAPIKey(ctx, integration)`
-  call site uses `strings.TrimSpace(integration.APIKeyRef)` directly (the repo already decrypted it).
- [ ] **Step 3:** `autoscan.NewRepository` gains a `*secret.Cipher`. Encrypt `api_key_ref` in
-  `CreateConnection` / `UpdateConnection` (AAD `"autoscan_connections:api_key_ref:"+id`, same
-  keep-existing CASE semantics); apply the read-path contract in `scanConnection`.
- [ ] **Step 4:** In `internal/autoscan/connection.go`, delete the `SecretResolver` interface, the
-  `ConnectionResolver.secrets` field, and the secret-resolution branch in `Resolve`. For a linked Requests
-  integration, `RequestIntegrationLookup.Get` returns the requests repo's **already-decrypted** key — use
-  it directly. For a standalone connection, the autoscan repo already decrypted it. `Resolve` now only
-  resolves base URL + linkage and returns plaintext.
- [ ] **Step 5:** Remove the `AutoscanSecretResolver` parameter from `BuildAutoscanService`
-  (`internal/api/autoscan_wiring.go`) and drop the `SetSecretResolver(settingsRepo)` calls in
-  `internal/api/router.go` and `cmd/silo/main.go` (including the reconcile-worker service). Thread
-  `dataCipher` into the requests/autoscan repo constructors at all wiring sites.
- [ ] **Step 6:** Verify no API response serializes the raw key: the integration/connection response DTOs
-  still emit only `has_api_key`. Add/extend a test asserting the create→store→read round-trip yields the
-  original key, and that the stored column value is `enc:v1:`-prefixed.
- [ ] **Step 7:** `GOWORK=off go build ./...`; `GOWORK=off go test ./internal/requests/... ./internal/autoscan/...`.
-
---
-
-## Task 5: Per-table credential columns
-
-**Files:** Modify `internal/subtitles/pgrepo.go`, `internal/watchsync/repository.go`,
-`internal/webhooksync/repo.go`, `internal/historyimport/repo_admin.go`, `internal/historyimport/repo.go`,
-plus their constructor call sites.
-
-Each repo gains a `*secret.Cipher` constructor arg and follows encrypt-on-write / decrypt-on-read with a
-row-bound AAD. Preserve existing keep-existing CASE/COALESCE semantics — encrypt only non-empty incoming
-values. All read paths use the read-path contract (pass through legacy plaintext, hard-fail corrupt
-ciphertext). These columns **never** had the resolver indirection — they always stored literal
-credentials — so no resolve-then-encrypt is needed (unlike the arr columns).
-
- [ ] **Step 1: subtitles** — encrypt `api_key` + `password` in `UpsertProviderConfig`; decrypt in
-  `ListProviderConfigs` and `GetProviderConfig`. Keep the existing `HasAPIKey`/`HasCredentials` flags
-  (set them from the decrypted values). AAD PK = `provider_name`.
- [ ] **Step 2: watchsync** — encrypt `access_token` + `refresh_token` in `UpsertConnection`. Add a
-  `decryptConnection(*Connection)` helper and call it after **every** scan path (list/get/by-provider/etc.
-  — there are several). AAD PK = connection `id`.
- [ ] **Step 3: webhooksync** — encrypt `access_token` in `CreateConnection`; decrypt in `scanConnection`.
-  **Do NOT touch `webhook_secret`** — it is equality-looked-up in `GetConnectionBySecret`
-  (`WHERE webhook_secret = $1`) and is carved out for the hashing follow-up. AAD PK = connection `id`.
- [ ] **Step 4: historyimport admin token** — encrypt in `SetSourceAdminToken`; decrypt in
-  `GetSourceWithAdminToken`; `ClearSourceAdminToken` (writes NULL) is unchanged. AAD PK = source `id`.
- [ ] **Step 5: historyimport session tokens** — in `internal/historyimport/repo.go`, encrypt
-  `connect_access_token` (`history_import_connect_sessions`) and `auth_token`
-  (`history_import_plex_sessions`) on insert/update; decrypt on scan (note the existing
-  `COALESCE(auth_token, '')` read). These are read by session `id`, not by token value. `pin_id`/`pin_code`
-  are transient pairing artifacts — leave them. AAD PK = session `id`.
- [ ] **Step 6:** Thread `dataCipher` into each constructor at its wiring site (`router.go` / `main.go`).
- [ ] **Step 7:** `GOWORK=off go build ./...`; package tests for each modified repo pass.
-
---
-
-## Task 6: Idempotent startup backfill
-
-**Files:** Create `internal/secret/backfill.go`, `internal/secret/backfill_test.go`; modify `cmd/silo/main.go`.
-
- [ ] **Step 1: Generic in-place backfill** for the literal-credential columns (subtitle ×2, watchsync ×2,
-  webhook `access_token`, historyimport `admin_token`, historyimport session `connect_access_token` +
-  `auth_token`). Per `BackfillTarget {table, column, idColumn, aadPrefix}`: select rows where the column
-  is non-null, non-empty, and `NOT LIKE 'enc:v1:%'`; for each, compute AAD = `aadPrefix + ":" + id`,
-  `EncryptIfPlaintext`, and `UPDATE ... SET col = $1 WHERE id = $2 AND col = $3` (the `AND col = $3` guard
-  makes concurrent multi-node boots converge without double-encrypting). Empty values are skipped (never
-  encrypt `""`).
- [ ] **Step 2: Resolve-then-encrypt backfill for the two arr columns** (`request_integrations.api_key_ref`,
-  `autoscan_connections.api_key_ref`). This is **separate** from Step 1 because legacy rows may hold a
-  `server_settings` key name rather than a literal key. For each row whose value is not already
-  `enc:v1:`-prefixed, replicate the old `resolveAPIKey` semantics **once**:
-  1. `resolved := encryptedSettingsRepo.Get(ctx, value)` (the decrypting decorator — handles both a
-     sensitive-and-encrypted target like `requests.radarr.api_key` and a plaintext custom key).
-  2. If `resolved` is non-empty, the row held a *reference* → encrypt `resolved` inline.
-     Else the row held a *literal* key → encrypt `value` inline.
-  3. `UPDATE ... SET api_key_ref = <enc> WHERE id = $2 AND api_key_ref = <original>`, AAD bound to the row id.
-  Run this **after** `BackfillSensitiveSettings` so the referenced settings are consistent (the decorator
-  decrypts regardless, but ordering keeps it deterministic). Optionally log/flag now-orphaned
-  `requests.{radarr,sonarr}.api_key` settings rows for a later cleanup (do not delete in this PR).
- [ ] **Step 3: Failure posture (decided):** best-effort. Collect per-row/per-target errors, log each at
-  ERROR, and emit a single startup summary line (`secret backfill: encrypted N, failed M`). A failed
-  encrypt leaves the pre-existing plaintext (no *new* exposure vs. today) and reads still succeed via the
-  read-path pass-through, so it must **not** block boot — reliability over a hard stop. (Read-path decrypt
-  failures on an `enc:v1:` value still hard-fail the individual operation.)
- [ ] **Step 4: Ordering in `cmd/silo/main.go`** — gate on migration-running modes only (mirror the
-  existing migration guard; proxy/transcode nodes skip the backfill). Sequence:
-  `LoadBootstrap (read SECRET_KEY) → open pool → RunMigrations → construct dataCipher → wrap settingsRepo →
-  BackfillSensitiveSettings → generic column backfill → arr resolve-then-encrypt backfill → GetAll(decrypts)
-  → auto-gen jwt_secret (writes encrypted) → [pool recreate? re-wrap settingsRepo] → LoadFromDB(plaintext) → validate`.
-  The settings backfill + `GetAll` must precede `LoadFromDB` so config consumers read decrypted values.
- [ ] **Step 5: Concurrency note** — the `AND col = $3` idempotency guard is sufficient for the common
-  single-primary deploy. For multi-primary races, optionally wrap the backfill in a dedicated Postgres
-  advisory lock with a **fresh** lock id (do **not** reuse the migration `legacyBootstrapLocker` id — that
-  would extend the migration lock's held duration unpredictably).
- [ ] **Step 6: Tests** (`backfill_test.go`, against a test DB): seed plaintext rows → backfill →
-  all become `enc:v1:` and decrypt to the originals; second run is a no-op (no double-encrypt); mixed
-  plaintext/ciphertext rows handled; empty values skipped; one failing row does not abort the rest;
-  **arr resolve-then-encrypt:** a row holding `requests.radarr.api_key` (with that settings key present)
-  ends up encrypting the *resolved* credential, and a row holding a literal key encrypts the literal.
- [ ] **Step 7:** Boot against a DB pre-seeded with plaintext credentials **and** a legacy arr row that
-  references a settings key; confirm the summary log, that every target column is `enc:v1:` afterward, that
-  the arr row decrypts to the real Radarr key (not the setting name), and that a second boot reports
-  `encrypted 0`.
-
---
-
-## Task 7: Verification, docs, follow-up
-
- [ ] **Step 1: Regression guard tests:**
-  - API key auth still works — `api_keys.api_key` is stored as the literal `sa_`-prefixed token and
-    `GetByKey` (`WHERE api_key = $1`) still resolves (proves it was *not* routed through encryption).
-  - `auth.jwt_secret` is consistent across two simulated boots (encrypted at rest, plaintext to
-    `LoadFromDB`), and the stored `server_settings` row is `enc:v1:`-prefixed.
-  - Inbound webhook routing still works (`webhook_secret` untouched).
-  - A legacy arr integration that referenced `requests.sonarr.api_key` still fulfills after backfill.
- [ ] **Step 2:** `GOWORK=off go build ./...`, `make lint`, `make verify-local-paths`,
-  `cd web && pnpm run lint && pnpm run format:check` (frontend unaffected — confirm green).
- [ ] **Step 3:** Write `docs/architecture/secret-encryption.md`: how `SECRET_KEY` is generated, that it
-  must be backed up **separately** from DB dumps (treat like a CA private key), what happens on key loss
-  (encrypted secrets unrecoverable → re-enter integrations), the rollback/downgrade hazard (an old binary
-  reads `enc:v1:auth.jwt_secret` as a literal JWT secret → all sessions invalid; document that downgrade
-  requires decrypting settings back to plaintext or clearing `auth.jwt_secret`), and the envelope/version
-  scheme for future rotation.
- [ ] **Step 4: File the follow-up issues:**
-  1. **Hash equality-lookup secrets** (`api_keys.api_key`, `webhook_sync_connections.webhook_secret`) —
-     store a deterministic hash, look up by hash.
-  2. **Encrypt plugin runtime config** (`plugin_runtime_configs.config_value`) — coordinated with the
-     `Silo` host repo and plugin-manifest secret-field metadata; must also re-encrypt/purge the legacy
-     plaintext `introdb.api_key` copy. Note the dead `plex_sync_connections` table as a drop candidate.
- [ ] **Step 5:** Update the issue #45 acceptance check: no plaintext arr keys at rest (Requests +
-  Autoscan); `api_key_ref` is unambiguous (inline ciphertext, no literal fallback); existing rows
-  encrypted by the backfill (arr rows resolved-then-encrypted); S3 + the broader server-owned credential
-  set covered; remaining gaps (equality-lookup hashing, plugin JSONB) tracked as follow-ups.
-
---
-
-## Safety checklist (the implementer must not skip)
-
-1. `SECRET_KEY` is read in `LoadBootstrap` and **fatals** if absent/short — never defaults to a zero key
-   or a hash of `DATABASE_URL`.
-2. The cipher is constructed once, right after bootstrap, before any `settingsRepo` call — threaded as a
-   dependency, never a global.
-3. The settings backfill + decryption happen **before** `config.LoadFromDB` consumes the map.
-4. The auto-generated `auth.jwt_secret` is written **encrypted**, while the in-memory map keeps plaintext
-   for `LoadFromDB`.
-5. **`settingsRepo` is re-wrapped as the `EncryptedSettingsRepo` after the max-connections pool recreation
-   (main.go ~399)** and at every other construction site — no raw settings repo escapes into later wiring.
-6. The two **arr columns** use the **resolve-then-encrypt** backfill (not in-place) so legacy
-   `server_settings` references become the real credential before encryption; the other columns use the
-   plain in-place backfill.
-7. `SensitiveSettingKeys` is **audited from the config loader's real inputs** (incl.
-   `redis.sentinel_password` and the legacy `s3.operational_*` / `recommendations.openai_api_key`
-   aliases), not copied from the old redaction map.
-8. `api_keys.api_key` and `webhook_sync_connections.webhook_secret` are **never** routed through
-   encryption — they are equality-looked-up and would break auth/routing (separate hashing task).
-9. Every decrypt site obeys the **read-path contract**: pass through non-prefixed plaintext; **error
-   (never fall back)** on a corrupt `enc:v1:` value. Audit every old `if resolved == ""` site removed in Task 4.
-10. AAD binds to **row identity** (`table:column:<pk>`); PKs in scope (integration/connection ids, uuids,
-    `provider_name`) are stable. server_settings binds to its key.
-11. The backfill is prefix-gated and idempotent (`AND col = $3` guard); proxy/transcode nodes skip it.
-12. `plex_sync_connections` is not a target (dead table); `plugin_runtime_configs.config_value` is a
-    documented deferred gap, not silently ignored; `subtitle_provider_config.username` stays plaintext.
@@ -1,377 +0,0 @@
-# AI Services Core, Metadata Translation & Whisper ASR — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Design:** `docs/superpowers/specs/2026-06-10-ai-translation-and-asr-design.md` (read it first; this plan does not repeat the rationale).
-
-**Goal:** Extract the subtitle-AI LLM plumbing into shared packages (`internal/ai/llm`, `internal/ai/translate`, `internal/ai/jobrunner`), add AI translation of overviews/taglines into the existing localization tables with field provenance, and add Whisper ASR subtitle generation (`transcribe`, `transcribe_translate`). Single PR.
-
-**Architecture:** New `internal/ai/*` packages consumed by a refactored `internal/subtitles/ai` and a new `internal/metadata/translation` service. One new Goose migration (jobs table, provenance columns, library auto-translate flag). New `ai.*` settings keys with loader fallback to legacy `subtitle_ai.*` rows (encrypted values are GCM-bound to their key — never rename rows in SQL). Frontend: AI Services settings page, metadata-editor translate action, library toggle, player "generate from audio" mode.
-
-**Tech stack:** Go (chi, pgx), PostgreSQL via Goose SQL migrations, React + TypeScript (TanStack Query), Vitest.
-
-Commands assume the repository root is the cwd.
-
---
-
-## Ordering and verification
-
-Tasks 1–4 are a pure refactor and must leave subtitle translation behaviorally unchanged — run `go build ./... && go test ./internal/...` after each. Tasks 5–11 are backend features; 12–15 frontend; 16 final verification.
-
-Before opening the MR: `make lint`, `cd web && pnpm run lint && pnpm run format:check`, `make verify-local-paths`.
-
---
-
-## File structure
-
-**Create**
- `internal/ai/llm/client.go`, `client_test.go`, `config.go` — shared OpenAI-compatible client (chat + transcription)
- `internal/ai/llm/transcribe.go` — multipart `/v1/audio/transcriptions`, `verbose_json` types
- `internal/ai/translate/translate.go`, `translate_test.go` — generic segment batch translator (package `aitranslate`)
- `internal/ai/jobrunner/runner.go`, `runner_test.go` — dispatch/semaphore/heartbeat/reaper/cancel registry
- `internal/metadata/translation/{job.go,pgrepo.go,service.go,prompt.go,service_test.go}`
- `internal/subtitles/ai/transcriber.go`, `transcriber_test.go` — ASR pipeline
- `internal/playback/audio_extract.go` — ffmpeg chunked audio extraction helper
- `internal/api/handlers/metadata_ai.go`
- `migrations/sql/<timestamp>_ai_metadata_translation_and_asr.sql` (via `make migrate-create`)
- `web/src/pages/admin-settings/AIServicesSettings.tsx`
-
-**Modify**
- `internal/subtitles/ai/{client.go→deleted,translator.go,service.go,engine.go,job.go,config.go,pgrepo.go}`
- `internal/config/{config.go,db_loader.go}`; `internal/catalog/encrypted_settings_repo.go`
- `internal/catalog/{localization_repo.go,detail.go}`; `internal/models/media.go`
- `internal/metadata/service.go` (provider provenance + auto-enqueue hook)
- `internal/api/handlers/subtitle_ai.go`; router registration; `cmd/silo/main.go` wiring
- `web/src/pages/admin-settings/SubtitlesSettings.tsx`, `web/src/components/EditMetadataDialog.tsx`, `web/src/player/components/SubtitleTranslateModal.tsx`, library settings form, `web/src/api/` types/client, admin settings nav/route registration
-
---
-
-## Task 1: `internal/ai/llm` — shared client
-
- [ ] **Step 1: Move the chat client.** Create `internal/ai/llm` (package `llm`). Move `Client`, `chat` (export as `Chat`), `chatMessage` (export as `Message`), retry helpers (`sleepCtx`, `rateLimitBackoff`, `truncate`) from `internal/subtitles/ai/client.go`. New `llm.Config`:
-
-```go
-type Config struct {
-    BaseURL    string // chat endpoint, no trailing /v1
-    APIKey     string
-    ChatModel  string
-    ASRBaseURL string // empty = BaseURL
-    ASRAPIKey  string // empty = APIKey
-    ASRModel   string
-    MaxConcurrentJobs int
-}
-```
-
-Log lines lose the "subtitle" wording (they are shared now).
-
- [ ] **Step 2: Add `Transcribe`.** In `transcribe.go`:
-
-```go
-type TranscribeRequest struct {
-    Filename string
-    Audio    io.Reader
-    Language string        // optional ISO-639-1 hint
-    Timeout  time.Duration // per-request; sized to chunk length by the caller
-}
-type TranscriptionSegment struct{ Start, End float64; Text string }
-type Transcription struct{ Language string; Segments []TranscriptionSegment }
-func (c *Client) Transcribe(ctx context.Context, req TranscribeRequest) (*Transcription, error)
-```
-
-Multipart fields: `file`, `model` (=`ASRModel`), `response_format=verbose_json`, `temperature=0`, optional `language`. Reuse the same 429/5xx/transport retry-with-backoff loop as `Chat` (extract a shared `doWithRetry` rather than duplicating it). Empty `segments` in the response is an error (`transcription returned no segments`), not a silent fallback.
-
- [ ] **Step 3: Tests** (`client_test.go`, httptest): chat retries on 429 (honors `Retry-After`), 5xx, 200-with-error-object, empty choices; transcribe happy path (multipart fields present, segments parsed), missing-segments error, ASR base-url/key override falling back to chat values.
-
- [ ] **Step 4: Commit.** `refactor(ai): extract shared OpenAI-compatible LLM client with transcription support`
-
---
-
-## Task 2: `internal/ai/translate` — generic segment translator
-
- [ ] **Step 1: Move the batch logic.** Package `aitranslate`. Move `buildIndexedJSON`, `extractJSONObject`, and the batch loop from `internal/subtitles/ai/translator.go`, generalized:
-
-```go
-type Segment struct{ ID, Text string }
-type Request struct {
-    Segments         []Segment
-    SystemPrompt     string // caller-supplied; domain-specific
-    BatchSize        int
-    ContextNeighbors int    // preceding source segments sent untranslated
-}
-type ChatFn func(ctx context.Context, system, user string) (string, error)
-func Translate(ctx context.Context, chat ChatFn, req Request,
-    onBatch func(batch []Segment, done, total int)) ([]Segment, error)
-```
-
-Wire protocol unchanged: 1-based indexed JSON per batch, same-keys response, malformed-response retries (`maxRetries = 2`), completeness check. `ChatFn` keeps the package free of an `llm` dependency and trivially testable.
-
- [ ] **Step 2: Tests:** batch splitting/boundaries, context neighbors, code-fence tolerance, omitted-key retry then failure, ctx cancellation between batches.
-
- [ ] **Step 3: Commit.** `refactor(ai): extract generic batched segment translator`
-
---
-
-## Task 3: `internal/ai/jobrunner` — shared job lifecycle
-
- [ ] **Step 1: Extract the runner.** Move dispatch/heartbeat/reaper/cancel mechanics from `internal/subtitles/ai/service.go` (lines ~136–319) behind:
-
-```go
-type Store interface {
-    Heartbeat(ctx context.Context, id int64) error
-    ResetStaleJobs(ctx context.Context, before time.Time, message string) (int64, error)
-    MarkCancelled(ctx context.Context, id int64, message string) error
-}
-type Runner struct{ /* baseCtx, sem (shared), store, logger, cancels, wg */ }
-func New(appCtx context.Context, sem chan struct{}, store Store, logger *slog.Logger) *Runner
-func (r *Runner) Recover()                      // reap + background reaper loop
-func (r *Runner) Dispatch(id int64, run func(ctx context.Context)) // semaphore + heartbeat + cancel registry
-func (r *Runner) Cancel(id int64) bool          // true if an in-flight goroutine was cancelled
-```
-
-Heartbeat-while-queued behavior (the comment block in `dispatch`) must be preserved verbatim — it is load-bearing for multi-instance safety. Constants (30 s heartbeat, 2 min stale, 1 min reaper) move here.
-
- [ ] **Step 2: Shared semaphore.** The semaphore is **constructed by the caller** (`cmd/silo`) at size `ai.max_concurrent_jobs` and passed to every `Runner`, so subtitle + metadata + ASR jobs share one bound.
-
- [ ] **Step 3: Tests:** dispatch bounded by a size-1 shared semaphore across two runners; cancel of queued job marks cancelled without running; reaper resets a stale heartbeat row (fake store).
-
- [ ] **Step 4: Commit.** `refactor(ai): extract shared job lifecycle runner`
-
---
-
-## Task 4: Refactor `internal/subtitles/ai` onto the shared core
-
- [ ] **Step 1:** Delete `client.go`; `LLMTranslator` becomes an adapter: cues → `aitranslate.Segment` (ID = 1-based index, Text = joined lines), subtitle system prompt stays here, `splitCueLines` maps back. `Service` keeps job semantics but delegates lifecycle to `jobrunner.Runner`; `pgrepo` satisfies `jobrunner.Store`.
- [ ] **Step 2:** Update `cmd/silo/main.go` wiring (build `llm.Client` + shared semaphore once; pass into the subtitle service).
- [ ] **Step 3:** `go build ./... && go test ./internal/...` — subtitle translation behavior unchanged (same prompts, same batching, same job rows).
- [ ] **Step 4: Commit.** `refactor(subtitles): consume shared AI core`
-
---
-
-## Task 5: Migration
-
- [ ] **Step 1:** `make migrate-create NAME=ai_metadata_translation_and_asr`, then fill the generated file:
-
-```sql
-- +goose Up
-- +goose StatementBegin
-CREATE TABLE public.metadata_translation_jobs (
-    id               bigserial   PRIMARY KEY,
-    target_kind      text        NOT NULL,                   -- 'item' | 'season' | 'episode'
-    content_id       text        NOT NULL,
-    include_children boolean     NOT NULL DEFAULT true,
-    source_language  text        NOT NULL DEFAULT '',
-    target_language  text        NOT NULL,
-    engine           text        NOT NULL DEFAULT 'openai',
-    model            text        NOT NULL DEFAULT '',
-    status           text        NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|cancelled
-    progress         double precision NOT NULL DEFAULT 0,
-    progress_message text        NOT NULL DEFAULT '',
-    fields_done      integer     NOT NULL DEFAULT 0,
-    fields_total     integer     NOT NULL DEFAULT 0,
-    force            boolean     NOT NULL DEFAULT false,
-    error_message    text        NOT NULL DEFAULT '',
-    idempotency_key  text        NOT NULL,
-    requested_by     integer,
-    created_at       timestamptz NOT NULL DEFAULT now(),
-    updated_at       timestamptz NOT NULL DEFAULT now(),
-    heartbeat_at     timestamptz NOT NULL DEFAULT now()
-);
-CREATE UNIQUE INDEX metadata_translation_jobs_active_idempotency_idx
-    ON public.metadata_translation_jobs (idempotency_key)
-    WHERE status IN ('pending', 'running');
-CREATE INDEX metadata_translation_jobs_content_idx
-    ON public.metadata_translation_jobs (content_id, created_at DESC);
-CREATE INDEX metadata_translation_jobs_status_idx
-    ON public.metadata_translation_jobs (status) WHERE status IN ('pending', 'running');
-
-- Field provenance: 'provider' | 'ai' | 'manual'. manual > provider > ai.
-ALTER TABLE media_item_localizations
-    ADD COLUMN overview_source text NOT NULL DEFAULT 'provider'
-        CHECK (overview_source IN ('provider', 'ai', 'manual')),
-    ADD COLUMN tagline_source  text NOT NULL DEFAULT 'provider'
-        CHECK (tagline_source IN ('provider', 'ai', 'manual'));
-ALTER TABLE season_localizations
-    ADD COLUMN overview_source text NOT NULL DEFAULT 'provider'
-        CHECK (overview_source IN ('provider', 'ai', 'manual'));
-ALTER TABLE episode_localizations
-    ADD COLUMN overview_source text NOT NULL DEFAULT 'provider'
-        CHECK (overview_source IN ('provider', 'ai', 'manual'));
-
-ALTER TABLE media_folders
-    ADD COLUMN auto_translate_metadata boolean NOT NULL DEFAULT false;
-- +goose StatementEnd
-
-- +goose Down
-- +goose StatementBegin
-ALTER TABLE media_folders DROP COLUMN auto_translate_metadata;
-ALTER TABLE episode_localizations DROP COLUMN overview_source;
-ALTER TABLE season_localizations DROP COLUMN overview_source;
-ALTER TABLE media_item_localizations DROP COLUMN tagline_source, DROP COLUMN overview_source;
-DROP TABLE IF EXISTS public.metadata_translation_jobs;
-- +goose StatementEnd
-```
-
- [ ] **Step 2:** `make migrate-up` against the local stack (`docker compose up -d postgres redis`), then `make migrate-status`.
- [ ] **Step 3: Commit.** `feat(metadata): migration for translation jobs, localization provenance, library auto-translate`
-
---
-
-## Task 6: Settings & config
-
- [ ] **Step 1: Config structs** (`internal/config/config.go`): add `AIConfig` (fields mirroring `llm.Config`); slim `SubtitleAIConfig` to `Enabled`, `TranscribeEnabled`, `BatchSize`, `ContextNeighbors`; add `MetadataAIConfig{Enabled bool}`.
- [ ] **Step 2: Loader** (`internal/config/db_loader.go`): load `ai.*` with legacy fallback, following the `recommendations.embedding_auth_token` precedent at line ~409:
-
-```go
-cfg.AI.BaseURL  = stringOr(m, "ai.base_url",  stringOr(m, "subtitle_ai.base_url", "https://api.openai.com"))
-cfg.AI.APIKey   = stringOr(m, "ai.api_key",   stringOr(m, "subtitle_ai.api_key", ""))
-cfg.AI.ChatModel = stringOr(m, "ai.chat_model", stringOr(m, "subtitle_ai.chat_model", "gpt-4o-mini"))
-// ai.max_concurrent_jobs ← subtitle_ai.max_concurrent_jobs ← 2
-// ai.asr_model (default "whisper-1"), ai.asr_base_url, ai.asr_api_key (default "")
-// subtitle_ai.transcribe_enabled, metadata_ai.enabled (default false)
-```
-
-**Never** rename the legacy rows in SQL — encrypted values are GCM-bound to their setting key (`internal/catalog/encrypted_settings_repo.go`).
-
- [ ] **Step 3:** Add `ai.api_key`, `ai.asr_api_key` to `sensitiveSettingKeys`.
- [ ] **Step 4:** Readiness helpers: subtitle translate = `SubtitleAI.Enabled && AI chat ready`; ASR = `SubtitleAI.TranscribeEnabled && AI.ASRModel != "" && (asr or chat base URL set)`; metadata = `MetadataAI.Enabled && AI chat ready`.
- [ ] **Step 5: Commit.** `feat(config): shared ai.* settings with legacy subtitle_ai fallback`
-
---
-
-## Task 7: Provenance-aware localization writes
-
- [ ] **Step 1: Models** (`internal/models/media.go`): add `OverviewSource`/`TaglineSource` to `MediaItemLocalization`, `OverviewSource` to `SeasonLocalization`/`EpisodeLocalization`.
- [ ] **Step 2: Provider upsert rules** (`internal/catalog/localization_repo.go`): rewrite the three `Upsert` statements so, per AI-writable field:
-  - existing source `manual` → keep existing value and source;
-  - incoming value empty → keep existing value and source;
-  - otherwise → take incoming value, set source `provider`.
-
-Single-statement `ON CONFLICT … DO UPDATE` with `CASE` (no read-modify-write). Pattern for one field:
-
-```sql
-overview = CASE
-    WHEN media_item_localizations.overview_source = 'manual' THEN media_item_localizations.overview
-    WHEN EXCLUDED.overview = '' THEN media_item_localizations.overview
-    ELSE EXCLUDED.overview END,
-overview_source = CASE
-    WHEN media_item_localizations.overview_source = 'manual' THEN media_item_localizations.overview_source
-    WHEN EXCLUDED.overview = '' THEN media_item_localizations.overview_source
-    ELSE 'provider' END
-```
-
- [ ] **Step 3: AI upsert methods**: `UpsertAITranslation(ctx, contentID, language string, overview, tagline *string, force bool)` per repo (nil pointer = field not part of this write). Insert path populates only the translated fields (other text columns empty). Update path per field: write when existing source is `ai`, existing value is empty, or `force` — never when `manual`; `force` may overwrite `provider` (the admin asked). Sets source `ai`.
- [ ] **Step 4: Serving hardening** (`internal/catalog/detail.go`): verify `LocalizeItemModel` / `LocalizeSeasonModel` / `LocalizeEpisodeModel` only override base fields with **non-empty** localization values (AI rows carry empty titles). Fix any field that clobbers; add a regression test.
- [ ] **Step 5: Tests** for the upsert matrix (provider-over-ai, ai-skips-provider-unless-force, manual-untouchable, empty-never-blanks), following the existing repo/service test patterns in `internal/catalog`.
- [ ] **Step 6: Commit.** `feat(catalog): field provenance for localizations with provider/ai/manual precedence`
-
---
-
-## Task 8: `internal/metadata/translation` service
-
- [ ] **Step 1: Job model + repo** (`job.go`, `pgrepo.go`): mirror `internal/subtitles/ai/{job.go,pgrepo.go}` shapes against `metadata_translation_jobs`; satisfy `jobrunner.Store`. Idempotency key = SHA-256 of `content_id|target_kind|target_language|model`.
- [ ] **Step 2: Service** (`service.go`): `Enqueue`, `GetJob`, `ListJobs(contentID)`, `Cancel`, `Recover`, using `jobrunner.Runner` + the shared semaphore. The run loop:
-  1. Expand targets: `item` → item overview+tagline; series item with `include_children` → + every season overview + every episode overview; `season` (+children → its episodes); `episode` → its overview. Source text comes from the **base** rows (default metadata language); `source_language` recorded from the item's `default_metadata_language`.
-  2. Skip-if-filled: drop any field whose target-language localization value is already non-empty, unless `force`. All skipped → complete immediately ("Nothing to translate").
-  3. Build `aitranslate.Segment`s (IDs `item:overview`, `item:tagline`, `season:<content_id>:overview`, `episode:<content_id>:overview`), translate with `prompt.go`'s system prompt (names the title/year, "translate media catalog descriptions", preserve proper nouns/character names/tone, no added information), `BatchSize` = package constant `metadataBatchSize = 10`, `ContextNeighbors = 0`.
-  4. Per batch: provenance-aware AI upserts (Task 7) + `fields_done`/progress update. Persisting per batch means a cancelled job keeps completed fields.
- [ ] **Step 3: Tests** (fake repos + fake `ChatFn`): series expansion counts, skip-if-filled short-circuit (zero chat calls), force overwrites `ai`+`provider` but never `manual`, per-batch persistence on cancellation mid-job.
- [ ] **Step 4: Commit.** `feat(metadata): AI translation service for overviews and taglines`
-
---
-
-## Task 9: Ingestion hook + library flag
-
- [ ] **Step 1:** Switch the provider localization writes in `internal/metadata/service.go` (item ~line 1476, season ~2921, episode ~3080) to the provenance-aware upserts — no other behavior change.
- [ ] **Step 2:** Thread `auto_translate_metadata` through the `MediaFolder` model, folder repo scan/update, and the folder settings API payload.
- [ ] **Step 3: Auto-enqueue hook.** After an item's refresh persists (single point at the end of the item flow — not per season/episode), when: folder flag set, folder `metadata_language` non-empty and ≠ item `default_metadata_language`, metadata AI ready, and the item's target-language localization is missing overview (or tagline) → `Enqueue` a non-force `item` job with `include_children=true`. Fire-and-forget (log on error); the active-idempotency index plus skip-if-filled make repeat refreshes free.
- [ ] **Step 4: Commit.** `feat(metadata): per-library auto-translate fallback on refresh`
-
---
-
-## Task 10: Metadata AI API
-
- [ ] **Step 1:** `internal/api/handlers/metadata_ai.go`, mirroring `subtitle_ai.go` shapes:
-  - `GET  /api/v1/metadata/ai/status` → `{enabled}`
-  - `POST /api/v1/metadata/ai/translate` `{content_id, target_kind, target_language, include_children, force}` → `{job}` (joins an in-flight duplicate, same as subtitles)
-  - `GET  /api/v1/metadata/ai/jobs/{job_id}`, `POST /api/v1/metadata/ai/jobs/{job_id}/cancel`, `GET /api/v1/metadata/ai/jobs?content_id=…`
- [ ] **Step 2:** Gate with the same permission as metadata editing (metadata curation permission; see `internal/catalog/update.go` callers). Register routes; wire the service in `cmd/silo/main.go`.
- [ ] **Step 3:** Handler tests following `internal/api/handlers` conventions (validation: bad kind, missing language, disabled engine → 400/503 mapping).
- [ ] **Step 4: Commit.** `feat(api): metadata AI translation endpoints`
-
---
-
-## Task 11: Whisper ASR
-
- [ ] **Step 1: Audio extraction** (`internal/playback/audio_extract.go`), alongside the existing subtitle extraction helpers:
-
-```go
-// ExtractAudioChunks extracts one audio track to 16 kHz mono WAV chunks in dir.
-// Returns ordered chunk paths; chunkSeconds = 600 in production.
-func ExtractAudioChunks(ctx context.Context, filePath string, audioTrackIndex int,
-    dir, ffmpegPath string, chunkSeconds int) ([]string, error)
-```
-
-Single ffmpeg pass: `-vn -map 0:a:<idx> -ac 1 -ar 16000 -c:a pcm_s16le -f segment -segment_time <n> <dir>/chunk%05d.wav`.
-
- [ ] **Step 2: Transcriber** (`internal/subtitles/ai/transcriber.go`):
-
-```go
-type Transcriber interface {
-    Transcribe(ctx context.Context, req TranscribeJobRequest,
-        onChunk func(cues []SubtitleCue, done, total int)) ([]SubtitleCue, string /*detected lang*/, error)
-}
-```
-
-`WhisperTranscriber` implementation: temp dir (`os.MkdirTemp`, removed on all exit paths) → `ExtractAudioChunks` → per chunk `llm.Client.Transcribe` (per-request timeout ∝ chunk duration; pass the job's language hint) → offset segment times by `chunkIndex*chunkSeconds` → cues (one per segment, wrapped to ≤2 lines ×~42 chars via a `wrapCueText` helper; whitespace-only segments dropped). Chunk processing order starts at the chunk containing `StartPosition`, then wraps (mirrors `reorderFromPosition` semantics).
-
- [ ] **Step 3: Wire kinds into the service.** `Service.run` branches on `job.Kind`:
-  - `translate`: existing path.
-  - `transcribe`: resolve audio track (`source_index` = audio index, `-1` → default/first; reject files without audio), transcribe (progress 10–70 %, live cue streaming via the existing notifier callbacks), store SRT as provider `transcribed`, language = hint or detected, release name `"<Language> (AI transcribed)"`, notify `SubtitleReady`.
-  - `transcribe_translate`: `transcribe`, store the transcript track, then run the existing `Translator` on the cues (70–95 %), store provider `translated`, `result_subtitle_id` = translated track.
-
-Enqueue validation per kind (ASR requires `TranscribeEnabled`; idempotency model component = `asr_model` or `asr_model+chat_model` for the chained kind).
-
- [ ] **Step 4:** API surface: `kind` field (optional, default `translate`) on the existing enqueue request in `subtitle_ai.go`; `transcribe_enabled` on the status response.
- [ ] **Step 5: Tests** (`transcriber_test.go`, fake client): timestamp stitching across chunks, playhead-first chunk ordering, cue wrapping, empty-segments chunk → job error, temp-dir cleanup on failure (assert via `t.TempDir` layout).
- [ ] **Step 6: Commit.** `feat(subtitles): Whisper ASR transcribe and transcribe_translate jobs`
-
---
-
-## Task 12: Frontend — AI Services settings page
-
- [ ] **Step 1:** `web/src/pages/admin-settings/AIServicesSettings.tsx`: connection card (`ai.base_url`, `ai.api_key` via the sensitive-key pattern already used in `SubtitlesSettings.tsx:264`, `ai.chat_model`, `ai.asr_model`, optional `ai.asr_base_url`/`ai.asr_api_key`, `ai.max_concurrent_jobs`) + features card (`subtitle_ai.enabled`, `subtitle_ai.transcribe_enabled`, `metadata_ai.enabled`, `subtitle_ai.batch_size`, `subtitle_ai.context_neighbors`). Reads show effective values (new key, falling back to the legacy key when unset — same fallback order as the loader); writes always target the new `ai.*` keys.
- [ ] **Step 2:** Remove the AI card from `SubtitlesSettings.tsx` (leave a link/hint to the new page); register the page in the admin settings nav + route following the existing page registrations.
- [ ] **Step 3: Commit.** `feat(web): AI services settings page`
-
---
-
-## Task 13: Frontend — metadata translate action
-
- [ ] **Step 1:** API client functions + types for the Task 10 endpoints.
- [ ] **Step 2:** `EditMetadataDialog.tsx`: "Translate with AI" action (visible when `metadata_ai` status is enabled): target language (default = library `metadata_language`), `include_children` (series only), `force` checkbox; enqueue, poll the job every ~1.5 s, show `progress_message`/`fields_done`, invalidate the item detail query on completion.
- [ ] **Step 3: Commit.** `feat(web): translate descriptions from the metadata editor`
-
---
-
-## Task 14: Frontend — library auto-translate toggle
-
- [ ] **Step 1:** Add the `auto_translate_metadata` switch to the library settings form next to the metadata-language field (helper text: "When metadata providers have no translation for this library's language, translate descriptions with AI"). Disabled state with hint when `metadata_ai` is off.
- [ ] **Step 2: Commit.** `feat(web): library auto-translate toggle`
-
---
-
-## Task 15: Frontend — player "Generate from audio"
-
- [ ] **Step 1:** `SubtitleTranslateModal.tsx`: when `transcribe_enabled`, add a source option "Generate from audio (AI)" listing the file's audio tracks; submit with `kind: "transcribe"` (or `transcribe_translate` when the chosen output language differs from the audio language). Surface it prominently when no text subtitle source exists (today's dead end for bitmap-only files).
- [ ] **Step 2: Commit.** `feat(web): generate subtitles from audio in the player`
-
---
-
-## Task 16: Verification
-
- [ ] `go build ./... && go test ./...`
- [ ] `make lint`
- [ ] `cd web && pnpm run lint && pnpm run format:check`
- [ ] `make verify-local-paths`
- [ ] Manual smoke against the local stack: enqueue a metadata translation for a series (verify localization rows + provenance values), re-run a refresh (verify provider values overwrite `ai` rows and `manual` simulation survives), run a `transcribe` job on a short file against a local Whisper-compatible server.
- [ ] MR description: problem, approach, link to the design doc, risks (Whisper endpoint variance, chunk-boundary artifacts), AI-use disclosure, screenshots of the new settings page / editor action / player mode.
@@ -1,276 +0,0 @@
-# Plan: Personal + Server sections on the user Collections tab
-
-Status: Draft
-Branch: `feat/collections-server-section`
-Owner: TBD
-Commands assume the repository root is the cwd.
-
-## Problem
-
-The user-facing **Collections** tab on the home screen (`web/src/pages/Collections.tsx`)
-only shows the signed-in profile's *personal* collections. For most users this list is
-empty or nearly empty, so the tab looks broken or pointless.
-
-Meanwhile, server-curated collections (admin-created "library collections") only appear
-*inside each individual library's* Collections tab (`web/src/pages/LibraryCollections.tsx`,
-served by `GET /library/{id}/collections`). There is no place in the app where a user can
-see the collections curated across the whole server — they are effectively hidden behind
-per-library navigation.
-
-We want the top-level Collections tab to become the single home for collections:
-
-1. **Your collections** — the user's personal/shared collections, with a large section
-   title, shown at the top (current behavior, kept intact: grouping, drag-reorder, create,
-   edit, sync, delete).
-2. **Server collections** — below that, a clearly titled section aggregating the visible
-   server (library) collections across every library the user can access, so they are no
-   longer buried per-library.
-
-## Current state (what exists today)
-
-### Frontend
- `web/src/pages/Collections.tsx` — the top-level tab. Renders the page header + a
-  `GroupedCollectionsBoard` of personal collections. Data via `useCollections()` /
-  `useCollectionGroups()` (`web/src/hooks/queries/collections.ts`), both backed by
-  `GET /collections` → `CollectionsListResponse { collections, groups }`.
- `web/src/pages/LibraryCollections.tsx` — per-library tab. Renders a poster grid
-  (`CollectionPosterCard`) grouped by admin groups + ungrouped. Data via
-  `useLibraryCollections(libraryId)` → `GET /library/{id}/collections` →
-  `LibraryTabResponse { groups, ungrouped }`. **This is the visual we want to reuse for the
-  server section** (poster cards, item-count badge, navigate to catalog href).
- `web/src/api/types.ts` — `Collection`, `CollectionGroup`, `CollectionsListResponse`,
-  `LibraryTabResponse`, `LibraryTabGroup`, `LibraryTabCollection`, `LibraryTabUngrouped`.
- Catalog hrefs: `buildLibraryCollectionCatalogHref(id, title)` and
-  `buildUserCollectionCatalogHref(id, title)` in `web/src/pages/catalogSearchParams.ts`.
-
-### Backend
- `internal/api/handlers/collections.go` — personal collection handlers under `/collections`
-  (registered in `internal/api/router.go` ~lines 1700-1726, behind `RequireProfile`).
- `internal/api/handlers/library_collections.go`:
-  - `HandleListLibraryCollections` (line 813) — builds the per-library `LibraryTabResponse`.
-  - `requestCanAccessLibrary` (line 3311) — checks `access.GetScope(ctx).AllowedLibraryIDs`
-    (nil ⇒ access to all libraries).
-  - `LibraryCollectionRepository.ListAll(ctx, libraryID *int, opts)`
-    (`internal/catalog/library_collection_repo.go:368`) — **with `libraryID == nil` it
-    already returns server collections across all libraries** (uses
-    `libraryCollectionScopeFallbackJoin`), filtering `visibility = 'visible'` unless
-    `IncludeHidden`. This is the aggregation primitive we need.
-  - `presignGPURL` / `toLibraryCollectionResponses` — turn stored poster paths into signed
-    URLs for the response.
-
-## Design decision: aggregate on the server, new endpoint
-
-We add a new **user-facing aggregate endpoint** rather than fanning out N per-library calls
-from the client (avoids N round-trips, keeps access/visibility filtering server-side, and
-matches the "Performance first / Reliability first" priorities in `CLAUDE.md`).
-
-### New endpoint
-
-`GET /collections/server` (registered next to the other `/collections` routes in
-`internal/api/router.go`, behind `RequireProfile`).
-
-Response shape (new types, mirrors the poster-card needs without per-library group noise):
-
-```jsonc
-{
-  "libraries": [
-    {
-      "library_id": 3,
-      "library_name": "Movies",
-      "total_count": 80,           // total visible server collections in this library
-      "collections": [            // CAPPED teaser slice (see "Scale & pagination")
-        {
-          "id": "...",
-          "title": "...",
-          "poster_url": "https://signed...",
-          "poster_thumbhash": "...",
-          "item_count": 42,
-          "featured": false
-        }
-      ]
-    }
-  ]
-}
-```
-
-Grouping by library (with `library_name`) is the recommended default: it lets the frontend
-render "Server collections" as one **horizontal scrollable row per library**, which keeps a
-large catalog legible. (Alternative: a single flat list — simpler UI, but loses provenance
-and the per-library "See all" affordance. Recommend per-library grouping.)
-
-### Scale & pagination (many collections per library)
-
-The server section is a **discovery** surface aggregating across *all* accessible libraries
-at once, so a full wrapping grid per library does not scale (e.g. 5 libraries × 80
-collections = 400 stacked tiles). Decisions:
-
- **Render each library as a horizontal carousel row**, not a wrapping grid. Heading = the
-  library name + a **"See all →"** link.
- **Cap the response** at ~20 collections per library and include `total_count`. Ordering of
-  the capped slice follows the repo's existing `featured DESC, sort_order ASC, title ASC`
-  ("best first"), so the teaser row surfaces featured/curated collections.
- **"See all" links to the existing per-library Collections tab**
-  (`/library/{id}` Collections tab, served by the unchanged
-  `GET /library/{id}/collections`), which already renders the full wrapping grid with admin
-  grouping. We do **not** build a new full-aggregate view — reuse the canonical
-  "show everything for this library" surface.
- This caps payload size and the per-library query cost, and keeps the home tab fast
-  ("Performance first").
-
-### API contract impact
-
- `GET /collections` (personal) — **unchanged**.
- `GET /library/{id}/collections` (per-library tab, "See all" target) — **unchanged**;
-  reused as-is.
- `GET /collections/server` — **new, additive**. No existing response changes; no
-  Android/Apple contract break.
-
-### Why a separate endpoint, not extending `GET /collections`
-
-It is tempting to make `GET /collections` return both personal and server collections in one
-call. We deliberately do **not**, for three reasons:
-
- **Client safety / semantics.** `GET /collections`'s `collections[]` array is the user's
-  *editable, personal* shelves — web and the Android/Apple clients render reorder/edit/
-  delete/sync affordances on it. Mixing read-only server collections into that same array is
-  a *silent semantic break*: the JSON still parses, so nothing errors, but clients would
-  offer "delete"/"reorder" on collections the user can't mutate (→ 403/404). A new sibling
-  field (`{ collections, groups, server }`) would be additive and parse-safe, but still
-  couples discovery into the personal-management contract.
- **Cache / refetch lifecycle.** `GET /collections` is the heavily-mutated query —
-  invalidated on every create, edit, reorder, group change, and sync (via
-  `invalidateUserCollectionQueries`). Server collections don't change on a personal reorder,
-  so folding them in would refetch the whole server-wide catalog on every personal mutation
-  ("Performance first" violation). Separate endpoints ⇒ independent cache keys + lifecycles.
- **Zero downstream risk.** A brand-new `/collections/server` endpoint cannot break existing
-  clients, because nothing calls it yet. Consolidating into one call later is a *deliberate
-  follow-up requiring coordinated Android/Apple work* — and must use a distinct field, never
-  overload `collections[]`.
-
-### Handler logic (`HandleListServerCollections`)
-
-1. Resolve accessible library IDs: read `access.GetScope(ctx)`. If `AllowedLibraryIDs ==
-   nil`, the user can see all libraries → list all of them; else restrict to that set.
-2. List visible server collections:
-   - Simplest correct approach: call `repo.ListAll(ctx, nil, ListLibraryCollectionsOptions{})`
-     once (server-wide, visible-only), then **filter each collection to libraries the user
-     can access** and bucket by library. This requires knowing each collection's
-     library membership (`library_collection_libraries`). If `ListAll` does not already
-     return membership, either (a) add a per-library loop calling
-     `repo.ListByLibrary(ctx, libID, opts)` for each accessible library (bounded by library
-     count, each query already does the grouping/sort), or (b) extend the repo to return
-     library membership. **Recommended: per-accessible-library loop** — reuses the existing,
-     tested `ListByLibrary` path and naturally yields the per-library buckets and respects
-     scope. Deduplicate collections that span multiple libraries if we choose flat output;
-     for per-library output, a collection legitimately appears under each of its libraries.
-3. For each library, set `total_count` to the full visible count, then **cap
-   `collections` to ~20** (keep the repo's `featured DESC, sort_order ASC, title ASC`
-   ordering so featured/curated collections lead). Define the cap as a single named
-   constant.
-4. Resolve library display names (catalog/library store lookup) for `library_name`.
-5. Presign poster URLs via the existing `presignGPURL` helper — only for the capped slice,
-   so we never presign 100 posters we won't send.
-6. Skip empty libraries. Return `200` with `{ libraries: [] }` when nothing is visible.
-
-Reuse existing helpers (`presignGPURL`, sort helpers like `applyCollectionSort`) rather than
-duplicating logic. Add the new response structs next to the existing
-`libraryTabResponse` types in `library_collections.go`, or in `collections.go` if cleaner —
-keep them in the package that owns the behavior.
-
-## Frontend changes
-
-### Types (`web/src/api/types.ts`)
-Add:
-```ts
-export interface ServerCollectionsLibrary {
-  library_id: number;
-  library_name: string;
-  total_count: number; // total visible; collections[] is a capped teaser slice
-  collections: LibraryTabCollection[]; // reuse existing shape
-}
-export interface ServerCollectionsResponse {
-  libraries: ServerCollectionsLibrary[];
-}
-```
-
-### Query hook (`web/src/hooks/queries/collections.ts` + `keys.ts`)
- Add `collectionKeys.server()` to `web/src/hooks/queries/keys.ts`.
- Add `useServerCollections()` → `GET /collections/server` →
-  `ServerCollectionsResponse`. Independent query key from `/collections`, so the personal
-  section keeps its single round-trip and the server section loads in parallel.
-
-### Page (`web/src/pages/Collections.tsx`)
-Restructure into two titled sections inside the existing `page-shell`:
-
-1. **"Your collections"** section
-   - Add a large section title (e.g. `<h2 class="page-title ...">Your collections</h2>`)
-     above the existing `GroupedCollectionsBoard` / empty-state block. Keep all current
-     personal-collection behavior unchanged (create, group, reorder, sync, delete).
-   - The page-level `<h1>Collections</h1>` header + subtitle + action buttons stay at the
-     very top.
-
-2. **"Server collections"** section (new)
-   - Title `<h2>Server collections</h2>` with a short subtitle ("Curated across every
-     library on this server").
-   - Use `useServerCollections()`. Render **one horizontal scrollable row per library**
-     (carousel), not a wrapping grid. Each poster card reuses the **same visual as
-     `LibraryCollections.tsx`** — extract `CollectionPosterCard` into a shared component so
-     both pages use it (avoids duplicate logic per `CLAUDE.md` maintainability rule).
-     Proposed location: `web/src/components/collections/CollectionPosterCard.tsx`.
-   - For each `library` bucket: a sub-heading row with `library_name` and a **"See all →"**
-     link routing to that library's existing Collections tab (the unchanged
-     `GET /library/{id}/collections` surface). Show "See all" only when
-     `total_count > collections.length`; optionally include the count, e.g. "See all (80)".
-   - Cards navigate via `buildLibraryCollectionCatalogHref(id, title)` and show the
-     item-count badge. These are admin/library collections (`kind="regular"`); the
-     sidebar-pin affordance can remain — pass `library.library_id` as `libraryId`.
-   - Use the project's existing horizontal-row/carousel pattern if one exists (check
-     `web/src/components` for a shelf/row component used on the home screen) rather than
-     hand-rolling overflow scrolling; reuse it for consistent snap/scroll behavior.
-   - Loading: skeleton row(s) (reuse the existing skeleton block pattern).
-   - Empty: if `libraries` is empty, render nothing (or a muted "No server collections yet"
-     line) — do not show a scary empty state, since the personal section above may have
-     content.
-
-### Refactor note
-Extracting `CollectionPosterCard` is the only shared-logic extraction required. Keep the
-extraction behavior-identical for `LibraryCollections.tsx` (props: `collection`, `kind`,
-`libraryId`). The per-library tab keeps its wrapping grid; only the new server section uses
-horizontal rows.
-
-## Out of scope / non-goals
- No changes to how admin/library collections are created or to per-library tabs.
- No reordering/editing of server collections from the user Collections tab (read-only).
- No new visibility model — we honor existing `visibility = 'visible'` + access scope.
-
-## Risks / follow-ups
- **Access scope correctness**: must not leak collections from libraries outside
-  `AllowedLibraryIDs`. Mitigate by driving the query from accessible library IDs, and add a
-  test for a restricted-scope user.
- **Collections spanning multiple libraries** appear once per library in per-library output;
-  confirm this is the desired UX (vs. dedup). Decide before implementation.
- **Performance**: per-accessible-library loop is N queries. Acceptable for typical library
-  counts; if N grows large, revisit with a single membership-aware query. Add an index check
-  on `library_collection_libraries(library_id)` (likely already present).
- **Client parity**: this is a new server endpoint and a web-only UI change. Android/Apple
-  clients have their own collections surfaces — file follow-up issues if they should mirror
-  the personal+server split. No API contract break (purely additive endpoint).
- **Empty-state UX** for users with no personal AND no server collections — ensure the page
-  still reads sensibly.
-
-## Verification
- Backend: `go build ./...`, `go vet ./...`, and a handler/unit test for
-  `HandleListServerCollections` covering (a) full access, (b) restricted scope, (c) empty.
- Frontend: `cd web && pnpm run lint && pnpm run format:check`; `make verify-local-paths`.
- Manual: log in as a normal profile with empty personal collections; confirm the
-  "Your collections" section shows the empty/create state and the "Server collections"
-  section lists library collections grouped by library with correct posters, counts, and
-  working navigation into each collection's catalog view.
-
-## Implementation order
-1. Backend: response types + `HandleListServerCollections` + route registration.
-2. Backend test for access-scope filtering.
-3. Frontend: types + `useServerCollections` hook + `collectionKeys.server()`.
-4. Frontend: extract shared `CollectionPosterCard`; refactor `LibraryCollections.tsx`.
-5. Frontend: restructure `Collections.tsx` into the two titled sections.
-6. Lint/format/build/manual verification.
@@ -1,14 +1,13 @@
 # Audiobooks Absorption — Discovery Findings

 Produced by sub-plan 1, Task 1. Locks data-model and integration
-decisions for the audiobook foundation migrations and downstream sub-plans.
+decisions for migrations 139–142 and downstream sub-plans.

 ## D1 — Next migration number

-Original snapshot: `138_search_number_word_normalization.up.sql` was the
-highest existing migration. The landed implementation was renumbered to
-`147_abs_sessions`, `157_podcast_feeds`, `159_media_folders_kind_noop`, and
-`160_audiobooks_feature_flag`.
+Highest existing migration: 138_search_number_word_normalization.up.sql
+Next available number: 139
+Sub-plan 1 will use migrations 139 through 142.

 ## D2 — `media_libraries` kind/type column

@@ -17,10 +16,10 @@ The spec refers to `media_libraries` but the actual table is `media_folders`.
 library content. Current values in production: `movies`, `series`, `mixed`.

 Existing column 'type' (text) discriminates library content on `media_folders`.
-Task 4 (migration 159) should ADD the value `audiobooks` to the type vocabulary
+Task 4 (migration 141) should ADD the value `audiobooks` to the type vocabulary
 rather than add a new column. The audiobook scanner branch will set
 `media_folders.type = 'audiobooks'` for audiobook libraries. No schema change
-needed for the column itself; migration 159 becomes a no-op DDL migration that
+needed for the column itself; migration 141 becomes a no-op DDL migration that
 documents the new allowed value and adds any supporting indexes if needed.

 No CHECK constraint or enum enforces the `type` column values, so adding
@@ -1,224 +0,0 @@
-# Audiobook Player QoL Improvements
-
-Commands assume the repository root is the cwd. All paths are repository-relative.
-
-## Goal
-
-Bring the web audiobook player to feature parity with best-in-class audiobook apps
-(Audiobookshelf, Audible, BookPlayer, Prologue) on the quality-of-life axis. The current
-surface architecture (persistent mini bar + expandable Now Listening view, playback
-survives navigation) is already the de-facto standard and stays as-is.
-
-Explicitly **out of scope**: Media Session / lock-screen integration, bookmarks (needs a
-server endpoint — follow-up), offline/download, queue.
-
-## Features
-
-1. **Keyboard shortcuts** — space/K play-pause, arrow skips, volume, chapter nav, speed step.
-2. **Configurable skip intervals** — asymmetric defaults (back 10s, forward 30s), user-tunable.
-3. **Expanded speed control** — 0.5×–3.0× with fine stepping, presets, and per-book memory.
-4. **Chapter prev/next buttons** — alongside the seconds-skip buttons.
-5. **Volume control** — reuse the shared `VolumeControl`, persisted like the video player.
-6. **Smart rewind** — auto-rewind on resume, scaled by how long playback was paused.
-7. **Time remaining at current speed** — real-clock remaining display in Now Listening.
-
-No server/API changes are required; everything is web-frontend only, so no Android/Apple
-client coordination is needed. (Per-book speed memory is device-local in v1; syncing it
-server-side via profile settings is a noted follow-up.)
-
-## Existing seams (read these first)
-
-| File | Relevance |
-| --- | --- |
-| `web/src/pages/audiobooks/player/useAudiobookPlayback.ts` | Playback engine. `togglePlay` (~line 499), `skip` (~534), `setRate` (~541), returned API (~690+). All engine work lands here. |
-| `web/src/pages/audiobooks/player/MiniBar.tsx` | Bottom bar. Hardcoded `SKIP_*_SECONDS = 30` and `PLAYBACK_RATES` at lines 10–12. |
-| `web/src/pages/audiobooks/player/NowListening.tsx` | Full-screen view. Same hardcoded constants; dead "More" button (lines 50–56) becomes the settings menu trigger; remaining-time toggle at lines 33–37. |
-| `web/src/pages/audiobooks/player/AudiobookPlayer.tsx` | Wrapper that owns mini/now-listening mode — mount point for the keyboard shortcuts hook. |
-| `web/src/player/components/VolumeControl.tsx` | Existing slider + `getPersistedVolume`/`persistVolume` helpers (shared `player-volume`/`player-muted` storage keys). Styled for dark video overlay — needs a surface-toned variant. |
-| `web/src/player/components/SpeedMenu.tsx` | Current preset-only menu (shared with video player). Audiobook gets a richer `SpeedControl`; video keeps `SpeedMenu` untouched. |
-| `web/src/player/hooks/useKeyboardShortcuts.ts` | Video player's shortcut hook — pattern to mirror (input-field guard, single document listener). |
-| `web/src/utils/storage.ts` | Typed localStorage wrapper — add new keys here, never call `localStorage` directly. |
-| `web/src/player/components/SeekBar.tsx`, `CircleButton.tsx`, `SleepTimerMenu.tsx`, `ChaptersMenu.tsx` | Established player design language; reuse, don't fork. |
-
-## Design language
-
-These are additions to an existing, refined system — extend it, don't restyle it:
-
- **Surfaces**: mini bar is a themed surface (`bg-background`, `border-t`, token colors).
-  Popovers anchored to it use the established dark-glass treatment
-  (`bg-black/90 backdrop-blur-sm rounded-lg shadow-xl`, white/75 text, `data-active` rows)
-  exactly as `SpeedMenu`/`SleepTimerMenu` do today.
- **Type**: time and rate values are always `font-mono`/`tabular-nums` so nothing shifts as
-  digits tick. The new speed readout (`1.45×`) must reserve width for two decimals.
- **Buttons**: all transport controls are `CircleButton` (`sm` secondary flanks, `md`/`lg`
-  primary center). Chapter prev/next use `SkipBack`/`SkipForward` lucide glyphs at the same
-  stroke weight (1.6) as the rotate icons, so the cluster reads as one family.
- **Micro-interactions**, small and purposeful:
-  - Skip buttons: a quick ~18° icon flick in the skip direction on press
-    (CSS transform transition, ~150ms ease-out) — confirms the action without a toast.
-  - Speed stepper: value crossfades (opacity 120ms) on change; the active preset chip gets
-    the same `bg-white/5 text-white` treatment as current menu rows.
-  - Smart rewind: when it fires, the seek bar playhead animates the small jump back rather
-    than teleporting (SeekBar already animates position; verify it holds for ≤30s deltas).
- **Accessibility**: every new control keeps the existing patterns — `aria-label`,
-  `aria-expanded`/`aria-haspopup` on triggers, roving focus + Escape in menus (copy from
-  `SleepTimerMenu`), `role="slider"` semantics from `VolumeControl`/`SeekBar`.
-
-## Phase 1 — Engine + preferences model
-
-### 1a. Preferences hook
-
-New `web/src/pages/audiobooks/player/useAudiobookPrefs.ts`:
-
- Add storage keys: `AUDIOBOOK_SKIP_BACK`, `AUDIOBOOK_SKIP_FORWARD`,
-  `AUDIOBOOK_SMART_REWIND` (bool), `AUDIOBOOK_RATES` (JSON map) in `web/src/utils/storage.ts`.
- Exposes `{ skipBack, skipForward, smartRewind, setSkipBack, setSkipForward, setSmartRewind }`.
- Defaults: back **10s**, forward **30s** (the asymmetric convention — small "what did she
-  say?" hops back, bigger hops forward), smart rewind **on**.
- Allowed skip values: 5, 10, 15, 30, 45, 60, 90 (two digits max keeps `SkipIcon`'s inset
-  number legible).
- Per-book rate map: single JSON object `{ [contentId]: rate }` under `AUDIOBOOK_RATES`,
-  LRU-capped at 50 entries (store `{ rate, at }` and evict oldest on insert).
-  Helpers `getBookRate(contentId)` / `setBookRate(contentId, rate)` live here too.
-
-### 1b. Engine extensions (`useAudiobookPlayback.ts`)
-
- **Volume/mute**: initialize from `getPersistedVolume()`; apply to the `<audio>` element in
-  an effect; expose `volume`, `muted`, `setVolume`, `setMuted`; persist via `persistVolume`.
-  Sharing the video player's keys is intentional — one volume preference per device.
- **Per-book rate**: on mount, initialize `rate` from `getBookRate(contentId)` (fallback 1);
-  in `setRate`, also `setBookRate`. The hook needs `contentId` passed in (it already
-  receives the files/options object — extend that input).
- **Chapter navigation**: expose `nextChapter()` and `prevChapter()`.
-  - `next`: seek to start of the chapter after `currentChapter`; no-op at the last chapter.
-  - `prev`: if more than 3s into the current chapter, seek to its start; otherwise seek to
-    the previous chapter's start (the universal music/audiobook convention).
- **Smart rewind**: record `pausedAtRef = performance.now()` whenever playback pauses (in
-  the `pause` event handler so it also catches OS-initiated pauses). On resume, before
-  `audio.play()`, compute rewind from pause duration and `seekTo(currentTime - rewind)`:
-  - < 10s paused → 0s; < 1min → 3s; < 10min → 10s; < 1h → 20s; ≥ 1h → 30s.
-  - Clamp at 0; skip entirely when the smart-rewind pref is off or the resume immediately
-    follows a user seek (seeking sets a short suppress flag so explicit jumps aren't undone).
-  - Also apply on **cold resume**: when starting with `initialPositionSeconds > 0` from the
-    detail page, rewind by the same schedule using the age of the saved progress if the
-    API exposes an updated-at timestamp; otherwise apply a flat 10s. Keep this logic in one
-    pure function `smartRewindSeconds(pauseMs)` so it's unit-testable.
- **Skip intervals**: no engine change — `skip(delta)` already takes a signed delta; the UI
-  passes the configured values.
-
-### 1c. Tests
-
-Vitest, colocated like existing `*.test.tsx`:
-
- `smartRewindSeconds` schedule boundaries.
- Per-book rate LRU (cap, eviction, malformed-JSON tolerance).
- `prevChapter` 3s threshold behavior and first/last chapter edges
-  (chapter math is pure — test against `buildChapterList` fixtures from
-  `web/src/lib/audiobooks/chapters.ts`).
-
-## Phase 2 — Controls UI
-
-### 2a. SpeedControl (new, audiobook-specific)
-
-New `web/src/pages/audiobooks/player/SpeedControl.tsx`, replacing `SpeedMenu` usage in both
-audiobook views (video player keeps `SpeedMenu`):
-
- Trigger: same `player-utility-btn` showing the current rate (`1.45×`, tabular-nums).
- Popover (dark-glass, bottom-anchored like today):
-  - A stepper row: `−` / big mono readout / `+`, stepping **0.05** per tap, clamped to
-    **0.5–3.0**. Press-and-hold repeats (250ms initial, 80ms repeat).
-  - A preset chip row: 1× · 1.25× · 1.5× · 1.75× · 2× · 2.5× · 3×.
-  - Footnote line: "Remembered for this book" (quiet `text-white/40`, 11px) — makes the
-    per-book memory discoverable instead of magical.
- Keyboard: ArrowUp/Down step inside the popover; Escape closes (copy menu plumbing from
-  `SleepTimerMenu`).
-
-### 2b. Chapter prev/next buttons
-
- Add `SkipBack`/`SkipForward` `CircleButton size="sm" variant="secondary"` on the outside
-  of the transport cluster in both `MiniBar` and `NowListening`:
-  `⏮ ↺10 ▶ ↻30 ⏭`. Wire to `prevChapter`/`nextChapter`; render only when
-  `playback.chapters.length > 0`; disable at the ends (prev stays enabled mid-chapter).
- In `MiniBar`, hide the chapter buttons below `sm:` — the 3-column grid is already tight
-  on phones and the chapters menu remains available.
-
-### 2c. Volume
-
- Add a `tone` prop to `web/src/player/components/VolumeControl.tsx`
-  (`"overlay"` = current white-on-dark, `"surface"` = theme tokens: track `bg-muted`,
-  fill `bg-foreground`, focus ring `ring-ring`). Default `"overlay"` so the video player is
-  untouched.
- Mount in `MiniBar`'s right cluster (before the sleep timer) at `md:` and up, and in
-  `NowListening`'s utility row. Wire to the new engine `volume`/`muted` state.
-
-### 2d. Player settings menu
-
-New `web/src/pages/audiobooks/player/PlayerSettingsMenu.tsx` (dark-glass popover):
-
- **Skip back** / **Skip forward**: rows of small value chips (5/10/15/30/45/60/90s).
- **Smart rewind**: toggle row with a one-line description ("Backs up a little after a pause").
- Triggers: the currently-dead "More" (`MoreHorizontal`) button in `NowListening`
-  (lines 50–56) and a matching trigger in `MiniBar`'s right cluster.
- `MiniBar`/`NowListening` read `useAudiobookPrefs()` and pass the configured seconds to
-  the skip buttons and `SkipIcon` (which already renders a dynamic number) — delete the
-  `SKIP_*_SECONDS` constants.
-
-## Phase 3 — Shortcuts + time display + polish
-
-### 3a. Keyboard shortcuts
-
-New `web/src/pages/audiobooks/player/useAudiobookKeyboardShortcuts.ts`, mounted in
-`AudiobookPlayer.tsx` (so it's active in both mini and expanded modes, on every route):
-
-| Key | Action |
-| --- | --- |
-| Space / K | play-pause |
-| ← / → | skip by configured back/forward seconds |
-| ↑ / ↓ | volume ±5% |
-| M | mute toggle |
-| N / P | next / previous chapter |
-| Shift+. / Shift+, | speed +0.05 / −0.05 (YouTube convention) |
-| E | expand / collapse Now Listening |
-| Esc | collapse Now Listening (expanded mode only) |
-
- Mirror `useKeyboardShortcuts.ts` guards: ignore when target is input/textarea/
-  contentEditable, single document listener, cleanup on unmount.
- Additional guard: **do nothing while a video session is active** — the video player binds
-  the same keys. Check `WatchPlaybackProvider` state (or simply whether a `<video>` watch
-  route is mounted) and bail; the audiobook bar is backgrounded in that case anyway. Space
-  must also not fire when a button has focus (let the focused control handle Enter/Space).
- Add `title` tooltips with the shortcut hint to transport buttons
-  (e.g. `Back 10 seconds (←)`) for discoverability.
-
-### 3b. Time remaining at current speed
-
-In `NowListening`, the right time label currently toggles total ↔ remaining. Make it cycle
-three states (persist last choice in component state only):
-
-1. total (`12:04:00`)
-2. remaining (`−3:21:09`)
-3. remaining at speed (`−2:14:06 at 1.5×`) — `remaining / rate`, hidden (skipped in the
-   cycle) when `rate === 1`.
-
-Keep the `data-testid="now-listening-right-time"` hook and update its test.
-
-### 3c. Polish pass
-
- Skip-flick and speed-crossfade micro-interactions from the design section.
- Verify mini bar layout on 360px-wide viewports with all new controls (chapter buttons and
-  volume hidden, settings menu accessible).
- `cd web && pnpm run lint && pnpm run format:check`; run the player test suites.
-
-## Risks / notes
-
- `useAudiobookPlayback.ts` is 707 lines and growing — extract smart rewind + prefs-coupled
-  logic into small pure modules (`smartRewind.ts`) rather than inflating the hook; consider
-  splitting volume/rate concerns into a `useAudioElementSettings` helper if the hook passes
-  ~800 lines.
- Smart rewind must not fight the 10s progress reporter: rewinding on resume changes
-  `currentTime`, which triggers a progress write — that's correct (the rewound position is
-  the truth), just confirm no oscillation with the suppress-after-seek flag.
- Per-book rate uses `contentId`; switching narrators navigates to a different `contentId`,
-  so each narration remembers its own speed — acceptable, arguably desirable.
- Cross-device sync of prefs/per-book speed is a candidate follow-up once a profile
-  settings endpoint exists; the `useAudiobookPrefs` API is the seam to swap storage behind.
@@ -1,388 +0,0 @@
-# Silo Notifications — Architecture Overview
-
-**Date:** 2026-04-28
-**Status:** Draft
-**Scope:** Cross-cutting design covering all delivery channels: durable in-app inbox, realtime websocket, Apple Push (APNs), Android Push (FCM), and outbound webhooks.
-**Companion docs:**
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md) — Foundation
- [`02-apns-relay.md`](./02-apns-relay.md) — Apple push
- [`03-fcm-relay.md`](./03-fcm-relay.md) — Android push
- [`04-outbound-webhooks.md`](./04-outbound-webhooks.md) — Discord and generic webhooks
-
-## Goal
-
-Silo should notify a profile when a new episode of a series they care about becomes available in their library. "Care about" means at least one of: the series is favorited, watchlisted, in continue-watching, or has a profile-eligible next-up cursor.
-
-The notification should reach the profile through whichever delivery channels the profile has configured: an in-app inbox with realtime push to connected clients, mobile push notifications to Apple and Android devices, and outbound webhooks to user-chosen destinations like a Discord channel.
-
-## Why this is hard
-
-Three constraints pull in different directions:
-
-1. **Self-hosted privacy.** Silo is self-hosted media. Notification content (episode titles, posters, profile names, library identity) must never leave the user's server unless the user has explicitly opted into a destination that requires it.
-2. **Mobile push gatekeeping.** Apple and Google require pushes to the official App Store / Play Store builds to be authenticated by the credentials of the developer account that signed and published the app. There is no fully self-hosted, zero-Silo-infrastructure path to push to the official mobile apps.
-3. **Multi-profile fairness.** A single user account on a Silo server can have multiple profiles (kid, adult, parent, etc.). Notifications must be scoped to the active profile. Devices, push tokens, webhooks, and preferences are all profile-scoped.
-
-The design resolves these by:
-
- Routing all notification work through a durable per-profile inbox that lives on the user's own server. Everything else is a transport on top of this inbox.
- Operating a privacy-preserving relay for APNs and FCM that holds the official-app credentials and accepts only opaque push requests. Self-hosted servers opt in. The relay never sees notification content.
- Profile-scoping every database row, every API surface, every websocket subscription, and every push registration.
-
-## Mental model
-
-```
-                    ┌─────────────────────────────────────────────────┐
-                    │                                                 │
-   ingest/scan ────► release_events  (one row per newly-available     │
-                    │   episode in a library)                         │
-                    │      │                                          │
-                    │      ▼                                          │
-                    │   fanout worker                                 │
-                    │      │                                          │
-                    │      │   loads profile_series_interest          │
-                    │      │   applies eligibility + preferences      │
-                    │      ▼                                          │
-                    │   notification_deliveries  (one row per         │
-                    │      eligible profile per release)              │
-                    │      │                                          │
-                    │      │   AFTER COMMIT                           │
-                    │      ▼                                          │
-                    │   channel dispatcher  ◄── fans out to channels: │
-                    │                                                 │
-                    │   ┌───────────────┬───────────────┬─────────┐   │
-                    │   │               │               │         │   │
-                    │   ▼               ▼               ▼         ▼   │
-                    │ websocket    apple push       android   webhooks│
-                    │ (in-app)     (APNs relay      push      (per    │
-                    │              or custom)       (FCM)     profile)│
-                    │   │               │               │         │   │
-                    └───┼───────────────┼───────────────┼─────────┼───┘
-                        ▼               ▼               ▼         ▼
-                 connected       iOS / tvOS /        Android    Discord /
-                 browser tabs    macOS apps          apps       user URL
-                 and apps        (wake then          (wake)     (content
-                                 fetch metadata)                included)
-```
-
-Three invariants make this work:
-
- **The durable row is the source of truth.** Realtime websocket events, mobile pushes, and webhooks are all triggered *after* the `notification_deliveries` row commits. If any transport fails, the inbox row still exists and shows up on next reconnect or refresh.
- **The fanout worker decides recipients exactly once.** Recipients are derived from a compact `profile_series_interest` index keyed by `(library_id, series_id)`. Per-channel transports are purely about delivery — they never make recipient decisions.
- **Dispatch enqueue is durable (outbox).** The same fanout transaction that inserts `notification_deliveries` also inserts `pending` per-target attempt rows for the push and webhook channels (`push_delivery_attempts` / `webhook_delivery_attempts`). The post-commit dispatcher *claims* those rows for immediate delivery; recovery workers sweep stale `pending` rows. A crash between delivery commit and dispatch therefore delays pushes/webhooks instead of silently dropping them. The websocket channel deliberately has no outbox row — it is best-effort because the inbox snapshot covers reconnect. See `01-release-events-and-inbox.md` "Transaction and Concurrency Rules".
-
-## Channels at a glance
-
-| Channel | Where it lives | Trust model | Content visibility |
-|---|---|---|---|
-| **In-app inbox** | User's own server, accessed via authenticated REST API | Same auth as the rest of Silo | Full content |
-| **Realtime websocket** | User's own server, `/events/ws` channel `notifications` | Same auth, profile-scoped | Full content |
-| **Apple Push (APNs)** | Silo-operated relay (or admin-supplied custom APNs credentials) | Opt-in. Self-hosters trust the relay to forward opaque requests. | Opaque payload only — app fetches content from user server after wake |
-| **Android Push (FCM)** | Silo-operated relay (or admin-supplied custom FCM credentials) | Same as APNs | Opaque data-only message — app fetches content from user server after wake |
-| **Outbound webhooks** | User-chosen destination URL (e.g., Discord, Slack, custom service) | Profile chose the destination; trust is implicit | Full content included by default. Discord type renders native embeds; generic type sends signed JSON |
-
-## Triggers (what generates a notification)
-
-A notification is generated when a new episode becomes available in a library and at least one profile has interest in the series:
-
- **Favorite** — the series is favorited by the profile.
- **Watchlist** — the series is on the profile's watchlist.
- **Continue watching** — the profile has in-progress watch state for the series.
- **Next up** — the new episode is at or beyond the profile's `next_expected_episode_key` cursor and the profile has progression state for the series.
-
-A profile may match multiple reasons for a single release event. The `notification_deliveries` row records all matching reasons in a `reason_flags` JSONB column; the fanout produces exactly one delivery per `(profile_id, release_event_id)` regardless of how many reasons matched. A second uniqueness rule spans libraries: because Silo media items are catalog-level (`media_item_libraries` is a junction), the same episode landing in two libraries (e.g., "TV" and "TV 4K") shares one `episode_id`, and at most one `episode.available` delivery is created per `(profile_id, episode_id)` — dual-quality library setups do not double-notify.
-
-**Back-catalog protection:** "newly available" must mean *newly released to this server*, not *newly seen by the notifications feature*. The first scan of a newly created library and the one-time feature-enable backfill **seed** `episode_availability` without creating release events, and the fanout worker applies a per-series burst cap for bulk additions to existing libraries. Without this, importing a 200-episode back-catalog of a series with hundreds of interested profiles would generate tens of thousands of deliveries and pushes in a single scan. Full rules in `01-release-events-and-inbox.md` "Seeding and Burst Suppression".
-
-**v1 explicitly does not support:**
-
- Movie additions. Silo has no movie-availability detector parallel to the per-episode one in this design; without it, there's nothing to fan out from for movies. Users *can* watchlist movies that don't yet exist in their library (via TMDB lookups), but the missing piece is the ingest-time signal that a watchlisted movie has now arrived. v2 can add a `movie_availability` table and analogous release events; the fanout/inbox/channel layers in this design are movie-ready by construction.
- Metadata-only updates (poster refreshes, title corrections).
- Generic library-changed notifications.
- Aggregated notifications like "3 new episodes available." Per-episode deliveries first; aggregation is a presentation concern that can stack on top.
-
-## Mode terminology
-
-The design uses three vocabularies that correspond to different layers; they are intentionally not the same word. This is the canonical mapping:
-
-| Layer | Terms | Where it lives |
-|---|---|---|
-| **Profile-level push mode** (UI-facing) | `off`, `in_app_only`, `private_push` | `push_devices.push_mode` |
-| **APNs wire mode** (relay request `mode` field) | `private_alert`, `background_wake` | Sent to APNs relay or used in custom APNs payload builder |
-| **FCM wire mode** (relay request `mode` field) | `private_data`, `background_wake` | Sent to FCM relay or used in custom FCM payload builder |
-
-Mapping:
-
- Profile `private_push` → APNs `private_alert` for visible wakes, FCM `private_data` for visible wakes.
- Profile `in_app_only` → no remote push at all (websocket / inbox only).
- Profile `off` → no notifications for this device whatsoever.
- The `background_wake` wire mode is reserved for low-noise sync (per-channel spec details). It is not exposed at profile level in v1.
-
-## Preference model
-
-Preferences are profile-scoped and flat. There is no per-channel × per-reason matrix.
-
-```
-notification_preferences (per profile)
-├── enabled                  bool   — global kill switch
-├── notify_favorites         bool
-├── notify_watchlist         bool
-├── notify_continue_watching bool
-└── notify_next_up           bool
-```
-
-Per-webhook reason gating uses **the same four boolean columns** on `notification_webhooks` (`notify_favorites`, `notify_watchlist`, `notify_continue_watching`, `notify_next_up`) — not a single structured `reason_filters` JSON field.
-
-**Precedence:** profile preferences are a **hard gate** applied during fanout (a delivery row is not created if all matching reasons are disabled at the profile level). Per-webhook flags and per-device push mode are **additional filters** applied during dispatch — they can narrow what fires for a specific destination but cannot re-enable a reason the profile has globally disabled.
-
-Each push device has a `push_mode` (`off`, `in_app_only`, `private_push`) that gates whether mobile push fires for that specific device. Each webhook has its own `enabled` flag and per-webhook `notify_favorites` / `notify_watchlist` / `notify_continue_watching` / `notify_next_up` booleans for finer control.
-
-The fanout worker uses `notification_preferences` to decide whether to *create* a `notification_delivery` at all. The channel dispatcher uses per-device and per-webhook flags to decide which transports fire after the row commits.
-
-This means: if a profile turns off `notify_continue_watching`, a delivery is never created for a continue-watching-only match, and no transports fire. If a profile leaves the reason flags on but disables a specific Discord webhook, the inbox row + websocket + push still fire normally — the webhook just doesn't.
-
-## Mobile push: why a relay is necessary
-
-Apple and Google operate the only push infrastructure that can wake a closed app on iOS and Android. To send a push to the official Silo app on the App Store or Play Store, the request must be authenticated by the credentials of the developer account that signed and published that app build:
-
- **APNs:** Apple Developer Team ID + Auth Key ID + `.p8` private key. The auth key is account-scoped (not topic-scoped); it can sign JWTs that authorize push to any bundle topic the team owns. The `apns-topic` request header selects which topic the push targets, and Apple rejects requests whose topic is not owned by the signing team.
- **FCM:** Firebase service account JSON whose private key signs a JWT exchanged for an OAuth2 access token. The service account is scoped to a specific Firebase project, and the project owns one or more registered Android app package names. (Package + SHA-1 cert fingerprint registration matters for Firebase Authentication and App Check, but for plain FCM v1 push the service account + package name + matching FCM registration token are what's required.)
-
-Distributing these credentials to thousands of self-hosted Silo installations is not viable:
-
-1. It violates Apple's and Google's developer agreements, which prohibit sharing credentials outside the team.
-2. Anyone with a copy could push to every Silo app worldwide.
-3. Apple actively monitors and revokes leaked keys.
-
-Therefore the design separates two paths:
-
-### Hosted relay (`silo_relay`) — the default for official-app users
-
-A small Silo-operated service holds the official APNs `.p8` key and FCM service account JSON. Self-hosted servers opt in by configuring a relay API key, then call the relay with opaque push requests. The relay signs and forwards to APNs / FCM. The relay never sees notification content.
-
-The relay is **stateless on the request path**. Its database holds only:
-
- relay accounts (one per opt-in self-hosted server installation)
- relay API keys (with `last_used_at`, revocable)
- minimal per-account allowlists (which app topics this account may push to)
- redacted operational logs (no APNs/FCM tokens, no notification content)
-
-It does **not** store user identities, profile data, device-to-user mappings, or notification content. Apple and Google do the actual addressing — when a push request goes out, the relay just forwards `{token, opaque_ids}` to APNs/FCM, and APNs/FCM deliver based on the device token.
-
-### Custom credentials (`custom_apns` / `custom_fcm`) — escape hatch
-
-Power users, white-label deployments, or anyone running a fork that ships its own resigned mobile app can configure their own Apple/Google developer credentials. The user's Silo server signs requests directly using those credentials and sends to APNs/FCM without going through the Silo relay.
-
-Custom mode is **only useful if the admin has shipped a custom-signed app build under their own developer account** with their own bundle/package ID. It does not let a self-hoster push to the official App Store / Play Store app — that's not technically possible without the official developer credentials.
-
-### Addressing flow walkthrough
-
-The most common question on this design is "how does the relay know which user/device to send to with thousands of servers and thousands of users?" The answer is: it doesn't, because Apple and Google handle addressing.
-
-```
-1. User installs official Silo app on iPhone from App Store.
-2. App calls iOS push registration; Apple returns an opaque APNs device token
-   (~100 bytes, unique per app install per device).
-3. App POSTs that token to the user's OWN server:
-     POST https://my-silo.example.com/api/v1/devices/push/apple
-     { device_id, apns_token, ... }
-4. User's server stores in its push_devices table, scoped to the active profile.
-5. New episode lands. Fanout worker creates a notification_delivery row.
-6. Channel dispatcher loads the profile's enabled push_devices and POSTs
-   to the relay (or signs directly via custom_apns):
-     POST https://relay.silo.app/v1/apple/send
-     Authorization: Bearer rk_thisServersRelayApiKey
-     {
-       "token": "740f...",                    ← APNs device token from step 3
-       "topic": "com.continuum.app.ios",
-       "environment": "production",
-       "mode": "private_alert",
-       "server_device_id": "01JOPAQUE...",    ← lets app find right local server
-       "delivery_id": "01JDELIVERY..."        ← lets app fetch notification meta
-     }
-7. Relay signs JWT with Silo's .p8, forwards to APNs:
-     POST https://api.push.apple.com/3/device/740f...
-     apns-topic: com.continuum.app.ios
-     authorization: bearer <signed JWT>
-     {generic opaque payload with silo.* fields}
-8. Apple delivers to the iPhone holding token 740f...
-9. App wakes, reads server_device_id, finds matching local server account,
-   GETs full notification content from the user's own server.
-```
-
-The relay knows: a relay API key was used (so: which self-hosted server installation), the server's egress IP address (inherent to any hosted relay — the server connects to it directly), an APNs device token, a timestamp, and opaque IDs. The relay does not know: which user, which profile, what notification content, what server URL, what library, or what media item. Even a fully compromised relay leaks only timing + device tokens + egress IPs, not notification content or identity. The egress IP is the closest thing to an identity leak in this design — for home hosting it identifies the household's connection — and is listed here so the privacy claims stay exhaustive rather than over-strong.
-
-## Threat model summary
-
-Detailed per-channel threat models live in each channel's spec. The cross-cutting summary:
-
-| Channel | Adversary | Worst case |
-|---|---|---|
-| In-app inbox + websocket | Network attacker | Existing Silo auth threat model. Notifications add no new surface. |
-| APNs / FCM relay (operator) | Compromised relay or hostile relay operator | Can learn device tokens, push timing, and the server's egress IP for opted-in servers. Cannot learn user identity, notification content, server URL, or library data. Cannot fabricate meaningful pushes (only generic opaque payloads). |
-| APNs / FCM (Apple / Google) | Apple / Google as platform operator | Can see app topic, device token, generic payload, timing. No user identity, no media metadata, no server URL. |
-| Outbound webhooks | Webhook destination operator (e.g., Discord) | Sees full notification content (titles, posters, episode info) for the profile that configured the webhook. The profile chose this destination; this is the explicit trade. |
-| Outbound webhooks | Network attacker who owns a URL submitted by the user | Can receive the profile's notifications until the webhook is removed. Mitigated by HMAC for generic webhooks, HTTPS-only, host blocklist (no localhost / RFC1918 by default), and a profile-visible "last seen" / failure status. |
-
-## Channel dispatcher boundary
-
-A single internal `Dispatcher` interface fans the durable row out to channels. Each channel implements the same minimal contract:
-
-```go
-type Dispatcher interface {
-    // Called once per notification_deliveries row, AFTER the row commits.
-    // Per-target dispatchers (push, webhooks) do not decide their own work:
-    // the fanout transaction already enqueued one `pending` attempt row per
-    // (delivery_id, target_id), where target_id is push_device.id or
-    // notification_webhook.id. Dispatch claims and sends those rows; a
-    // recovery worker sweeps `pending` rows whose claim never happened
-    // (crash between commit and dispatch). Idempotency is therefore
-    // by (delivery_id, target_id, attempt_number). The websocket dispatcher
-    // has no per-target row and is instead idempotent by delivery_id alone —
-    // re-publishing the same delivery_id is a no-op for connected clients.
-    Dispatch(ctx context.Context, delivery NotificationDelivery) error
-}
-```
-
-Implementations:
-
- `WebsocketDispatcher` — publishes a `notification.created` event on the `notifications` channel, scoped to the delivery's `(user_id, profile_id)`. Best-effort; durable row is the source of truth.
- `ApplePushDispatcher` — selects enabled `push_devices` for the profile where `platform = 'apple'` and routes through the configured provider (`silo_relay` or `custom_apns`). Records each attempt in `push_delivery_attempts`.
- `AndroidPushDispatcher` — same but `platform = 'android'`, routes through `silo_relay` or `custom_fcm`.
- `WebhookDispatcher` — selects enabled `notification_webhooks` for the profile, applies per-webhook reason filters, and POSTs the channel-specific payload (Discord embed or generic JSON+HMAC). Records each attempt in `webhook_delivery_attempts`.
-
-Channel failures are isolated: if APNs is down, webhooks and websocket still fire. If a webhook destination is unreachable, push still fires. The fanout worker does **not** wait for any dispatcher to succeed before marking the release event processed; the durable delivery rows plus the `pending` outbox attempt rows (enqueued in the same transaction) guarantee eventual delivery for push and webhooks even across a crash. The relay-bound dispatchers additionally pace their sends client-side (token bucket) so a burst never trips the relay's rate limits — see `02`/`03` "Relay pacing".
-
-## Capability surface
-
-The frontend and mobile clients need to know what's available without guessing. A single capability endpoint returns the truth:
-
-```http
-GET /api/v1/notifications/capability
-```
-
-```json
-{
-  "in_app": { "enabled": true },
-  "apple_push": {
-    "available": true,
-    "provider": "silo_relay",
-    "supported_modes": ["private_push", "in_app_only"]
-  },
-  "android_push": {
-    "available": false,
-    "provider": "off",
-    "supported_modes": ["in_app_only"]
-  },
-  "webhooks": {
-    "available": true,
-    "max_per_profile": 10,
-    "supported_types": ["discord", "generic"]
-  }
-}
-```
-
-Clients render setup UI from this response. They never have to introspect admin settings.
-
-## Data model overview
-
-The full schemas live in the per-channel specs. The shared shape:
-
-| Table | Purpose | Spec |
-|---|---|---|
-| `episode_availability` | "Episode E became available in library L." Idempotent. Seeded silently for back-catalog. | 01 |
-| `release_events` | One per `(library_id, episode_id)` newly-available event. | 01 |
-| `notification_library_seed_state` | Per-library marker: availability has been seeded; release events may now be emitted. | 01 |
-| `profile_series_interest` | Compact recipient index keyed by `(profile_id, library_id, series_id)`. | 01 |
-| `notification_deliveries` | Per-profile durable inbox row. Cross-library dedupe via partial unique `(profile_id, episode_id)`. | 01 |
-| `notification_preferences` | Per-profile reason toggles + master enable. | 01 |
-| `push_devices` | Per-profile-per-device push registration. Platform-tagged (`apple` / `android`). | 02 / 03 |
-| `push_delivery_attempts` | Per-attempt push log. No notification content. | 02 / 03 |
-| `notification_webhooks` | Per-profile webhook destinations (Discord or generic). | 04 |
-| `webhook_delivery_attempts` | Per-attempt webhook log. | 04 |
-
-A single migration block lands the foundation tables. APNs/FCM/webhook tables can land in separate migrations as those channels ship — they don't block the v1 in-app inbox.
-
-## API surface overview
-
-Profile-scoped (require `X-Profile-Id` header):
-
- `GET /api/v1/notifications` — paginated inbox (newest-first, `before` cursor).
- `GET /api/v1/notifications/sync` — forward sync (`since` cursor); the endpoint mobile clients call after a push wake.
- `GET /api/v1/notifications/{id}` — single delivery by ID.
- `GET /api/v1/notifications/unread-count` — for the badge.
- `POST /api/v1/notifications/{id}/read` — mark single read.
- `POST /api/v1/notifications/read-all` — mark all read.
- `POST /api/v1/events/ws-ticket` — mint a short-lived single-use websocket ticket bound to `(user_id, profile_id)`.
- `GET /api/v1/notifications/preferences` — read profile prefs.
- `PUT /api/v1/notifications/preferences` — update profile prefs.
- `GET /api/v1/notifications/capability` — what channels are available.
- `POST /api/v1/devices/push/apple` — register an APNs device.
- `POST /api/v1/devices/push/fcm` — register an FCM device.
- `DELETE /api/v1/devices/push/{id}` — disable a push device.
- `GET /api/v1/notifications/webhooks` — list profile's webhooks.
- `POST /api/v1/notifications/webhooks` — create a webhook.
- `PUT /api/v1/notifications/webhooks/{id}` — update a webhook.
- `DELETE /api/v1/notifications/webhooks/{id}` — delete a webhook.
- `POST /api/v1/notifications/webhooks/{id}/test` — fire a test event.
-
-Admin-scoped:
-
- Settings registry entries for APNs and FCM provider configuration (admin-only via existing `internal/api/handlers/settings.go` patterns).
-
-## Realtime channel
-
-A new event channel `notifications` joins the existing `catalog`, `jobs`, `sessions`, `tasks`, `scans`, `history_import`, `user_state`, `plugins` channels in `internal/events/types.go`. The websocket handler must validate active profile identity and must reject `notifications` events whose `profile_id` doesn't match the connection's bound profile.
-
-Because browsers can't set custom headers on WebSocket connections, profile identity is carried by a **short-lived single-use ticket**: the client calls `POST /api/v1/events/ws-ticket` (normal auth + `X-Profile-Id`), receives an opaque ticket valid for ~30 seconds, and passes it as a `ticket` query parameter on the handshake. The server consumes the ticket and binds the connection to the `(user_id, profile_id)` it was minted for. A long-lived profile token must **not** be passed in the query string — self-hosted servers commonly sit behind reverse proxies whose access logs capture query strings, and a logged ticket that expired 30 seconds after minting is harmless where a logged profile token is not.
-
-Event types on this channel:
-
- `notification.created` — a new delivery for the bound profile.
- `notification.read` — a delivery was marked read (allows multi-tab coherence).
-
-Snapshot on subscribe: recent unread deliveries for the bound profile, so reconnecting clients hydrate without a separate REST call.
-
-## Out of scope for v1
-
- Movie release notifications (no trigger surface; v2).
- Request-fulfilled notifications ("your requested item is now available"). Silo's requests system postdates this design; it is the most obvious next notification type and slots into the extensible `notification_deliveries.type` registry without schema changes. v2.
- Aggregated notifications ("3 new episodes available"; presentation layer, can stack on per-episode rows later). The per-series burst cap in `01` bounds bulk-addition volume until an aggregated delivery type exists.
- Web Push (browser PWA notifications via Push API). Possible v2 — would mirror APNs/FCM as a third push platform.
- Email or SMS delivery.
- Cross-profile / household-wide notification views.
- Admin-level system notifications ("scan complete", "library health alert"). The existing realtime events hub (`internal/events/`, with the operational publisher wrapper at `internal/notifications/hub.go`) already handles operational events; this folder's design is strictly user-facing media notifications.
- Notification templates / customization beyond Discord-vs-generic.
- Time-window quiet hours. Could be added to `notification_preferences` later; not v1.
- Locale negotiation for push payloads. APNs / FCM payloads use generic localization keys (`SILO_NOTIFICATION_GENERIC_BODY` etc.) so the OS picks language from device locale.
-
-## Open questions
-
-These are the few remaining items not yet decided. None block writing the per-channel specs.
-
-1. **Service-level rate limits per relay account.** Per-second and per-day caps need real numbers. Suggest 10 req/sec burst, 50,000 req/day initial quota; tune from logs. The server-side dispatchers pace their relay calls client-side (default 5 req/sec token bucket, see `02`/`03`) so a hundreds-of-users server drains bursts smoothly instead of slamming into 429s; the per-series burst cap in `01` bounds worst-case burst size.
-2. **Webhook destination domain blocklist edge cases.** RFC ranges are defined in `04-outbound-webhooks.md`; remaining open question is whether IPv6 v4-mapped addresses (`::ffff:0:0/96`) and CGNAT (`100.64.0.0/10`) need any admin escape hatch beyond the global `allow_private_destinations` flag.
-3. **Discord image proxy timing.** Ship in v1 (build `media.discord-cdn-proxy.silo.app`) or defer to v1.5 with text-only embeds? Recommendation in `04`: defer to v1.5; v1 ships text-only embeds.
-
-Resolved during review (no longer open):
-
- **Relay service code lives in a separate repo** (provisional `silo-push-relay`). This folder defines the contract.
- **Migration ordering.** Foundation schema lands as one migration; per-channel schemas can land separately as their channels ship.
- **`server_device_id` lifecycle.** Stable across token rotation; rotates only when a device is removed and re-registered.
-
-## Phasing
-
-Implementation phases gated by feature flags:
-
-| Phase | Flag | Capability |
-|---|---|---|
-| 1 | `notifications.schema_enabled` | Tables exist; no writes. |
-| 2 | `notifications.interest_updaters_enabled` | `profile_series_interest` updates land on favorites/watchlist/playback events. Backfill task runs. |
-| 3 | `notifications.release_events_enabled` | Availability seeding backfill runs first, then ingest writes `release_events`. No fanout yet. |
-| 4 | `notifications.fanout_enabled` | Fanout worker runs; `notification_deliveries` rows materialize. Websocket channel published. |
-| 5 | `notifications.ui_enabled` | Inbox API + frontend badge + page exposed. |
-| 6 | `notifications.webhooks_enabled` | Outbound webhooks + Discord/generic dispatchers. v1 ships **text-only** Discord embeds (no `image` or `avatar_url` fields) to avoid leaking the user's server origin to Discord. v1.5 adds the optional `media.discord-cdn-proxy.silo.app` proxy and re-enables embed images. |
-| 7 | `notifications.apple_push_enabled` | APNs registration + dispatcher. Requires relay infra (or admin-supplied custom credentials). |
-| 8 | `notifications.android_push_enabled` | FCM registration + dispatcher. Requires relay infra (or admin-supplied custom credentials). |
-
-Phases 1-6 ship without any new external infrastructure. Phases 7-8 require Silo to provision Apple Developer + Firebase developer accounts and operate the relay service.
@@ -1,891 +0,0 @@
-# Privacy-Preserving APNs Relay Spec
-
-**Date:** 2026-04-27 (refined 2026-04-28)
-**Status:** Draft (refined; open questions resolved)
-**Scope:** Silo server push integration, Apple clients, opt-in central APNs relay, custom APNs provider configuration
-**Depends On:**
- [`00-architecture-overview.md`](./00-architecture-overview.md) — read first for cross-cutting context
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md) — foundational durable inbox + fanout
-**Sibling spec:**
- [`03-fcm-relay.md`](./03-fcm-relay.md) — Android push using the same threat model and architecture
-
-## Summary
-
-Silo should support remote Apple notifications through either an opt-in
-central APNs relay or admin-configured APNs credentials, while keeping
-notification metadata on the user's own Silo server.
-
-The hosted relay should be a constrained transport service. It should receive
-only the minimum fields needed to submit an APNs request:
-
- an APNs device token
- APNs environment and app topic
- a push mode
- an opaque server/device correlation key
- an opaque delivery identifier
- optional badge count
-
-Neither provider path may send titles, item names, usernames, profile names,
-library names, server URLs, artwork URLs, watched-state metadata, or
-notification body text through APNs.
-
-When the Apple device wakes, the app should fetch real notification metadata
-directly from the user's Silo server using the existing authenticated
-server connection.
-
-## Problem
-
-Reliable Apple remote notifications require APNs. A self-hosted Silo server
-cannot directly wake an iPhone, iPad, or Apple TV app in the background without
-going through Apple's push infrastructure.
-
-That creates two product concerns:
-
-1. Privacy: notification contents should not be exposed to Apple or a Silo
-   operated relay.
-2. Operational friction: most server admins should not need to create and manage
-   their own Apple developer account, APNs key, bundle topic, and push service.
-
-Silo should offer a practical default that preserves the self-hosted trust
-model as much as the platform allows.
-
-## Decision
-
-Add configurable Apple push providers for the official Apple app:
-
- `off`: no remote Apple push
- `silo_relay`: Silo's hosted APNs relay
- `custom_apns`: admin-supplied APNs credentials used directly by the server
-
-The relay submits APNs requests using Silo-controlled Apple credentials for
-the official app bundle. A self-hosted server admin may opt in to use this relay.
-The relay's API should intentionally prevent notification content from being
-sent through the relay.
-
-If `custom_apns` is selected, the user's Silo server submits directly to
-APNs using admin-provided Apple developer credentials. This avoids the Silo
-relay entirely, but it must use the same minimal payload and metadata-fetch
-rules as the hosted relay path.
-
-The default push mode should be **Private Alert**:
-
- APNs displays a generic Silo notification.
- The APNs payload contains only opaque identifiers.
- The app fetches the actual notification row from the user's server when it is
-  opened or granted background execution.
-
-The implementation should also support **Background Wake** for low-noise sync,
-with the explicit understanding that iOS background pushes are opportunistic and
-not a reliable user-visible notification mechanism.
-
-## Goals
-
- Make Apple push possible without every admin managing APNs credentials.
- Keep actual notification metadata on the user's Silo server.
- Make relay participation explicit and disabled by default.
- Make APNs credentials configurable for admins who want to avoid the hosted
-  relay.
- Keep the relay stateless for device subscriptions where possible.
- Keep APNs payloads opaque and generic.
- Keep the hosted relay and custom APNs paths behaviorally equivalent from the
-  app's point of view.
- Fit on top of the durable notification inbox design.
-
-## Non-Goals
-
- Replacing APNs for Apple remote push.
- Shipping notification content through the central relay.
- Requiring Firebase or Google services for this Apple path.
- Solving Android push in this spec.
- Adding marketing, analytics, or delivery-tracking exports to the relay.
- Hiding APNs itself from Apple devices. Custom APNs still uses Apple APNs.
- Making silent background delivery as reliable as visible push.
-
-## Threat Model
-
-### What The User's Server Knows
-
-The user's Silo server knows:
-
- the notification content
- the profile and user recipients
- the registered local devices
- APNs device tokens for those devices
- push delivery attempts and failures
-
-This is acceptable because the server is already the authority for the user's
-media, profiles, sessions, and notification inbox.
-
-### What The Central Relay May Know
-
-The relay may see:
-
- an opt-in relay account or install identifier
- the server's egress IP address (inherent to any hosted relay — the server
-  connects to it directly; for home hosting this identifies the household's
-  connection, making it the closest thing to an identity leak in this design)
- APNs device tokens submitted in send requests
- request timestamps
- coarse push mode, such as `private_alert` or `background_wake`
- opaque `collapse_id` values (per-server-keyed HMACs of series identity; the
-  relay can group one server's pushes into series-equivalence classes but
-  cannot recover which series, nor correlate across servers — see "Send Apple
-  Push" validation)
- APNs response status and APNs request IDs
- opaque delivery identifiers
-
-The relay must not receive enough information to know what media item,
-notification type, profile, user, library, server hostname, or server URL caused
-the push.
-
-### What Apple May Know
-
-Apple/APNs may see:
-
- the official app topic
- the target device token
- APNs headers
- request timing
- the generic APNs payload
-
-Apple must not receive media titles, usernames, library names, server URLs,
-artwork URLs, or other notification metadata in the payload.
-
-### Residual Metadata Leakage
-
-This design cannot hide that a device received a Silo push at a particular
-time, nor the egress IP of the server sending relay requests. It can only hide
-the meaning and content of the push. Admins for whom IP exposure matters can
-route relay traffic through their existing VPN/proxy egress; the relay path is
-plain HTTPS and needs no special handling.
-
-## User And Admin Controls
-
-### Server Admin Control
-
-The server admin must explicitly choose an Apple push provider.
-
-Suggested setting:
-
-```text
-notifications.apple_push.provider = off | silo_relay | custom_apns
-```
-
-Default:
-
-```text
-off
-```
-
-If `silo_relay` is selected, the admin configures a relay API key and
-accepts a clear privacy notice:
-
-```text
-Silo Relay can wake Apple devices through APNs, but notification details
-stay on this server. The relay receives APNs device tokens, timestamps, opaque
-delivery IDs, and generic push mode only.
-```
-
-If `custom_apns` is selected, the admin configures their own Apple developer
-APNs credentials:
-
-```text
-notifications.apple_push.custom.team_id
-notifications.apple_push.custom.key_id
-notifications.apple_push.custom.private_key
-notifications.apple_push.custom.default_environment = production | sandbox
-notifications.apple_push.custom.allowed_topics = [...]
-```
-
-The server then sends directly to APNs and does not call the Silo relay.
-The same private payload rules still apply.
-
-### Device User Control
-
-Each Apple device must opt in independently:
-
- the OS notification permission must be granted
- the app must be signed into a Silo server
- the active profile must enable push notifications for that device
- the server admin must have enabled an Apple push provider
-
-Admins must not be able to silently enroll every profile/device into remote push
-without the device having granted OS notification permission.
-
-### Profile Control
-
-Push preferences should sit on top of the durable notification preferences from
-the inbox design.
-
-Suggested profile/device modes:
-
- `off`: never send remote push to this device
- `in_app_only`: websocket and inbox only
- `private_push`: generic APNs wake/alert, fetch details from server
- `full_preview`: out of scope for v1; would require explicit user consent and
-  a separate privacy warning
-
-V1 should ship only `off`, `in_app_only`, and `private_push`.
-
-## System Architecture
-
-```mermaid
-sequenceDiagram
-  participant App as Apple App
-  participant Server as User Silo Server
-  participant Relay as Silo APNs Relay
-  participant APNs as Apple APNs
-
-  App->>App: Request OS notification permission
-  App->>App: Register for remote notifications
-  App->>Server: Register device token and opaque server_device_id
-  Server->>Server: Store encrypted token and device preferences
-  Server->>Server: Create durable notification_delivery
-  Server->>Relay: Send minimal APNs relay request
-  Relay->>APNs: Submit generic APNs payload
-  APNs->>App: Deliver private alert or background wake
-  App->>Server: Fetch notification metadata directly
-  Server->>App: Return inbox rows for active profile
-```
-
-## Ownership Boundaries
-
-### This Repository
-
-Silo owns:
-
- admin settings for selecting a push provider
- profile and device notification preferences
- APNs token registration from Apple clients
- durable storage of device registrations
- push fanout from `notification_deliveries`
- relay client integration
- retry, backoff, and APNs error handling
- inbox sync APIs used after wake
-
-### Apple Client Repository
-
-The Apple app owns:
-
- APNs registration
- notification permission UX
- device registration API calls
- local server/device correlation
- wake handling
- fetching metadata from the user's server
- rendering local/in-app notification details
-
-### Central Relay Service
-
-The central relay owns:
-
- APNs provider credentials for official Silo bundle topics
- relay API authentication
- request validation and rate limiting
- APNs request submission
- redacted operational logs
- minimal delivery status reporting
-
-The relay should live outside this repo unless the project later decides to
-co-locate the service code. This repo should define the contract and implement
-the self-hosted server side.
-
-### Custom APNs Mode
-
-When `custom_apns` is selected, there is no central relay in the send path.
-
-The user's Silo server owns:
-
- APNs provider authentication using the configured team ID, key ID, and private
-  key
- topic allowlisting for the official Silo app bundle IDs it intends to
-  support
- sandbox vs production environment selection
- APNs request construction
- APNs response handling
- APNs credential rotation and secret storage
-
-Custom APNs mode must not unlock richer payloads. It exists to let admins avoid
-the Silo relay, not to bypass the privacy-preserving notification contract.
-
-## Data Model
-
-This spec assumes `notification_deliveries` exists from the durable notification
-inbox design.
-
-### `push_devices`
-
-Purpose: profile/device-scoped remote push registration. Shared across Apple and Android — see [`03-fcm-relay.md`](./03-fcm-relay.md) for the FCM-specific columns.
-
-Columns:
-
- `id text primary key`
- `user_id integer not null` (matches `users.id integer`)
- `profile_id text not null`
- `device_id text not null`
- `platform text not null` — `'apple'` or `'android'`. Required; the row is invalid without it.
- `provider text not null` — for Apple rows: `'silo_relay'` or `'custom_apns'`. For Android rows: `'silo_relay'` or `'custom_fcm'`. (Effectively the active configured provider at registration time; updates rewrite the row.)
- `apns_environment text` — `'production'` / `'sandbox'`. Nullable; populated only for `platform = 'apple'`.
- `apns_topic text` — bundle topic. Nullable; populated only for `platform = 'apple'`.
- `apns_token_ciphertext bytea` — nullable; populated only for `platform = 'apple'`.
- `apns_token_hash text` — nullable; populated only for `platform = 'apple'`.
- `fcm_token_ciphertext bytea` — nullable; populated only for `platform = 'android'`. Defined here so the table is forward-compatible with [`03-fcm-relay.md`](./03-fcm-relay.md); the FCM spec adds the rest of the Android-specific columns.
- `fcm_token_hash text` — nullable; Android only.
- `fcm_project_id text` — nullable; Android only.
- `fcm_package_name text` — nullable; Android only.
- `server_device_id text not null` — random opaque value, generated server-side at registration. Stable across token rotation; rotates only when the device is removed and re-registered.
- `push_mode text not null default 'private_push'` — profile-level mode (see [`00-architecture-overview.md`](./00-architecture-overview.md) "Mode terminology").
- `enabled boolean not null default true`
- `last_seen_at timestamptz`
- `last_success_at timestamptz`
- `last_failure_at timestamptz`
- `last_failure_code text`
- `created_at timestamptz not null default now()`
- `updated_at timestamptz not null default now()`
-
-Constraints:
-
- unique on `(profile_id, device_id, platform)` — a device can register exactly once per platform per profile, regardless of which provider the admin happens to have configured. This matters because admins may flip between `silo_relay` and `custom_apns` mid-rotation; a `provider`-scoped unique key would leave stale rows behind.
- unique on `(server_device_id)`
- `CHECK ((platform = 'apple' AND apns_token_hash IS NOT NULL AND fcm_token_hash IS NULL) OR (platform = 'android' AND fcm_token_hash IS NOT NULL AND apns_token_hash IS NULL))` — exactly the platform-appropriate token columns are populated.
-
-Notes:
-
- `server_device_id` must be random and opaque. It is the value included in the
-  APNs payload so the app can map the push back to the correct local server
-  account.
- Store APNs tokens encrypted at rest when the local encryption facility exists.
- Store `apns_token_hash` for dedupe and diagnostics without logging raw tokens.
-
-### `push_delivery_attempts`
-
-Purpose: operational record of push attempts without notification content.
-
-Columns:
-
- `id text primary key`
- `notification_delivery_id text not null`
- `push_device_id text not null`
- `provider text not null`
- `attempt_number integer not null` — 1-based counter incremented on each retry. Used as the `Idempotency-Key` suffix for relay calls (see Send Apple Push), and lets diagnostics distinguish "10 attempts of one delivery" from "10 deliveries each first-attempted".
- `relay_request_id text`
- `apns_id text` — Apple's APNs ID returned in the response. Nullable; null for FCM rows.
- `fcm_message_name text` — FCM v1 message name (see [`03-fcm-relay.md`](./03-fcm-relay.md)). Nullable; null for APNs rows.
- `status text not null` — `'pending'`, `'delivered'`, `'retrying'`, `'failed'`, `'device_disabled'`. `pending` rows are the dispatch outbox: the fanout transaction in [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md) inserts attempt 1 as `pending` in the same transaction as the delivery; the push dispatcher claims and sends them post-commit.
- `failure_code text`
- `attempted_at timestamptz not null default now()`
- `next_retry_at timestamptz`
-
-Constraints:
-
- unique on `(notification_delivery_id, push_device_id, attempt_number)` to make the relay's `Idempotency-Key` deterministic and prevent double-claims of an attempt.
- add an index on `(status, next_retry_at)` for retry workers. The same index serves outbox recovery: a sweeper claims `pending` rows older than ~60s (crash between delivery commit and dispatch) with `FOR UPDATE SKIP LOCKED`.
-
-Retention:
-
- keep successful attempts for a short operational window, such as 14 days
- keep failed attempts longer, such as 30 to 90 days, to diagnose device issues
-
-## Server API Surface
-
-### Register Apple Push Device
-
-```http
-POST /api/v1/devices/push/apple
-```
-
-Profile-scoped. Requires normal auth plus active profile context.
-
-Request:
-
-```json
-{
-  "device_id": "apple-device-local-id",
-  "apns_token": "hex-or-base64-token",
-  "apns_environment": "production",
-  "apns_topic": "com.continuum.app.ios",
-  "push_mode": "private_push"
-}
-```
-
-Response:
-
-```json
-{
-  "id": "01J...",
-  "server_device_id": "01JOPAQUE...",
-  "enabled": true,
-  "push_mode": "private_push"
-}
-```
-
-Rules:
-
- `apns_topic` must be allowlisted by app build/channel.
- `apns_environment` must be `sandbox` or `production`.
- registration is idempotent by `(profile_id, device_id, provider)`.
- token rotation updates the encrypted token and token hash.
- a disabled server push provider should still allow registration, but should
-  report that remote push is unavailable in a capability field if the frontend
-  needs it.
-
-### Disable Push Device
-
-```http
-DELETE /api/v1/devices/push/{id}
-```
-
-Profile-scoped and idempotent.
-
-The server may either delete the row or mark `enabled = false`. Marking disabled
-is preferred for diagnostics and future re-enable flows.
-
-### Push Capability
-
-```http
-GET /api/v1/notifications/capability
-```
-
-The full envelope is defined in [`00-architecture-overview.md`](./00-architecture-overview.md). The Apple-relevant slice is:
-
-```json
-{
-  "apple_push": {
-    "available": true,
-    "provider": "silo_relay",
-    "available_providers": ["silo_relay", "custom_apns"],
-    "supported_modes": ["private_push", "in_app_only"],
-    "privacy_mode": "metadata_fetch"
-  }
-}
-```
-
-The full response also includes `in_app`, `android_push` (see [`03-fcm-relay.md`](./03-fcm-relay.md)), and `webhooks` (see [`04-outbound-webhooks.md`](./04-outbound-webhooks.md)).
-
-This lets clients present truthful setup UI without guessing whether the admin
-has enabled remote push.
-
-## Relay API Contract
-
-The relay API should be intentionally narrow. The user server should not send an
-arbitrary APNs payload.
-
-### Send Apple Push
-
-```http
-POST /v1/apple/send
-Authorization: Bearer <relay_api_key>
-Idempotency-Key: <notification_delivery_id>:<push_device_id>:<attempt_number>
-```
-
-Request:
-
-```json
-{
-  "token": "apns-token",
-  "environment": "production",
-  "topic": "com.continuum.app.ios",
-  "mode": "private_alert",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_id": "01JOPAQUE_COLLAPSE"
-}
-```
-
-Response:
-
-```json
-{
-  "request_id": "01JRELAY...",
-  "apns_id": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "accepted"
-}
-```
-
-Validation:
-
- `token` is required and must be plausible for APNs.
- `environment` must be `sandbox` or `production`. The relay forwards `production` requests to `https://api.push.apple.com` and `sandbox` requests to `https://api.development.push.apple.com` (Apple's current canonical hostnames; older docs/libraries also reference `api.sandbox.push.apple.com`, but `api.development.push.apple.com` is the current Apple-documented form).
- `topic` must be allowlisted for the relay account.
- `mode` must be `private_alert` or `background_wake`.
- `server_device_id` and `delivery_id` must be opaque values with length limits (recommend ≤128 chars, ULID-shaped).
- `collapse_id` must be opaque and ≤64 bytes — Apple enforces a 64-byte cap on `apns-collapse-id`. Reject longer values with HTTP 400.
- `collapse_id` derivation (server-side rule, not relay-enforced): the server computes `collapse_id = base32(HMAC-SHA256(server_collapse_secret, series_id))` truncated to 26 chars, where `server_collapse_secret` is a random per-server secret generated at first use. Never send raw or plainly-hashed `series_id` — an unkeyed hash would let the relay (or Apple) dictionary-match popular series IDs. Residual: the relay can still group one server's pushes into per-series equivalence classes (that is what collapse is for); the per-server key prevents recovering the series or correlating across servers.
- `badge` is optional. Default should be omitted to avoid leaking unread counts through APNs unless the user/admin explicitly enables badge sync.
- no free-form notification title or body fields are accepted.
- no image URL, media ID, username, server hostname, or server URL field is accepted.
-
-### Relay-Built APNs Payloads
-
-For `private_alert`, the relay constructs:
-
-```json
-{
-  "aps": {
-    "alert": {
-      "title-loc-key": "SILO_NOTIFICATION_TITLE",
-      "loc-key": "SILO_NOTIFICATION_GENERIC_BODY"
-    },
-    "sound": "default"
-  },
-  "silo": {
-    "v": 1,
-    "wake": "notifications.changed",
-    "server_device_id": "01JOPAQUE...",
-    "delivery_id": "01JDELIVERY..."
-  }
-}
-```
-
-For `background_wake`, the relay constructs:
-
-```json
-{
-  "aps": {
-    "content-available": 1
-  },
-  "silo": {
-    "v": 1,
-    "wake": "notifications.changed",
-    "server_device_id": "01JOPAQUE...",
-    "delivery_id": "01JDELIVERY..."
-  }
-}
-```
-
-Headers:
-
- `apns-topic`: selected from the allowlisted `topic`
- `apns-push-type`: `alert` for `private_alert`, `background` for
-  `background_wake`
- `apns-priority`: `10` for `private_alert`, `5` for `background_wake`
- `apns-collapse-id`: optional opaque `collapse_id`
-
-The relay should not allow callers to override this payload shape in v1.
-
-## Custom APNs Contract
-
-`custom_apns` should share the same internal send model as `silo_relay`,
-but replace the relay HTTP call with a direct APNs provider request.
-
-The server-side push sender should accept only a structured internal request:
-
-```json
-{
-  "token": "apns-token",
-  "environment": "production",
-  "topic": "com.continuum.app.ios",
-  "mode": "private_alert",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_id": "01JOPAQUE_COLLAPSE"
-}
-```
-
-The sender builds the APNs payload locally using the exact same payload shapes
-defined above for `private_alert` and `background_wake`.
-
-Configuration:
-
- `team_id`: Apple developer team ID.
- `key_id`: APNs auth key ID.
- `private_key`: APNs `.p8` private key, stored as a secret.
- `default_environment`: `production` or `sandbox`.
- `allowed_topics`: explicit bundle topics this server is allowed to send for.
-
-Rules:
-
- The admin may configure credentials, environment, and topics.
- The server must not expose a free-form APNs JSON payload setting.
- The server must not expose custom title/body templates for remote push in v1.
- Topic values must match the device registration topic and the configured
-  allowlist.
- Sandbox tokens must be sent to the sandbox endpoint and production tokens to
-  the production endpoint.
- APNs auth tokens should be cached briefly and regenerated before expiry.
- Credential validation should provide a test-send or dry-run diagnostic that
-  does not include notification content.
-
-## Wake And Metadata Fetch
-
-When the app receives a push:
-
-1. Read `silo.v`, `server_device_id`, and `delivery_id`.
-2. Find the local server account that owns `server_device_id`.
-3. If background execution is available, call the server immediately.
-4. If the app is opened from the notification, call the server before rendering
-   the target screen.
-5. Fetch notification metadata from the user's server.
-6. Render the real notification from server data.
-
-Suggested fetch:
-
-```http
-GET /api/v1/notifications/sync?since=<last_cursor>
-```
-
-or:
-
-```http
-GET /api/v1/notifications/{delivery_id}
-```
-
-The sync endpoint is preferred because push delivery is not guaranteed and
-multiple notification deliveries can be coalesced.
-
-If the app cannot reach the server, it should keep the generic notification and
-retry the inbox sync later.
-
-## Fanout Rules
-
-Push fanout should happen after durable inbox delivery commits.
-
-Flow:
-
-1. `notification_deliveries` row is created. **In the same transaction**, the
-   fanout worker enqueues one `pending` `push_delivery_attempts` row per
-   enabled `push_device` of the recipient profile (the dispatch outbox — see
-   [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)
-   "Transaction and Concurrency Rules").
-2. The realtime websocket event is published for connected clients.
-3. The push dispatcher claims the `pending` attempt rows post-commit
-   (`FOR UPDATE SKIP LOCKED`); a recovery sweeper claims rows older than ~60s
-   whose dispatch never ran.
-4. Each claimed attempt sends through the configured provider:
-   - `silo_relay`: send the minimal relay request
-   - `custom_apns`: build the same minimal APNs payload locally and send it
-     directly to APNs
-5. APNs errors update device state and attempt status.
-
-Do not block notification delivery creation on APNs or relay availability.
-
-### Relay pacing
-
-The dispatcher paces relay calls client-side with a token bucket (default 5
-req/sec, setting `notifications.push.relay_send_rate`), shared across the APNs
-and FCM dispatchers since both consume the same relay account quota. On a
-server with hundreds of users, a popular release can enqueue several hundred
-push attempts at once; pacing drains the queue smoothly instead of slamming
-into the relay's rate limit and burning retries on 429s. `TooManyRequests`
-from the relay is still honored with backoff — pacing is the steady-state
-mechanism, backoff is the safety net. The per-series burst cap in `01` bounds
-worst-case queue depth. Custom APNs sends are paced separately and more
-generously (Apple's own limits are far higher than any single-server relay
-quota).
-
-## APNs Error Handling
-
-The server should handle relay/APNs failures without exposing notification
-content.
-
-Recommended handling:
-
- `BadDeviceToken` / `InvalidToken`: disable the token and require re-registration. (Apple has migrated some responses from `BadDeviceToken` to `InvalidToken`; treat them equivalently.)
- `Unregistered`: disable the token.
- `DeviceTokenNotForTopic`: disable and log a build/topic mismatch.
- `TooManyRequests`: retry with backoff.
- `ExpiredProviderToken`: applies only to `custom_apns`. The cached APNs JWT has expired. Regenerate the JWT immediately and retry the request once before backing off. The relay path never surfaces this code because the relay manages its own JWTs.
- `TooManyProviderTokenUpdates`: applies only to `custom_apns`. Apple has rate-limited JWT regeneration. Stop regenerating; reuse the existing token; retry after backoff. Indicates a bug in the JWT cache (regenerating more often than every 20 minutes).
- relay unavailable, APNs unavailable, or network timeout: retry with backoff.
- malformed request: mark failed and surface admin diagnostics.
-
-Errors should be visible to admins as operational status, not to normal users
-unless their device needs reauthorization.
-
-## Privacy Requirements
-
-The implementation must satisfy these requirements before shipping:
-
- Relay requests contain no notification title or body.
- Relay requests contain no media identifiers.
- Relay requests contain no server hostname or base URL.
- Relay requests contain no profile, username, library, collection, or item names.
- Relay requests *do* carry `apns-topic` (e.g., `com.continuum.app.ios`) and `mode` (`private_alert` / `background_wake`). These are platform/build identifiers that Apple already sees; documenting them here so the privacy claim list is exhaustive rather than over-strong.
- Direct APNs payloads contain no notification title or body beyond generic
-  localizable keys.
- Direct APNs payloads contain no media identifiers, server hostname, server URL,
-  profile name, username, library name, collection name, or item name.
- Relay logs redact raw APNs tokens.
- Relay logs redact authorization headers.
- Relay logs do not persist full request payloads.
- Server logs redact APNs tokens and relay API keys.
- Badge count is disabled by default.
- Push registration and remote push provider use are opt-in.
- Device unregister disables further push attempts for that device.
-
-## Security Requirements
-
- Relay API uses TLS only.
- Relay API keys are scoped to a relay account or install identifier.
- Relay API keys can be revoked without changing the user's Silo server
-  authentication.
- Relay requests are rate limited by API key and coarse token hash.
- Relay supports idempotency keys to prevent duplicate APNs sends during retry.
- Relay does not accept arbitrary APNs payload JSON in v1.
- Server stores relay API keys as secrets.
- Server stores custom APNs private keys as secrets.
- Server never logs custom APNs private keys, generated provider tokens, or APNs
-  auth headers.
- Server stores APNs tokens encrypted at rest where local secret storage exists.
- Admin diagnostics must not print raw APNs tokens.
-
-## Settings And UX
-
-Admin settings should explain the tradeoff plainly:
-
-```text
-Apple Push Provider
-
-Off
-  No Apple remote push. Devices still receive in-app realtime updates while open.
-
-Silo Relay
-  Uses Silo's APNs relay to wake Apple devices. Notification details stay on
-  this server. The relay receives APNs device tokens, timestamps, and opaque
-  delivery IDs.
-
-Custom APNs
-  Advanced. Send directly to Apple APNs using your own Apple developer
-  credentials. Notification details still stay on this server.
-```
-
-Device settings should describe the user-visible mode:
-
-```text
-Private Push
-  Show a generic Silo notification, then fetch details from your server when
-  this device wakes.
-```
-
-Do not claim the central relay is fully self-hosted. The truthful claim is:
-
-```text
-Notification content stays on your server. Apple, and the Silo relay if
-selected, may still process generic wake messages needed for Apple push
-delivery.
-```
-
-## Implementation Plan
-
-### Task 1: Add Push Provider Settings
-
-Files likely involved:
-
- `internal/api/handlers/settings.go`
- `web/src/lib/settingsManifest.ts`
- settings UI files as needed
-
-Add server/admin settings for:
-
- provider selection
- relay endpoint
- relay API key
- custom APNs team ID
- custom APNs key ID
- custom APNs private key
- custom APNs environment
- custom APNs topic allowlist
- badge sync enabled or disabled
- relay send rate (`notifications.push.relay_send_rate`, shared with FCM pacing)
-
-Default provider must be `off`.
-
-### Task 2: Add Push Device Registration
-
-Files likely involved:
-
- new migration under `migrations/`
- new package or service under `internal/notifications`
- `internal/api/handlers/notifications.go`
- `internal/api/router.go`
-
-Add profile-scoped Apple push device registration, token rotation, and disable
-APIs.
-
-### Task 3: Add Apple Push Provider Clients
-
-Files likely involved:
-
- `internal/notifications/apple_relay.go`
- `internal/notifications/apple_apns.go`
- config/settings accessors
-
-Implement the narrow `/v1/apple/send` client. The client should not accept a
-free-form title/body/content payload.
-
-Implement the direct APNs client for `custom_apns` using the same internal
-request shape and payload builder.
-
-### Task 4: Add Push Fanout Worker
-
-Files likely involved:
-
- `internal/notifications/push_fanout.go`
- notification delivery creation path from the durable inbox implementation
-
-Trigger push fanout after `notification_deliveries` commit. Use retries and
-record `push_delivery_attempts`.
-
-### Task 5: Add Apple Client Registration And Wake Handling
-
-Files live in the Apple client repository, not this server repo.
-
-Required client behavior:
-
- request notification permission
- register APNs token with the user's server
- store `server_device_id` locally
- handle token rotation
- fetch notification metadata after wake/open
- unregister or disable on sign-out/profile removal
-
-### Task 6: Add Admin Diagnostics
-
-Expose high-level status:
-
- provider enabled/disabled
- number of registered Apple devices
- last relay success
- last relay failure code
- custom APNs credential presence and topic/environment status
- last custom APNs success
- last custom APNs failure code
- token/topic mismatch warnings
-
-Do not expose raw APNs tokens.
-
-## Validation Plan
-
-Use minimal verification while the work is still design-only. When implemented,
-verify:
-
- relay-disabled servers never call the relay
- `custom_apns` servers never call the relay
- device registration is profile-scoped and idempotent
- APNs tokens are redacted in logs
- relay request bodies contain no titles, body text, item IDs, server URLs, or
-  profile names
- direct APNs payloads contain no titles, body text, item IDs, server URLs, or
-  profile names beyond the generic localizable notification keys
- custom APNs private keys and generated provider tokens are redacted in logs
- creating one `notification_delivery` sends at most one push per enabled device
- APNs token rotation updates the stored token without duplicating devices
- `Unregistered` and `BadDeviceToken` disable the affected device
- app wake fetches notification metadata from the user's server
- server offline after push leaves only the generic notification visible
-
-## Resolved Questions (was: Open Questions)
-
-These four open questions from the original draft were resolved during the multi-channel refinement:
-
- **Topics: per-platform.** Official Silo builds use separate APNs topics for iOS, tvOS, and macOS. Each is a different bundle ID with its own provisioning. The `apns_topic` allowlist on a relay account enumerates the per-platform topics the account may push to.
- **Badge counts: disabled in v1.** Badge count leaks unread volume through APNs. v1 ships without badge updates; an explicit per-profile opt-in to badge sync can land in v2 alongside a privacy notice.
- **Relay statefulness: stateless v1.** No stored token aliases. The relay accepts raw APNs tokens on every request. Token aliases add complexity for a benefit (reduced repeat-token exposure to relay logs) that is small compared to "redact tokens from logs." Add aliases later if abuse-pattern analysis or rate-limit pressure justifies it.
- **Relay deployment repo: out of scope for this spec.** The relay implementation lives in a separate repo (provisional name `silo-push-relay`). This document defines the contract the user-facing Silo server implements; the relay's internal architecture (deployment platform, dependency tree, etc.) is the relay repo's concern.
-
-## Remaining Open Questions
-
- **Multi-bundle topic allowlist UX.** When an admin configures custom APNs, how do they declare allowlisted topics — free-text textarea, or a structured list? Recommendation: structured list with platform tags (iOS / tvOS / macOS) so the UI can show which platforms have working push.
- **APNs JWT cache lifetime.** APNs JWTs are valid for 60 minutes per Apple's docs but may be reused across requests. Should the custom APNs path cache and reuse, or sign per-request? Recommendation: cache with regeneration at 50 minutes to leave headroom, matching Apple's recommendation.
@@ -1,748 +0,0 @@
-# Privacy-Preserving FCM Relay Spec
-
-**Date:** 2026-04-28
-**Status:** Draft
-**Scope:** Silo server push integration for Android, opt-in central FCM relay, custom FCM provider configuration
-**Depends On:**
- [`00-architecture-overview.md`](./00-architecture-overview.md)
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)
- [`02-apns-relay.md`](./02-apns-relay.md) — sibling spec; structurally identical with FCM-specific differences
-
-## Summary
-
-Silo should support remote Android notifications through either an opt-in central FCM relay or admin-configured Firebase Cloud Messaging credentials, while keeping notification metadata on the user's own Silo server.
-
-The hosted relay should be a constrained transport service. It should receive only the minimum fields needed to submit a Firebase Cloud Messaging v1 API request:
-
- an FCM registration token
- the target Firebase project ID and Android package name (allowlisted)
- a push mode
- an opaque server/device correlation key
- an opaque delivery identifier
- optional badge count (disabled by default)
-
-Neither provider path may send titles, item names, usernames, profile names, library names, server URLs, artwork URLs, watched-state metadata, or notification body text through FCM.
-
-When the Android device wakes, the app should fetch real notification metadata directly from the user's Silo server using the existing authenticated server connection.
-
-## Why this spec mirrors APNs
-
-The reasoning, threat model, and fanout flow are identical to the APNs case. Apple and Google both gatekeep mobile push at the app-bundle level: only the developer who signed and published the app can authenticate pushes to it. The same arguments for a hosted relay apply unchanged. The differences are entirely about FCM's protocol and credentials:
-
- **Auth:** FCM v1 API uses **OAuth2 with a Google service account**, not a JWT signed with a `.p8` key.
- **Endpoint:** Pushes go to `https://fcm.googleapis.com/v1/projects/{project_id}/messages:send`.
- **Project model:** A Firebase project owns the Android app's package name + SHA-1 cert fingerprint mapping. The relay holds one service account JSON per official Firebase project.
- **Topics vs tokens:** FCM supports both topic broadcasts and per-token sends. Silo uses **per-token sends only** — topic broadcasts would leak audience information.
- **Message types:** FCM has `notification` and `data` messages. The privacy design uses **data-only messages** so the OS can't render content the relay shouldn't have constructed.
-
-## Decision
-
-Add configurable Android push providers for the official Silo Android app:
-
- `off`: no remote Android push
- `silo_relay`: Silo's hosted FCM relay
- `custom_fcm`: admin-supplied FCM service account JSON used directly by the server
-
-The relay submits FCM v1 requests using Silo-controlled Firebase credentials for the official app package. A self-hosted server admin may opt in to use this relay. The relay's API should intentionally prevent notification content from being sent through the relay.
-
-If `custom_fcm` is selected, the user's Silo server calls FCM v1 directly using admin-provided service account JSON. This avoids the Silo relay entirely, but it must use the same minimal payload and metadata-fetch rules as the hosted relay path.
-
-The default push mode should be **Private Data Wake**:
-
- FCM delivers a data-only message.
- The data payload contains only opaque identifiers.
- The Android app handles the message via `FirebaseMessagingService.onMessageReceived` and constructs a generic local notification while it fetches the actual notification row from the user's server.
-
-The implementation should also support **Background Wake** for low-noise sync, with the explicit understanding that Android background data messages are subject to Doze, App Standby, and battery-optimization restrictions and are not a reliable user-visible notification mechanism.
-
-## Goals
-
- Make Android push possible without every admin managing their own Firebase project.
- Keep actual notification metadata on the user's Silo server.
- Make relay participation explicit and disabled by default.
- Make FCM credentials configurable for admins who want to avoid the hosted relay.
- Keep the relay stateless for device subscriptions where possible.
- Keep FCM payloads opaque and generic (data-only).
- Keep the hosted relay and custom FCM paths behaviorally equivalent from the app's point of view.
- Fit on top of the durable notification inbox design.
-
-## Non-Goals
-
- Replacing FCM for Android remote push.
- Shipping notification content through the central relay.
- Requiring Apple push services for this Android path.
- Supporting Huawei Mobile Services (HMS) push, Amazon Device Messaging, or other Android-adjacent push systems in v1. Could be added later as parallel providers.
- Adding marketing, analytics, or delivery-tracking exports to the relay.
- Hiding FCM itself from Android devices. Custom FCM still uses Google FCM.
- Making silent background delivery as reliable as visible notifications.
-
-## Threat Model
-
-### What The User's Server Knows
-
-The user's Silo server knows:
-
- the notification content
- the profile and user recipients
- the registered local devices
- FCM registration tokens for those devices
- push delivery attempts and failures
-
-This is acceptable because the server is already the authority for the user's media, profiles, sessions, and notification inbox.
-
-### What The Central Relay May Know
-
-The relay may see:
-
- an opt-in relay account or install identifier
- the server's egress IP address (inherent to any hosted relay — the server connects to it directly; see the identical note in [`02-apns-relay.md`](./02-apns-relay.md))
- FCM registration tokens submitted in send requests
- request timestamps
- coarse push mode, such as `private_data` or `background_wake`
- opaque `collapse_key` values (per-server-keyed HMACs of series identity; same derivation rule as APNs `collapse_id`)
- FCM response status and FCM message names
- opaque delivery identifiers
-
-The relay must not receive enough information to know what media item, notification type, profile, user, library, server hostname, or server URL caused the push.
-
-### What Google May Know
-
-Google / FCM may see:
-
- the official app package name and Firebase project
- the target FCM registration token
- FCM v1 request headers
- request timing
- the generic FCM data payload (which contains only opaque identifiers)
-
-Google must not receive media titles, usernames, library names, server URLs, artwork URLs, or other notification metadata in the payload. In particular, the design uses **data-only messages**, never `notification` messages, so Google's servers don't carry rendering content.
-
-### Residual Metadata Leakage
-
-This design cannot hide that a device received a Silo push at a particular time, nor the egress IP of the server sending relay requests. It can only hide the meaning and content of the push. Additionally, on Android, FCM delivery may be delayed by Doze / App Standby; an adversary observing wake patterns may infer rough activity but not content.
-
-## User And Admin Controls
-
-### Server Admin Control
-
-The server admin must explicitly choose an Android push provider.
-
-Suggested setting:
-
-```text
-notifications.android_push.provider = off | silo_relay | custom_fcm
-```
-
-Default:
-
-```text
-off
-```
-
-If `silo_relay` is selected, the admin configures a relay API key and accepts a clear privacy notice:
-
-```text
-Silo Relay can wake Android devices through Firebase Cloud Messaging,
-but notification details stay on this server. The relay receives FCM
-registration tokens, timestamps, opaque delivery IDs, and generic push mode
-only.
-```
-
-If `custom_fcm` is selected, the admin configures their own Firebase service account JSON:
-
-```text
-notifications.android_push.custom.service_account_json
-notifications.android_push.custom.project_id
-notifications.android_push.custom.allowed_packages = [...]
-```
-
-The server then sends directly to FCM and does not call the Silo relay. The same private payload rules still apply.
-
-### Device User Control
-
-Each Android device must opt in independently:
-
- the OS notification permission must be granted (Android 13+ requires `POST_NOTIFICATIONS` runtime permission)
- the app must be signed into a Silo server
- the active profile must enable push notifications for that device
- the server admin must have enabled an Android push provider
-
-Admins must not be able to silently enroll every profile/device into remote push without the device having granted OS notification permission.
-
-### Profile Control
-
-Push preferences sit on top of the durable notification preferences from the inbox design. The push-mode field on a `push_devices` row is shared across platforms (`apple` and `android`) so the same `push_mode` enum applies.
-
-Suggested profile/device modes:
-
- `off`: never send remote push to this device
- `in_app_only`: websocket and inbox only
- `private_push`: generic FCM data wake, fetch details from server
- `full_preview`: out of scope for v1
-
-V1 should ship only `off`, `in_app_only`, and `private_push`.
-
-## System Architecture
-
-```mermaid
-sequenceDiagram
-  participant App as Android App
-  participant Server as User Silo Server
-  participant Relay as Silo FCM Relay
-  participant FCM as Google FCM
-
-  App->>App: Request POST_NOTIFICATIONS permission (API 33+)
-  App->>App: Get FCM registration token via FirebaseMessaging.getToken()
-  App->>Server: Register registration token and opaque server_device_id
-  Server->>Server: Store encrypted token and device preferences
-  Server->>Server: Create durable notification_delivery
-  Server->>Relay: Send minimal FCM relay request
-  Relay->>FCM: Submit data-only message via FCM v1 API
-  FCM->>App: Deliver data message; FirebaseMessagingService.onMessageReceived
-  App->>Server: Fetch notification metadata directly
-  Server->>App: Return inbox rows for active profile
-```
-
-## Ownership Boundaries
-
-### This Repository
-
-Silo owns:
-
- admin settings for selecting an Android push provider
- profile and device notification preferences
- FCM token registration from Android clients
- durable storage of device registrations
- push fanout from `notification_deliveries`
- relay client integration
- retry, backoff, and FCM error handling
- inbox sync APIs used after wake
-
-### Android Client Repository
-
-The Android app owns:
-
- FCM registration via Firebase SDK
- notification permission UX (`POST_NOTIFICATIONS` on API 33+)
- device registration API calls
- local server/device correlation
- `FirebaseMessagingService.onMessageReceived` handling
- fetching metadata from the user's server
- rendering local notifications via `NotificationManager` after the wake
-
-### Central Relay Service
-
-The central relay owns:
-
- FCM service account credentials for the official Silo Firebase project(s)
- relay API authentication
- request validation and rate limiting
- FCM v1 request submission with OAuth2 access token caching
- redacted operational logs
- minimal delivery status reporting
-
-The relay should live outside this repo unless the project later decides to co-locate the service code. This repo defines the contract and implements the self-hosted server side. The relay implementation can share most code with the APNs relay; only the upstream provider client differs.
-
-### Custom FCM Mode
-
-When `custom_fcm` is selected, there is no central relay in the send path.
-
-The user's Silo server owns:
-
- FCM v1 OAuth2 token generation from the configured service account JSON
- access token caching (Google's OAuth2 access tokens are short-lived; cache and refresh on expiry)
- package allowlisting for the official Silo app package(s) it intends to support
- FCM v1 request construction (data-only)
- FCM response handling
- FCM credential rotation and secret storage
-
-Custom FCM mode must not unlock richer payloads. It exists to let admins avoid the Silo relay, not to bypass the privacy-preserving notification contract.
-
-## Data Model
-
-The `push_devices` and `push_delivery_attempts` schemas are owned by [`02-apns-relay.md`](./02-apns-relay.md) and are platform-tagged from the start (`platform = 'apple' | 'android'`) so this spec adds no new columns. The Android-relevant columns on `push_devices` are:
-
- `platform text not null` — must be `'android'` for FCM rows.
- `provider text not null` — `'silo_relay'` or `'custom_fcm'`.
- `fcm_token_ciphertext bytea` — required for Android rows.
- `fcm_token_hash text` — required for Android rows; used for dedupe/diagnostics without logging raw tokens.
- `fcm_project_id text` — the Firebase project the token was minted under.
- `fcm_package_name text` — the Android package name (e.g., `com.continuum.app.android`).
- All `apns_*` columns must be null for Android rows. The `CHECK` constraint defined in `02-apns-relay.md` enforces this exclusivity.
-
-Unique constraints (defined in `02-apns-relay.md`): `(profile_id, device_id, platform)` and `(server_device_id)`. Both are intentionally platform-scoped, not provider-scoped — the same Android device cannot register twice even if the admin flips between `silo_relay` and `custom_fcm`.
-
-`push_delivery_attempts` columns relevant to FCM (also owned by 02):
-
- `provider text not null` — for FCM rows: `'silo_relay'` or `'custom_fcm'`.
- `apns_id text` — null for FCM rows.
- `fcm_message_name text` — populated on success with FCM v1's response `name` (e.g., `"projects/continuum-prod-android/messages/0:..."`); null for APNs rows.
- `attempt_number integer not null` — 1-based; participates in the unique constraint and in the relay `Idempotency-Key`.
-
-Retention is identical to APNs: ~14 days for successes, 30-90 for failures.
-
-## Server API Surface
-
-### Register Android Push Device
-
-```http
-POST /api/v1/devices/push/fcm
-```
-
-Profile-scoped. Requires normal auth plus active profile context.
-
-Request:
-
-```json
-{
-  "device_id": "android-device-local-id",
-  "fcm_token": "long-fcm-registration-token",
-  "fcm_project_id": "continuum-prod-android",
-  "fcm_package_name": "com.continuum.app.android",
-  "push_mode": "private_push"
-}
-```
-
-Response:
-
-```json
-{
-  "id": "01J...",
-  "server_device_id": "01JOPAQUE...",
-  "enabled": true,
-  "push_mode": "private_push"
-}
-```
-
-Rules:
-
- `fcm_package_name` must be allowlisted for the configured provider's allowed_packages list.
- `fcm_project_id` must match the configured Firebase project for the active provider.
- registration is idempotent by `(profile_id, device_id, platform)` where platform is implied as `android`.
- token rotation updates the encrypted token and token hash. FCM tokens rotate periodically; the app should call this endpoint whenever `FirebaseMessagingService.onNewToken` fires.
- a disabled server push provider should still allow registration, but should report that remote push is unavailable in the capability response.
-
-### Disable Push Device
-
-Shared with APNs, see [`02-apns-relay.md`](./02-apns-relay.md):
-
-```http
-DELETE /api/v1/devices/push/{id}
-```
-
-### Push Capability
-
-Extended from the APNs spec to include Android:
-
-```http
-GET /api/v1/notifications/capability
-```
-
-Response:
-
-```json
-{
-  "in_app": { "enabled": true },
-  "apple_push": {
-    "available": true,
-    "provider": "silo_relay",
-    "available_providers": ["silo_relay", "custom_apns"],
-    "supported_modes": ["private_push", "in_app_only"]
-  },
-  "android_push": {
-    "available": true,
-    "provider": "silo_relay",
-    "available_providers": ["silo_relay", "custom_fcm"],
-    "supported_modes": ["private_push", "in_app_only"]
-  },
-  "webhooks": {
-    "available": true,
-    "max_per_profile": 10,
-    "supported_types": ["discord", "generic"]
-  }
-}
-```
-
-## Relay API Contract
-
-The relay API should be intentionally narrow. The user server should not send an arbitrary FCM payload.
-
-### Send Android Push
-
-```http
-POST /v1/fcm/send
-Authorization: Bearer <relay_api_key>
-Idempotency-Key: <notification_delivery_id>:<push_device_id>:<attempt_number>
-```
-
-Request:
-
-```json
-{
-  "token": "fcm-registration-token",
-  "project_id": "continuum-prod-android",
-  "package_name": "com.continuum.app.android",
-  "mode": "private_data",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_key": "01JOPAQUE_COLLAPSE"
-}
-```
-
-Response:
-
-```json
-{
-  "request_id": "01JRELAY...",
-  "fcm_message_name": "projects/continuum-prod-android/messages/0:1234567890123456%abcdef",
-  "status": "accepted"
-}
-```
-
-Validation:
-
- `token` is required and must be plausible for FCM (FCM tokens are typically 152-180+ chars, base64url-ish).
- `project_id` must match the configured Firebase project for this relay account's allowed packages.
- `package_name` must be allowlisted for the relay account.
- `mode` must be `private_data` or `background_wake`. Note: this is the **wire mode** (FCM-side); the profile-level mode is `private_push`. See [`00-architecture-overview.md`](./00-architecture-overview.md) "Mode terminology" for the mapping.
- `server_device_id`, `delivery_id`, and `collapse_key` must be opaque values with length limits.
- `collapse_key` derivation (server-side rule, not relay-enforced): identical to the APNs `collapse_id` rule in [`02-apns-relay.md`](./02-apns-relay.md) — `base32(HMAC-SHA256(server_collapse_secret, series_id))` truncated, using the same per-server secret. Never send raw or plainly-hashed `series_id`.
- `badge` is optional. Default should be omitted to avoid leaking unread counts unless the user/admin explicitly enables badge sync.
- no free-form notification title or body fields are accepted.
- no image URL, media ID, username, server hostname, or server URL field is accepted.
-
-### Relay-Built FCM Payloads
-
-For `private_data`, the relay constructs:
-
-```json
-{
-  "message": {
-    "token": "fcm-registration-token",
-    "data": {
-      "v": "1",
-      "wake": "notifications.changed",
-      "server_device_id": "01JOPAQUE...",
-      "delivery_id": "01JDELIVERY..."
-    },
-    "android": {
-      "priority": "high",
-      "collapse_key": "01JOPAQUE_COLLAPSE"
-    }
-  }
-}
-```
-
-For `background_wake`, the relay constructs:
-
-```json
-{
-  "message": {
-    "token": "fcm-registration-token",
-    "data": {
-      "v": "1",
-      "wake": "notifications.changed",
-      "server_device_id": "01JOPAQUE...",
-      "delivery_id": "01JDELIVERY..."
-    },
-    "android": {
-      "priority": "normal",
-      "collapse_key": "01JOPAQUE_COLLAPSE"
-    }
-  }
-}
-```
-
-Notes:
-
- The relay sends **data-only messages** (no top-level `notification` field) so Google never carries rendering content. The Android app constructs the local notification in `onMessageReceived`.
- `priority: high` is used for `private_data` so the message wakes the app even under Doze. High-priority data messages are subject to FCM's anti-abuse quotas — if a server hits the quota, deliveries fall back to normal priority and may be deferred.
- `collapse_key` allows multiple pushes for the same series to coalesce when the device is offline, mirroring `apns-collapse-id`.
- The relay does not allow callers to override this payload shape in v1.
-
-## Custom FCM Contract
-
-`custom_fcm` should share the same internal send model as `silo_relay`, but replace the relay HTTP call with a direct FCM v1 API request.
-
-The server-side push sender should accept only a structured internal request (same shape as the relay request body above):
-
-```json
-{
-  "token": "fcm-registration-token",
-  "project_id": "continuum-prod-android",
-  "package_name": "com.continuum.app.android",
-  "mode": "private_data",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_key": "01JOPAQUE_COLLAPSE"
-}
-```
-
-The sender builds the FCM v1 payload locally using the exact same payload shapes defined above for `private_data` and `background_wake`.
-
-Configuration:
-
- `service_account_json`: full Firebase service account JSON, stored as a secret.
- `project_id`: Firebase project ID.
- `allowed_packages`: explicit Android package names this server is allowed to send for.
-
-Rules:
-
- The admin may configure credentials, project ID, and allowed packages.
- The server must not expose a free-form FCM JSON payload setting.
- The server must not expose custom title/body templates for remote push in v1.
- Package values must match the device registration package and the configured allowlist.
- OAuth2 access tokens should be cached and regenerated before expiry (Google access tokens are typically valid for 1 hour).
- Credential validation should provide a test-send or dry-run diagnostic that does not include notification content. FCM v1 supports `validate_only: true` requests for this purpose.
-
-## Wake And Metadata Fetch
-
-When the app receives an FCM data message:
-
-1. `FirebaseMessagingService.onMessageReceived(remoteMessage)` fires.
-2. Read `data.v`, `data.server_device_id`, and `data.delivery_id`.
-3. Find the local server account that owns `server_device_id`.
-4. If the app is in the foreground, update in-app inbox state directly.
-5. If background:
-   - Construct a generic local notification using `NotificationManager` with a localized "New Silo notification" title.
-   - Schedule a `WorkManager` job to fetch the actual metadata from the user's server.
-   - When the fetch returns, update the visible notification with real content (or replace it).
-6. If the app is opened from the notification, call the server before rendering the target screen.
-
-Suggested fetch:
-
-```http
-GET /api/v1/notifications/sync?since=<last_cursor>
-```
-
-or:
-
-```http
-GET /api/v1/notifications/{delivery_id}
-```
-
-The sync endpoint is preferred because push delivery is not guaranteed and multiple notification deliveries can be coalesced.
-
-If the app cannot reach the server, it should keep the generic notification and retry the inbox sync when connectivity returns.
-
-## Fanout Rules
-
-Push fanout should happen after durable inbox delivery commits. Same flow as APNs:
-
-1. `notification_deliveries` row is created. In the same transaction, the fanout worker enqueues one `pending` `push_delivery_attempts` row per enabled Android `push_device` (the dispatch outbox — see [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)).
-2. The realtime websocket event is published for connected clients.
-3. The push dispatcher claims the `pending` attempt rows post-commit, partitioned by platform; a recovery sweeper claims rows older than ~60s whose dispatch never ran.
-4. Each claimed attempt sends through the configured Android provider:
-   - `silo_relay`: send the minimal relay request.
-   - `custom_fcm`: build the same minimal FCM v1 payload locally and send directly.
-5. FCM errors update device state and attempt status.
-
-Do not block notification delivery creation on FCM or relay availability.
-
-Relay pacing is shared with APNs: one token bucket (`notifications.push.relay_send_rate`, default 5 req/sec) covers both dispatchers because both consume the same relay account quota. See [`02-apns-relay.md`](./02-apns-relay.md) "Relay pacing".
-
-## FCM Error Handling
-
-The server should handle relay/FCM failures without exposing notification content.
-
-FCM v1 error codes worth handling explicitly:
-
- `UNREGISTERED` (404): the token is no longer valid (app uninstalled or data cleared). Disable the device and require re-registration.
- `INVALID_ARGUMENT` (400): malformed request. Mark failed and surface admin diagnostics. Should be rare given the constrained payload.
- `SENDER_ID_MISMATCH` (403): the token was minted under a different Firebase project. Disable and log.
- `QUOTA_EXCEEDED` (429): retry with backoff, **honoring the `Retry-After` response header** if present (FCM uses standard HTTP semantics here). Common when high-priority data-message quotas are hit; FCM specifically throttles high-priority data messages that don't surface a user-visible notification on the device. Consider falling back to `priority: normal` after repeated 429s within a cooldown window.
- `UNAVAILABLE` (503): FCM is temporarily down. Retry with backoff.
- `INTERNAL` (500): retry with backoff.
- `THIRD_PARTY_AUTH_ERROR` (401): credential failure (relay or custom_fcm). Surface in admin diagnostics; do not retry until the admin fixes it.
- relay unavailable, FCM unavailable, or network timeout: retry with backoff.
-
-Errors should be visible to admins as operational status, not to normal users unless their device needs reauthorization.
-
-## Privacy Requirements
-
-The implementation must satisfy these requirements before shipping:
-
- Relay requests contain no notification title or body.
- Relay requests contain no media identifiers.
- Relay requests contain no server hostname or base URL.
- Relay requests contain no profile, username, library, collection, or item names.
- Direct FCM payloads contain no notification title or body. Specifically: **no top-level `notification` object** in the FCM v1 message — data-only messages only.
- Direct FCM payloads contain no media identifiers, server hostname, server URL, profile name, username, library name, collection name, or item name.
- Relay logs redact raw FCM tokens.
- Relay logs redact authorization headers and OAuth2 access tokens.
- Relay logs do not persist full request payloads.
- Server logs redact FCM tokens, custom service account JSON contents, and generated OAuth2 access tokens.
- Badge count is disabled by default.
- Push registration and remote push provider use are opt-in.
- Device unregister disables further push attempts for that device.
-
-## Security Requirements
-
- Relay API uses TLS only.
- Relay API keys are scoped to a relay account or install identifier.
- Relay API keys can be revoked without changing the user's Silo server authentication.
- Relay requests are rate limited by API key and coarse token hash.
- Relay supports idempotency keys to prevent duplicate FCM sends during retry.
- Relay does not accept arbitrary FCM payload JSON in v1.
- Server stores relay API keys as secrets.
- Server stores custom FCM service account JSON as a secret.
- Server never logs custom FCM service account JSON contents, generated OAuth2 access tokens, or FCM authorization headers.
- Server stores FCM registration tokens encrypted at rest where local secret storage exists.
- Admin diagnostics must not print raw FCM tokens or service account JSON.
- Custom FCM service account JSON must validate as a real Google service account JSON before being accepted (parse + sanity check `type: "service_account"` and required key fields).
-
-## Settings And UX
-
-Admin settings should explain the tradeoff plainly:
-
-```text
-Android Push Provider
-
-Off
-  No Android remote push. Devices still receive in-app realtime updates while open.
-
-Silo Relay
-  Uses Silo's FCM relay to wake Android devices. Notification details stay on
-  this server. The relay receives FCM tokens, timestamps, and opaque delivery IDs.
-
-Custom FCM
-  Advanced. Send directly to Google FCM using your own Firebase service account.
-  Notification details still stay on this server. Only useful if you've published
-  your own signed Android app variant under your own Firebase project.
-```
-
-Device settings (shared with APNs) should describe the user-visible mode:
-
-```text
-Private Push
-  Show a generic Silo notification, then fetch details from your server when
-  this device wakes.
-```
-
-Do not claim the central relay is fully self-hosted. The truthful claim is:
-
-```text
-Notification content stays on your server. Google FCM, and the Silo relay
-if selected, may still process generic wake messages needed for Android push
-delivery.
-```
-
-## Implementation Plan
-
-### Task 1: Add Android Push Provider Settings
-
-Files likely involved:
-
- `internal/api/handlers/settings.go`
- `web/src/lib/settingsManifest.ts` (or admin-scope equivalent)
- settings UI files as needed
-
-Add server/admin settings for:
-
- provider selection
- relay endpoint
- relay API key
- custom FCM service account JSON
- custom FCM project ID
- custom FCM allowed packages
- badge sync enabled or disabled (shared with Apple settings)
-
-Default provider must be `off`.
-
-### Task 2: Extend Push Device Registration
-
-Files likely involved:
-
- migration extending `push_devices` from the APNs spec to add FCM-specific columns and a check constraint
- `internal/notifications` package
- `internal/api/handlers/notifications.go`
- `internal/api/router.go`
-
-Add profile-scoped Android push device registration, token rotation, and disable APIs.
-
-If the APNs spec lands first, this task is purely additive (new columns nullable, new endpoint, expanded `platform` enum).
-
-### Task 3: Add Android Push Provider Clients
-
-Files likely involved:
-
- `internal/notifications/fcm_relay.go`
- `internal/notifications/fcm_direct.go`
- config/settings accessors
-
-Implement the narrow `/v1/fcm/send` relay client. The client should not accept a free-form notification payload.
-
-Implement the direct FCM v1 client for `custom_fcm` using:
-
- `golang.org/x/oauth2/google` for service-account-based OAuth2 token generation, or an equivalent that doesn't add a heavy Google SDK dependency.
- Cached access token with refresh-before-expiry.
- Standard `net/http` for the FCM v1 endpoint.
-
-Both clients use the same internal request shape and payload builder so the dispatcher code is uniform.
-
-### Task 4: Extend Push Fanout Worker
-
-Files likely involved:
-
- `internal/notifications/push_fanout.go` (shared with APNs)
-
-Trigger Android push fanout for devices with `platform = 'android'`. Use retries and record `push_delivery_attempts` with `fcm_message_name` populated on success.
-
-### Task 5: Add Android Client Registration And Wake Handling
-
-Files live in the Android client repository, not this server repo.
-
-Required client behavior:
-
- request `POST_NOTIFICATIONS` permission on Android 13+
- get FCM registration token via `FirebaseMessaging.getInstance().getToken()`
- register token with the user's server
- handle `FirebaseMessagingService.onNewToken` for token rotation
- store `server_device_id` locally, scoped to the active server account
- handle `onMessageReceived` for both foreground and background data messages
- fetch notification metadata after wake/open
- unregister or disable on sign-out / profile removal / app data clear
-
-### Task 6: Add Admin Diagnostics
-
-Expose high-level status (extending the APNs diagnostics surface):
-
- provider enabled/disabled
- number of registered Android devices
- last relay success
- last relay failure code
- custom FCM credential presence and project/package status
- last custom FCM success
- last custom FCM failure code
- token/package/project mismatch warnings
-
-Do not expose raw FCM tokens or service account JSON.
-
-## Validation Plan
-
-Use minimal verification while the work is still design-only. When implemented, verify:
-
- relay-disabled servers never call the relay
- `custom_fcm` servers never call the relay
- device registration is profile-scoped and idempotent
- FCM tokens are redacted in logs
- relay request bodies contain no titles, body text, item IDs, server URLs, or profile names
- direct FCM payloads contain no `notification` object and no titles, body text, item IDs, server URLs, or profile names
- custom FCM service account JSON is redacted in logs
- generated OAuth2 access tokens are redacted in logs
- creating one `notification_delivery` sends at most one push per enabled device
- FCM token rotation updates the stored token without duplicating devices
- `UNREGISTERED` and `SENDER_ID_MISMATCH` disable the affected device
- `QUOTA_EXCEEDED` triggers backoff
- app wake fetches notification metadata from the user's server
- server offline after push leaves only the generic notification visible
-
-## Open Questions
-
- Should official Silo Android builds use one Firebase project per build channel (debug / staging / prod), or share?
- Should badge counts (Android notification dots / numbers) be allowed in `private_push`, or deferred?
- Should the relay store hashed FCM token aliases to avoid sending raw tokens on every request? Defer to v2 unless rate-limit pressure justifies it.
- Should the server fall back to `priority: normal` after repeated `QUOTA_EXCEEDED` to keep deliveries flowing at the cost of latency? Recommendation: yes, with a cooldown timer.
- Should we also add a Huawei Mobile Services (HMS) push path for non-Google Android devices? Out of scope v1; could mirror this spec as `04-hms-relay.md` later.
@@ -1,731 +0,0 @@
-# Outbound Webhooks Spec
-
-**Date:** 2026-04-28
-**Status:** Draft
-**Scope:** Profile-scoped outbound webhook destinations for Silo notifications. Native Discord embed type and generic JSON+HMAC type.
-**Depends On:**
- [`00-architecture-overview.md`](./00-architecture-overview.md)
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)
-
-## Summary
-
-Silo should let each profile send their notifications to user-chosen webhook destinations: a Discord channel, a Slack incoming webhook, a personal automation service, or any HTTP endpoint that accepts JSON. Webhooks are configured per profile, support per-webhook reason filters, and include full notification content by default — the profile chose the destination, so trust is implicit.
-
-Two webhook types ship in v1:
-
- **Discord** — native Discord embed payload. The user pastes a Discord channel webhook URL; Silo POSTs Discord-formatted embeds.
- **Generic** — canonical Silo JSON, HMAC-SHA256 signed via `X-Silo-Signature`. Suitable for Slack-incoming-webhook-style targets, custom user automations, or any HTTP endpoint.
-
-## Why this is different from APNs / FCM
-
-The privacy model inverts. APNs and FCM relay paths route through infrastructure operators (Apple, Google, Silo's relay) that the user did not directly choose. Therefore those paths carry no notification content — only opaque IDs.
-
-Outbound webhooks go to a destination the **profile explicitly configured**. By choosing the URL, the profile is consenting to send notification content to that endpoint. There is no privacy benefit to gating content out of webhooks the profile set up themselves; doing so would just make the feature useless ("New episode! [check Silo]" is no better than what's already in the app).
-
-The trust model is therefore:
-
- Profile chose the URL → notification content is included by default.
- Discord embeds get series title, episode title, season/episode numbers, and poster.
- Generic webhooks get the same data in canonical JSON, plus an HMAC signature derived from a per-webhook signing secret.
- Silo still enforces privacy guardrails the profile cannot opt out of: HTTPS only, no localhost / RFC1918 destinations by default, redacted logs, retry/disable on persistent failure.
-
-## Decision
-
-Add per-profile webhook destinations, configurable through the profile's notification preferences UI:
-
- Profile creates a webhook by pasting a URL and optionally a name and reason filters.
- Webhook type is detected from the URL or selected explicitly: `discord` (matches Discord webhook URL pattern) or `generic`.
- Silo POSTs a typed payload to the URL whenever a `notification_deliveries` row commits for that profile and the webhook's reason filters allow it.
- Failed deliveries are retried with exponential backoff and disabled after a configurable consecutive-failure threshold.
- Each webhook has a profile-visible status: enabled, last success, last failure code, consecutive failure count.
-
-## Goals
-
- Let a profile send Silo notifications to Discord, Slack, or any user-chosen URL.
- Render natively in Discord without the user copy-pasting JSON templates.
- Provide a stable, signed, well-documented generic format for everything else.
- Keep the feature profile-scoped: a profile only sees and controls their own webhooks.
- Add no new infrastructure dependencies (no relay needed; webhooks are direct outbound HTTP from the user's Silo server).
- Make failure modes legible to the profile so they can fix a broken webhook themselves.
-
-## Non-Goals
-
- Server-wide / admin-level webhooks for system events (scan complete, library health, etc.). Out of scope v1; Silo's existing realtime hub already handles operational events.
- Webhook destinations that require OAuth (Slack apps, Discord bots, Microsoft Teams Adaptive Cards). Webhook-style endpoints with an unauth'd POST URL are sufficient for v1.
- Per-event-type custom payload templates. The Discord embed shape and the generic JSON shape are fixed in v1; richer customization is v2.
- Webhook retry windows beyond 24 hours. After ~24h of consecutive failures, the webhook is auto-disabled and the profile is notified in-app.
- Multiple webhook destinations per webhook row (e.g., one row firing to two URLs). One URL per row.
- Two-way webhooks. Silo only POSTs out; it does not consume webhook responses for state.
-
-## Trust Model
-
-The profile chose the destination URL. By creating a webhook, the profile consents to send full notification content (titles, posters, episode metadata) to that URL.
-
-What we still don't trust the profile about:
-
- **HTTPS:** Required. `http://` URLs are rejected.
- **Local / private destinations:** Rejected by default. Specifically, the URL host must resolve to an address outside all of the following ranges:
-  - **IPv4 private/special:** `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10` (CGNAT / RFC6598), `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.0.0.0/24` (IETF protocol assignments), `192.0.2.0/24` / `198.51.100.0/24` / `203.0.113.0/24` (TEST-NET-1/2/3), `192.88.99.0/24` (deprecated 6to4 anycast), `192.168.0.0/16`, `198.18.0.0/15` (benchmarking, RFC 2544), `224.0.0.0/4` (multicast), `240.0.0.0/4` (reserved future use)
-  - **IPv6 private/special:** `::/128` (unspecified), `::1/128` (loopback), `fc00::/7` (ULA), `fe80::/10` (link-local), `2001:db8::/32` (documentation), `64:ff9b::/96` (NAT64)
-  - **IPv4-mapped IPv6:** `::ffff:0:0/96` — the most likely real-world bypass. A literal `::ffff:127.0.0.1` resolves to loopback when the connection is established but bypasses naive IPv4-only checks. The validator must unwrap v4-mapped addresses and re-check against the IPv4 deny set.
-  - **DNS names that resolve to any of the above** at registration time *and* at delivery time (DNS rebinding mitigation; see below).
-
-  An admin-only setting `notifications.webhooks.allow_private_destinations = true` may be set for dev environments. It applies globally to the server and is intended only for development.
- **Server URL leakage:** Webhook payloads must **not** include the user's Silo server hostname, base URL, or absolute artwork URLs that include the server origin. Posters in Discord embeds use a profile-token-signed proxy URL (or, for v1, the embed omits images if the server URL would leak). Generic webhooks include only relative paths and let the receiver fetch from the server using their own knowledge of the server URL.
- **Relay leakage:** The webhook delivery path runs entirely on the user's own Silo server; no Silo-operated infrastructure is involved.
-
-## User Flow
-
-```
-1. Profile opens Settings -> Notifications -> Webhooks.
-2. Profile clicks "Add webhook".
-3. Pastes a URL like https://discord.com/api/webhooks/123/abc.
-4. Silo auto-detects Discord type from URL pattern.
-5. Profile names the webhook ("Family Discord") and toggles
-   reason filters: favorites on, watchlist on, continue_watching off, next_up off.
-6. Profile clicks "Test", Silo POSTs a sample notification.
-7. Discord channel shows the test embed; profile clicks "Save".
-8. From now on, matching new-episode notifications post to Discord.
-9. If the webhook URL becomes invalid (Discord deletes it), Silo:
-    a. Marks each 404'd delivery failed immediately (non-retryable 4xx);
-       transient network failures instead retry with backoff for ~24h.
-    b. After 3 consecutive non-retryable-4xx deliveries (or the retry
-       threshold for persistent network failures), auto-disables the webhook.
-    c. Posts an in-app notification to the profile: "Your 'Family Discord'
-       webhook stopped working. Last error: 404. Edit settings to fix."
-```
-
-## Data Model
-
-### `notification_webhooks`
-
-Purpose: profile-scoped webhook destination.
-
-Columns:
-
- `id text primary key`
- `user_id integer not null` (matches `users.id integer`)
- `profile_id text not null`
- `name varchar(64) not null` — user-friendly label, capped to bound row size
- `type text not null` — `'discord'` or `'generic'`
- `url_ciphertext bytea not null` — destination URL, encrypted at rest
- `url_host varchar(253) not null` — denormalized host (no path) for diagnostics and validation logs (253 = max DNS host length)
- `signing_secret_ciphertext bytea` — null for `discord` (Discord webhooks don't sign); required for `generic`
- `enabled boolean not null default true`
- `notify_favorites boolean not null default true`
- `notify_watchlist boolean not null default true`
- `notify_continue_watching boolean not null default true`
- `notify_next_up boolean not null default true`
- `consecutive_failures integer not null default 0`
- `disabled_reason varchar(256)` — populated when auto-disabled
- `last_success_at timestamptz`
- `last_failure_at timestamptz`
- `last_failure_status integer`
- `last_failure_message varchar(256)` — short, non-sensitive diagnostic, e.g., "404 Not Found"
- `created_at timestamptz not null default now()`
- `updated_at timestamptz not null default now()`
-
-Constraints:
-
- `(profile_id, name)` is unique per profile to prevent duplicate-name confusion.
- `CHECK (type IN ('discord', 'generic'))`.
- `CHECK (type = 'discord' OR signing_secret_ciphertext IS NOT NULL)` — generic webhooks must have a signing secret.
-
-Indexes:
-
- `(profile_id)` for the listing endpoint.
- `(profile_id, enabled)` partial index where `enabled = true` for the dispatcher hot path.
-
-Notes:
-
- URLs and signing secrets are encrypted using the same local secret-storage facility as other sensitive columns (e.g., APNs tokens). If that facility doesn't exist yet, this spec lands the columns as plain `bytea` containing UTF-8 bytes for v1; an explicit follow-up adds the encryption layer.
- `disabled_reason` is set when the system auto-disables; cleared when the profile re-enables.
-
-### `webhook_delivery_attempts`
-
-Purpose: operational record of webhook attempts.
-
-Columns:
-
- `id text primary key`
- `notification_delivery_id text not null references notification_deliveries(id) on delete cascade`
- `webhook_id text not null references notification_webhooks(id) on delete cascade`
- `attempt_number integer not null`
- `attempted_at timestamptz not null default now()`
- `next_retry_at timestamptz`
- `http_status integer`
- `outcome text not null` — `'pending'`, `'delivered'`, `'retrying'`, `'failed'`, `'auto_disabled'`
- `failure_message varchar(256)` — short diagnostic (e.g., HTTP status text, DNS error class). Must not include payload contents.
-
-Constraints:
-
- `(webhook_id, notification_delivery_id, attempt_number)` is unique to prevent double-claims under retry concurrency.
- `CHECK (outcome IN ('pending', 'delivered', 'retrying', 'failed', 'auto_disabled'))`.
- index on `(webhook_id, attempted_at desc)` for per-webhook history listing.
- index on `(outcome, next_retry_at)` for the retry worker.
-
-Retention:
-
- keep `delivered` rows for ~7 days
- keep `failed`/`auto_disabled` rows for ~30 days for profile-visible debugging
- keep `pending`/`retrying` rows until they resolve
-
-## Server API Surface
-
-All endpoints are profile-scoped and require `X-Profile-Id` middleware.
-
-### List Webhooks
-
-```http
-GET /api/v1/notifications/webhooks
-```
-
-Response:
-
-```json
-{
-  "webhooks": [
-    {
-      "id": "01J...",
-      "name": "Family Discord",
-      "type": "discord",
-      "url_host": "discord.com",
-      "enabled": true,
-      "notify_favorites": true,
-      "notify_watchlist": true,
-      "notify_continue_watching": false,
-      "notify_next_up": false,
-      "last_success_at": "2026-04-27T18:32:11Z",
-      "last_failure_at": null,
-      "last_failure_status": null,
-      "last_failure_message": null,
-      "consecutive_failures": 0,
-      "disabled_reason": null
-    }
-  ]
-}
-```
-
-Note the response **never includes the full URL or signing secret**. It returns only `url_host` so the profile can identify which Discord/Slack/etc. the webhook points at without leaking the secret URL token (which functions as the auth credential for Discord webhooks).
-
-### Create Webhook
-
-```http
-POST /api/v1/notifications/webhooks
-```
-
-Request:
-
-```json
-{
-  "name": "Family Discord",
-  "url": "https://discord.com/api/webhooks/123456/abcdef-token",
-  "type": "discord",
-  "notify_favorites": true,
-  "notify_watchlist": true,
-  "notify_continue_watching": false,
-  "notify_next_up": false
-}
-```
-
-Rules:
-
- `type` is optional; if omitted, the server detects Discord URLs via pattern (`https://discord.com/api/webhooks/{id}/{token}` or `https://discordapp.com/...`). All other URLs default to `generic`.
- For `generic`, the server generates a random signing secret (32 bytes, base64) and returns it **once** in the response. The profile is responsible for storing it on the receiving service.
- URL must pass private-destination guards.
- URL must use `https`.
- `name` length capped at 64 chars; reject empty or whitespace-only.
- Per-profile cap: max 10 webhooks (configurable via admin setting; documented as `notifications.webhooks.max_per_profile`).
-
-Response:
-
-```json
-{
-  "id": "01J...",
-  "name": "Family Discord",
-  "type": "discord",
-  "url_host": "discord.com",
-  "enabled": true,
-  "notify_favorites": true,
-  "notify_watchlist": true,
-  "notify_continue_watching": false,
-  "notify_next_up": false,
-  "signing_secret": null
-}
-```
-
-For `generic`:
-
-```json
-{
-  "id": "01J...",
-  "name": "My Slack Webhook",
-  "type": "generic",
-  "url_host": "hooks.slack.com",
-  "enabled": true,
-  "notify_favorites": true,
-  "notify_watchlist": true,
-  "notify_continue_watching": true,
-  "notify_next_up": true,
-  "signing_secret": "base64-encoded-secret-shown-once"
-}
-```
-
-`signing_secret` is **only** returned at create time and is never re-fetchable. Rotation requires a separate endpoint.
-
-### Update Webhook
-
-```http
-PUT /api/v1/notifications/webhooks/{id}
-```
-
-Request fields are all optional; included fields are updated:
-
-```json
-{
-  "name": "Renamed",
-  "enabled": true,
-  "notify_favorites": false,
-  "url": "https://discord.com/api/webhooks/.../new-token"
-}
-```
-
-Updating the URL re-validates against the private-destination guard and resets `consecutive_failures` to 0.
-
-### Delete Webhook
-
-```http
-DELETE /api/v1/notifications/webhooks/{id}
-```
-
-Idempotent. Cascades to `webhook_delivery_attempts`.
-
-### Rotate Signing Secret (generic only)
-
-```http
-POST /api/v1/notifications/webhooks/{id}/rotate-secret
-```
-
-Generates and returns a new signing secret. The profile must update the receiving service to use the new secret.
-
-### Test Webhook
-
-```http
-POST /api/v1/notifications/webhooks/{id}/test
-```
-
-Synchronously POSTs a sample payload to the destination and returns the result:
-
-```json
-{
-  "ok": true,
-  "http_status": 204,
-  "duration_ms": 187
-}
-```
-
-or:
-
-```json
-{
-  "ok": false,
-  "http_status": 404,
-  "duration_ms": 234,
-  "message": "404 Not Found"
-}
-```
-
-The test payload is identical in shape to a real notification but is clearly marked (e.g., embed footer text "Silo test notification" for Discord; `"test": true` field in generic). Test sends do not consume the retry/auto-disable counters.
-
-## Payload Formats
-
-### Discord
-
-The Discord webhook API documents the `POST /api/webhooks/{id}/{token}` endpoint, which accepts a JSON body with optional `content` (plain text) and `embeds` (rich cards). Silo sends embeds only; no `content` field, so the message renders cleanly without a leading text line.
-
-**v1 payload (text-only, no images):**
-
-```json
-{
-  "embeds": [
-    {
-      "title": "Severance — S2 E1: Hello, Ms. Cobel",
-      "description": "New episode available on Silo",
-      "color": 5814783,
-      "footer": {
-        "text": "Silo • Severance"
-      },
-      "timestamp": "2026-04-28T12:34:56Z",
-      "fields": [
-        { "name": "Reason", "value": "Favorited & Continue Watching", "inline": true },
-        { "name": "Season", "value": "2", "inline": true },
-        { "name": "Episode", "value": "1", "inline": true }
-      ]
-    }
-  ],
-  "username": "Silo"
-}
-```
-
-**v1.5 payload (with image proxy, additive):**
-
-In v1.5, the builder adds `image` (poster) and `avatar_url` (Silo mark) fields, both pointing at `media.discord-cdn-proxy.silo.app` URLs. **In v1, these fields MUST be omitted entirely** — the builder must not fall back to absolute URLs that include the user's server origin. The privacy contract is broken if Discord sees the user's server URL in any embed field.
-
-Notes on the Discord payload:
-
- **v1 builder rule:** the `image` field, the embed's `url` field, and the top-level `avatar_url` field must be omitted. Discord renders the embed without an image; the channel webhook's configured avatar is used. There is no fallback to the user's server URL.
- **v1.5 builder rule:** `image.url` and `avatar_url` use a CDN proxy hosted at `media.discord-cdn-proxy.silo.app`. The proxy is a small Silo-operated service that takes a short-lived signed URL token (issued by the user's server when constructing the webhook payload) and server-side streams the corresponding asset from the user's server. The leak vector being mitigated is *Discord's own infrastructure* fetching and caching the embed image — Discord's CDN (`media.discordapp.net`) fetches once from whatever origin the embed names; end-users only ever see the cached `media.discordapp.net` URL. The proxy ensures the origin Discord fetches from is the proxy, not the user's server.
- **Discord embed limits** (apply to both v1 and v1.5; payload builder must enforce):
-  - 6,000 char total across `title` + `description` + `field.name` + `field.value` + `footer.text` per embed
-  - `title`: 256 chars
-  - `description`: 4,096 chars
-  - `fields`: 25 max; `field.name` 256 chars, `field.value` 1,024 chars
-  - `footer.text`: 2,048 chars
-  - 10 embeds per message (Silo sends one)
-  - **Truncation policy:** prefer to truncate `description` first (with ellipsis), then field values. Never truncate `title`. If even truncated content exceeds the 6,000-char total, drop fields right-to-left until under cap.
- `color` is a Discord embed accent color encoded as decimal RGB. Silo picks per-reason: favorite=5814783 (Silo brand purple), watchlist=3066993 (green), continue_watching=15844367 (yellow), next_up=15158332 (red).
- `username` overrides the Discord webhook's default name to "Silo".
- The webhook URL itself is the auth — Discord's webhook tokens are bearer credentials in the URL path. This is why we never return the URL on read.
-
-The Discord embed structure follows Discord's webhook API. See [Discord embed object docs](https://discord.com/developers/docs/resources/channel#embed-object) for the full schema.
-
-### Generic
-
-JSON body, signed via HMAC-SHA256 over the raw bytes Silo sends. Receivers verify against the literal bytes they received — no canonicalization required on either side.
-
-Headers:
-
- `Content-Type: application/json`
- `User-Agent: Silo-Webhook/1.0`
- `X-Silo-Event: notification.created`
- `X-Silo-Webhook-Id: 01J...` — the webhook row ID
- `X-Silo-Delivery-Id: 01J...` — the underlying `notification_deliveries.id`
- `X-Silo-Timestamp: 1714299296` — Unix epoch seconds, integer
- `X-Silo-Signature: t=1714299296,v1=<hex-hmac-sha256>`
-  - HMAC-SHA256 of the byte string `{X-Silo-Timestamp}.{request body bytes}` using the per-webhook signing secret. The result is hex-encoded.
-  - Format follows Stripe's signing convention so receivers can use existing libraries (Stripe Go SDK, `stripe-signature` ports, etc.).
-  - **The timestamp value in the body's `timestamp` field is informational and may be RFC3339 for human readability; only the `X-Silo-Timestamp` header value (Unix epoch integer) participates in the HMAC computation.**
-
-Body:
-
-```json
-{
-  "event": "notification.created",
-  "delivery_id": "01J...",
-  "webhook_id": "01J...",
-  "timestamp": "2026-04-28T12:34:56Z",
-  "version": 1,
-  "test": false,
-  "profile_id": "profile-1",
-  "library_id": 7,
-  "type": "episode.available",
-  "reason_flags": {
-    "favorite": true,
-    "watchlist": false,
-    "continue_watching": true,
-    "next_up": true
-  },
-  "series": {
-    "id": "series-123",
-    "title": "Severance"
-  },
-  "episode": {
-    "id": "episode-456",
-    "title": "Hello, Ms. Cobel",
-    "season_number": 2,
-    "episode_number": 1
-  }
-}
-```
-
-Notes on the generic payload:
-
- The body is canonicalized (sorted keys, UTF-8 encoded) before HMAC computation so the receiver can verify deterministically.
- `profile_id` is included so the receiver can route by profile (one Slack channel per profile, etc.). It is the profile's own ID and is acceptable to share with the destination the profile chose.
- No server URL, no absolute poster URLs, no library name. The receiver cannot link this back to the user's server hostname unless the profile has separately told them.
- `version: 1` allows future schema changes without breaking existing receivers.
- `test: true` distinguishes test sends from real sends.
-
-### Signature Verification (generic)
-
-Receivers verify by:
-
-```
-parts = X-Silo-Signature.split(",")
-ts = parts.find("t=").value           // Unix epoch integer (string form)
-v1 = parts.find("v1=").value          // hex string
-
-raw_body = literal request body bytes (do NOT re-parse and re-serialize JSON)
-expected = hex(hmac_sha256(secret, ts + "." + raw_body))
-
-if constant_time_compare(v1, expected) and abs(now_epoch - parse_int(ts)) < 300:
-    accept
-else:
-    reject
-```
-
-Key rules:
-
- Sign and verify the **literal request body bytes**, not a re-canonicalized form. This eliminates JSON-canonicalization ambiguity (number formatting, escape rules, key ordering) and matches Stripe's pattern.
- `ts` and `now_epoch` are both Unix epoch seconds (integer). The timestamp window of 300 seconds (5 minutes) prevents replay; receivers may tighten if they wish.
- Use a constant-time comparator (`hmac.equal`, `crypto/subtle.ConstantTimeCompare`, etc.) to avoid timing attacks.
-
-### Signing Secret Rotation
-
-`POST /api/v1/notifications/webhooks/{id}/rotate-secret` generates a new signing secret and returns it once. After rotation:
-
- The new secret takes effect immediately for all subsequent deliveries.
- **Pending and retrying delivery attempts re-sign with the current secret on each retry**, not the secret that was active when the attempt was first enqueued. This means receivers who have updated to the new secret will accept the retried delivery; receivers still on the old secret will reject it. The expected operational pattern is: profile rotates the secret and updates their receiver atomically (or near-atomically); brief retry-window mismatches are acceptable.
- Silo does **not** keep the old secret around after rotation. There is no dual-acceptance window.
-
-## Delivery Semantics
-
-### Send path
-
-1. The fanout transaction in [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md) commits the `notification_deliveries` row **and**, in the same transaction, one `webhook_delivery_attempts` row with `outcome = 'pending'` per enabled, reason-matching webhook (the dispatch outbox). Two filters apply at enqueue time:
-   - **Type deny list.** `webhook.auto_disabled` deliveries never enqueue webhook attempts — a webhook auto-disable notice must never be re-dispatched as a webhook, otherwise a broken webhook would generate an auto-disable notification that fires another webhook attempt that fails again, looping. Other notification types may join this list as they're added.
-   - **Per-webhook reason filter** (`notify_favorites`, etc.). No matching reason, no attempt row.
-2. `WebhookDispatcher.Dispatch(delivery)` runs post-commit and claims the delivery's `pending` attempt rows (`FOR UPDATE SKIP LOCKED`).
-3. For each claimed attempt:
-   - Construct the payload (Discord embed or generic JSON).
-   - POST the payload with a 10-second total timeout.
-   - On success (HTTP 2xx): mark attempt `delivered`, update webhook `last_success_at`, reset `consecutive_failures = 0`.
-   - On failure: mark attempt `retrying` with `next_retry_at`, increment `consecutive_failures` on the webhook.
-4. The retry worker reads `webhook_delivery_attempts WHERE (outcome = 'retrying' AND next_retry_at <= now()) OR (outcome = 'pending' AND attempted_at <= now() - interval '60 seconds')` — the second arm is outbox recovery for attempts whose post-commit dispatch never ran (process crash).
-5. When `consecutive_failures` exceeds the threshold (default 10) over a span > 24h, the webhook is auto-disabled (`enabled = false`, `disabled_reason = '...'`), and an in-app notification is posted to the profile via the in-app inbox.
-
-### Preference precedence (relationship to `notification_preferences`)
-
-Profile-level `notification_preferences.notify_*` flags are a **hard gate** applied during fanout (see [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)). A delivery row is never created if all matching reasons are disabled at the profile level — so the dispatcher never sees those events.
-
-Per-webhook `notify_*` flags are an **additional filter** applied during dispatch. They can narrow what fires for a specific webhook, but they cannot re-enable a reason the profile has globally disabled. The frontend must reflect this: if a profile turns off `notify_continue_watching` globally, the per-webhook continue-watching checkbox should appear disabled with explanatory text rather than implying the user can re-enable it for one destination.
-
-### Retry schedule
-
-Exponential backoff, capped at 24h total:
-
-| Attempt | Delay since first attempt |
-|---|---|
-| 1 | 0 (immediate) |
-| 2 | 30s |
-| 3 | 2m |
-| 4 | 10m |
-| 5 | 30m |
-| 6 | 2h |
-| 7 | 6h |
-| 8 | 12h |
-| 9 | 18h |
-| 10 | 24h, then auto-disable |
-
-Each attempt has a 10s total timeout.
-
-**4xx skip-retry:** 4xx HTTP responses (except `408 Request Timeout`, `425 Too Early`, `429 Too Many Requests`) are deterministic destination-side rejections — retrying *this delivery* won't help, so the attempt is marked `failed` immediately without walking the 10-attempt schedule. Auto-disable, however, requires **3 consecutive deliveries** to fail with a non-retryable 4xx (tracked via `consecutive_failures` plus the failure-status class) before the webhook is disabled. A single 4xx is not proof the webhook is dead: destination-side WAF/CDN blips (Discord behind Cloudflare) intermittently return 403/400 for valid webhooks, and instant disable on one such blip would force pointless manual re-enables. Three consecutive deterministic rejections is strong evidence the URL is actually gone. The profile is notified in-app per "Auto-Disable Notification" below.
-
-`429 Too Many Requests` honors the `Retry-After` header if present (overriding the schedule above for that attempt).
-
-### Concurrency
-
-The dispatcher fans webhook deliveries in parallel within a small bounded pool (e.g., 16 workers per server process). One slow webhook destination cannot block other deliveries.
-
-### Test delivery isolation
-
-`POST /webhooks/{id}/test` sends synchronously, does not write to `webhook_delivery_attempts`, does not affect `consecutive_failures`, and returns the HTTP result inline.
-
-## Privacy Requirements
-
- Webhook URLs are encrypted at rest where the local encryption facility supports it.
- Webhook URLs are never returned in API responses (only `url_host`).
- Generic signing secrets are returned only at create / rotate time; never readable after.
- Logs redact full URLs (host only) and full signing secrets.
- Logs do not persist webhook payload bodies. Failure logs may include HTTP status text.
- Webhook payloads must not include the Silo server URL or absolute artwork URLs that include the server origin.
- An admin must not be able to read another profile's webhook URLs or signing secrets.
-
-## Security Requirements
-
- HTTPS-only destinations.
- Private-destination guard on URL submission and on each delivery (re-resolve to catch DNS rebinding to private IPs).
- HMAC-SHA256 with per-webhook 32-byte signing secrets for `generic`.
- Signing secret returned only at create / rotate; rotation immediately invalidates the previous secret.
- Per-profile cap on webhook count (default 10).
- Per-profile rate limit on webhook delivery (e.g., 60 deliveries / 60 seconds / profile across all webhooks). Notifications that exceed the limit are still durably stored in the inbox; webhooks just don't fire for them. Logged so admins can spot runaway scenarios.
- TLS verification is enforced and not user-overridable.
- HTTP redirects are followed (max 3 hops) but the final URL must still pass the private-destination guard at each hop.
-
-## DNS Rebinding Mitigation
-
-A naive implementation that resolves the URL once at registration time is vulnerable to DNS rebinding: the host could resolve to a public IP at registration and a private IP at delivery time. Mitigation:
-
- At delivery time, resolve the host yourself, validate the resolved IPs against the private deny set, then connect using the validated IP (or a controlled `net.Dialer` that re-validates the address it's about to connect to).
- Do not let the standard library transparently re-resolve on each request.
- The `internal/notifications/webhook_http.go` HTTP client should use a custom `Dialer.Control` callback that inspects the resolved address and refuses connections to private ranges.
-
-## Settings And UX
-
-Profile-level settings:
-
-```text
-Webhooks
-
-Add webhook
-  Send Silo notifications to a webhook URL.
-  Discord URLs render as native Discord embeds.
-  Other URLs receive signed JSON.
-
-[Family Discord]                              ✓ enabled
-  discord.com
-  ✓ Favorites  ✓ Watchlist  ☐ Continue watching  ☐ Next up
-  Last success: 2 hours ago
-  [ Test ]  [ Edit ]  [ Delete ]
-
-[Slack: #media]                               ✓ enabled
-  hooks.slack.com
-  ✓ all reasons
-  Last failure: 3 minutes ago — 404 Not Found
-  ⚠ This webhook is failing. Check the destination URL.
-  [ Test ]  [ Edit ]  [ Delete ]
-
-+ Add webhook
-```
-
-Admin-level settings (server-wide guards, default values):
-
- `notifications.webhooks.max_per_profile` (default 10)
- `notifications.webhooks.allow_private_destinations` (default false; for dev environments)
- `notifications.webhooks.deliveries_per_minute_per_profile` (default 60)
-
-## Implementation Plan
-
-### Task 1: Schema
-
-Files:
-
- new migration under `migrations/` adding `notification_webhooks` and `webhook_delivery_attempts` tables.
-
-### Task 2: Webhook Repository And Service
-
-Files:
-
- `internal/notifications/webhook_repo.go`
- `internal/notifications/webhook_service.go` (CRUD, validation, signing-secret handling)
-
-Includes:
-
- URL validation (https, private-destination guard)
- Discord URL detection
- signing secret generation
- per-profile count enforcement
-
-### Task 3: HTTP Client With Address Guard
-
-Files:
-
- `internal/notifications/webhook_http.go`
-
-Custom HTTP client with:
-
- 10-second timeout
- TLS verification non-overridable
- `Dialer.Control` callback that re-validates the resolved IP at connect time
- bounded redirect handling
- structured error reporting (DNS error class, TCP, TLS, HTTP status) for `failure_message`
-
-### Task 4: Payload Builders
-
-Files:
-
- `internal/notifications/webhook_payload_discord.go`
- `internal/notifications/webhook_payload_generic.go`
-
-Each pure function `func Build(delivery NotificationDelivery, hook Webhook) ([]byte, error)`. No side effects, easy to unit test.
-
-### Task 5: Dispatcher Integration
-
-Files:
-
- `internal/notifications/webhook_dispatcher.go`
-
-Implements the channel `Dispatcher` interface from `00-architecture-overview.md`. Loads enabled webhooks for the delivery's profile, applies reason filters, posts payloads, records attempts.
-
-### Task 6: Retry Worker
-
-Files:
-
- `internal/notifications/webhook_retry_worker.go`
-
-Polls `webhook_delivery_attempts WHERE outcome = 'retrying' AND next_retry_at <= now()` with `FOR UPDATE SKIP LOCKED`. Re-dispatches and updates state. Handles auto-disable.
-
-### Task 7: API Handlers And Routes
-
-Files:
-
- `internal/api/handlers/notifications_webhooks.go`
- `internal/api/router.go`
-
-Routes:
-
- `GET /api/v1/notifications/webhooks`
- `POST /api/v1/notifications/webhooks`
- `PUT /api/v1/notifications/webhooks/{id}`
- `DELETE /api/v1/notifications/webhooks/{id}`
- `POST /api/v1/notifications/webhooks/{id}/test`
- `POST /api/v1/notifications/webhooks/{id}/rotate-secret`
-
-All require `RequireProfile` middleware.
-
-### Task 8: Frontend
-
-Files:
-
- `web/src/pages/settings/NotificationWebhooksSettings.tsx`
- `web/src/hooks/queries/notification-webhooks.ts`
- form components, status pills, test-result display
-
-Includes:
-
- "Show signing secret once" UX with explicit "I've saved it" confirmation.
- Show secret-rotation flow.
- Last-failure status with admin-level message ("404 Not Found"), not stack traces.
- Test button.
- Per-reason filter checkboxes.
-
-### Task 9: Auto-Disable Notification
-
-When auto-disable fires, create a `notification_deliveries` row with `type = "webhook.auto_disabled"`, including the webhook name and last failure code. The profile sees this in their inbox so a broken webhook doesn't fail silently.
-
-### Task 10: Optional CDN Proxy For Discord Images
-
-Files:
-
- separate repo (e.g., `silo-discord-cdn-proxy`)
- `internal/notifications/webhook_image_signer.go` for issuing short-lived signed URL tokens
-
-Out of scope for v1 unless Discord image rendering is wanted in the first release. v1 ships embeds without images; v1.5 adds the proxy and image URLs.
-
-## Validation Plan
-
- Unit tests for URL validators (HTTPS, private-IP guard, DNS resolution).
- Unit tests for payload builders (Discord shape, generic canonicalization, HMAC determinism).
- Integration test: round-trip a generic webhook against a stubbed receiver that verifies the signature.
- Integration test: Discord embed against `https://discord.com/api/webhooks/.../test-only` (or recorded fixture) — manual verification only since Discord doesn't offer a sandbox.
- Concurrency test: 100 deliveries in parallel; verify retry rows aren't double-counted.
- Auto-disable test: simulate 3 consecutive deliveries returning 404 and verify the webhook is disabled with the correct in-app notification; verify 1-2 isolated 4xx blips do **not** disable it; verify persistent timeouts exhaust the 10-attempt schedule before disabling.
- Outbox recovery test: commit deliveries with `pending` attempt rows, skip the inline dispatcher, and verify the retry worker sends them after the 60s recovery window.
- Manual verification:
-  - Create a Discord webhook URL.
-  - Add it to a profile.
-  - Trigger a release event.
-  - Confirm the embed renders correctly in Discord.
-  - Disable the Discord webhook on Discord's side.
-  - Trigger another event.
-  - Verify the webhook auto-disables after retries.
-  - Verify the profile receives an in-app "webhook auto-disabled" notification.
-
-## Open Questions
-
- **Discord image proxy scope.** Build it in v1, or ship v1 without images and add v1.5? Recommendation: ship without images in v1 — text-only embeds are useful and require no new infra. Add the proxy in v1.5 if user feedback wants images.
- **Slack and Microsoft Teams native types.** Should we add `slack` and `teams` types alongside `discord` and `generic`? Both Slack incoming webhooks and Teams Adaptive Cards have their own JSON shapes. Recommendation: `generic` works for Slack (Slack incoming webhooks accept arbitrary JSON; users can build their own message format with a Workflow). Teams requires Adaptive Card JSON specifically. Defer both to v2 unless concrete user demand emerges.
- **Per-event-type templating.** Some users will want to customize the embed text. Recommendation: defer to v2; v1 fixed shapes ship faster and most users will accept them.
- **Webhook "channels" beyond episode.available.** Should webhook payloads cover other event types (release-aggregated, server announcements)? V1 only fires on `notification.created` for `episode.available`. Other types are forward-compatible via the `event` and `type` fields.
- **Outgoing IP.** Webhook deliveries originate from the user's Silo server IP. Do we need an option to route through a proxy? Recommendation: not v1; document that deliveries come from the server's egress IP.
- **Backpressure.** What happens when a profile's webhook is slow but reachable, blocking delivery for an hour at a time? The 10s timeout caps individual deliveries; bounded worker pool caps fanout concurrency. A single bad webhook shouldn't degrade other webhooks because each delivery runs independently.
@@ -1,54 +0,0 @@
-# Web Push Spec
-
-**Date:** 2026-06-11
-**Status:** Implemented
-**Scope:** Browser push notifications (Push API + VAPID) as a third push platform alongside the deferred APNs/FCM channels.
-**Depends On:**
- [`00-architecture-overview.md`](./00-architecture-overview.md)
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)
-
-## Why Web Push ships before APNs/FCM
-
-The architecture overview deferred mobile push because Apple and Google require pushes to official store builds to be signed by the publisher's credentials, forcing a Silo-operated relay. Web Push has neither problem:
-
- **No accounts, no relay.** The server self-provisions a VAPID keypair on first use. Any standards-compliant browser push service (Chrome, Firefox, Edge, Safari 16+) accepts VAPID-signed requests from any origin.
- **Content-safe by protocol.** Payloads are encrypted end-to-end (RFC 8291, `aes128gcm`) to keys held only by the subscribed browser. The vendor push service relays ciphertext. Unlike the APNs/FCM design, payloads can therefore carry full display content (titles, episode numbers, poster URLs) without violating the self-hosted privacy model — there is no opaque-wake/fetch dance.
-
-The residual leak matches the relay threat model: the push service sees the user server's egress IP, delivery timing, and payload size. It never sees content or identity.
-
-## Data model
-
- `web_push_subscriptions` — profile-scoped browser registrations: `endpoint` (unique; a resubscription from the same browser under a different profile reassigns the row), `p256dh`, `auth`, `device_name`, failure bookkeeping. No FK to profiles (per-user SQLite stores); profile deletion purges in code.
- `web_push_delivery_attempts` — the durable dispatch outbox, mirroring `webhook_delivery_attempts`: `pending` rows enqueued in the fanout transaction, claimed post-commit with a lease, swept by the retry loop after a crash.
-
-## VAPID identity
-
-Generated once and persisted in `server_settings`:
-
- `notifications.web_push.vapid_public_key` — served to clients via the capability endpoint.
- `notifications.web_push.vapid_private_key` — encrypted at rest (`SensitiveSettingKeys`).
-
-The private key is persisted before the public key so a crash between writes regenerates the pair instead of stranding clients with an unusable public key. The pair must never be rotated casually: browsers bind subscriptions to it.
-
-## API surface (profile-scoped)
-
- `GET /api/v1/notifications/capability` — `web_push: { available, public_key }`.
- `POST /api/v1/notifications/web-push/subscriptions` — body is `PushSubscription.toJSON()` plus `device_name`.
- `GET /api/v1/notifications/web-push/subscriptions` — for the settings UI device list.
- `DELETE /api/v1/notifications/web-push/subscriptions/{id}`
- `POST /api/v1/notifications/web-push/unsubscribe` — by endpoint (browsers don't know row IDs).
-
-Subscription endpoints are attacker-controllable URLs the server will POST to, so they pass the same HTTPS + private-destination guard as webhooks, both at registration and at connect time (guarded dialer).
-
-## Delivery semantics
-
- Fanout enqueues one `pending` attempt per enabled subscription of each recipient profile, in the same transaction as the delivery rows. No per-reason filters: profile preferences already gate delivery creation.
- Retry schedule is short (30s/2m/10m/30m, 5 attempts): vendor push services queue messages for offline devices themselves (TTL 12h), so server-side retries only ride out transient push-service errors.
- `404`/`410` from the push service is the protocol's unsubscribe signal: the subscription row is deleted, not retried.
- `notifications.web_push_enabled` is the kill switch (default on).
-
-## Client
-
- `web/public/sw.js` — displays notifications and routes clicks (episode deep link, or the inbox).
- `web/src/lib/webPush.ts` — permission + subscribe/unsubscribe flows.
- Settings → Notifications → "Browser Notifications" — this-browser toggle plus a revocable list of the profile's other subscribed devices.
@@ -1,169 +0,0 @@
-# Notifications v1.5 Roadmap
-
-**Date:** 2026-06-11
-**Status:** Draft (work not started)
-**Scope:** The remaining notification work between the shipped v1 and the deferred v2 push channels. Each item is independent and sized to land as its own PR.
-**Depends On:**
- [`00-architecture-overview.md`](./00-architecture-overview.md)
- [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md) — implemented
- [`04-outbound-webhooks.md`](./04-outbound-webhooks.md) — implemented
- [`05-web-push.md`](./05-web-push.md) — implemented
-
-## Where v1 landed (context for this doc)
-
-Implemented 2026-06-11: the full foundation (availability seeding, release events,
-interest index, fanout worker with burst caps, websocket channel with ticket
-handshake, inbox/sync/preferences/capability APIs, web inbox + badge + settings),
-outbound webhooks (Discord + generic HMAC, SSRF guard, durable outbox, retry +
-auto-disable), Web Push (VAPID self-provisioned, E2E-encrypted payloads, service
-worker), and the shared SMTP core (`internal/mail`, see
-`docs/architecture/email.md`) with an admin Email settings page — but no feature
-consuming email yet.
-
-**Deferred to v2 by explicit decision:** APNs (`02`) and FCM (`03`) — they
-require Silo-operated relay infrastructure and developer accounts. Also v2 per
-the original plans: movie availability, aggregated notifications ("3 new
-episodes"), quiet hours, cross-profile views.
-
---
-
-## 1. Admin settings UI for notification controls
-
-**Why:** every `notifications.*` setting works today but is reachable only
-through the raw admin settings API. Admins should not need `curl` to find the
-kill switches.
-
-**What:** an admin settings page ("Notifications", next to the Email page added
-in v1) exposing:
-
-| Group | Keys |
-|---|---|
-| Kill switches | `notifications.release_events_enabled`, `notifications.fanout_enabled`, `notifications.ui_enabled`, `notifications.webhooks_enabled`, `notifications.web_push_enabled` |
-| Fanout tuning | `notifications.fanout.settle_seconds` (default 30), `notifications.fanout.max_series_burst` (default 3) |
-| Webhook guards | `notifications.webhooks.max_per_profile` (10), `notifications.webhooks.allow_private_destinations` (false; dev only — label it loudly), `notifications.webhooks.deliveries_per_minute_per_profile` (60) |
-| Retention | `notifications.retention.read_days` (90), `notifications.retention.unread_days` (180), `notifications.retention.event_days` (30) |
-
-**Files:** add `web/src/pages/admin-settings/NotificationsAdminSettings.tsx`
-(follow `EmailSettings.tsx` / `useSettingsForm`), register in
-`web/src/pages/admin-settings/AdminSettingsLayout.tsx`. No backend work — all
-keys are live-read.
-
-**Effort:** small (one page, no migrations, no Go changes).
-
---
-
-## 2. Request-fulfilled notifications (`request.fulfilled`)
-
-**Why:** `00-architecture-overview.md` calls this "the most obvious next
-notification type." Users who request media currently learn it arrived by
-checking manually; every delivery channel they configured should tell them.
-
-**Design:** the `notification_deliveries.type` registry is extensible by
-construction — no schema change.
-
- New type `request.fulfilled`. `reason_flags` carries the operational shape
-  (like `webhook.auto_disabled` does), e.g.
-  `{"request_id": "...", "tmdb_id": 123, "media_type": "movie"}` — never the
-  four reason booleans.
- **Hook point:** the request reconciliation service (`internal/mediarequests`)
-  is where a request transitions to available/fulfilled. On that transition,
-  insert a delivery via `DeliveryRepository.InsertOperational` (the path the
-  webhook auto-disable notice already uses) and publish through the system's
-  dispatchers so websocket, web push, and webhooks all fire.
- **Recipient:** the requesting profile (requests are profile-attributed). No
-  `profile_series_interest` involvement — this is a direct, not fanned-out,
-  notification.
- **Webhook enqueue:** operational inserts bypass the fanout outbox, so either
-  (a) extend `InsertOperational` to optionally enqueue per-target attempt rows,
-  or (b) add a small shared "dispatch one delivery durably" helper used by both
-  this and the auto-disable notice. Prefer (b); the auto-disable notice
-  deliberately skips webhooks (loop guard) but request notices should not.
- **Per-reason preferences:** add nothing in v1.5. The profile master toggle
-  (`notification_preferences.enabled`) gates it; a dedicated
-  `notify_requests` flag can come later if users ask.
- **Clients:** the web inbox/toast/web-push renderers fall back to a generic
-  card for unknown types; add a `request.fulfilled` case with the media title,
-  poster, and a deep link to the item (or the request page until matched).
-
-**Effort:** medium-small. The delivery/dispatch machinery all exists.
-
---
-
-## 3. Email digest channel
-
-**Why:** first real consumer of `internal/mail`; reaches users who don't keep a
-browser open and have no webhook.
-
-**Open design decisions (resolve before building):**
-
- **Account-level, not profile-level.** Email addresses live on `users`;
-  profiles have none. A digest therefore aggregates across the account's
-  profiles (group by profile inside the email body).
- **Digest, not per-episode.** Per-episode email is spam at hundreds-of-users
-  scale and duplicates the realtime channels. Recommend: opt-in daily digest of
-  unread deliveries, sent by a taskmanager task (reuse the checkpointed
-  iteration pattern from the interest backfill), with a per-user
-  enable + cadence setting.
- **Unsubscribe / preference surface:** account settings, not profile
-  notification preferences.
-
-**Files (sketch):** `internal/notifications/email_digest.go` (compose from
-`DeliveryRepository`, send via `mail.Sender`, branch on
-`mail.ErrNotConfigured`), a `taskmanager` task, a small user-settings surface.
-
-**Effort:** medium. Blocked on the design decisions above, not on plumbing.
-
---
-
-## 4. Native client adoption (no push required)
-
-**Why:** the Android and Apple apps gain a full notification experience today —
-APNs/FCM only add closed-app wake-ups later.
-
-Server surfaces ready for clients (`silo-android`, `silo-apple`):
-
- `GET /api/v1/notifications` + `unread-count` + read endpoints — inbox UI.
- `GET /api/v1/notifications/sync` — opaque forward cursor for
-  reconnect/foreground catch-up (this is also the wake-fetch endpoint the v2
-  push specs assume, so client work done now is reused).
- `POST /api/v1/events/ws-ticket` + `ticket` query param on `/api/v1/events/ws`,
-  `notifications` channel — realtime while the app is open. Snapshot on
-  subscribe hydrates recent unread.
- `GET /api/v1/notifications/capability` — drive setup UI from this, never from
-  admin settings.
- `GET/PUT /api/v1/notifications/preferences` — per-profile reason toggles.
-
-**Effort:** client-repo work; the server side is done. Coordinate per the
-multi-repo guidance in the repo root `CLAUDE.md`.
-
---
-
-## 5. Hardening backlog (defer freely)
-
- **DB-backed integration tests** from the `01` verification plan: idempotent
-  availability/event inserts, cross-library delivery dedupe, per-series burst
-  cap, outbox recovery (pending rows with no dispatch → retry worker sends),
-  multi-node claim safety. The behaviors shipped and were exercised manually on
-  dev; they are not yet pinned by automated tests because the repo has no
-  Postgres test harness for this package.
- **Metrics:** `01` names Prometheus-style counters
-  (`release_events_suppressed_total`, etc.); v1 ships them as structured log
-  fields. Revisit when the repo grows a metrics registry — keep the names.
- **Discord embed images** via the `media.discord-cdn-proxy` service
-  (see `04`, "v1.5 payload"). Requires a new Silo-operated repo/service plus
-  `webhook_image_signer.go`; v1 deliberately ships text-only embeds so the
-  user's server origin never reaches Discord.
- **Webhook delivery history endpoint:** `webhook_delivery_attempts` already
-  has the listing index; a `GET /api/v1/notifications/webhooks/{id}/attempts`
-  endpoint + UI table would make failures self-diagnosable beyond the
-  last-failure summary.
-
---
-
-## Suggested order
-
-1. Admin settings UI (#1) — smallest, completes operability.
-2. Request-fulfilled (#2) — highest product value per effort.
-3. Webhook history endpoint (#5, last bullet) — pairs naturally with #1.
-4. Email digest (#3) — after its design decisions are made.
-5. Native clients (#4) — parallel track in the client repos.
@@ -1,109 +0,0 @@
-# Notifications: Email Channel
-
-**Date:** 2026-06-11
-**Status:** Implemented (written post-implementation)
-**Scope:** Item 3 of [`06-v1.5-roadmap.md`](./06-v1.5-roadmap.md) — the first real consumer of the shared SMTP core (`internal/mail`, `docs/architecture/email.md`).
-**Depends On:** [`00-architecture-overview.md`](./00-architecture-overview.md), [`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)
-
-## Decisions (resolving the roadmap's open questions)
-
- **Account-level, as planned.** Email addresses live on `users`; one mode
-  covers every profile on the account and one email aggregates across them.
- **Per-episode AND digest, not digest-only.** The roadmap recommended
-  digest-only; product direction chose to offer per-episode alerts too, gated
-  by an admin allowance (`notifications.email.allow_per_episode`). When the
-  admin disallows it, accounts set to per-episode are **coerced to the daily
-  digest** rather than silenced.
- **Interest-scoped by construction.** Email consumes existing
-  `notification_deliveries` rows, which the fanout only creates for profiles
-  with series interest (favorites, watchlist, continue-watching, next-up) and
-  for direct notices (`request.fulfilled`, `webhook.auto_disabled`). The
-  channel adds no targeting of its own — it is never "all new content".
- **Opt-in, default off.** Users enable it per account in Settings →
-  Notifications; enabling initializes the watermark to now so history never
-  floods a fresh opt-in.
-
-## Architecture: watermark sweep, not a third outbox
-
-Webhooks and web push use per-target outbox attempt rows. Email deliberately
-does not:
-
- Deliveries already carry `user_id`, and an account whose profiles follow the
-  same series gets one row per profile — a per-row outbox would email the same
-  episode several times. The sweep collapses them (dedupe by `episode_id`, by
-  `request_id` for requests).
- A per-account watermark over `(created_at, id)` that advances **only after a
-  successful SMTP send** gives durability for free: a crash or SMTP outage
-  re-sends on the next pass instead of dropping.
- Both cadences are the same mechanism: per-episode sweeps every minute (and
-  is nudged by the dispatcher seconds after fanout commits); the digest is the
-  same sweep gated on "today's send hour passed and not yet stamped today".
-
-State lives in `notification_email_prefs` (`migrations/sql/`,
-`email_notification_channel`): mode, watermark, `last_digest_at`, and failure
-backoff counters (`last_attempt_at`, `consecutive_failures`; 1m doubling,
-capped at 6h). No FK to `users` per the notification-tables rule; deleted or
-disabled accounts drop out of the recipient join. A supporting index
-`notification_deliveries_user_created_idx (user_id, created_at, id)` serves
-the sweep.
-
-**Multi-node safety:** each account is processed inside one transaction that
-claims the prefs row `FOR UPDATE SKIP LOCKED`, re-derives eligibility from the
-locked row (mode flips and another node's digest stamp are both re-checked),
-sends, then commits the watermark/stamp. Failed sends commit only the backoff
-counters. `mail.ErrNotConfigured` aborts the whole pass; three consecutive
-send failures end it early (SMTP trouble is global, not per-recipient).
-
-**Flood bounds:** one email renders at most 30 lines (`…and N more in your
-Silo inbox`), one pass fetches at most 200 rows per account, and upstream the
-per-series burst cap already limits fanout volume. Digest emails include only
-rows still unread at compose time; the watermark passes read rows silently.
-
-## Files
-
-| Piece | Location |
-|---|---|
-| Modes, prefs repo (`notification_email_prefs`) | `internal/notifications/email_prefs_repo.go` |
-| Worker, dispatcher nudge, System service methods | `internal/notifications/email_digest.go` |
-| Subject/text/HTML rendering | `internal/notifications/email_compose.go` |
-| Account sweep query | `DeliveryRepository.ListForUserSince` (`internal/notifications/delivery_repo.go`) |
-| Settings accessors | `internal/notifications/settings.go` |
-| API handlers | `internal/api/handlers/notifications_email.go` (+ capability in `notifications.go`) |
-| Web UI (user) | `EmailSection` in `web/src/pages/settings/NotificationsSettings.tsx` |
-| Web UI (admin) | Email group in `web/src/pages/admin-settings/NotificationsAdminSettings.tsx` |
-| Logic tests | `internal/notifications/email_logic_test.go` |
-
-The worker is wired in `notifications.NewSystem` (new `mail.Sender` parameter,
-passed from `cmd/silo/main.go`); its dispatcher joins the `MultiDispatcher`,
-so operational deliveries (`request.fulfilled`, `webhook.auto_disabled`) nudge
-it exactly like fanout rows do.
-
-## Settings
-
-| Key | Default | Meaning |
-|---|---|---|
-| `notifications.email_enabled` | `true` | Channel kill switch (availability still requires SMTP configured via `email.*`) |
-| `notifications.email.allow_per_episode` | `true` | Admin allowance for the per-episode cadence |
-| `notifications.email.digest_hour` | `8` | Hour (0–23, server-local) daily digests go out |
-| `notifications.email.external_url` | empty | Public base URL for deep links in emails; empty sends link-free emails (the server origin is never leaked implicitly) |
-
-## API
-
- `GET /api/v1/notifications/email-preferences` → `{"mode": "off" | "per_episode" | "daily_digest"}`
- `PUT /api/v1/notifications/email-preferences` `{"mode": ...}` — 400 codes:
-  `bad_request` (unknown mode), `not_allowed` (per-episode disallowed),
-  `no_email` (account has no address). Any profile on the account may set it.
- `GET /api/v1/notifications/capability` gained
-  `"email": {"available", "modes", "digest_hour"}`; clients gate setup UI on
-  it as usual. `available` requires the kill switch on **and**
-  `mail.Sender.Enabled()` — never read `email.*` settings directly.
-
-## Deliberately not in v1
-
- Posters/images in emails (would require externally reachable presigned URLs).
- `List-Unsubscribe` headers / tokenized unsubscribe endpoint (self-hosted,
-  opt-in; revisit if servers grow beyond household scale).
- Per-user digest hour (admin-global for now).
- DB-backed integration tests for the sweep (same Postgres-harness gap as the
-  rest of `01`'s verification backlog; pure logic is covered by
-  `email_logic_test.go`).
@@ -1,88 +0,0 @@
-# Silo Notifications — Design Index
-
-> **Provenance:** Imported 2026-06-11 from `ContinuumApp/continuum` (`docs/superpowers/plans/notifications/` at `04aa9266`), written 2026-04-28 before the project was renamed to Silo. Reviewed and amended 2026-06-11: product naming and all wire contracts (payload keys, headers, settings enums, localization keys, provisional domains/repo names) are normalized to Silo. Bundle topics, Android package names, and Firebase project IDs intentionally keep their current official client-build values (`com.continuum.app.*`, `continuum-prod-android`) — they are allowlist *config*, not part of this design's contract, and the shipped client builds still use them. Relay/proxy hostnames (`relay.silo.app`, `media.discord-cdn-proxy.silo.app`) are provisional. See "2026-06-11 review amendments" below for the design-level changes made during review.
-
-This folder collects the design work for Silo's notification system, covering durable in-app inbox + websocket realtime, Apple Push (APNs), Android Push (FCM), and outbound webhooks (Discord-native + generic).
-
-A self-contained visual summary of the design decisions (who/what/where/why per decision, pipeline, trust model) lives at [`design-decisions.html`](./design-decisions.html) — open it in any browser; no build or network access required.
-
-## Reading order
-
-1. **[`00-architecture-overview.md`](./00-architecture-overview.md)** — Cross-cutting overview. Read this first. Explains the channel model, fanout pipeline, preference shape, threat model, and addressing model (why a relay is required for mobile push). Links into the per-channel specs.
-2. **[`01-release-events-and-inbox.md`](./01-release-events-and-inbox.md)** — Foundation. Durable `release_events` -> per-profile `notification_deliveries` fanout, the in-app inbox API, the websocket channel, and per-profile preferences. Vendor-agnostic; nothing else works without this.
-3. **[`02-apns-relay.md`](./02-apns-relay.md)** — Apple push. Privacy-preserving design with three provider modes (`off` / `silo_relay` / `custom_apns`).
-4. **[`03-fcm-relay.md`](./03-fcm-relay.md)** — Android push. Mirrors the APNs spec with `off` / `silo_relay` / `custom_fcm` modes using FCM v1 (OAuth2 service-account JSON).
-5. **[`04-outbound-webhooks.md`](./04-outbound-webhooks.md)** — Profile-scoped outbound webhooks. Native Discord embed type and generic JSON+HMAC type. Content included by default because the profile chose the destination.
-
-## Status
-
-| Doc | Status |
-|---|---|
-| 00-architecture-overview | Draft (amended 2026-06-11) |
-| 01-release-events-and-inbox | Draft (refined, amended 2026-06-11) |
-| 02-apns-relay | Draft (refined, amended 2026-06-11) |
-| 03-fcm-relay | Draft (amended 2026-06-11) |
-| 04-outbound-webhooks | Draft (amended 2026-06-11) |
-
-Nothing in this folder has been implemented. The codebase has zero notification-related code beyond the existing realtime events hub (`internal/events/`, with the operational publisher wrapper at `internal/notifications/hub.go`), which publishes catalog/jobs events and is unrelated to the user-facing notification system designed here.
-
-## 2026-06-11 review amendments
-
-A scaling and privacy review (self-hosted servers with hundreds of users) resolved four design-level gaps. The detailed designs live in the per-doc sections; this is the index:
-
-1. **Back-catalog seeding + burst suppression** (`01`). First scan of a new library and the feature-enable backfill seed `episode_availability` *without* creating release events; bulk additions to existing libraries are bounded by a per-series fanout burst cap. Without this, importing a 200-episode back-catalog of a popular series would generate tens of thousands of deliveries and pushes in one scan.
-2. **Durable dispatch outbox** (`01`, referenced by `02`/`03`/`04`). The fanout transaction that inserts `notification_deliveries` also inserts `pending` per-target attempt rows for the push and webhook channels. A crash between delivery commit and dispatch no longer silently loses pushes/webhooks; recovery workers drain stale pending rows.
-3. **Cross-library episode dedupe** (`01`). Media items in Silo are catalog-level (`media_item_libraries` junction), so the same episode landing in "TV" and "TV 4K" shares one `episode_id`. A partial unique index on `(profile_id, episode_id)` guarantees at most one `episode.available` delivery per profile per episode across libraries.
-4. **Mobile wake-fetch endpoints defined in the foundation** (`01`). `GET /api/v1/notifications/sync` (forward cursor) and `GET /api/v1/notifications/{id}` — previously referenced by `02`/`03` but defined nowhere.
-
-Smaller amendments: relay threat models now list the server's egress IP as residual leakage (`00`/`02`/`03`); `collapse_id`/`collapse_key` derivation is specified as per-server-keyed HMAC so the relay can't read series identity out of it (`02`/`03`); the websocket handshake uses a short-lived single-use ticket instead of a long-lived profile token in the query string (`00`/`01`); client-side relay pacing (`02`/`03`); webhook auto-disable requires 3 consecutive non-retryable 4xx instead of 1 (`04`); SSRF deny list gains `198.18.0.0/15` and `192.88.99.0/24` (`04`); interest recompute fires on watch-state transitions, not every progress tick (`01`); profile-deletion cascades and `release_events.dedupe_key` composition are specified (`01`); migration tasks now follow the repo's timestamped Goose convention (`01`).
-
-## Scope summary
-
-**In scope (v1):**
-
- Episode-availability notifications (a new episode lands in a library and is relevant to a profile via favorites / watchlist / continue-watching / next-up).
- Durable per-profile inbox with read/unread state.
- Realtime websocket delivery for connected clients.
- Apple Push via opt-in Silo-operated relay or admin-supplied custom APNs credentials.
- Android Push via opt-in Silo-operated relay or admin-supplied custom FCM credentials.
- Outbound webhooks per profile, with native Discord embed rendering and generic JSON+HMAC.
-
-**Out of scope (v1):**
-
- Movie release notifications (the trigger surface — favoriting a movie that doesn't yet exist — isn't a flow Silo supports).
- Email, SMS, or other delivery channels.
- Browser Web Push (PWA) notifications.
- Cross-profile administrator dashboards.
- Marketing or promotional notifications.
- Third-party ingest events (Plex/Sonarr/Radarr) as notification sources.
-
-## Cross-cutting decisions
-
-These hold across all channels and were resolved during spec review:
-
- **Episode-only triggers in v1.** Confirmed: there's no UX path for a user to favorite/watchlist a movie before it exists in their library.
- **Per-profile webhooks include content by default.** The profile chose the destination; trust is implicit. Discord-native embeds show series and episode details; generic webhooks include the same.
- **Mobile push payloads stay opaque by default.** APNs and FCM relay paths never see notification content. The app fetches metadata from the user's own server after wake. No badge counts in v1 (deferred to user-opt-in in v2).
- **Preference shape is flat:** per-profile reason flags (favorites / watchlist / continue-watching / next-up) plus a master enable toggle on each push device and each webhook. Not a per-channel × per-reason matrix.
- **Per-platform APNs topics.** iOS, tvOS, and macOS each get their own bundle topic. Single-build collapse is a v2 concern.
- **Stateless relay v1.** No stored token aliases. Add only if abuse/rate-limit pressure justifies it.
- **Relay services live in their own repos.** This folder defines the contracts the user-server side implements; the actual relay deployment (APNs / FCM) is a separate operational repo.
- **Back-catalog never floods.** Initial library scans and the feature-enable backfill seed availability silently; per-series burst caps bound fanout for bulk additions (see `01`).
- **One delivery per episode per profile, across libraries.** Dual-quality library setups (e.g., "TV" + "TV 4K") do not double-notify.
- **Dispatch enqueue is durable (outbox).** Push and webhook sends survive a crash between delivery commit and dispatch; the websocket channel stays best-effort because the inbox snapshot covers reconnect.
-
-## Phasing
-
-Implementation should land in this order, gated by feature flags so partial deploys are safe:
-
-1. Schema (Phase 1 of `01-release-events-and-inbox.md`).
-2. `profile_series_interest` updaters and backfill task (no fanout yet).
-3. Availability seeding backfill, then release event creation (still no fanout). Seeding **must** complete before release events are enabled, or the first scan after enablement emits an event per back-catalog episode.
-4. In-app fanout worker, websocket channel, inbox APIs.
-5. Frontend inbox + badge + preference UI.
-6. Outbound webhooks (no new infra; can ship before mobile push).
-7. APNs relay + custom APNs.
-8. FCM relay + custom FCM.
-
-The relay services (steps 7-8) require Silo to provision Apple Developer + Firebase developer accounts and host the relay services. Steps 1-6 require no new external infrastructure.
@@ -1,281 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Silo notifications — design decisions</title>
-<style>
-:root {
-  color-scheme: light dark;
-  --background: #f4f4f6;
-  --card: #ffffff;
-  --border: #d8d8de;
-  --fg: #1a1a1e;
-  --fg-2: #3a3a42;
-  --muted: #63636b;
-  --chip: #e8e8ec;
-  --green: #22c55e;
-  --purple: #a855f7;
-  --amber: #f59e0b;
-}
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: #141417;
-    --card: #1c1c20;
-    --border: #28282e;
-    --fg: #e8e8ec;
-    --fg-2: #d0d0d6;
-    --muted: #9696a0;
-    --chip: #232328;
-    --green: #81c995;
-    --purple: #c78dbd;
-    --amber: #e8a87c;
-  }
-}
-* { box-sizing: border-box; }
-body {
-  margin: 0;
-  background: var(--background);
-  color: var(--fg);
-  font-family: "Outfit", ui-sans-serif, system-ui, "Helvetica Neue", sans-serif;
-  font-size: 14px;
-  line-height: 1.6;
-}
-main { max-width: 880px; margin: 0 auto; padding: 52px 28px 48px; }
-h1 { font-size: 24px; font-weight: 600; margin: 0 0 6px; letter-spacing: -0.01em; }
-.sub { color: var(--muted); font-size: 14px; margin: 0 0 8px; }
-.sub code { font-size: 12.5px; }
-h2 {
-  font-size: 17px; font-weight: 600; margin: 44px 0 14px;
-  padding-bottom: 8px; border-bottom: 1px solid var(--border);
-}
-p { color: var(--fg-2); margin: 0 0 12px; max-width: 72ch; }
-code {
-  font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
-  font-size: 12.5px; background: var(--chip); border-radius: 4px; padding: 1px 5px;
-}
-.legend { display: flex; flex-wrap: wrap; gap: 8px 22px; margin: 10px 0 0; font-size: 13px; color: var(--muted); }
-.legend span { display: inline-flex; align-items: center; gap: 7px; }
-.sw { width: 10px; height: 10px; border-radius: 2px; display: inline-block; }
-table { width: 100%; border-collapse: collapse; margin: 4px 0 0; }
-th { text-align: left; font-size: 13px; font-weight: 600; color: var(--fg); padding: 8px 14px 8px 0; border-bottom: 1px solid var(--border); }
-td { font-size: 13.5px; color: var(--fg-2); padding: 9px 14px 9px 0; border-bottom: 1px solid var(--border); vertical-align: top; }
-td:first-child, th:first-child { white-space: nowrap; }
-.grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(340px, 1fr)); gap: 14px; }
-.card {
-  background: var(--card); border: 1px solid var(--border);
-  border-radius: 12px; padding: 16px 18px;
-}
-.card h3 { font-size: 14.5px; font-weight: 600; margin: 0 0 10px; }
-.kv { display: grid; grid-template-columns: 54px 1fr; row-gap: 7px; column-gap: 10px; }
-.kv dt { font-size: 13px; font-weight: 500; color: var(--muted); margin: 0; }
-.kv dd { font-size: 13.5px; color: var(--fg-2); margin: 0; line-height: 1.55; }
-.svgwrap { border: 1px solid var(--border); border-radius: 12px; background: var(--card); padding: 18px 14px 10px; }
-svg text { font-family: "Outfit", ui-sans-serif, system-ui, sans-serif; }
-.bt { font-size: 13px; font-weight: 600; fill: var(--fg); }
-.bm { font-size: 12.5px; font-weight: 600; fill: var(--fg); font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; }
-.bs { font-size: 11.5px; fill: var(--muted); }
-.bx { fill: var(--card); stroke: var(--border); }
-ul.docs { padding-left: 20px; margin: 0; color: var(--fg-2); }
-ul.docs li { margin: 4px 0; }
-footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
-</style>
-</head>
-<body>
-<main>
-
-<h1>Silo notifications — design decisions</h1>
-<p class="sub">Episode-availability notifications for a self-hosted, privacy-focused media server, designed to hold up with hundreds of users on one install.</p>
-<p class="sub">Companion to the specs in <code>docs/superpowers/plans/notifications/</code> · drafts amended 2026-06-11</p>
-
-<h2>How a notification flows</h2>
-<p>Ingest records availability, a worker fans out to interested profiles, and a durable inbox row is written before any channel fires. Every channel below the row is a transport, never a source of truth.</p>
-<div class="svgwrap">
-<svg width="100%" viewBox="0 0 760 452" role="img" aria-label="Pipeline from library scan to release events to the fanout worker, into a durable notification_deliveries row, which dispatches to websocket, Apple push, Android push, and webhook channels after commit. The push channels continue through the opt-in Silo push relay, which sees only a device token and opaque IDs, then through APNs or FCM, and the woken device fetches notification details from the user's own server. A dashed path shows custom credentials skipping the relay.">
-<defs>
-<marker id="a" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
-<path d="M2 1L8 5L2 9" fill="none" stroke="var(--muted)" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
-</marker>
-</defs>
-<rect class="bx" x="20" y="24" width="190" height="52" rx="8"/>
-<text class="bt" x="115" y="45" text-anchor="middle">Scan and ingest</text>
-<text class="bs" x="115" y="63" text-anchor="middle">new episode lands</text>
-<rect class="bx" x="280" y="24" width="190" height="52" rx="8"/>
-<text class="bm" x="375" y="45" text-anchor="middle">release_events</text>
-<text class="bs" x="375" y="63" text-anchor="middle">one row per episode</text>
-<rect class="bx" x="540" y="24" width="190" height="52" rx="8"/>
-<text class="bt" x="635" y="45" text-anchor="middle">Fanout worker</text>
-<text class="bs" x="635" y="63" text-anchor="middle">burst caps + eligibility</text>
-<line x1="214" y1="50" x2="274" y2="50" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<line x1="474" y1="50" x2="534" y2="50" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<path d="M635 76 L635 98 L380 98 L380 114" fill="none" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<rect class="bx" x="250" y="120" width="260" height="52" rx="8"/>
-<text class="bm" x="380" y="141" text-anchor="middle">notification_deliveries</text>
-<text class="bs" x="380" y="159" text-anchor="middle">durable row, dispatched after commit</text>
-<line x1="380" y1="174" x2="97" y2="206" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<line x1="380" y1="174" x2="287" y2="206" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<line x1="380" y1="174" x2="473" y2="206" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<line x1="380" y1="174" x2="663" y2="206" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<rect class="bx" x="10" y="212" width="170" height="52" rx="8" stroke="var(--green)"/>
-<text class="bt" x="95" y="233" text-anchor="middle">Websocket</text>
-<text class="bs" x="95" y="251" text-anchor="middle">full content</text>
-<rect class="bx" x="200" y="212" width="170" height="52" rx="8" stroke="var(--purple)"/>
-<text class="bt" x="285" y="233" text-anchor="middle">Apple push</text>
-<text class="bs" x="285" y="251" text-anchor="middle">opaque wake</text>
-<rect class="bx" x="390" y="212" width="170" height="52" rx="8" stroke="var(--purple)"/>
-<text class="bt" x="475" y="233" text-anchor="middle">Android push</text>
-<text class="bs" x="475" y="251" text-anchor="middle">opaque wake</text>
-<rect class="bx" x="580" y="212" width="170" height="52" rx="8" stroke="var(--amber)"/>
-<text class="bt" x="665" y="233" text-anchor="middle">Webhooks</text>
-<text class="bs" x="665" y="251" text-anchor="middle">your chosen URL</text>
-<line x1="285" y1="268" x2="345" y2="292" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<line x1="475" y1="268" x2="415" y2="292" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<rect class="bx" x="290" y="296" width="180" height="52" rx="8" stroke="var(--purple)"/>
-<text class="bt" x="380" y="317" text-anchor="middle">Silo push relay</text>
-<text class="bs" x="380" y="335" text-anchor="middle">sees token + opaque IDs</text>
-<line x1="380" y1="352" x2="380" y2="380" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<path d="M230 268 L230 410 L284 410" fill="none" stroke="var(--muted)" stroke-width="1" stroke-dasharray="4 4" marker-end="url(#a)"/>
-<text class="bs" x="222" y="352" text-anchor="end">custom credentials</text>
-<text class="bs" x="222" y="368" text-anchor="end">skip the relay</text>
-<rect class="bx" x="290" y="384" width="180" height="52" rx="8" stroke="var(--purple)"/>
-<text class="bt" x="380" y="405" text-anchor="middle">APNs / FCM</text>
-<text class="bs" x="380" y="423" text-anchor="middle">deliver the generic wake</text>
-<line x1="474" y1="410" x2="536" y2="410" stroke="var(--muted)" stroke-width="1" marker-end="url(#a)"/>
-<rect class="bx" x="540" y="384" width="190" height="52" rx="8" stroke="var(--green)"/>
-<text class="bt" x="635" y="405" text-anchor="middle">Device wakes</text>
-<text class="bs" x="635" y="423" text-anchor="middle">fetches details from home</text>
-</svg>
-<div class="legend" style="padding: 8px 6px 8px;">
-<span><i class="sw" style="background: var(--green);"></i>content stays in Silo</span>
-<span><i class="sw" style="background: var(--purple);"></i>opaque wake only, device fetches from home</span>
-<span><i class="sw" style="background: var(--amber);"></i>full content to a destination the profile chose</span>
-</div>
-</div>
-
-<h2>Trust model</h2>
-<table>
-<thead><tr><th>Channel</th><th>Who sees content</th><th>Why that's acceptable</th></tr></thead>
-<tbody>
-<tr><td><i class="sw" style="background: var(--green); margin-right: 8px;"></i>Inbox + websocket</td><td>Only the user's own server and signed-in clients</td><td>Same auth boundary as the rest of Silo</td></tr>
-<tr><td><i class="sw" style="background: var(--purple); margin-right: 8px;"></i>Apple / Android push</td><td>Nobody — relay and Apple/Google see a device token, timestamps, and opaque IDs</td><td>The device fetches real content from the user's server after waking</td></tr>
-<tr><td><i class="sw" style="background: var(--amber); margin-right: 8px;"></i>Webhooks</td><td>The destination operator (e.g., Discord)</td><td>The profile pasted that URL; consent is explicit</td></tr>
-</tbody>
-</table>
-
-<h2>Foundation</h2>
-<div class="grid">
-<div class="card">
-<h3>Durable inbox is the source of truth</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Every profile on the server</dd>
-<dt>What</dt><dd>One delivery row per event; every channel is just a transport on top</dd>
-<dt>Where</dt><dd>The server's own PostgreSQL</dd>
-<dt>Why</dt><dd>Transports fail — the row survives, so reconnect or refresh always recovers</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Preferences are flat, not a matrix</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Profiles tuning what they hear about</dd>
-<dt>What</dt><dd>Four reason toggles plus a master switch; per-device and per-webhook filters can only narrow further</dd>
-<dt>Where</dt><dd>Hard gate at fanout, extra filters at dispatch</dd>
-<dt>Why</dt><dd>A per-channel by per-reason grid is unexplainable in UI and impossible to debug</dd>
-</dl>
-</div>
-</div>
-
-<h2>Privacy boundaries</h2>
-<div class="grid">
-<div class="card">
-<h3>Opaque push through a hosted relay</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Admins who opt in; official store app builds</dd>
-<dt>What</dt><dd>The relay holds the Apple and Google signing credentials and forwards a device token plus opaque IDs only</dd>
-<dt>Where</dt><dd>Silo-operated service in its own repo, stateless on the request path</dd>
-<dt>Why</dt><dd>Only the publisher's credentials can wake store builds; content never leaves the server — the device fetches details from home after waking</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Custom credentials escape hatch</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Power users and forks shipping their own signed app builds</dd>
-<dt>What</dt><dd><code>custom_apns</code> / <code>custom_fcm</code> send straight to Apple or Google with the exact same minimal payload</dd>
-<dt>Where</dt><dd>Entirely on the user's server</dd>
-<dt>Why</dt><dd>Zero Silo infrastructure in the path, without loosening the privacy contract</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Profiles, not accounts, are the unit</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Households sharing one login across several profiles</dd>
-<dt>What</dt><dd>Preferences, devices, webhooks, inbox rows, and websocket bindings are all profile-keyed</dd>
-<dt>Where</dt><dd>Every table, API route, and event envelope</dd>
-<dt>Why</dt><dd>A kid's profile and a parent's profile must not see each other's activity</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Webhooks carry full content, by choice</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Each profile, up to 10 destinations</dd>
-<dt>What</dt><dd>Discord embeds or HMAC-signed JSON with series and episode details</dd>
-<dt>Where</dt><dd>Direct HTTPS from the server to the URL the profile pasted</dd>
-<dt>Why</dt><dd>Choosing the destination is the consent; HTTPS-only, the SSRF deny list, and no-server-origin rules stay mandatory</dd>
-</dl>
-</div>
-</div>
-
-<h2>Scale and reliability</h2>
-<div class="grid">
-<div class="card">
-<h3>Fanout reads a compact interest index</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Servers with hundreds of users, roughly 1,000 profiles</dd>
-<dt>What</dt><dd><code>profile_series_interest</code> keyed by library and series, updated on favorite, watchlist, and watch transitions</dd>
-<dt>Where</dt><dd>Written at interaction time, read once per release event</dd>
-<dt>Why</dt><dd>Cost scales with profiles interested in one series, not with a million-episode catalog</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Back-catalog imports never flood</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Anyone adding a new library or a full season pack</dd>
-<dt>What</dt><dd>First scans seed availability silently; bulk additions cap at 3 notifications per series per scan</dd>
-<dt>Where</dt><dd>Scanner seeding plus the fanout worker burst cap</dd>
-<dt>Why</dt><dd>One 200-episode import with 300 interested profiles would otherwise mean about 60,000 pushes in a single scan</dd>
-</dl>
-</div>
-<div class="card">
-<h3>Dispatch enqueue is durable (outbox)</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Operators who care what a crash costs</dd>
-<dt>What</dt><dd>Pending push and webhook attempt rows commit in the same transaction as the inbox row</dd>
-<dt>Where</dt><dd>The fanout transaction; recovery workers sweep stale rows</dd>
-<dt>Why</dt><dd>A crash between commit and dispatch delays sends instead of silently losing them</dd>
-</dl>
-</div>
-<div class="card">
-<h3>One delivery per episode, across libraries</h3>
-<dl class="kv">
-<dt>Who</dt><dd>Dual-quality setups like TV plus TV 4K</dd>
-<dt>What</dt><dd>A partial unique index on profile and episode spans libraries; the first event processed wins</dd>
-<dt>Where</dt><dd>The <code>notification_deliveries</code> schema</dd>
-<dt>Why</dt><dd>Media items are catalog-level in Silo, so the same episode landing twice must not notify twice</dd>
-</dl>
-</div>
-</div>
-
-<h2>Source documents</h2>
-<ul class="docs">
-<li><code>00-architecture-overview.md</code> — channel model, fanout pipeline, threat model, relay addressing</li>
-<li><code>01-release-events-and-inbox.md</code> — durable inbox, fanout worker, seeding and burst suppression, sync API</li>
-<li><code>02-apns-relay.md</code> — Apple push: hosted relay and custom APNs</li>
-<li><code>03-fcm-relay.md</code> — Android push: hosted relay and custom FCM</li>
-<li><code>04-outbound-webhooks.md</code> — Discord and generic JSON+HMAC webhooks</li>
-<li><code>README.md</code> — reading order, status, and the 2026-06-11 amendment index</li>
-</ul>
-
-<footer>Generated 2026-06-11 from the amended notification specs. Commands and paths assume the repository root is the cwd.</footer>
-
-</main>
-</body>
-</html>
@@ -1,967 +0,0 @@
-# Silo Push Relay — Engineering Spec
-
-**Date:** 2026-06-13
-**Status:** Draft (implementation-grade)
-**Service:** `silo-push-relay` (provisional repo name; the relay code lives in a **separate repository**)
-**Provisional hostname:** `relay.silo.app`
-**Stack:** Go 1.25+, PostgreSQL, Redis
-
-**Provenance / source contracts (read these first):**
-
- [`../00-architecture-overview.md`](../00-architecture-overview.md) — cross-cutting design; "Mobile push: why a relay is necessary", addressing-flow walkthrough, mode terminology, cross-channel threat model.
- [`../02-apns-relay.md`](../02-apns-relay.md) — **the external APNs relay contract** (`POST /v1/apple/send`): request/response/validation, relay-built payloads, headers, error handling. The self-hosted Silo server is already designed against this; the relay is its counterpart and must honor it exactly.
- [`../03-fcm-relay.md`](../03-fcm-relay.md) — **the external FCM relay contract** (`POST /v1/fcm/send`): request/response/validation, relay-built data-only payloads, Android config, error handling.
- [`./02-apns-fcm-2026-reference.md`](./02-apns-fcm-2026-reference.md) — the 2026-current Apple/Google/Go reference this service is built on. Where the older contract docs (authored 2026-04) glossed an upstream-provider mechanic, **this reference wins for the upstream side**; the **external relay contract from 02/03 is never changed** — reconciliations are called out explicitly in §5.2 (FCM upstream field casing), §6.2 (sandbox host), §6.4 (APNs error mapping), and §7.5.
-
-> **Commands assume the repository root is the cwd.** No local absolute filesystem paths or transient worktree IDs appear in this document; all repo references are repository-relative.
-
---
-
-## 1. Title, Provenance, Status, Scope
-
-### 1.1 What this service is
-
-`silo-push-relay` is a small, **stateless-on-the-request-path** HTTP service that:
-
-1. Holds the official Silo Apple (`.p8` APNs auth key) and Google (Firebase service-account JSON) push credentials.
-2. Accepts authenticated, **opaque, content-free** push requests from opted-in self-hosted Silo servers on two endpoints: `POST /v1/apple/send` and `POST /v1/fcm/send`.
-3. Builds a fixed, generic APNs / FCM payload from those opaque fields and forwards it to APNs / FCM on the caller's behalf.
-4. Maps the upstream provider response back to a narrow caller-facing result.
-
-It is the **server counterpart** to the relay-client integration in `02-apns-relay.md` and `03-fcm-relay.md`. Those two documents define the wire contract from the self-hosted Silo server's perspective; this document specifies the service that answers it. **The external request/response contract in 02/03 is authoritative and is reproduced here byte-for-byte; this spec adds the server-internal design (upstream clients, storage, auth, rate limiting, idempotency, ops) that 02/03 deliberately left to "a separate repo".**
-
-### 1.2 What this service is NOT
-
- It is **not** a Silo media server, and it shares no database, auth system, or deployment with `silo-server`.
- It is **not** a general-purpose push gateway: it accepts only the narrow JSON shape in §5; it never accepts a free-form APNs/FCM payload, title, body, or media identifier.
- It is **not** an addressing service. Apple and Google do the addressing from the device token. The relay never resolves a token to a user, profile, device-to-user mapping, or server.
- It does **not** store notification content, user/profile identity, server URLs, or token→user aliases (v1 is stateless on the request path; see `02-apns-relay.md` "Relay statefulness: stateless v1").
- It is **not** in the `custom_apns` / `custom_fcm` path. When a self-hosted admin configures their own credentials, the Silo server talks to APNs/FCM directly and never touches this relay (see `00-architecture-overview.md` "Custom credentials").
-
-### 1.3 Relationship to the contract docs and the separate repo
-
-| Concern | Owner | Document |
-|---|---|---|
-| External relay request/response/validation/payloads | `02`/`03` (authoritative) | `../02-apns-relay.md`, `../03-fcm-relay.md` |
-| Self-hosted server's relay-client, dispatcher, pacing, retry | `silo-server` | `../02`, `../03`, `../00` |
-| Relay service internals (this doc): upstream clients, DB, auth, rate limit, idempotency, deploy | `silo-push-relay` (separate repo) | **this file** |
-| 2026-current upstream provider mechanics (JWT, OAuth2, endpoints, error tables) | reference | `./02-apns-fcm-2026-reference.md` |
-
-These design docs are authored **here in `silo-server`** alongside the `02`/`03` contracts purely for co-location. The relay **code** lives elsewhere (`silo-push-relay`).
-
---
-
-## 2. Goals and Non-Goals
-
-### 2.1 Goals
-
- **G1 — Faithful contract.** Implement `POST /v1/apple/send` and `POST /v1/fcm/send` exactly as `02`/`03` specify: same request fields, same validation rules, same response shape, same relay-built payloads, same headers.
- **G2 — Content-free by construction.** The request schema admits **only** the opaque fields in §5. Any unexpected/free-form field is rejected with `400`. The relay cannot forward content even if a caller tries.
- **G3 — Credential custody.** Hold the official `.p8` and SA JSON in a secret manager, never on disk in the repo/image, never in env vars where avoidable (§11).
- **G4 — Stateless request path.** No per-request DB writes other than throttled `last_used_at` and redacted op-logs. Idempotency + rate-limit state live in Redis. The relay can be horizontally scaled and a single instance can be killed mid-flight without data loss (the server-side outbox in `../01-release-events-and-inbox.md` guarantees re-delivery).
- **G5 — Correct upstream mechanics (2026).** One cached ES256 JWT per APNs team (regenerated ~50 min, never < 20 min apart); one cached OAuth2 access token per FCM project (~1 h, refresh with margin); HTTP/2 connection reuse with PING health checks; correct reason→error mapping. Per `./02-apns-fcm-2026-reference.md`.
- **G6 — Multi-tenant isolation.** Every API key, rate-limit bucket, idempotency key, and log line is scoped by `account_id`. Per-account allowlists bound which APNs topics / FCM (project, package) an account may push to.
- **G7 — Minimal attack surface for admin ops.** No public admin HTTP API in v1. Account/key/allowlist administration is a CLI (`relayctl`) writing directly to the DB (§5.6).
- **G8 — Operable.** Structured redacted logs, Prometheus metrics, `/healthz` + `/readyz`, graceful shutdown.
-
-### 2.2 Non-goals
-
- **NG1** — Storing token→user aliases, device subscriptions, or any user/profile identity (deferred; `02` "stateless v1").
- **NG2** — Accepting arbitrary APNs/FCM JSON, custom titles/bodies, badge by default, or topic broadcasts (FCM `topic`/`condition` are never used — per-token only, per `03`).
- **NG3** — Delivery receipts, analytics, marketing exports, or open-tracking.
- **NG4** — APNs broadcast / Live Activity channels (`/4/broadcasts/...`) — out of scope; see `./02-apns-fcm-2026-reference.md` §1.10. v1 uses only `/3/device/<token>`.
- **NG5** — Web Push, HMS, ADM, or any non-APNs/non-FCM transport.
- **NG6** — A public self-service signup / billing surface. Accounts are provisioned by Silo operators via `relayctl`.
- **NG7** — The `custom_apns` / `custom_fcm` direct paths (those run inside `silo-server`, not here).
-
---
-
-## 3. Trust and Threat Model
-
-### 3.1 What the relay sees (restated from `00`/`02`/`03`)
-
-The relay, even fully compromised, sees only:
-
- **Which self-hosted installation** is calling — the relay API key (`rk_…`) maps 1:1 to a relay account.
- **The server's egress IP** — inherent to any hosted relay; the server connects directly. For home hosting this identifies the household connection. **This is the closest thing to an identity leak in the design** and is listed so the privacy claim stays exhaustive, not over-strong (`00` addressing-flow note).
- **A device token** — APNs device token (~100 bytes hex) or FCM registration token (~152–180+ chars).
- **Request timing.**
- **Coarse wire mode** — `private_alert`/`background_wake` (APNs) or `private_data`/`background_wake` (FCM).
- **Opaque `collapse_id` / `collapse_key`** — per-server-keyed HMACs (see §3.3).
- **Opaque correlation IDs** — `server_device_id`, `delivery_id`.
- **Upstream response status** — APNs `apns-id` / FCM message name, status code, reason string.
- **`apns-topic` / FCM (`project_id`, `package_name`)** — platform/build identifiers Apple/Google already see (`02` privacy note).
-
-### 3.2 What the relay must NEVER see or store
-
-Per `00`/`02`/`03`: no notification title or body, no media identifiers, no profile/user/username/library/collection/item names, no server hostname or base URL, no artwork URLs, no watched-state metadata, no device→user mapping, and **no token aliases** (stateless v1). The request schema (§5) has no field that could carry any of these, and an unknown field is a hard `400` (§12).
-
-### 3.3 Collapse-ID equivalence classes (opaque to the relay)
-
-The Silo server computes `collapse_id = base32(HMAC-SHA256(server_collapse_secret, series_id))` truncated to 26 chars (APNs) / equivalent for FCM `collapse_key`, where `server_collapse_secret` is a random per-server secret (`02`/`03`). The relay treats this as **opaque** and never derives it. Residual leakage: the relay can group **one server's** pushes into per-series equivalence classes (that is what collapse is *for*), but the per-server key prevents recovering the series identity or correlating the same series across two different servers.
-
-### 3.4 Residual leakage (exhaustive)
-
-| Leak | To whom | Why it's irreducible | Mitigation |
-|---|---|---|---|
-| Egress IP | Relay operator | Server connects directly over HTTPS | Admin may route relay traffic through their own VPN/proxy egress (`02` residual-leakage note) |
-| Push timing | Relay operator + Apple/Google | A push is an observable network event | None — only meaning/content is hidden |
-| Device token | Relay operator + Apple/Google | Required to address the device | Tokens never logged raw; truncated/hashed (§11/§12) |
-| Collapse equivalence class | Relay operator | Collapse must be a stable per-series key | Per-server HMAC key prevents series recovery & cross-server correlation (§3.3) |
-| App topic / Firebase project + package | Relay operator + Apple/Google | Required by the upstream APIs | Platform/build identifiers Apple/Google already hold |
-
-The relay **cannot** learn user identity, notification content, server URL, or library data even when fully compromised (`00` threat-model summary). It **cannot fabricate meaningful pushes** — only generic opaque wake payloads.
-
-### 3.5 Adversaries
-
-| Adversary | Capability | Worst case | Control |
-|---|---|---|---|
-| Hostile/compromised relay operator | Full DB + request stream | Learns device tokens, timing, egress IPs of opted-in servers; can send generic wakes | No content/identity; per-server collapse keying; opt-in & disabled by default |
-| Stolen relay API key | Can send opaque pushes as that account | Generic wakes to tokens the thief already holds; bounded by per-account allowlist + rate limits | Revoke key (`relayctl key revoke`); rotate; per-account quota caps spend (OWASP API4:2023) |
-| Cross-tenant attacker | Tries to push to another account's topic/token | Rejected: topic/project/package not on attacker's allowlist | Per-account allowlist enforcement (§8.4); namespaced Redis keys |
-| Apple / Google | Platform operator | Sees topic, token, generic payload, timing | No identity/content (data-only FCM; loc-key-only APNs alert) |
-
---
-
-## 4. Architecture
-
-### 4.1 Request path (stateless)
-
-```
-1. TLS terminate (LB or in-process) → HTTP/2 inbound.
-2. Auth middleware: parse "Authorization: Bearer rk_<prefix>_<secret>";
-   SELECT row by indexed prefix; constant-time-compare hash; reject revoked/expired.
-3. Rate-limit middleware: per-account Redis token bucket (Lua: refill→check→consume).
-   Over limit → 429 + Retry-After.
-4. Body decode with DisallowUnknownFields (any unexpected field → 400).
-5. Validate fields (§5) incl. allowlist check (topic / project+package).
-6. Idempotency: Idempotency-Key header → Redis SET NX lock; replay / 409 / 422.
-7. Build the fixed relay payload (§5) + headers; forward to upstream APNs/FCM
-   client (cached JWT / OAuth2 token, reused HTTP/2 conn).
-8. Map upstream response → caller-facing JSON (§5).
-9. Store the {status, body} under the idempotency key (TTL ~24h);
-   throttled last_used_at update; emit redacted op-log + metrics.
-```
-
-The only synchronous DB touch on the hot path is the **API-key lookup** (indexed, O(1) by prefix) and, at most once per minute per key, a `last_used_at` write. Idempotency and rate-limit state are in Redis. No notification content, no token alias, ever persisted.
-
-### 4.2 Component diagram
-
-```mermaid
-flowchart TB
-  subgraph Server["Self-hosted Silo server (caller)"]
-    DISP[Push dispatcher + client-side pacing\n5 req/s token bucket]
-  end
-
-  DISP -->|"POST /v1/apple/send  Bearer rk_…  Idempotency-Key"| LB[(TLS / Load balancer)]
-  DISP -->|"POST /v1/fcm/send"| LB
-
-  subgraph Relay["silo-push-relay (stateless replicas)"]
-    LB --> API[HTTP server\nnet/http, HTTP/2, timeouts]
-    API --> AUTH[Auth middleware\nprefix lookup + ConstantTimeCompare]
-    AUTH --> RL[Rate-limit middleware\nRedis Lua token bucket]
-    RL --> IDEM[Idempotency\nRedis SET NX / replay / 409 / 422]
-    IDEM --> VAL[Validate + allowlist\nDisallowUnknownFields]
-    VAL --> AC[APNs client\ncached ES256 JWT ~50m\nper-team HTTP/2 pool]
-    VAL --> FC[FCM client\ncached OAuth2 token ~1h\nHTTP/2]
-    API --> OPS[/healthz /readyz /metrics/]
-    AUTH -. redacted .-> LOG[slog JSON]
-  end
-
-  AC -->|"POST /3/device/<token>"| APNS[(api.push.apple.com\n/ api.sandbox.push.apple.com)]
-  FC -->|"POST /v1/projects/{id}/messages:send"| FCM[(fcm.googleapis.com)]
-
-  AUTH --> PG[(PostgreSQL\naccounts / api_keys /\nallowlists / op_logs)]
-  RL --> REDIS[(Redis\nidempotency + rate buckets)]
-  IDEM --> REDIS
-
-  CLI[relayctl CLI\naccount/key/allowlist admin] --> PG
-  SM[(Secret manager)] -.->|.p8 / SA JSON / pepper| AC
-  SM -.-> FC
-```
-
-### 4.3 Data stores
-
-| Store | Holds | Why | Notes |
-|---|---|---|---|
-| **PostgreSQL** | `relay_accounts`, `relay_api_keys`, `relay_apns_allowlist`, `relay_fcm_allowlist`, `relay_op_logs` | Durable, low-write config + redacted audit | `jackc/pgx/v5` + `pgxpool` (`./02-apns-fcm-2026-reference.md` §3.4). Never stores tokens, content, or identity. |
-| **Redis** | `idem:{account}:{key}` (idempotency lock/result), `rl:{account}` (token-bucket state) | Fast, TTL'd, shared across replicas | `redis/go-redis/v9`. Atomic Lua for rate-limit; `SET NX` for idempotency. Idle keys TTL out. |
-| **Secret manager** | APNs `.p8`, FCM SA JSON, API-key HMAC pepper, DB/Redis creds | Credential custody | KMS/Vault/secret-manager preferred over mounted file over env var (OWASP, `./02-apns-fcm-2026-reference.md` §4.5/§5). |
-
-### 4.4 Credential holding
-
- **APNs:** one (or a few, scoped) `.p8` ES256 keys + Team ID + Key ID per official team. Prefer team-scoped + topic-specific keys (Feb-2025 hardening) for least privilege (`./02-apns-fcm-2026-reference.md` §1.2). A connection pool is **per APNs team** (a connection cannot serve multiple teams — §1.1 of the reference).
- **FCM:** one service-account JSON per official Firebase project (`continuum-prod-android`). On GCP, prefer keyless Workload Identity / attached SA; off-GCP, the JSON lives in the secret manager (`./02-apns-fcm-2026-reference.md` §2.2/§4.5).
- Credentials are loaded **once at startup** from the secret manager into memory; never written to disk, never logged, never returned by any endpoint. Reload requires a process restart (v1) or SIGHUP-triggered re-read (optional).
-
---
-
-## 5. Public API Contract
-
-All endpoints are HTTPS-only over HTTP/2. Authentication is `Authorization: Bearer rk_<key>` (§8.2). `Content-Type: application/json` for send endpoints. Bodies are decoded with `DisallowUnknownFields` — **any unrecognized field is a `400`** (§12). Unless stated otherwise, error bodies use the shape in §5.5.
-
-### 5.1 `POST /v1/apple/send`
-
-Authoritative source: `02-apns-relay.md` "Send Apple Push". Reproduced exactly.
-
-**Request**
-
-```http
-POST /v1/apple/send HTTP/2
-Host: relay.silo.app
-Authorization: Bearer rk_live_3Qw9...secret...
-Idempotency-Key: 01JDELIVERY...:01JDEVICE...:1
-Content-Type: application/json
-```
-
-```json
-{
-  "token": "apns-token",
-  "environment": "production",
-  "topic": "com.continuum.app.ios",
-  "mode": "private_alert",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_id": "01JOPAQUE_COLLAPSE"
-}
-```
-
-**Field table**
-
-| Field | Type | Required | Rule |
-|---|---|---|---|
-| `token` | string | yes | Required; must be plausible for APNs — non-empty, hex-shaped (`^[0-9a-fA-F]+$`). Apple device tokens are commonly **64 hex chars (32 bytes)** but Apple does not guarantee a fixed length and has lengthened them historically, so the relay enforces a **generous bound (e.g. ≥ 64 and ≤ 256 hex chars)** rather than a tight guess that could reject valid future-length tokens. Reject non-hex / out-of-bound → `400 invalid_token`. |
-| `environment` | string | yes | `production` or `sandbox`. Selects upstream host (§6.2). Any other value → `400 invalid_environment`. |
-| `topic` | string | yes | Must be on the account's APNs topic allowlist (§8.4). Not allowlisted → `403 topic_not_allowed`. |
-| `mode` | string | yes | `private_alert` or `background_wake`. Other → `400 invalid_mode`. |
-| `server_device_id` | string | yes | Opaque; length-limited (≤128 chars, ULID-shaped recommended). Over limit → `400 invalid_field`. |
-| `delivery_id` | string | yes | Opaque; length-limited (≤128). |
-| `badge` | integer \| null | no | Default omitted. When present, must be a **bounded non-negative integer `0 ≤ badge ≤ 9999`** — out of range → `400 invalid_field`. This is the one numeric field copied verbatim into `aps.badge`, so it is bounded to keep it from becoming an unbounded caller-controlled channel visible to Apple. Badge is **disabled by default** to avoid leaking unread counts (`02` privacy); the relay forwards it only if provided. |
-| `collapse_id` | string \| null | no | Opaque; **≤ 64 bytes** (Apple's `apns-collapse-id` cap). Over 64 bytes → `400 invalid_collapse_id`. |
-
-No other fields are accepted: **no title, body, image URL, media ID, username, server hostname, or server URL** field exists (`02`). An unknown key → `400 unexpected_field`.
-
-**`Idempotency-Key` header** (required for sends): format `<notification_delivery_id>:<push_device_id>:<attempt_number>` (`02`/`03`). See §10.
-
-**Response — 200**
-
-```json
-{
-  "request_id": "01JRELAY...",
-  "apns_id": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "accepted"
-}
-```
-
- `request_id` — relay-generated ULID, also echoed as the `X-Request-Id` response header and used in logs.
- `apns_id` — Apple's `apns-id` response header (UUID).
- `status` — `accepted` on a 200 from APNs.
-
-> **Sandbox `apns-unique-id` (additive observability).** On a **200 in the sandbox/DEVELOPMENT environment only**, APNs additionally returns an `apns-unique-id` response header used by the Push Notifications Console Delivery Log (reference §1.6). It is the single most useful field for diagnosing "accepted-but-not-delivered" on sandbox. The relay **captures `apns-unique-id` (sandbox only)** into the op-log and the `relayctl ping-upstream` output, and may echo it in the sandbox 200 body, to aid delivery-log correlation during client QA. It is **never** present or logged for production sends.
-
-**Relay-built APNs payloads** (the relay constructs these; callers cannot override — `02`).
-
-`private_alert`:
-
-```json
-{
-  "aps": {
-    "alert": {
-      "title-loc-key": "SILO_NOTIFICATION_TITLE",
-      "loc-key": "SILO_NOTIFICATION_GENERIC_BODY"
-    },
-    "sound": "default"
-  },
-  "silo": {
-    "v": 1,
-    "wake": "notifications.changed",
-    "server_device_id": "01JOPAQUE...",
-    "delivery_id": "01JDELIVERY..."
-  }
-}
-```
-
-When `badge` is present and non-null, the relay adds `"badge": <n>` inside `aps`. Otherwise it is omitted entirely (no `badge` key).
-
-`background_wake`:
-
-```json
-{
-  "aps": { "content-available": 1 },
-  "silo": {
-    "v": 1,
-    "wake": "notifications.changed",
-    "server_device_id": "01JOPAQUE...",
-    "delivery_id": "01JDELIVERY..."
-  }
-}
-```
-
-**Exact APNs request headers the relay sets** (`02` Headers + reconciled with `./02-apns-fcm-2026-reference.md` §1.4):
-
-| Upstream header | `private_alert` | `background_wake` | Source |
-|---|---|---|---|
-| `:method` | `POST` | `POST` | fixed |
-| `:path` | `/3/device/<token>` | `/3/device/<token>` | `token` field |
-| `authorization` | `bearer <cached ES256 JWT>` | same | relay JWT (§6.1) |
-| `apns-topic` | the allowlisted `topic` | same | `topic` field |
-| `apns-push-type` | `alert` | `background` | `02` |
-| `apns-priority` | `10` | `5` | `02` (and reference §1.4.1: background **must** be 5; 10 is an error) |
-| `apns-collapse-id` | `collapse_id` if present (≤64B) | same | `02` |
-| `apns-id` | omitted (Apple auto-generates; echoed back) | same | reference §1.4 |
-| `apns-expiration` | **finite default** (e.g. `now + 4 h`) | **short TTL** (e.g. `now + 1 h`) | reference §1.4. **Configurable**; ships a sane non-30-day default — see below. |
-
-> **`apns-expiration` policy (v1 ships a finite default, not the 30-day store-and-retry).** With `apns-expiration` omitted, Apple stores and retries an undelivered push for up to **30 days** (reference §1.4) — a wake fired days later is useless or confusing for content that is fetched live from the user's server on wake (the underlying notification may already be read/deleted server-side). The relay therefore sets a **finite, configurable `apns-expiration`**: a few hours for `private_alert` (default ~4 h) and a **short** TTL for `background_wake` (default ~1 h), so a device offline for days does not get a stale wake. Both defaults are config values (per-deployment); the relay never ships the 30-day default. The FCM path sets the parallel `android.ttl` (§5.2) for parity. (Resolved from former open question §15 #5; values are tunable from product input.)
-
-Payload is **uncompressed JSON**, ≤ 4 KB (reference §1.5). The relay-built payloads are far under 4 KB; the relay still rejects with `400 payload_too_large` defensively if a (future) field pushes it over, and maps an upstream `413` per §6.4.
-
-**Error mapping back to the caller** — see §6.4.
-
-### 5.2 `POST /v1/fcm/send`
-
-Authoritative source: `03-fcm-relay.md` "Send Android Push". Reproduced exactly.
-
-**Request**
-
-```http
-POST /v1/fcm/send HTTP/2
-Host: relay.silo.app
-Authorization: Bearer rk_live_3Qw9...secret...
-Idempotency-Key: 01JDELIVERY...:01JDEVICE...:1
-Content-Type: application/json
-```
-
-```json
-{
-  "token": "fcm-registration-token",
-  "project_id": "continuum-prod-android",
-  "package_name": "com.continuum.app.android",
-  "mode": "private_data",
-  "server_device_id": "01JOPAQUE...",
-  "delivery_id": "01JDELIVERY...",
-  "badge": null,
-  "collapse_key": "01JOPAQUE_COLLAPSE"
-}
-```
-
-**Field table**
-
-| Field | Type | Required | Rule |
-|---|---|---|---|
-| `token` | string | yes | Plausible FCM token: non-empty, base64url-ish, **length 100 ≤ len ≤ 4096** (FCM tokens are typically 152–180+ chars — `03`; the upper bound guards against oversized-token abuse without rejecting legitimate longer tokens). Implausible → `400 invalid_token`. |
-| `project_id` | string | yes | Must match the configured Firebase project for this account's allowlist (§8.4). Mismatch → `403 project_not_allowed`. |
-| `package_name` | string | yes | Must be on the account's FCM package allowlist, paired with `project_id` (§8.4). Not allowlisted → `403 package_not_allowed`. |
-| `mode` | string | yes | `private_data` or `background_wake` (the **wire** mode; profile-level is `private_push` — `00`/`03`). Other → `400 invalid_mode`. |
-| `server_device_id` | string | yes | Opaque; ≤128 chars. |
-| `delivery_id` | string | yes | Opaque; ≤128 chars. |
-| `badge` | integer \| null | no | Accepted for caller-contract parity with the APNs endpoint, but **FCM has no data-only home for it** (the relay never builds a `notification` block). v1 **ignores `badge` on the FCM path** — it is neither rendered nor smuggled into the `data` map (§5.2 construction rules, §12). When present it must still pass the same bound as APNs (`0 ≤ badge ≤ 9999`); otherwise → `400 invalid_field`. |
-| `collapse_key` | string \| null | no | Opaque; **≤ 64 bytes**. This is the **inbound caller field name** (snake_case, per `03`); the relay maps it to the FCM REST field `android.collapseKey` (camelCase — see §5.2 construction rules). Over 64 bytes → `400 invalid_collapse_key`. |
-
-No free-form `notification`, title, body, image URL, media ID, username, or server URL field exists (`03`). Unknown key → `400 unexpected_field`.
-
-**Response — 200**
-
-```json
-{
-  "request_id": "01JRELAY...",
-  "fcm_message_name": "projects/continuum-prod-android/messages/0:1234567890123456%abcdef",
-  "status": "accepted"
-}
-```
-
- `fcm_message_name` — FCM v1 response `name`.
-
-**Relay-built FCM payloads — data-only, no `notification` block** (`03`).
-
-`private_data`:
-
-```json
-{
-  "message": {
-    "token": "fcm-registration-token",
-    "data": {
-      "v": "1",
-      "wake": "notifications.changed",
-      "server_device_id": "01JOPAQUE...",
-      "delivery_id": "01JDELIVERY..."
-    },
-    "android": {
-      "priority": "HIGH",
-      "collapseKey": "01JOPAQUE_COLLAPSE"
-    }
-  }
-}
-```
-
-`background_wake`:
-
-```json
-{
-  "message": {
-    "token": "fcm-registration-token",
-    "data": {
-      "v": "1",
-      "wake": "notifications.changed",
-      "server_device_id": "01JOPAQUE...",
-      "delivery_id": "01JDELIVERY..."
-    },
-    "android": {
-      "priority": "NORMAL",
-      "collapseKey": "01JOPAQUE_COLLAPSE"
-    }
-  }
-}
-```
-
-**Construction rules (reconciled with `./02-apns-fcm-2026-reference.md` §2.3/§2.4):**
-
- `message.data` is `map<string,string>` — **all values are strings** (`"v": "1"`, not `1`). It is a **fixed, closed set of keys** — exactly `{v, wake, server_device_id, delivery_id}` — with **no caller-controlled key or value** beyond the already-opaque IDs (§12). Reserved keys (`from`, `message_type`, `notification`, `google.*`, `gcm.*`) are never used, and `badge` is never injected into `data`.
- No top-level `message.notification` — **data-only** so Google carries no rendering content (`03`).
- `android.priority`: `"HIGH"` for `private_data` (wakes under Doze), `"NORMAL"` for `background_wake`. The relay emits the **canonical uppercase enum** values documented for FCM REST `AndroidConfig.priority` (reference §2.4); FCM also accepts lowercase, but the canonical form is used to avoid relying on a parenthetical allowance. **Reconciliation:** the `03` contract reproduces lowercase `high`/`normal`; the wire field accepts both and `priority` is relay-set (not a caller field), so this is an internal-upstream normalization with no external-contract impact.
- `android.collapseKey` (REST **camelCase** — reference §2.4): set to the caller's `collapse_key` when present, omitted otherwise. **Maps to FCM `android.collapseKey`** — the relay POSTs raw JSON to the FCM HTTP v1 REST endpoint, which rejects unknown fields (including a snake_case `collapse_key` inside `android`) with `INVALID_ARGUMENT`. **Reconciliation (parallel to the sandbox-host one in §6.2):** the inbound caller field stays `collapse_key` per `03`/§5.2; only the relay-built upstream FCM field is `collapseKey`.
- `android.ttl` (a duration string, e.g. `"14400s"`): set to a **finite, configurable** TTL for parity with the APNs `apns-expiration` policy (FCM otherwise defaults to **4 weeks** of storage). Default ~4 h for `private_data`, a shorter TTL for `background_wake`, so a device offline for days does not get a stale wake. Configurable per deployment.
- `validateOnly` (top-level, **camelCase** — reference §2.5) is the dry-run flag for the `relayctl` test path only (§7.3, §7.5); never set on production sends.
- The relay never sets FCM `topic`/`condition`; only `message.token` (per-token only — `03`).
- Payload ≤ 4096 bytes for token sends (reference §2.3); the fixed payload is far under.
-
-> **Reconciliation note (priority vs. reference §2.8).** The reference warns that high-priority data messages that never produce a user-facing notification can be deprioritized to normal by FCM over a ~7-day window. The `03` contract nonetheless specifies `priority: high` for `private_data` (the app *does* surface a notification after wake), and the relay **honors the `03` contract** — it does not second-guess priority. Deprioritization is an upstream behavior, not a contract change; the `03` doc already documents the quota fallback (caller may switch to normal after repeated 429s — §7.4).
-
-**Exact FCM request** the relay sends:
-
-```http
-POST /v1/projects/continuum-prod-android/messages:send HTTP/2
-Host: fcm.googleapis.com
-Authorization: Bearer <cached OAuth2 access token>
-Content-Type: application/json
-```
-
-**Error mapping** — see §7.4.
-
-### 5.3 `GET /healthz`
-
-Liveness. Returns `200 {"status":"ok"}` if the process is up. No dependency checks. Used by the orchestrator's liveness probe. Unauthenticated.
-
-### 5.4 `GET /readyz` and `GET /metrics`
-
- **`GET /readyz`** — readiness. Readiness gates on **core shared dependencies only**: Postgres reachable (`SELECT 1` via pool) and Redis reachable (`PING`). Per-provider health (APNs signer initialized; FCM token source initialized) is reported **separately, not as a binary gate**, so that a **single-provider** credential/init failure does **not** pull the whole replica from the LB and kill the healthy provider too (APNs and FCM are independent upstreams; the "channel failures are isolated" principle from `00` carried into the relay's own health model). The body is `200 {"status":"ready","providers":{"apns":"healthy|degraded","fcm":"healthy|degraded"}}` when core deps are up, or `503 {"status":"not_ready","checks":{...}}` only when **PG or Redis** is down. When a provider is `degraded`, the **send handler for that provider** returns `503 upstream_unavailable` for that provider only (the other provider keeps serving); a per-provider gauge and circuit-breaker state make `APNs degraded, FCM healthy` visible to operators rather than a binary not-ready. See §13.2 (`relay_provider_healthy`).
- **`GET /metrics`** — Prometheus exposition (`promhttp`). Bound to the internal network / scrape-only. See §13.2 for the catalog.
-
-### 5.5 Standard error body
-
-All 4xx/5xx (except health endpoints) return:
-
-```json
-{
-  "error": {
-    "code": "topic_not_allowed",
-    "message": "topic is not on this account's allowlist",
-    "request_id": "01JRELAY..."
-  }
-}
-```
-
-`code` is a stable machine string (see §6.4 / §7.4 tables). `request_id` matches `X-Request-Id`. `Retry-After` is set on `429`/`503` (§9, §10).
-
-### 5.6 Admin surface — `relayctl` CLI (no public admin HTTP API)
-
-To minimize attack surface (G7), there is **no HTTP admin API** in v1. Administration is a Go CLI, `relayctl`, that connects **directly to the relay's PostgreSQL** (via a privileged DSN held by operators only) and performs the operations below. It runs from an operator workstation or a jump host — never exposed to the public internet.
-
-| Command | Action | DB effect |
-|---|---|---|
-| `relayctl account create --name <label> [--note <text>]` | Provision a relay account (one per opt-in installation). Prints the new `account_id`. | INSERT `relay_accounts`. |
-| `relayctl account list [--active]` | List accounts with status, key count, last activity. | SELECT. |
-| `relayctl account disable --account <id>` | Suspend an account (all keys rejected, but rows retained). | UPDATE `relay_accounts.status='disabled'`. |
-| `relayctl key issue --account <id> [--env live\|test] [--expires <dur>]` | Generate a new API key. **Prints the full `rk_…` token exactly once** (only the hash is stored). | INSERT `relay_api_keys`. |
-| `relayctl key list --account <id>` | List keys (prefix, created, last_used, revoked) — never the secret. | SELECT. |
-| `relayctl key revoke --key-prefix <prefix>` | Revoke a key immediately. | UPDATE `relay_api_keys.revoked_at=now()`. |
-| `relayctl allowlist apns set --account <id> --topics com.continuum.app.ios,.tvos,.macos` | Replace the account's APNs topic allowlist. | UPSERT `relay_apns_allowlist`. |
-| `relayctl allowlist fcm set --account <id> --project continuum-prod-android --packages com.continuum.app.android` | Replace the account's FCM (project, packages) allowlist. | UPSERT `relay_fcm_allowlist`. |
-| `relayctl allowlist show --account <id>` | Print effective allowlists. | SELECT. |
-
-`relayctl` operations are themselves audited into `relay_op_logs` (event `admin.*`) with the operator identity (OS user / `--actor`) but never the secret token. The CLI shares the relay's data-access package so schema and constraints stay in one place.
-
---
-
-## 6. Upstream APNs Client
-
-Built per `./02-apns-fcm-2026-reference.md` §1 and §3.1. Library choice: `github.com/sideshow/apns2 v0.25.0` **or** a hand-rolled `net/http` + `golang.org/x/net/http2` + `golang-jwt/jwt/v5` client (reference §3.1; bus-factor caveat in §15). Either way, the mechanics below are required.
-
-### 6.1 Auth — JWT ES256 lifecycle
-
- **Algorithm:** ES256 (ECDSA P-256) **only** — APNs accepts no other (reference §1.1).
- **Header:** `{"alg":"ES256","kid":"<10-char Key ID>"}`. **Claims:** `{"iss":"<10-char Team ID>","iat":<epoch seconds>}`.
- **Signing key:** the official `.p8` private key from the secret manager.
- **Caching:** generate **one** JWT, hold it in memory behind a mutex, reuse across all senders/connections/topics for that team (reference §1.1/§4.4).
- **Refresh cadence:** regenerate on a **~50-minute timer** (well inside Apple's 1-hour `iat` window), **never more often than once per 20 minutes**, and eagerly on a `403 ExpiredProviderToken` (then retry the request once). Over-frequent refresh → `429 TooManyProviderTokenUpdates`; back off and slow refresh (reference §1.1 lifecycle table).
- **Single-flight regeneration (stampede guard).** Under a burst of concurrent sends sharing one cached JWT, an expiry or a `403 ExpiredProviderToken` is observed by **many in-flight goroutines at once**. JWT regeneration **must be single-flighted** — e.g. `golang.org/x/sync/singleflight` keyed by team, or a generation counter behind the mutex: a goroutine seeing `ExpiredProviderToken` checks whether the JWT was **already refreshed since its request started** (compare its captured generation/`iat` to the current one) and, if so, **reuses the new token** instead of triggering another refresh. Only **one** refresh happens per ~20-min window regardless of how many concurrent 403s arrive. A naive per-goroutine regenerate-on-403 would trip `429 TooManyProviderTokenUpdates`; the 20-minute floor is honored **by this concurrency mechanism**, not just asserted. (Mirrors risk R3.)
- **Per-team pools.** A connection cannot map to multiple teams; open a separate JWT + HTTP/2 connection pool per APNs team (reference §1.1). v1 has one official team, so one pool — but the code keys pools by team to stay correct.
- **Key selection — `(environment, topic) → .p8 key`.** With Apple's Feb-2025 team-scoped/topic-specific keys (max 2 team-scoped keys per environment), more than one `.p8` may be loaded (e.g. a topic-specific key for `com.continuum.app.ios` plus a team key; or per-environment scoped keys). A **sandbox send must use a sandbox-scoped key and a production send a production-scoped key** — using the wrong one yields `403 BadEnvironmentKeyIdInToken` / `UnrelatedKeyIdInToken`. The relay therefore holds an explicit **key-selection map `(environment, topic) → key id`** in config, falling back to an unscoped team key only where no scoped key exists. **Startup validation:** every allowlisted `(topic, environment)` must resolve to a usable key, or startup fails. A `BadEnvironmentKeyIdInToken`/`UnrelatedKeyIdInToken` at runtime maps to `upstream_auth_error` (§6.4) and is treated as a **key-selection misconfiguration** (ops alert).
-
-### 6.2 Endpoint selection
-
-| `environment` field | Upstream host | Port |
-|---|---|---|
-| `production` | `https://api.push.apple.com` | 443 (2197 fallback) |
-| `sandbox` | `https://api.sandbox.push.apple.com` | 443 (2197 fallback) |
-
-Both hosts are **hardcoded constants** selected only by the `environment` enum — never derived from any other request field (§11 egress/SSRF posture).
-
-> **Reconciliation (host name).** `02-apns-relay.md` validation text names the sandbox host `https://api.development.push.apple.com`. **Both `api.sandbox.push.apple.com` and `api.development.push.apple.com` are valid, functionally-equivalent Apple sandbox aliases — both resolve.** The relay **standardizes on `api.sandbox.push.apple.com`** (reference §1.3; it also matches `sideshow/apns2 v0.25.0`'s `HostDevelopment` constant, which points at `api.sandbox.push.apple.com`). This is an *internal upstream* detail and does **not** change the external contract: callers still send `"environment": "sandbox"` exactly as `02` specifies. (See reference open question §5 item 4 / this spec §15 — now a note that the two hosts are interchangeable, not a discrepancy to resolve at build time.)
-
-### 6.3 Connection management
-
- HTTP/2 + TLS 1.2+ (1.3 acceptable). **Reuse one client / connection pool per process per environment per team**; never create a client per push (TLS setup is slow — reference §3.1). One well-tuned connection can do thousands of pushes/sec.
- Set a non-zero `ReadIdleTimeout` (~15 s) + `PingTimeout` (~15 s) on the `http2.Transport` to reap half-open connections (reference §3.3 — "the single most important tuning for a long-lived relay").
- Do **not** hardcode `SETTINGS_MAX_CONCURRENT_STREAMS`; read it from the server (reference §1.3/§3.3).
- Handle `GOAWAY`: drop the connection from the pool and reconnect; finish in-flight streams ≤ `Last-Stream-ID` (RFC 9113 §6.8). Go's `net/http2` transport does most of this when one client is reused (reference §1.3). **A stream severed by `GOAWAY`/reset before a final APNs response is mapped to `503 upstream_unavailable` (retryable) and is NOT retried in-process** — see §6.4 "Connection-severed / GOAWAY" for the exact caller-facing rule and the at-most-once rationale.
- Ensure the TLS trust store includes **USERTrust RSA** (SHA-2 root) — already in standard OS/Go pools; only matters if the relay pins or ships a minimal trust store (reference §1.7).
-
-### 6.4 Response / reason mapping → caller-facing error
-
-The relay parses the APNs JSON `{"reason":"…"}` (and the `timestamp` on 410), not just the status code (reference §1.6). It maps to a caller-facing `error.code` and decides retryability. **The relay does not itself retry transient upstream errors across separate caller requests** — it returns a retryable status so the caller's outbox/backoff (in `../01-release-events-and-inbox.md`/`02`) drives retries; the one exception is the in-process JWT-expiry retry (§6.1).
-
-| APNs status | APNs `reason` | Caller HTTP | Caller `error.code` | Retryable (caller)? |
-|---|---|---|---|---|
-| 200 | — | 200 | — | success |
-| 400 | `BadDeviceToken`, `InvalidToken`, `DeviceTokenNotForTopic`, `MissingDeviceToken` | 422 | `bad_device_token` | **No — purge token** (caller disables device, per `02`). `02` treats `BadDeviceToken`/`InvalidToken` equivalently: "Apple has migrated some responses from `BadDeviceToken` to `InvalidToken`; treat them equivalently." See the environment-mismatch caveat below. |
-| 400 | `BadTopic`, `MissingTopic`, `TopicDisallowed` | 400 | `bad_topic` | No (config error) |
-| 400 | `BadCollapseId` | 400 | `invalid_collapse_id` | No |
-| 400 | `BadExpirationDate`, `BadPriority`, `BadMessageId`, `InvalidPushType`, `PayloadEmpty`, `DuplicateHeaders`, `IdleTimeout` | 400 | `bad_request` | No |
-| 403 | `ExpiredProviderToken` | (internal) | — | **Relay regenerates JWT, retries once** (§6.1), then maps result |
-| 403 | `InvalidProviderToken`, `MissingProviderToken`, `UnrelatedKeyIdInToken`, `BadEnvironmentKeyIdInToken`, `Forbidden`, `BadCertificate*` | 502 | `upstream_auth_error` | No (relay misconfig — **ops alert**, not caller-fixable) |
-| 404 | `BadPath` | 502 | `upstream_error` | No |
-| 405 | `MethodNotAllowed` | 502 | `upstream_error` | No |
-| 410 | `Unregistered`, `ExpiredToken` | 410 | `unregistered` | **No — purge token** (caller disables device). `timestamp` (ms) passed through in `error.message` so caller can compare against its registration time. |
-| 413 | `PayloadTooLarge` | 400 | `payload_too_large` | No |
-| 429 | `TooManyProviderTokenUpdates` | 503 | `upstream_throttled` | Yes — relay slows JWT refresh; caller backs off |
-| 429 | `TooManyRequests` | 429 | `rate_limited` | Yes — per-device backoff; `Retry-After` set |
-| 500 | `InternalServerError` | 503 | `upstream_unavailable` | Yes (caller backoff ~15 min) |
-| 503 | `ServiceUnavailable`, `Shutdown` | 503 | `upstream_unavailable` | Yes (caller backoff) |
-
-**Default / fallback for unrecognized reasons.** Any **unmapped** `reason` string on a `400`/`403`/`410` (e.g. a future Apple reason the relay does not know) maps to `502 upstream_error`, **non-retryable, no token purge** — a safe default that surfaces the anomaly for investigation rather than silently dropping it or purging a possibly-live token. An unmapped `5xx` maps to `503 upstream_unavailable` (retryable). The exact unmapped reason is recorded in the op-log `upstream_reason` for triage.
-
-**Connection-severed / GOAWAY (no final response).** A request whose HTTP/2 stream is terminated by a `GOAWAY`, connection reset, or any transport drop **before a final APNs response arrives** is mapped to `503 upstream_unavailable` (retryable) — the same as a network timeout. The relay does **NOT** transparently retry such a request in-process; the caller's outbox (`01-release-events-and-inbox.md`) re-dispatches it under the same idempotency key, preserving at-most-once semantics (a request that may have been delivered must not be silently re-sent by the relay). Apple emits `GOAWAY` routinely for maintenance/overload, so this is a normal, expected outcome, distinguished in the op-log/metrics with a `connection_severed` outcome label.
-
-**Environment / sandbox-vs-production mismatch caveat.** A caller that sends `environment=sandbox` with a production token (or vice-versa) gets `BadDeviceToken`/`InvalidToken` from APNs for a token that may be perfectly valid in the other environment. The relay still returns `422 bad_device_token`, but **the caller should NOT treat the first such error from a newly-onboarded device as conclusive grounds to purge** when an environment mismatch is plausible. To let operators distinguish a systemic misconfiguration from genuinely dead tokens, the relay tags these op-logs/metrics so a burst of `bad_device_token` concentrated on **one account** (a likely env mixup) is visible separately from scattered dead tokens across many accounts. See §5.1 (token rules) and §8.4.
-
-Mapping to the caller's own error handling in `02`: `bad_device_token`/`unregistered` → the caller disables the device (`02` "BadDeviceToken / Unregistered: disable the token"); `upstream_throttled`/`rate_limited`/`upstream_unavailable` → the caller retries with backoff. The relay never surfaces `ExpiredProviderToken`/`TooManyProviderTokenUpdates` as caller-facing codes (those are the relay's own JWT lifecycle — `02` notes they apply only to `custom_apns`, never the relay path).
-
-Network timeout / connection failure to APNs → `503 upstream_unavailable` (retryable).
-
---
-
-## 7. Upstream FCM Client
-
-Built per `./02-apns-fcm-2026-reference.md` §2 and §3.2. Preferred path: `golang.org/x/oauth2/google` `TokenSource` (auto-caches + refreshes) + a custom HTTP/2 client posting the relay-built JSON (reference §3.2 — lighter than the Admin SDK and gives direct control of connection reuse and error classification). The Admin SDK (`firebase.google.com/go/v4/messaging`) is an acceptable alternative; pick exactly one.
-
-### 7.1 OAuth2 service-account token source + caching
-
- Build a `TokenSource` from the SA JSON with `google.CredentialsFromJSONWithType(ctx, jsonKey, google.ServiceAccount, "https://www.googleapis.com/auth/firebase.messaging")` (least-privilege scope; `CredentialsFromJSON` is deprecated — reference §2.2/§3.2). The `TokenSource` caches and auto-refreshes.
- Access tokens are valid **1 hour**; never mint per request. The library re-mints before expiry; if hand-rolling the JWT-bearer grant, refresh with a ~5-minute safety margin (reference §2.2).
- **Credential resolution:** prefer keyless **Workload Identity / attached SA** when the relay runs on GCP; off-GCP, load the SA JSON from the secret manager (reference §2.2/§4.5; §11 here).
- One token source **per Firebase project**. v1 has one official project (`continuum-prod-android`).
-
-### 7.2 Endpoint
-
-```http
-POST https://fcm.googleapis.com/v1/projects/{PROJECT_ID}/messages:send
-Authorization: Bearer <oauth2_access_token>
-Content-Type: application/json
-```
-
-Global host only — **no regional/data-residency send endpoints exist** as of June 2026 (reference §2.3). The host `fcm.googleapis.com` is a **hardcoded constant**, never derived from request input. `{PROJECT_ID}` is the validated `project_id` from the request: it is checked against a **strict charset (`^[a-z0-9-]+$`) before** allowlist lookup and before URL interpolation, so an allowlist row can never inject path-traversal or override the host (§11 egress/SSRF posture).
-
-### 7.3 Data-only message construction
-
-As in §5.2: `message.token` set to the caller's `token`; `message.data` is string-valued only (a fixed, closed key set — §5.2/§12); `message.android.priority` is the canonical `"HIGH"`/`"NORMAL"` enum by mode; the caller's `collapse_key` is mapped to the REST field `message.android.collapseKey` (camelCase) when present; **no `notification` block**. The relay can optionally use `validateOnly: true` (top-level, camelCase) for the `relayctl`-driven test path (reference §2.5) but **never** on production sends.
-
-### 7.4 Error mapping → caller-facing error + Retry-After
-
-The relay classifies on `error.status` / the `FcmError.errorCode` in `details[]`, not the bare HTTP code (reference §2.6).
-
-| FCM HTTP | `error.status` | Caller HTTP | Caller `error.code` | Retryable (caller)? |
-|---|---|---|---|---|
-| 200 | — | 200 | — | success |
-| 400 | `INVALID_ARGUMENT` | 422 | `invalid_argument` | No. Ambiguous (bad payload **or** bad token); since the relay payload is independently valid, the caller may treat it as a dead token (`03` / reference §2.6). |
-| 401 | `THIRD_PARTY_AUTH_ERROR` | 502 | `upstream_error` | **Not expected on this pure-Android path** — see note below. No auto-purge; surface for investigation. Do **NOT** page as a relay-credential failure. |
-| 403 | `SENDER_ID_MISMATCH` | 403 | `sender_id_mismatch` | **No — disable device** (token minted under a different project; `03`). |
-| 404 | `UNREGISTERED` | 410 | `unregistered` | **No — purge token** (`03`). Caller-facing **410** is an **intentional cross-provider normalization** — see note below. |
-| 429 | `QUOTA_EXCEEDED` (RESOURCE_EXHAUSTED) | 429 | `rate_limited` | Yes — **honor `Retry-After`** if present; else default **60 s** (reference §2.7). |
-| 429 / 400 | per-device rate (`DeviceMessageRateExceeded` — see note) | 429 | `rate_limited` | Yes — **retryable; NOT a token purge**. Conservative default `Retry-After` (60 s) if none provided. |
-| 401 / 403 | (HTTP **status**, not `FcmError` code) `UNAUTHENTICATED` / `PERMISSION_DENIED` on `messages:send`, **or** a non-200 from `oauth2.googleapis.com/token` at mint time | 502 | `upstream_auth_error` | No — **relay's own OAuth2 / service-account credential failure** (**ops alert**). See note below. |
-| 500 | `INTERNAL` | 503 | `upstream_unavailable` | Yes (backoff; no documented `Retry-After`). |
-| 503 | `UNAVAILABLE` | 503 | `upstream_unavailable` | Yes — **honor `Retry-After`** if present (reference §2.7). |
-| — | `UNSPECIFIED_ERROR` / any unmapped `errorCode` | 502 | `upstream_error` | No auto-purge; surface for investigation (reference §2.6). |
-
-**Note — `THIRD_PARTY_AUTH_ERROR` is not a relay-credential signal on this path.** Per Firebase's error-codes page, `THIRD_PARTY_AUTH_ERROR` means *"APNs certificate or web-push auth key was invalid or missing"* and is returned **only** for messages targeting **iOS-via-APNs or Web Push** registration tokens — i.e. when FCM itself must authenticate downstream to Apple/VAPID. The relay's `/v1/fcm/send` sends **only Android registration tokens** (data-only `message.token`, package `com.continuum.app.android`), so a legitimate Android send can never produce `THIRD_PARTY_AUTH_ERROR`. If it ever appears it indicates a **per-token/registration anomaly** (an Android token that is somehow APNs/web-bound — a client/registration bug), not a relay `.p8`/SA misconfiguration; treat it as `502 upstream_error`, surface for investigation, and do **not** page on-call as a credential failure.
-
-**Note — the relay's OWN FCM credential failure surfaces differently.** A failure of the relay's OAuth2 service-account auth shows up as a non-200 from the Google token endpoint (`oauth2.googleapis.com/token`) at mint time, or as an HTTP **status** `401 UNAUTHENTICATED` / `403 PERMISSION_DENIED` on `messages:send` (the gRPC/REST status, **not** an `FcmError.errorCode`). **These** are the signals that map to `upstream_auth_error` and warrant an ops alert (the alerting condition in `01-implementation-plan.md` keys on this `upstream_reason`, not on `THIRD_PARTY_AUTH_ERROR`).
-
-**Note — `UNREGISTERED` is deliberately re-mapped from FCM's native 404 to caller-facing 410.** FCM natively returns `UNREGISTERED` as HTTP **404**; the relay normalizes it to caller-facing **410** so it matches the same "dead token, purge" semantic the APNs path uses for `Unregistered` (where APNs natively uses 410). This is an **intentional cross-provider normalization** (not a bug) so the caller's device-disable logic is uniform across APNs and FCM. Similarly `SENDER_ID_MISMATCH` keeps FCM's native 403.
-
-**Note — per-device rate exceedance.** FCM enforces per-device Android caps (~240 msg/min, ~5000 msg/hr) that surface as a `DeviceMessageRateExceeded`-class error, **distinct from project-level `QUOTA_EXCEEDED`** (reference §2.7). Because the relay fans out bursty per-device wakes, this is a plausible real outcome. The exact error code/string for per-device exceedance is **not firmly documented**, so the relay detects it **defensively** by classifying on `error.status`/`errorCode` and maps it to a **retryable `429 rate_limited`** with a conservative default `Retry-After` — **never a token purge** (the device is fine, just rate-limited). The relay's coarse per-`(account, token_hash)` limiter (§9.1) is the local guard, but an upstream per-device error must still map to `429`, not fall through to `502`.
-
-**Retry-After honoring (reference §2.7):** on FCM `429`, the relay reads the upstream `Retry-After`; if absent it defaults to 60 s. It forwards this as the caller-facing `Retry-After` header on the `429 rate_limited` response (relative `delay-seconds`, not an absolute epoch — reference §4.2). On `503 UNAVAILABLE` it forwards any upstream `Retry-After`.
-
-Mapping to `03` caller handling: `unregistered`/`sender_id_mismatch`/`invalid_argument` → caller disables the device; `rate_limited` → caller backs off and may fall back to `priority: NORMAL` after repeated 429s (`03` open question, resolved "yes with cooldown"); `upstream_auth_error` → caller surfaces admin diagnostics, no retry. Note that `upstream_auth_error` is now sourced from the **relay's own** OAuth2/SA credential signals (HTTP `401 UNAUTHENTICATED` / `403 PERMISSION_DENIED` on `messages:send`, or a token-mint failure), **not** from `THIRD_PARTY_AUTH_ERROR` — which on this Android-only path is a registration anomaly, not a relay-credential problem (see the notes above and §7.5).
-
-### 7.5 Reconciliations with the older `03` contract
-
- **`Retry-After` on 429.** `03` says "honoring the `Retry-After` response header if present (FCM uses standard HTTP semantics here)". The reference (§2.6/§2.7) refines this: FCM's error page promises only `google.rpc.QuotaFailure` (not `RetryInfo`); treat `Retry-After`/`RetryInfo` as optional and fall back to 60 s. The relay implements the **reference's** refinement while still surfacing a `Retry-After` to the caller exactly as `03` expects.
- **No batch endpoint.** The reference (§2.1) confirms FCM's batch endpoint is discontinued; the relay sends **one POST per request** (it already does — one caller request = one device).
- **Upstream field casing — `collapseKey`, `priority`, `validateOnly`.** `03` writes the upstream Android fields in snake_case (`collapse_key`) and lowercase priority (`high`/`normal`), and writes the dry-run flag as `validate_only`. The correct **FCM HTTP v1 REST** field names are `android.collapseKey` (camelCase), the canonical `priority` enum `"HIGH"`/`"NORMAL"` (uppercase; lowercase also accepted), and top-level `validateOnly` (camelCase) (reference §2.4/§2.5). The relay uses the **REST-correct names on the upstream wire** while leaving the **inbound caller field `collapse_key` unchanged** per `03`. FCM v1 rejects unknown fields with `INVALID_ARGUMENT`, so this reconciliation is mandatory, not cosmetic.
- **FCM 4-distinct-collapse-key-per-device cap.** FCM stores at most **4 distinct collapse keys per device while offline**; a 5th distinct key evicts one nondeterministically (reference §2.7 — a delivery/storage behavior, **not** a per-message validation limit). Because `collapse_key` is a per-series HMAC and a device may follow **more than 4 series**, collapsible coalescing is **best-effort**: excess distinct keys evict nondeterministically and a collapsible wake may be dropped. This is **acceptable** because the durable inbox + sync (`01-release-events-and-inbox.md`) recovers any dropped wake; the relay treats `collapse_key` opaquely and takes no action. **Asymmetry note:** APNs has no equivalent documented per-device `collapse-id` cap, so the FCM path alone carries this best-effort caveat.
- **External contract unchanged.** None of the above alters the `03` request/response shapes; only the relay's internal upstream behavior is specified more precisely.
-
---
-
-## 8. Account, Key and Allowlist Model
-
-### 8.1 DB schema (PostgreSQL)
-
-Goose-style migration. All IDs are ULIDs stored as `text` for consistency with the Silo convention; timestamps are `timestamptz`.
-
-```sql
-- relay_accounts: one per opt-in self-hosted installation.
-CREATE TABLE relay_accounts (
-    id          text        PRIMARY KEY,                 -- ULID
-    name        text        NOT NULL,                    -- operator-facing label
-    status      text        NOT NULL DEFAULT 'active'
-                CHECK (status IN ('active','disabled')),
-    note        text,
-    created_at  timestamptz NOT NULL DEFAULT now(),
-    updated_at  timestamptz NOT NULL DEFAULT now()
-);
-
-- relay_api_keys: revocable bearer keys (rk_ prefix). Secret never stored.
-CREATE TABLE relay_api_keys (
-    id            text        PRIMARY KEY,               -- ULID
-    account_id    text        NOT NULL REFERENCES relay_accounts(id) ON DELETE CASCADE,
-    key_prefix    text        NOT NULL,                  -- non-secret, indexed lookup handle (e.g. rk_live_3Qw9XYZ)
-    key_hash      bytea       NOT NULL,                  -- HMAC-SHA256(pepper, secret), 32 bytes
-    env           text        NOT NULL DEFAULT 'live'
-                  CHECK (env IN ('live','test')),
-    created_at    timestamptz NOT NULL DEFAULT now(),
-    last_used_at  timestamptz,                           -- throttled write (<= 1/min)
-    expires_at    timestamptz,                           -- optional
-    revoked_at    timestamptz                            -- non-null = revoked
-);
-CREATE UNIQUE INDEX relay_api_keys_prefix_uidx ON relay_api_keys (key_prefix);
-CREATE INDEX        relay_api_keys_account_idx  ON relay_api_keys (account_id);
-
-- relay_apns_allowlist: which APNs topics an account may push to.
-CREATE TABLE relay_apns_allowlist (
-    account_id  text        NOT NULL REFERENCES relay_accounts(id) ON DELETE CASCADE,
-    topic       text        NOT NULL,                    -- e.g. com.continuum.app.ios
-    created_at  timestamptz NOT NULL DEFAULT now(),
-    PRIMARY KEY (account_id, topic)
-);
-
-- relay_fcm_allowlist: which (project, package) pairs an account may push to.
-CREATE TABLE relay_fcm_allowlist (
-    account_id    text        NOT NULL REFERENCES relay_accounts(id) ON DELETE CASCADE,
-    project_id    text        NOT NULL,                  -- e.g. continuum-prod-android
-    package_name  text        NOT NULL,                  -- e.g. com.continuum.app.android
-    created_at    timestamptz NOT NULL DEFAULT now(),
-    PRIMARY KEY (account_id, project_id, package_name)
-);
-
-- relay_op_logs: redacted operational/audit log. No tokens, no content.
-CREATE TABLE relay_op_logs (
-    id          bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-    occurred_at timestamptz NOT NULL DEFAULT now(),
-    account_id  text        REFERENCES relay_accounts(id) ON DELETE SET NULL,
-    request_id  text,                                    -- ULID echoed to caller
-    event       text        NOT NULL,                    -- e.g. send.apns, send.fcm, auth.reject, admin.key_issue
-    provider    text,                                    -- 'apns' | 'fcm' | null
-    outcome     text,                                    -- 'accepted' | 'rejected' | 'upstream_error' | ...
-    status_code int,                                     -- caller-facing HTTP status
-    error_code  text,                                    -- caller-facing error.code
-    upstream_reason text,                                -- APNs reason / FCM status (non-sensitive)
-    token_hash  text,                                    -- SHA-256(token) hex, NOT the raw token
-    egress_ip   inet,                                    -- caller egress IP
-    latency_ms  int
-);
-CREATE INDEX relay_op_logs_account_time_idx ON relay_op_logs (account_id, occurred_at DESC);
-CREATE INDEX relay_op_logs_time_idx         ON relay_op_logs (occurred_at DESC);
-```
-
-Notes:
- `relay_op_logs` is the only table written on the hot path besides the throttled `last_used_at`. It carries **no raw token, no payload, no identity** — only a `token_hash` (SHA-256 hex) for correlating repeated failures to one device without storing the token (reference §4.6). Retention: see §13.
- No table stores APNs/FCM device tokens, notification content, user/profile IDs, or token aliases — by design (`00` "Its database holds only…").
-
-### 8.2 API-key format, hashing, lookup, compare
-
- **Format:** `rk_<env>_<random>`. The **prefix** = `rk_<env>_<first 6–8 chars of the random>` is **non-secret**, stored in cleartext, and uniquely indexed (`key_prefix`). The full random part is 32 bytes from `crypto/rand`, base62/base64url-encoded. GitHub/Stripe-style design — lets a request `SELECT` by indexed prefix in O(1), then constant-time-compare (reference §4.1).
- **Hashing:** store `HMAC-SHA256(pepper, secret)` (32 bytes) where `pepper` is a server-side secret in the secret manager. A fast keyed hash is appropriate for **high-entropy 256-bit random keys** — OWASP's slow-KDF (argon2id) guidance is scoped to low-entropy passwords and would needlessly throttle per-request auth (reference §4.1). Never store plaintext.
- **Lookup + compare on each request (constant-time regardless of whether the prefix exists):**
-  1. Parse `Authorization: Bearer rk_<env>_<rest>`; reject malformed → `401 unauthorized`.
-  2. Derive `key_prefix` from the token; `SELECT … FROM relay_api_keys WHERE key_prefix = $1` (unique index).
-  3. If no row, or `revoked_at IS NOT NULL`, or `expires_at < now()`, or the account is `disabled` → still perform a **dummy `HMAC-SHA256` against a fixed decoy hash with `crypto/subtle.ConstantTimeCompare`**, then return the uniform `401 unauthorized` (do not distinguish reasons to the caller). **Do not short-circuit before the HMAC+compare** — an unknown prefix must take the same time as a known prefix with a wrong secret, or the timing difference is a key-enumeration oracle (a known/live prefix would otherwise reject measurably faster). The fine-grained `reason` (`unknown_prefix`/`hash_mismatch`/…) is kept **only in internal logs and the internal-only `/metrics`** (§13.2), never surfaced to a tenant or an untrusted scraper.
-  4. Compute `HMAC-SHA256(pepper, presented_secret)` and `crypto/subtle.ConstantTimeCompare` against `key_hash` (or the decoy). Mismatch → `401`. Never use `==`/`bytes.Equal` on secret material (reference §4.1).
-  5. Throttle-update `last_used_at` (at most once per minute per key). **The throttle clock lives in Redis** (`lastused:{key_prefix}` set `NX EX 60`) so the "≤1/min/key" bound holds **cross-replica** (a per-instance clock would allow N writes/min/key across N replicas); only when that `NX` succeeds does the relay issue the Postgres `UPDATE`. The Redis key carries no secret. This avoids a Postgres write per request (reference §4.1) without leaking a per-key validity side channel through DB write cadence.
- **Rotation:** multiple live keys per account are supported (issue a new key, deploy it on the server, then revoke the old) for zero-downtime rotation (reference §4.1).
- **Client-IP resolution (trusted-proxy requirement).** The relay runs **behind a TLS load balancer** (§4.2, §14.1), so Go's `http.Request.RemoteAddr` is the LB/proxy address, not the caller. The relay derives the client IP as follows: **use `RemoteAddr` unless the immediate peer is in the allowlisted trusted-LB CIDR set, in which case take exactly the right-most untrusted hop from the LB-set forwarding header (`X-Forwarded-For`)**. **Caller-supplied forwarding headers are ignored** — a caller cannot set `X-Forwarded-For`/`X-Real-IP` to forge an IP. The trusted-proxy CIDR list is a **config value**. Both the per-IP auth-failure limiter and the op-log `egress_ip` consume this single resolved IP. (Without this, a caller could either spread brute-force across unlimited fake IPs to defeat the per-IP throttle (OWASP API2:2023) and poison `egress_ip`, or — if `RemoteAddr` were trusted blindly behind the LB — collapse every tenant onto one IP and trip the throttle for all at once.)
- **Anti-brute-force — per-IP auth-failure limiter (specified).** Auth failures are rate-limited **per resolved client IP** (independent of the per-account bucket) to blunt key-guessing (OWASP API2:2023, reference §4.1). Concretely:
-  - **Store:** Redis, key `authfail:{client_ip}`, sliding/fixed window with `EXPIRE`.
-  - **Window / threshold:** e.g. **20 failures / 5 min** per IP (tunable).
-  - **Response on breach — *soft* lockout, not a hard block:** added latency / a `429` with `Retry-After` (e.g. 60 s backoff) rather than dropping the connection. This is deliberate because the doc anticipates **VPN/CGNAT shared egress** (§3.4): multiple self-hosted servers can share one egress IP, so a hard per-IP block would be collateral damage from a noisy/compromised neighbor. Optionally scope tracking by `(key_prefix, IP)` to further isolate neighbors.
-  - **Fail-open/closed stance:** this limiter **fails open** if Redis is unreachable (availability over a perfectly-enforced anti-guessing cap), logging `authfail_limiter.degraded`. The hard auth boundary (HMAC compare, allowlist) is always enforced from Postgres regardless.
-  - **Metric + runbook:** `relay_auth_failures_total{reason=…}` (internal only) plus a documented response runbook for the key-guessing alert (R8, §6.4 monitoring): inspect the offending IP/prefix, confirm whether a single account or a guessing pattern, revoke/rotate as needed.
-
-### 8.3 The `rk_` token is shown exactly once
-
-`relayctl key issue` prints the full `rk_…` token to stdout **once**; only the HMAC hash and prefix are persisted. There is no endpoint or command that can recover a secret. Lost keys are revoked and re-issued.
-
-### 8.4 Allowlist enforcement
-
-Enforced **after** auth, **before** building the upstream payload:
-
- **APNs (`/v1/apple/send`):** the request `topic` must exist in `relay_apns_allowlist` for the caller's `account_id`. Not present → `403 topic_not_allowed`. The official build config allowlist (allowlist config, **not** part of the contract) is the set `com.continuum.app.ios`, `com.continuum.app.tvos`, `com.continuum.app.macos` (`02` resolved-questions: per-platform topics).
- **FCM (`/v1/fcm/send`):** the `(project_id, package_name)` pair must exist in `relay_fcm_allowlist` for the caller's `account_id`. Missing project → `403 project_not_allowed`; project present but package not → `403 package_not_allowed`. Official build config: project `continuum-prod-android`, package `com.continuum.app.android`.
- Allowlists are loaded per request from Postgres (cheap, small) or from a short-TTL in-memory cache keyed by `account_id` (invalidated on `relayctl allowlist … set`). The cache must be per-account-scoped so one account's allowlist can never authorize another's push.
-
-These are **allowlist config values**, set by `relayctl`, not part of the external wire contract — a different deployment (e.g., a fork) would set different topics/packages.
-
-> **Environment ⇄ token consistency (operational caveat).** The allowlist does **not** (and cannot) verify that the request `environment` matches the environment the device `token` was minted for. A `sandbox`-vs-`production` mixup presents downstream as APNs `BadDeviceToken`/`InvalidToken` → `422 bad_device_token` (§6.4), which would otherwise tell the caller to purge a perfectly good token. To let operators catch a **systemic** misconfiguration, the relay emits a distinct op-log/metric tag for these so a burst of `bad_device_token` concentrated on **one account** (likely an env mixup) is distinguishable from scattered genuinely-dead tokens across many accounts. The cross-field rule is documented in §5.1 and §6.4.
-
---
-
-## 9. Rate Limiting and Quotas
-
-### 9.1 Model
-
-Per-account **token bucket** enforced in Redis with an atomic Lua script (refill → check → consume in one `EVAL`), state stored as a HASH `rl:{account_id} = {tokens, last_refill_ts}` with a TTL for idle-account eviction (reference §4.2). A Redis-backed limiter (not per-instance `x/time/rate`) is required because the relay runs multiple replicas behind a load balancer — per-instance limiters would not enforce a global cap.
-
-A second, coarser limiter keys on `(account_id, token_hash)` to blunt hammering a single device (the `02`/`03` "rate limited by API key and coarse token hash" requirement).
-
-**Redis operational requirements (eviction, HA, sizing).** Redis backs both idempotency (fail-closed) and rate limiting (fail-open), so its configuration is correctness-relevant, not just performance:
-
- **Non-evicting policy for idempotency.** The idempotency keyspace **must** run under `maxmemory-policy noeviction` (or live in a **dedicated Redis/db** separate from the rate-limit keyspace) so that memory pressure can **never silently evict an in-flight idempotency lock** — an evicted lock would silently violate at-most-once (a concurrent retry would get `NX`-success and double-send). Rate-limit keys may be evicted harmlessly; idempotency keys must not. This is called out in risks R4/R5.
- **HA topology.** Run Redis with an HA topology (Sentinel or Cluster) with prompt failover. A Redis failover/restart makes **every** send `503` while idempotency fails closed (§10) — a push-delaying, not push-losing, event (the caller outbox retries), **but only as long as idempotency stays fail-closed**. A Redis outage should **page ops**.
- **Keyspace sizing.** Size the idempotency keyspace from the quota math: ~`50k/day/account × N accounts`, each entry holding `{status, body, upstream_id, canonical_hash}` under a ~24 h TTL. Provision `maxmemory` with headroom above that working set so `noeviction` never starts rejecting writes.
-
-### 9.2 Suggested limits (ties to `00` open question #1)
-
-| Limit | Default | Source / rationale |
-|---|---|---|
-| Per-account burst | **~10 req/s** | `00` open question #1 ("Suggest 10 req/sec burst") |
-| Per-account daily quota | **50,000 req/day** | `00` open question #1 ("50,000 req/day initial quota") |
-| Bucket refill rate | 10 tokens/s, burst capacity 20 | derived from the 10 req/s target with a small burst allowance |
-| Per-(account, token) coarse cap | e.g. 1 req/3 s sustained | abuse guard on a single device |
-
-These are tunable per account (future column on `relay_accounts`); v1 ships a single global default and tunes from logs (`00`). The Silo server already paces its calls client-side (default 5 req/s shared token bucket — `02`/`03` "Relay pacing"), so a well-behaved caller stays comfortably under the 10 req/s burst; the relay limit is the backstop against a misbehaving or compromised caller (OWASP API4:2023 — cap per-tenant downstream spend).
-
-**Daily-quota mechanics (store, reset, fail-open).** The per-second token bucket (§9.1) does **not** model the 50,000 req/day cap; the daily counter is a **separate Redis counter** keyed `rl:day:{account_id}:{yyyymmdd}` with an `EXPIRE` past the day boundary, incremented atomically per accepted send:
-
- **Reset semantics:** a **fixed UTC calendar day** (the `{yyyymmdd}` is UTC), not a rolling 24 h — simple, predictable for operators, and the key self-expires.
- **Breach:** when the counter reaches 50,000 the account's sends return `429 rate_limited` for the rest of the UTC day with a `Retry-After` = seconds until 00:00 UTC. Daily exhaustion blocks **all** of an account's pushes until reset — a notable availability event, so it is **alerted** (see below), not silent.
- **Fail-open during a Redis outage:** like the per-second bucket, the daily counter **fails open** if Redis is unreachable — but this is exactly the abuse-amplification window, so it is **bounded** by the in-process fallback limiter in §9.4 (a compromised key cannot burn unlimited upstream sends during the outage) and the outage pages ops. The daily quota **cannot be enforced cross-replica while Redis is down**; that limitation is explicit.
- **Alerting:** a metric/alert fires for accounts **approaching** (e.g. ≥80%) or **hitting** the daily cap, since a legitimate hundreds-of-users server can plausibly hit 50k/day on a big release burst — operators should see this and raise the cap rather than have the account silently throttle. Reconcile the 50k/day default against the `02`/`03` burst-cap math when tuning.
-
-### 9.3 429 response
-
-On limit exceeded the relay returns:
-
-```http
-HTTP/2 429
-Retry-After: 3
-Content-Type: application/json
-X-Request-Id: 01JRELAY...
-
-{ "error": { "code": "rate_limited",
-             "message": "account rate limit exceeded",
-             "request_id": "01JRELAY..." } }
-```
-
-`Retry-After` is a **relative `delay-seconds`** integer (never an absolute Unix epoch — reference §4.2), computed from the bucket's time-to-next-token. The daily-quota breach also returns `429 rate_limited` with a longer `Retry-After` (seconds until the daily window rolls).
-
-### 9.4 Fail-open vs fail-closed (bounded, not unlimited)
-
-If Redis is unreachable, the rate-limit middleware **fails open** for availability (a push is more valuable than a perfectly enforced cap), but **bounded** — it does **not** simply remove the cap. When Redis is down the relay falls back to a **conservative per-instance in-process limiter** (`golang.org/x/time/rate`, keyed per `account_id`) that caps each account to a small multiple of its normal rate. This matters because the per-account quota is the primary control bounding a **stolen-key** attacker's spend and per-tenant downstream APNs/FCM cost (OWASP API4:2023, §3.5 "Stolen relay API key", G6): an unbounded fail-open would let a compromised `rk_` key send without limit against the official Apple/Google credentials — including burning the shared FCM project quota (§9.5) common to all tenants — for the entire outage. The **allowlist (always enforced from Postgres)** remains the hard boundary. A `rate_limit.degraded` op-log + metric fires; the **daily quota cannot be enforced cross-replica** during the outage, and an outage **pages ops**. The idempotency layer (§10), by contrast, **fails closed** to avoid double-sends. (Reference §4.2 — explicitly a per-endpoint decision.)
-
-### 9.5 Shared FCM project quota — global limiter / circuit breaker
-
-The per-account limits above are **local to each account**, but the **FCM project quota (~600k messages/min, reference §2.7) is SHARED across ALL relay accounts** sending to `continuum-prod-android`. Without a relay-side guard, one noisy/compromised account can exhaust the shared project quota and every other account's sends start returning `429 QUOTA_EXCEEDED` — a **multi-tenant fairness** failure (one noisy tenant degrades all). The relay therefore adds a **global (per-project) outbound limiter / circuit breaker** at the aggregation point — the only place that *can* see aggregate FCM rate across accounts:
-
- **(a) Track aggregate FCM send rate** against the documented project quota (a Redis counter keyed per project, e.g. `fcmq:{project_id}:{yyyymmddhhmm}` with a per-minute window).
- **(b) Shed load before hammering FCM:** when near the quota, return `503 upstream_throttled` (retryable) **before** forwarding, rather than spending quota on calls that FCM will reject anyway (some errors still count against quota).
- **(c) Anti-spike smoothing (optional):** honor the reference §2.7 guidance to avoid concentrating traffic in the 2-minute windows around `:00/:15/:30/:45` — the relay, as the cross-account aggregation point, is the only component that can actually implement this ramp.
- **Observability:** a `relay_fcm_project_quota_headroom` gauge plus an alert when headroom is low. This is explicitly a **multi-tenant fairness** control (a single account must not exhaust the shared project quota for all).
-
---
-
-## 10. Idempotency
-
-### 10.1 Key format
-
-`Idempotency-Key: <notification_delivery_id>:<push_device_id>:<attempt_number>` (`02`/`03`). This is **scoped per account** in storage (so two accounts cannot collide). The relay validates the header is present and non-empty on send endpoints; missing → `400 missing_idempotency_key`. The three-part shape is not strictly parsed (it is opaque to the relay), but it is length-limited (≤ 255 chars, Stripe-style — reference §4.3).
-
-### 10.2 Store, TTL, locking, duplicate semantics
-
-Redis, namespaced `idem:{account_id}:{key}` (reference §4.3):
-
-1. `SET idem:{account}:{key} <in_flight_marker> NX EX <lock_ttl>` (`lock_ttl` = 30 s). The `<in_flight_marker>` carries a **unique per-attempt nonce** so the completing request can prove ownership (see invariant below).
-2. **NX success** → this is the first request. Process it; on completion, **compare-and-set**: overwrite the key with the serialized `{status, body, upstream_id, canonical_hash}` and a **~24 h TTL** **only if the stored value is still this request's own in-flight marker** (i.e. the lock was not stolen by a concurrent request after a TTL expiry). Success *and* error are both recorded (reference §4.3 / Stripe model).
-3. **NX fail + stored completed result** → **replay** it: return the original status code and body verbatim (so a retried send returns the same `apns_id`/`fcm_message_name`, never a second upstream send).
-4. **NX fail + still the in-flight marker** → the original is mid-flight → **`409 conflict`** (`{"error":{"code":"idempotency_conflict",…}}`) so the caller retries later.
-5. **Same key, different request payload** → **`422 unprocessable`** (`idempotency_key_reuse`). The relay stores a `canonical_hash` of the request alongside the result and compares (reference §4.3). **The canonical hash is computed over the validated fields with the device `token` replaced by its already-computed `token_hash` (SHA-256) — the raw token is NEVER part of the canonical form.** The stored idempotency value contains only `{status, body, upstream_id, canonical_hash}`; it holds **no raw token** (matching the op-log guarantee §12, NG1). This keeps the "no token aliases / stateless v1" privacy guarantee intact even though the value lives in Redis under `idem:{account}:{key}` for ~24 h.
-
-> **Lock-TTL invariant (no double-send, no result-clobber).** The upstream APNs/FCM call **must run under a hard context deadline strictly shorter than `lock_ttl`** — e.g. **upstream timeout 10 s, `lock_ttl` 30 s** — and the handler **must refuse to send upstream if its own deadline would exceed the lock TTL**. Otherwise a slow first attempt (HTTP/2 setup + JWT/OAuth refresh + GOAWAY-reconnect can stack up) could outlive the 30 s lock; the lock would expire mid-flight, a concurrent retry of the same `Idempotency-Key` would get `NX`-success and fire a **second** upstream send (defeating at-most-once), and when the slow first attempt finally completed it would clobber the stored result with a different `apns_id`. The **compare-and-set on completion** (step 2) prevents the clobber — a lock that was stolen by a concurrent request cannot have its result overwritten by the original — and the **deadline-shorter-than-TTL** rule prevents the double-send in the first place. (Optionally, a lock heartbeat may renew the marker while genuinely in flight, but the deadline rule is the primary guarantee.) This invariant is the whole reason the idempotency store exists (R4).
-
-This guarantees **at-most-once upstream send** under the caller's concurrent retries (the `../01-release-events-and-inbox.md` outbox can re-claim and re-dispatch the same `(delivery_id, device_id, attempt_number)`), which is exactly why the key includes `attempt_number`: attempt 2 is a *new* idempotency key (intended re-send after a failure), while two concurrent dispatches of attempt 1 collapse to one upstream call.
-
-### 10.3 What a duplicate returns (summary)
-
-| Situation | Response |
-|---|---|
-| First request | Process; record `{status, body, upstream_id, canonical_hash}` (no raw token — §10.2) for ~24 h. |
-| Duplicate, original completed | Replay stored status + body (same `apns_id`/`fcm_message_name`). |
-| Duplicate, original in-flight | `409 idempotency_conflict`. |
-| Same key, different payload | `422 idempotency_key_reuse`. |
-| Missing key | `400 missing_idempotency_key`. |
-
-Idempotency **fails closed**: if Redis is unavailable, send endpoints return `503 upstream_unavailable` (retryable) rather than risk a double-send (contrast §9.4).
-
---
-
-## 11. Security Requirements
-
- **TLS only.** Public endpoints are HTTPS over HTTP/2; no plaintext listener. TLS 1.2+ (prefer 1.3). HSTS on the public hostname. (`02`/`03` "Relay API uses TLS only".)
- **Secret management.** APNs `.p8`, FCM SA JSON, the API-key HMAC pepper, and DB/Redis credentials live in a **secret manager** (KMS/Vault/cloud secret-manager). Ranking: secret-manager > tightly-permissioned mounted file > env var (**discouraged**) > in-image/repo (**forbidden**) (reference §4.5). On GCP, prefer keyless Workload Identity for FCM and avoid a downloadable SA JSON entirely (reference §4.5). Never commit or bake credentials into the image.
- **Key storage.** API keys stored only as `HMAC-SHA256(pepper, secret)` + non-secret prefix; constant-time compare; revocable; optional expiry; multiple live keys per account for rotation (§8.2). The relay's own `rk_` secret is shown once and never recoverable.
- **No raw secrets in transit out.** No endpoint returns the `.p8`, SA JSON, pepper, or any `rk_` secret. `/metrics` and op-logs carry none.
- **Redaction (enforced in middleware so it cannot be bypassed).** Never log: `Authorization`/bearer header, raw API key (log only the non-secret prefix or a hash), raw APNs/FCM device tokens (log `SHA-256` truncated hash only), notification payload bodies, the relay JWT, or OAuth2 access tokens (reference §4.6; `02`/`03` privacy/security requirements). See §12/§13.
- **Isolation / multi-tenancy.** Every API key, rate-limit bucket, idempotency key, allowlist cache entry, and log line is scoped by `account_id`. Shared-store keys are namespaced (`idem:{account}:…`, `rl:{account}`) to prevent cross-tenant collision or replay (reference §4.7). For APNs, connection pools are per-team (§6.1).
- **Network posture.** `/metrics` and `/readyz` bound to the internal/scrape network; only `/v1/*` and `/healthz` are public. `relayctl` reaches Postgres over a private network with a privileged DSN held by operators only — there is no public admin API (§5.6).
- **Input hardening.** `DisallowUnknownFields`, body size cap (e.g. 16 KiB — far above the ~1 KB legitimate body), explicit server timeouts (`ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout`, `MaxHeaderBytes`) since the zero value means no timeout (reference §3.3). Graceful shutdown via `srv.Shutdown(ctx)` on SIGTERM.
- **Egress / SSRF posture.** Both upstream hosts are **hardcoded constants** — `api.push.apple.com` / `api.sandbox.push.apple.com` (APNs) and `fcm.googleapis.com` (FCM) — **never derived from any request field**. The only request-derived value interpolated into an upstream URL is the FCM `project_id` (into `/v1/projects/{project_id}/messages:send`); it is **allowlist-checked** (§8.4) **and** validated against a strict charset **before** allowlist lookup and URL construction: `project_id` and `package_name` against `^[a-z0-9-]+$` / reverse-DNS, `topic` against the APNs reverse-DNS shape. This ensures an allowlist row can never introduce a path-traversal/host-override and the host can never be templated from caller input (SSRF/path-injection prevention).
- **Anti-brute-force** on auth failures per resolved client IP, with trusted-proxy IP resolution (§8.2).
-
---
-
-## 12. Privacy Requirements
-
-The relay's privacy guarantee is **structural**, not policy-based: the request schema has no field that can carry content, and unknown fields are rejected.
-
- **Content-free guarantee.** The send-endpoint structs contain only the fields in §5.1/§5.2. There is **no** title, body, image URL, media ID, username, server hostname, server URL, library/collection/item name, or watched-state field (`02`/`03` privacy requirements). The relay-built payloads use only generic localization keys (`SILO_NOTIFICATION_TITLE` / `SILO_NOTIFICATION_GENERIC_BODY`) and opaque IDs.
- **Reject any unexpected field.** JSON decoding uses `DisallowUnknownFields`; any field not in the schema → `400 unexpected_field`. This is the enforcement point for the content-free guarantee — a caller (buggy or hostile) cannot smuggle content through an extra key.
- **Badge disabled by default.** `badge` is omitted unless explicitly provided, so unread counts don't leak through APNs/FCM by default (`02`/`03`).
- **FCM is data-only with a closed key set.** No top-level `notification` block is ever constructed, so Google carries no rendering content (`03`). The `message.data` map is a **fixed, closed set of keys** — exactly `{v, wake, server_device_id, delivery_id}` — with **no caller-controlled key or value** beyond the already-opaque IDs (§5.2). `badge` is **never** injected into `data` (it has no data-only home and is ignored on the FCM path — §5.2), so the data-map allowlist cannot be widened by a provided badge or any extra key.
- **No raw token in any store.** Neither the op-log nor the idempotency store holds a raw device token: the op-log carries only `token_hash` (SHA-256), and the idempotency value's `canonical_hash` is computed with the token replaced by `token_hash` (§10.2). The stateless-v1 "no token aliases" guarantee (NG1) holds across both stores.
- **Redacted logging.** Op-logs and structured logs **never** contain: raw device tokens (only `SHA-256` hash), notification content (none exists), the `Authorization` header, the relay JWT, OAuth2 tokens, or the raw API key (only the prefix). Full request payloads are never persisted (`02`/`03` "Relay logs do not persist full request payloads"). What **is** logged for triage: `request_id`, `account_id`, status code, caller `error.code`, upstream reason, `token_hash`, egress IP, latency (reference §4.6).
- **No identity storage.** The relay stores no user/profile identity, no device→user mapping, no server URL, and no token aliases (`00`).
-
---
-
-## 13. Observability
-
-### 13.1 Structured logs (with redaction)
-
-`log/slog` JSON handler (reference §3.5). Every request emits one structured line through a redaction middleware that strips the disallowed fields (§12). Example (a rejected, allowlist-failed APNs send):
-
-```json
-{
-  "time": "2026-06-13T10:00:00Z",
-  "level": "WARN",
-  "msg": "send.apns rejected",
-  "request_id": "01JRELAY...",
-  "account_id": "01JACCOUNT...",
-  "provider": "apns",
-  "event": "send.apns",
-  "outcome": "rejected",
-  "status_code": 403,
-  "error_code": "topic_not_allowed",
-  "token_hash": "9f86d081...c2b5",
-  "egress_ip": "203.0.113.7",
-  "latency_ms": 2
-}
-```
-
-Redaction is implemented in middleware so no code path can log a raw token, the bearer header, the JWT, or an OAuth2 token. The redacted audit subset also lands in `relay_op_logs` (§8.1) for queryable history. **Op-log retention:** successful sends **>14 days** are deleted; failures/upstream errors **>90 days** are deleted (mirrors the `02`/`03` `push_delivery_attempts` retention guidance). At 50k/day/account this table grows unbounded without active GC, so retention is a **shipped deliverable, not a deferral** — enforced by a scheduled sweeper / `relayctl logs --gc` (specified in `01-implementation-plan.md` Phase 5), with a disk-usage / table-growth alert. Time-partitioning of `relay_op_logs` is the recommended store strategy; see §15 #8.
-
-### 13.2 Metrics catalog (Prometheus, `/metrics`)
-
-`prometheus/client_golang` (reference §3.5). Labels avoid high-cardinality fields (no token, no `request_id`).
-
-| Metric | Type | Labels | Meaning |
-|---|---|---|---|
-| `relay_requests_total` | counter | `provider`, `endpoint`, `status_code`, `error_code` | All inbound send requests by outcome. |
-| `relay_request_duration_seconds` | histogram | `provider`, `endpoint` | End-to-end relay latency. |
-| `relay_upstream_requests_total` | counter | `provider`, `upstream_status`, `upstream_reason` | APNs/FCM calls by upstream result. |
-| `relay_upstream_duration_seconds` | histogram | `provider` | Upstream call latency. |
-| `relay_auth_failures_total` | counter | `reason` (`bad_format`,`unknown_prefix`,`hash_mismatch`,`revoked`,`expired`,`account_disabled`) | Auth rejections. **`/metrics` is internal/scrape-only** — the `reason` split (which distinguishes `unknown_prefix` from `hash_mismatch`) must **never** be exposed to a tenant or untrusted scraper, or it becomes a key-enumeration oracle paired with the constant-time auth path (§8.2). |
-| `relay_rate_limited_total` | counter | `account_id`(low-card, hashed/bucketed if needed), `kind` (`account`,`token`) | 429s emitted. |
-| `relay_rate_limit_degraded_total` | counter | — | Fail-open events when Redis is down (§9.4). |
-| `relay_idempotency_total` | counter | `result` (`first`,`replay`,`conflict`,`reuse`) | Idempotency decisions. |
-| `relay_apns_jwt_refresh_total` | counter | `result` (`scheduled`,`expired_retry`,`throttled`) | JWT lifecycle (§6.1). |
-| `relay_fcm_token_refresh_total` | counter | `result` | OAuth2 token refreshes (§7.1). |
-| `relay_redis_up` / `relay_pg_up` | gauge | — | Core dependency health (drives `/readyz` — §5.4). |
-| `relay_provider_healthy` | gauge | `provider` | Per-provider init/circuit-breaker health (`1` healthy / `0` degraded) — does **not** gate `/readyz` (§5.4). |
-| `relay_provider_credential_healthy` | gauge | `provider` | Synthetic credential-validation result (§13.4); `0` triggers the credential alert. |
-| `relay_fcm_project_quota_headroom` | gauge | `project_id` | Remaining headroom against the shared FCM project quota (§9.5). |
-| `relay_daily_quota_used_ratio` | gauge | `account_id`(low-card/bucketed) | Fraction of the 50k/day cap consumed; alerts ≥80% (§9.2). |
-| `relay_connection_severed_total` | counter | `provider` | Sends mapped to `503` by GOAWAY/connection reset before a final response (§6.4). |
-| `relay_authfail_limiter_degraded_total` | counter | — | Per-IP auth-failure limiter fail-open events (§8.2). |
-
-### 13.3 Admin diagnostics
-
-`relayctl` provides read paths for operators (no raw secrets/tokens): `account list`, `key list`, `allowlist show`, and a `relayctl logs --account <id> [--since …] [--outcome rejected]` that queries `relay_op_logs` (redacted by construction). A `relayctl ping-upstream --provider apns|fcm --env sandbox` performs a credential-only health check (JWT sign / token mint, optionally an FCM `validateOnly:true` send) without sending real content — useful after a credential rotation. The same check captures the sandbox `apns-unique-id` (§5.1) when APNs returns one.
-
-### 13.4 Credential health, validation and rotation alerting
-
-Credentials can be revoked or rotated **out from under the relay** at any time — Apple "actively monitors and revokes leaked `.p8` keys" (`00`), and FCM SA keys / Workload-Identity bindings can be disabled. Relying only on production sends starting to fail (upstream `403 InvalidProviderToken` / the relay's own `401 UNAUTHENTICATED` / `403 PERMISSION_DENIED`) is too late. The relay therefore validates credentials **proactively**, distinguishing an **auth-layer** failure from a mere token-layer rejection:
-
- **Startup + periodic synthetic validation.** On startup and on a periodic timer, the relay exercises the auth layer end-to-end: an FCM `validateOnly:true` send, and an APNs send to a **known-bad token** that still forces APNs to authenticate the JWT (so an auth-layer `403 InvalidProviderToken`/`BadCertificate*` is distinguishable from a token-layer `400 BadDeviceToken` — the latter proves the credential is *accepted*). Note `/readyz` alone is **insufficient**: it only proves a JWT was **signed locally** / a token **minted**, not that APNs/FCM **accept** the credential.
- **`credential healthy` gauge.** Wire the synthetic-validation result into a per-provider `relay_provider_credential_healthy` gauge (§13.2) and surface it on the per-provider readiness signal (§5.4).
- **Continuous health via cron.** Schedule `relayctl ping-upstream` (e.g. a cron / scheduled run) for continuous credential health between restarts.
- **Alert on first auth failure.** Alert on the **first** `upstream_auth_error` (the relay's own credential signals — §6.4/§7.4), not after a sustained failure rate, since a revoked credential fails *all* sends immediately.
-
---
-
-## 14. Deployment and Operations
-
-### 14.1 Public endpoint & TLS
-
- One public hostname, `relay.silo.app`, terminating TLS (1.2+, prefer 1.3) at a load balancer or in-process. HTTP/2 end to end. Only `/v1/apple/send`, `/v1/fcm/send`, and `/healthz` are public; `/readyz` and `/metrics` are internal-only.
- Set explicit server timeouts and graceful shutdown (§11).
-
-### 14.2 High availability — "relay-down delays, never loses"
-
-The relay being down does **not** lose pushes: the self-hosted server's dispatch is an **outbox**. The fanout transaction in `../01-release-events-and-inbox.md` inserts `pending` `push_delivery_attempts` rows in the same transaction as the `notification_deliveries` row; the dispatcher claims them post-commit and a recovery sweeper re-claims stale `pending` rows (`00`/`02`/`03`). So if the relay returns `503`/times out, the caller marks the attempt `retrying` and retries with backoff — the durable inbox row and the outbox attempt row guarantee eventual delivery. **This means the relay can be operated with ordinary HA (multiple stateless replicas, rolling deploys) rather than five-nines durability.** A short relay outage only delays pushes.
-
- **Stateless replicas.** No in-memory request state that can't be reconstructed; idempotency and rate-limit state are in Redis, shared across replicas. Scale horizontally behind the LB.
- **Rolling deploys / kill-safety.** A replica can be drained (`srv.Shutdown`) or killed mid-request; the caller retries the same idempotency key, which either replays the recorded result or re-sends at-most-once (§10).
- **Drain ordering (no orphaned idempotency locks).** A clean drain must not turn into a 30 s stall per retry. On `SIGTERM`: (1) flip `/readyz` to `503` so the LB **stops routing new requests** to this replica; (2) keep serving **in-flight** handlers; (3) bound the `srv.Shutdown` grace period to **less than the idempotency `lock_ttl`** (§10.2) — and/or **release/downgrade the in-flight idempotency marker on handler context-cancellation** — so that a send killed mid-flight does **not** leave a stale 30 s `in_flight` marker in Redis. Otherwise the caller's immediate retry hits §10.2 case 4 and gets `409 idempotency_conflict` for up to `lock_ttl` seconds. The relationship between the shutdown grace period and `lock_ttl` is load-bearing and is asserted by a drain test (no orphaned in-flight markers after a rolling restart — see `01-implementation-plan.md`).
-
-### 14.3 Secret provisioning
-
- Provision the APNs `.p8` (+ Team ID, Key ID) and FCM SA JSON (or Workload Identity binding) into the secret manager out-of-band. The HMAC pepper and DB/Redis creds likewise. Never in the image or repo (§11).
- **Credential rotation runbook (overlap window, dual-key).** Apple permits **multiple active `.p8` keys per team**, and the relay already keys connection pools by team (§6.1), so rotation is **make-before-break**: (1) provision the new credential into the secret manager alongside the old; (2) load both — the relay supports an **overlap window** where old and new keys are both valid and the key-selection map (§6.1) can resolve to either; (3) run `relayctl ping-upstream` / the synthetic validation (§13.4) to confirm the **new** credential authenticates against APNs/FCM; (4) cut sends over to the new key (rolling restart picks up the new secret); (5) retire/revoke the old credential only after the new one is confirmed healthy. The same overlap pattern applies to FCM SA keys / Workload-Identity bindings. This avoids the failure mode where a single-key rotation revokes the old credential before the new one is proven, taking all pushes down.
-
-### 14.4 Sandbox vs production
-
- The relay supports both APNs environments via the request `environment` field, routing to `api.push.apple.com` (production) or `api.sandbox.push.apple.com` (sandbox) (§6.2). FCM has a single global host (no sandbox split — reference §2.3); test sends use `validateOnly:true` (reference §2.5).
- A **staging relay deployment** (separate hostname, separate accounts) is recommended for client QA so test traffic never touches production accounts/quotas.
-
-### 14.5 Scaling & regions
-
- **Scaling.** One well-tuned APNs HTTP/2 connection handles thousands of pushes/sec (reference §1.3/§3.1); one FCM token source serves the project. The bottleneck at relay scale is inbound throughput and Redis, both horizontally scalable. Keep upstream clients **process-singletons** (one per env/team/project), not per-request.
- **Regions.** APNs and FCM are global; FCM has no data-residency send endpoints (reference §2.3). v1 runs a single region close to the operator's Postgres/Redis. Multi-region is possible later (the request path is stateless; Redis/Postgres would need regional strategy) but is out of scope for v1.
- **Quota awareness.** FCM's default project quota is ~600k messages/min (reference §2.7); the relay's per-account 50k/day default (§9.2) is far under that even summed across many accounts. The **shared** project quota is nonetheless guarded by the relay-side global limiter / circuit breaker (§9.5) so one noisy account cannot exhaust it for all tenants; operators monitor `relay_fcm_project_quota_headroom` (§13.2), the project quota in Cloud Console, and `relay_upstream_requests_total{upstream_reason="QUOTA_EXCEEDED"}`.
-
---
-
-## 15. Open Questions
-
-1. **Per-account rate limits — real numbers.** v1 ships the `00`-suggested ~10 req/s burst + 50k/day defaults (§9.2); tune from production logs. Should limits become per-account columns on `relay_accounts` with `relayctl quota set`? (Ties to `00` open question #1.)
-2. **APNs sandbox hostname (resolved — note only).** `api.sandbox.push.apple.com` and `api.development.push.apple.com` are **interchangeable, both-resolving** Apple sandbox aliases; the relay standardizes on `api.sandbox.push.apple.com` (reference §1.3, reference open question §5 item 4). The external contract (`"environment":"sandbox"`) is unaffected either way. No build-time decision required.
-3. **`apns2` vs hand-rolled APNs client.** `sideshow/apns2` has had no release since v0.25.0 (Oct 2024) — bus-factor risk. Decide before implementation: adopt `apns2` or hand-roll `net/http2` + `golang-jwt/jwt/v5` (reference §3.1, §5.2).
-4. **FCM credentials: GCP-keyless vs off-GCP JSON.** If the relay runs on GCP, use Workload Identity / attached SA (no downloadable key); off-GCP, the SA JSON lives in the secret manager. Resolve in the deployment design (reference §4.5 / §2.2).
-5. **`apns-expiration` / `android.ttl` default values (resolved; tune from product input).** v1 **ships finite defaults** — `apns-expiration` ~4 h for `private_alert` / ~1 h for `background_wake`, and the parallel FCM `android.ttl` (§5.1/§5.2) — rather than the 30-day APNs / 4-week FCM store-and-retry, so stale wakes don't fire days later. The exact durations are configurable and may be tuned with product input (reference §1.4).
-6. **API-key hashing: HMAC pepper vs plain salted SHA-256.** This spec chooses HMAC-SHA-256 with a secret-manager pepper for defense-in-depth. Pepper rotation is operationally heavier (re-hash all keys or support dual peppers). Confirm the tradeoff (reference §4.1, open question §12).
-7. **Idempotency-Key spec status.** The IETF draft expired 2026-04-18 without becoming an RFC; the header name + Stripe-style semantics are de-facto standard. Re-check for an RFC before relying on its exact status-code semantics (reference §4.3).
-8. **Op-log volume & retention.** At 50k/day/account across many accounts, `relay_op_logs` grows unbounded without GC. v1 **ships** the retention sweep (delete success >14 d, failure >90 d — §13.1) as a scheduled `relayctl logs --gc` / built-in sweeper (`01-implementation-plan.md` Phase 5), with a table-growth alert. Open: whether to **time-partition** `relay_op_logs` (recommended) or offload to a log pipeline rather than Postgres at higher volume.
-9. **Multi-region.** Out of scope for v1 (single region). If latency to distant self-hosters matters, design a regional Redis/Postgres strategy for the otherwise-stateless request path.
-10. **FCM priority deprioritization.** The relay honors `03`'s `priority: high` for `private_data`. If FCM deprioritizes Silo's app-instance traffic over the 7-day window (reference §2.8), is any relay-side change warranted, or is this purely the caller's `priority: normal` fallback concern? Lean: caller's concern; revisit if metrics show systematic deprioritization.
@@ -1,738 +0,0 @@
-# Silo Push Relay — Implementation Plan
-
-**Date:** 2026-06-13
-**Status:** Draft (implementation-grade, phased)
-**Service:** `silo-push-relay` (provisional repo name; the relay code lives in a **separate repository**)
-**Provisional hostname:** `relay.silo.app`
-**Stack:** Go 1.25+, PostgreSQL, Redis
-
-**Source documents (read before executing any phase):**
-
- [`./00-relay-spec.md`](./00-relay-spec.md) — the engineering spec this plan implements. Section numbers below (e.g. "spec §6.4") refer to it.
- [`./02-apns-fcm-2026-reference.md`](./02-apns-fcm-2026-reference.md) — 2026-current Apple/Google/Go reference (cited as "reference §N").
- [`../02-apns-relay.md`](../02-apns-relay.md) and [`../03-fcm-relay.md`](../03-fcm-relay.md) — the **authoritative external wire contract** (the `02`/`03` request/response shapes). The relay must honor these byte-for-byte.
-
-> **Commands assume the repository root is the cwd.** This document contains no local absolute filesystem paths or transient worktree IDs; all repo references are repository-relative.
-
-> **Repo boundary.** This plan describes a **separate repository** (`silo-push-relay`). The design docs are authored here in `silo-server` purely for co-location with the `02`/`03` contracts. The relay **code** lives elsewhere. The one deliberate coupling is the shared `pushwire` payload-builder package, mirrored into both repos (see §3 and Phase 3/4).
-
---
-
-## 1. Overview
-
-### 1.1 What is being built
-
-A small, **stateless-on-the-request-path** Go HTTP service that holds the official Silo Apple (`.p8` APNs auth key) and Google (Firebase service-account JSON) push credentials, accepts authenticated **content-free** push requests from opted-in self-hosted Silo servers on two endpoints, builds a fixed generic APNs/FCM payload, forwards it upstream, and maps the upstream result back to a narrow caller-facing response.
-
-The two send endpoints and their contract are fixed by `02`/`03` and reproduced in spec §5:
-
-| Endpoint | Purpose | Authoritative contract |
-|---|---|---|
-| `POST /v1/apple/send` | Forward one opaque push to APNs for one device token | `../02-apns-relay.md`, spec §5.1 |
-| `POST /v1/fcm/send` | Forward one opaque data-only push to FCM for one device token | `../03-fcm-relay.md`, spec §5.2 |
-| `GET /healthz` | Liveness (public) | spec §5.3 |
-| `GET /readyz` | Readiness incl. PG/Redis core deps + per-provider credential health (internal) | spec §5.4 |
-| `GET /metrics` | Prometheus exposition (internal) | endpoint spec §5.4; metric catalog §13.2 |
-
-Administration is a CLI (`relayctl`) that writes directly to the relay's PostgreSQL — **there is no public admin HTTP API** in v1 (spec §5.6).
-
-### 1.2 The v1 cut line
-
-**In scope (v1):**
-
- `POST /v1/apple/send` and `POST /v1/fcm/send` exactly per `02`/`03`.
- Bearer auth (`rk_` keys), per-account allowlists, Redis token-bucket rate limiting, Redis idempotency.
- APNs token-based (ES256 `.p8`) client with cached JWT; FCM HTTP v1 client with cached OAuth2 token.
- PostgreSQL storage of accounts/keys/allowlists/redacted op-logs only; Goose-style migrations.
- `relayctl` admin CLI; structured redacted logs; Prometheus metrics; `/healthz` + `/readyz`; graceful shutdown.
- Single region, multiple stateless replicas behind a TLS load balancer.
-
-**Explicitly out of scope (v1)** — from spec §2.2 / NG1–NG7:
-
- Token→user aliases, device subscriptions, any user/profile identity (stateless v1).
- Arbitrary APNs/FCM JSON, custom titles/bodies, topic/condition broadcasts, badge-by-default.
- Delivery receipts, analytics, open-tracking.
- APNs broadcast / Live Activity channels (`/4/broadcasts/...`).
- Web Push, HMS, ADM, or any non-APNs/non-FCM transport.
- A public self-service signup / billing surface.
- The `custom_apns` / `custom_fcm` direct paths (those run inside `silo-server`).
- Multi-region (the request path is stateless, but Redis/Postgres regional strategy is deferred).
-
-### 1.3 The real long pole: provider account provisioning
-
-**Apple/Firebase account provisioning is the critical-path dependency, not the code.** Obtaining the official Apple Developer team, generating a `.p8` APNs auth key (Key ID + Team ID), registering per-platform bundle topics, standing up the Firebase project(s), and minting a service-account JSON can take days-to-weeks of organizational/approval lead time and is **fully decoupled from coding**.
-
-> **Action: start the §7 provisioning checklist on day 1, in parallel with Phase 0.** Phases 0–2 (scaffold, storage, auth/rate-limit/idempotency) need **no** live provider credentials and can complete entirely against fakes and contract tests. Only Phase 3 (APNs integration tests against sandbox) and Phase 4 (FCM `validateOnly`) are gated on credentials. If provisioning slips, the code still reaches "everything but live upstream" without blocking.
-
-```mermaid
-flowchart LR
-  subgraph Track A — Code
-    P0[Phase 0\nscaffold] --> P1[Phase 1\nstorage] --> P2[Phase 2\nauth/RL/idem]
-    P2 --> P3[Phase 3\nAPNs]
-    P2 --> P4[Phase 4\nFCM]
-    P3 --> P5[Phase 5\nobservability]
-    P4 --> P5
-    P5 --> P6[Phase 6\nharden+deploy]
-  end
-  subgraph Track B — Provisioning (parallel, long pole)
-    A1[Apple team + .p8 + topics]
-    G1[Firebase project + SA JSON + package]
-  end
-  A1 -. gates .-> P3
-  G1 -. gates .-> P4
-  A1 -. gates .-> P6
-  G1 -. gates .-> P6
-```
-
---
-
-## 2. Repository Bootstrap
-
-### 2.1 Go module path
-
-```
-module github.com/silo-app/silo-push-relay
-```
-
-Target **Go 1.25+** (required by `jackc/pgx v5.10` and `firebase.google.com/go/v4 v4.20`; reference §3 version-targeting note). Pin in `go.mod` with `go 1.25`.
-
-### 2.2 Directory layout
-
-```
-silo-push-relay/
-├── cmd/
-│   ├── relay/                  # main HTTP service entrypoint (wires config → stores → clients → server)
-│   │   └── main.go
-│   └── relayctl/               # admin CLI (account/key/allowlist/logs/ping-upstream); writes directly to PG
-│       └── main.go
-├── internal/
-│   ├── config/                 # env + secret-manager config loading, validation, defaults
-│   ├── httpapi/                # router, handlers, middleware (auth, rate limit, idempotency, redaction), error bodies
-│   ├── apns/                   # APNs upstream client: ES256 JWT lifecycle, HTTP/2 pool, reason→error mapping
-│   ├── fcm/                    # FCM upstream client: OAuth2 token source, HTTP/2 client, status→error mapping
-│   ├── accounts/              # data-access for accounts/keys/allowlists (shared by httpapi + relayctl)
-│   ├── ratelimit/              # Redis Lua token-bucket limiter (per-account + coarse per-token)
-│   ├── idempotency/            # Redis SET NX lock / replay / 409 / 422 store
-│   ├── pushwire/               # SHARED payload builders (APNs + FCM payload/header construction) — mirrored into silo-server
-│   ├── oplog/                  # redacted op-log writer (PG) + token hashing helper
-│   ├── observability/          # slog JSON handler + redaction, Prometheus registry/metrics, /healthz /readyz /metrics
-│   └── store/                  # pgxpool + go-redis bootstrapping, health pings, migration runner hook
-├── migrations/
-│   └── sql/                    # Goose-style timestamped SQL migrations (see §2.6)
-├── deploy/
-│   ├── Dockerfile
-│   └── (k8s / compose manifests as applicable)
-├── Makefile
-├── go.mod
-├── go.sum
-├── .golangci.yml
-├── .github/workflows/ci.yml    # or equivalent CI config
-└── README.md
-```
-
-Package ownership mirrors the Silo convention (CLAUDE.md "keep new code in the package that owns the behavior"): no catch-all `utils` package; shared payload logic lives in `pushwire`; shared data-access lives in `accounts`/`store` so `relayctl` and `httpapi` share schema and constraints (spec §5.6 "The CLI shares the relay's data-access package").
-
-### 2.3 The shared `pushwire` package (maintainability win)
-
-`internal/pushwire` is the single source of truth for **how an opaque request becomes an upstream payload + headers** — the APNs `aps`/`silo` dictionaries and `apns-*` headers (spec §5.1), and the FCM data-only `message` body + `android` config (spec §5.2). It is intentionally **dependency-light** (pure Go structs + JSON, no network) so it can be **mirrored into `silo-server`** under its `custom_apns` / `custom_fcm` paths, where the self-hosted server builds the *same* payloads when an admin uses their own credentials. One package, two repos: the relay and the direct-credential path can never drift on payload shape. (See §3 dependency table and Phase 3/4.)
-
-> **Mirroring mechanism & sync runbook (drift/ownership hazard — make it explicit).** Keep `pushwire` import-cycle-free and free of relay-only types (no DB, no config). **Designate one repo as the canonical source of truth** for `pushwire` (the relay repo `silo-push-relay`, since it owns the upstream payload contract). The copy in `silo-server` is a **checked-in generated artifact**, not a hand-edited file: commit a **content checksum** of the canonical package alongside it, and have **both** repos' CI verify their local copy against that checksum (a copied package in repo A cannot fail repo B's CI on its own, so a passive golden-file test in one repo is insufficient). Bump a **versioned payload-schema constant** on any payload change so a mismatch is unambiguous. Add a golden-file + closed-allowlist-key contract test on both sides (Phase 3/4 / §5.2). Document the ownership/sync runbook (who regenerates, in what order, how the checksum is bumped) so a payload change cannot silently diverge until the other repo happens to update. The preferred end state is a small shared module both repos import rather than a manual copy.
-
-### 2.4 Config strategy
-
-Twelve-factor-ish, but credentials come from a **secret manager**, not env vars (spec §11, reference §4.5 ranking: secret-manager > mounted file > env var > in-image). `internal/config` resolves, in order of preference per secret:
-
-| Config | Source (preferred → fallback) | Notes |
-|---|---|---|
-| APNs `.p8` private key, Key ID, Team ID | secret manager → mounted file | never env var, never in image |
-| FCM SA JSON **or** Workload Identity binding | GCP attached SA / Workload Identity → secret manager JSON | off-GCP uses JSON; on-GCP keyless (reference §4.5) |
-| API-key HMAC pepper | secret manager | rotation is heavier (spec open Q#6) |
-| Postgres DSN, Redis URL | secret manager → env | pool-tuned |
-| Non-secret tuning (timeouts, rate defaults, listen addrs, log level, environment label) | env vars / flags | safe to log |
-
-`config.Load(ctx)` returns a validated, fully-populated struct or a hard error; the process refuses to start with a missing/invalid credential. Provide a `config.Validate()` that `cmd/relay` calls before opening any listener. Non-secret defaults (rate limits from spec §9.2, timeouts from spec §11) live as constants with env overrides.
-
-### 2.5 Makefile (mirror Silo's Makefile-driven workflow)
-
-`make` targets, modeled on `silo-server`'s Makefile (CLAUDE.md §Build):
-
-```make
-make build            # go build ./cmd/relay ./cmd/relayctl
-make run              # run cmd/relay locally against docker-compose PG+Redis
-make test             # go test ./... (unit + contract; no live providers)
-make test-integration # go test -tags=integration ./...  (APNs sandbox + FCM validateOnly; needs creds)
-make lint             # golangci-lint run
-make fmt              # gofmt -w + goimports
-make migrate-create NAME=add_thing   # timestamped Goose migration scaffold
-make migrate-up       # apply migrations
-make migrate-status   # list migration state
-make relayctl ARGS="account list"    # build+run the admin CLI
-make docker           # build deploy/Dockerfile
-make loadtest         # run the k6/vegeta burst scenario (Phase 6)
-```
-
-`make migrate-create NAME=...` must produce a **timestamped** filename (CLAUDE.md: "New migrations must use timestamped filenames created with `make migrate-create`; do not run `goose fix` or create paired `.up.sql`/`.down.sql` files"). The relay uses single-file Goose SQL migrations with `-- +goose Up` / `-- +goose Down`.
-
-### 2.6 Migrations (Goose-style)
-
-`migrations/sql/<timestamp>_<name>.sql`, run by a Goose runner wired in `internal/store` and invokable via `make migrate-up` and on `cmd/relay` startup (behind a flag). The v1 schema is exactly spec §8.1 (`relay_accounts`, `relay_api_keys`, `relay_apns_allowlist`, `relay_fcm_allowlist`, `relay_op_logs`). IDs are ULIDs stored as `text`; timestamps are `timestamptz` (Silo convention).
-
-### 2.7 CI outline
-
-CI (GitHub Actions or equivalent) runs on every push/PR:
-
-```yaml
-jobs:
-  build-test:
-    steps:
-      - setup-go 1.25
-      - make lint                # golangci-lint
-      - make build
-      - make test                # unit + contract tests (no provider creds)
-      - upload coverage
-  migrate-check:
-    services: [postgres, redis]
-    steps:
-      - make migrate-up          # migrations apply cleanly on a fresh DB
-      - make migrate-status
-  integration:                   # gated: only when provider creds are available (Phase 3+)
-    if: secrets.APNS_P8 != '' && secrets.FCM_SA_JSON != ''
-    services: [postgres, redis]
-    steps:
-      - make test-integration    # APNs sandbox + FCM validateOnly contract tests
-```
-
-The `integration` job is **conditional on secrets being present** so Phases 0–2 are green long before any credential exists.
-
---
-
-## 3. Dependency Choices
-
-All versions are from the reference §3.7 pinned list. Pin exact versions in `go.mod`; bump deliberately.
-
-| Concern | Library | Version | One-line rationale |
-|---|---|---|---|
-| APNs client | `github.com/sideshow/apns2` **or** hand-rolled | `v0.25.0` / `x/net/http2 v0.56.0` + `golang-jwt/jwt/v5 v5.3.1` | De-facto Go APNs HTTP/2 client (auto JWT + conn reuse); **decide vs. hand-rolled before Phase 3** because `apns2` has had no release since Oct 2024 (bus-factor; reference §3.1, spec open Q#3). |
-| FCM auth | `golang.org/x/oauth2/google` | `v0.36.0` | `CredentialsFromJSONWithType(..., google.ServiceAccount, firebase.messaging scope)` gives an auto-caching/-refreshing `TokenSource`; lighter than the Admin SDK and gives direct control of conn reuse + error classification (reference §3.2 — preferred for a fixed payload). |
-| FCM (alt, batteries-included) | `firebase.google.com/go/v4/messaging` | `v4.20.0` | Acceptable alternative with `IsUnregistered`/`IsQuotaExceeded` helpers; **pick exactly one** FCM path, not both (reference §3.2). Plan defaults to the `x/oauth2` path. |
-| JWT (ES256 sign for APNs; RS256 for hand-rolled FCM grant) | `github.com/golang-jwt/jwt/v5` | `v5.3.1` | Maintained JWT lib; ES256 for APNs, RS256 if hand-rolling the FCM token exchange (reference §3.1). |
-| HTTP/2 transport tuning | `golang.org/x/net/http2` | `v0.56.0` | `ReadIdleTimeout`+`PingTimeout` to reap half-open upstream conns — "the single most important tuning for a long-lived relay" (reference §3.3). |
-| Postgres | `github.com/jackc/pgx/v5` + `pgxpool` | `v5.10.0` | Recommended driver/pool; `pgxpool.New` is concurrency-safe + health-checked (reference §3.4). |
-| Redis | `github.com/redis/go-redis/v9` | `v9.20.1` | Context-first client with pooling; atomic Lua for rate-limit, `SET NX` for idempotency (reference §3.4). |
-| Router | stdlib `net/http` (Go 1.22+ `http.ServeMux` patterns) | stdlib | Two routes + health/metrics need no framework; stdlib `ServeMux` supports method+path patterns and gets HTTP/2 over TLS automatically. Avoids a dependency; middleware is plain `http.Handler` wrapping. |
-| Structured logging | `log/slog` | stdlib (Go 1.21+) | `slog.NewJSONHandler` for production; redaction middleware so secrets can't leak (reference §3.5, spec §13.1). |
-| Metrics | `github.com/prometheus/client_golang` | `v1.23.2` | Custom registry + `promhttp.HandlerFor` for `/metrics`; per-provider latency histograms + outcome counters (reference §3.5, spec §13.2). |
-| Per-instance rate (outbound pacing helper) | `golang.org/x/time/rate` | current | `Reservation.Delay()` to compute relative `Retry-After`; used for in-process pacing, **not** the cross-replica cap (that is Redis — reference §4.2). |
-| ULID generation | `github.com/oklog/ulid/v2` (or equivalent) | current | Generate `request_id` and entity IDs as ULIDs (Silo convention; spec §8.1). |
-
-**Decision to make before Phase 3 (spec open Q#3):** adopt `sideshow/apns2` or hand-roll the APNs client. Recommendation: prototype both in Phase 3 behind the `internal/apns` interface; pick `apns2` if its recent commit/issue activity is acceptable, else hand-roll on `x/net/http2` + `golang-jwt/jwt/v5` mirroring the verified `apns2` internals (reference §3.1: `HostProduction`/`HostDevelopment`, `TokenTimeout=3000`s, `ReadIdleTimeout=15s`). Either way the rest of the service depends only on the `internal/apns` interface, not the concrete client.
-
-**`pushwire` maintainability note (reference + spec §5).** The shared `pushwire` package builds the exact APNs/FCM payloads and headers. Because `silo-server`'s `custom_apns`/`custom_fcm` paths must produce identical payloads, `pushwire` is mirrored into `silo-server` with **one canonical source repo** (the relay), a **committed checksum verified in CI on both sides**, and a **closed-allowlist-key** test so an added `data`/payload key fails CI regardless of golden-file regeneration order (§2.3 sync runbook, §5.2). This is also a **supply-chain control for the content-free guarantee**: the payload-builder that enforces "data-only, no `notification` block, fixed key set" is enforced in two repos that must not drift. Payload shape is defined once.
-
---
-
-## 4. Phased Tasks
-
-Effort sizes: **S** ≈ 1 day, **M** ≈ 2–3 days, **L** ≈ 4–5 days (one engineer). Sizes are rough.
-
-### Phase 0 — Scaffold, config, health, CI  (size: M)
-
-**Goal.** A buildable, lintable, testable repo that boots `cmd/relay`, serves `/healthz`, loads config, and is green in CI — with **no** provider dependency.
-
-**Files to create/modify.**
-
- `go.mod`, `go.sum`, `.golangci.yml`, `Makefile`, `README.md`, `.github/workflows/ci.yml`, `deploy/Dockerfile`.
- `cmd/relay/main.go` — load config, build slog JSON logger, start an `http.Server` with explicit timeouts and graceful shutdown, mount `/healthz`.
- `internal/config/config.go` — `Load(ctx)`, `Validate()`, defaults; secret-manager interface stub (real wiring in Phase 6).
- `internal/observability/logger.go` — `slog.NewJSONHandler` setup.
- `internal/httpapi/server.go`, `internal/httpapi/router.go`, `internal/httpapi/health.go` — router, `/healthz`.
- `internal/httpapi/errors.go` — the standard error body (spec §5.5) and a `writeError(w, status, code, msg, requestID)` helper.
-
-**Implementation notes.**
-
- Server timeouts are **mandatory** (zero = no timeout): `ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout`, `MaxHeaderBytes` (reference §3.3, spec §11). Body size cap ~16 KiB.
- Graceful shutdown: on SIGTERM/SIGINT call `srv.Shutdown(ctx)` with a bounded context (spec §14.2).
- `/healthz` returns `200 {"status":"ok"}`, unauthenticated, no dependency checks (spec §5.3).
- Error body shape is fixed (spec §5.5):
-  ```json
-  { "error": { "code": "string_code", "message": "human readable", "request_id": "01JRELAY..." } }
-  ```
-  Every request gets a ULID `request_id`, echoed as the `X-Request-Id` response header.
-
-**Tests.**
-
- Unit: `config.Validate` rejects missing required fields; `writeError` emits exact JSON + `X-Request-Id`.
- Unit: `/healthz` returns 200 with the exact body.
- CI: `make lint`, `make build`, `make test` green; `migrate-check` job present (no migrations yet → no-op pass).
-
-**Acceptance criteria.**
-
- [ ] `make build` produces `relay` and `relayctl` binaries.
- [ ] `make lint` and `make test` pass in CI with zero provider credentials.
- [ ] `cmd/relay` boots, serves `/healthz` 200, and shuts down gracefully on SIGTERM.
- [ ] Every response carries `X-Request-Id`; errors use the §5.5 shape.
-
---
-
-### Phase 1 — Storage, migrations, `relayctl` admin CLI  (size: L)
-
-**Goal.** The full PostgreSQL schema, a migration runner, the shared data-access package, and a working `relayctl` that can provision accounts/keys/allowlists and read op-logs — all without touching providers.
-
-**Files to create/modify.**
-
- `migrations/sql/<ts>_init_relay_schema.sql` — exact schema from spec §8.1: `relay_accounts`, `relay_api_keys`, `relay_apns_allowlist`, `relay_fcm_allowlist`, `relay_op_logs`, plus indexes (`relay_api_keys_prefix_uidx`, `relay_api_keys_account_idx`, `relay_op_logs_account_time_idx`, `relay_op_logs_time_idx`).
- `internal/store/postgres.go` — `pgxpool.New(ctx, dsn)`, `Ping`, migration runner hook.
- `internal/store/redis.go` — `go-redis` client + `PING` (used Phase 2).
- `internal/accounts/` — data-access: `CreateAccount`, `ListAccounts`, `DisableAccount`, `IssueKey`, `ListKeys`, `RevokeKey`, `LookupKeyByPrefix`, `SetApnsAllowlist`, `SetFcmAllowlist`, `GetAllowlists`. Used by both `httpapi` and `relayctl`.
- `internal/accounts/keys.go` — key generation + hashing (see notes).
- `internal/oplog/oplog.go` — `Write(ctx, entry)` to `relay_op_logs`; `TokenHash(token) string` (SHA-256 hex).
- `cmd/relayctl/main.go` + subcommands per spec §5.6 table.
-
-**Implementation notes.**
-
- **API-key format & hashing** (spec §8.2, reference §4.1):
-  - Format `rk_<env>_<base62/base64url>`; env ∈ {`live`,`test`}. Random secret = 32 bytes from `crypto/rand`.
-  - **Prefix** = `rk_<env>_<first 6–8 chars of random>`, non-secret, stored cleartext, uniquely indexed.
-  - Store `key_hash = HMAC-SHA256(pepper, secret)` (32 bytes). Never store plaintext. Fast keyed hash is correct for 256-bit random keys (do **not** use argon2id here).
-  - `relayctl key issue` prints the full `rk_…` **exactly once** to stdout; only hash+prefix persist (spec §8.3).
- `relayctl` connects directly to Postgres with a privileged DSN held by operators (no public admin API; spec §5.6). Each mutating command writes an `admin.*` op-log with operator identity (OS user / `--actor`) and never the secret token (spec §5.6).
- Allowlist commands replace the set atomically (UPSERT/DELETE in one tx) for `relay_apns_allowlist` / `relay_fcm_allowlist`.
- Official allowlist config values to seed in examples/tests (allowlist config, **not** the contract — spec §8.4): APNs topics `com.continuum.app.ios`, `com.continuum.app.tvos`, `com.continuum.app.macos`; FCM project `continuum-prod-android`, package `com.continuum.app.android`.
-
-**`relayctl` command surface (spec §5.6 / §13.3).**
-
-| Command | Effect |
-|---|---|
-| `relayctl account create --name <label> [--note <text>]` | INSERT `relay_accounts`; print `account_id` |
-| `relayctl account list [--active]` | SELECT accounts + key count + last activity |
-| `relayctl account disable --account <id>` | `status='disabled'` |
-| `relayctl key issue --account <id> [--env live\|test] [--expires <dur>]` | INSERT key; print `rk_…` once |
-| `relayctl key list --account <id>` | SELECT (prefix/created/last_used/revoked; never secret) |
-| `relayctl key revoke --key-prefix <prefix>` | `revoked_at=now()` |
-| `relayctl allowlist apns set --account <id> --topics a,b,c` | replace APNs allowlist |
-| `relayctl allowlist fcm set --account <id> --project <p> --packages a,b` | replace FCM allowlist |
-| `relayctl allowlist show --account <id>` | print effective allowlists |
-| `relayctl logs --account <id> [--since …] [--outcome rejected]` | query `relay_op_logs` (redacted) |
-| `relayctl logs --gc` | retention GC: delete success rows >14d, failure/reject rows >90d (Phase 5; cron-schedulable) |
-| `relayctl ping-upstream --provider apns\|fcm --env sandbox` | credential-only health check; flips `relay_credential_healthy` (Phase 3/4/6) |
-
-**Tests.**
-
- Integration (PG via docker-compose): `make migrate-up` applies cleanly on a fresh DB; `make migrate-status` lists state.
- Unit/integration: `IssueKey` → `LookupKeyByPrefix` round-trips; hash is HMAC-SHA256; plaintext never stored.
- Integration: full `relayctl` flow — create account → issue key → set allowlists → list/show; `admin.*` op-logs written without secrets.
- Unit: `oplog.TokenHash` is stable SHA-256 hex; op-log entry rejects/strips raw token.
-
-**Acceptance criteria.**
-
- [ ] Migrations apply on a fresh DB and match spec §8.1 exactly (column names/types/constraints/indexes).
- [ ] `relayctl` can provision an account, issue a key (printed once), set both allowlists, and read redacted logs.
- [ ] No table stores tokens, content, or identity; `relay_op_logs` holds only `token_hash`, never raw tokens.
- [ ] Key hash is HMAC-SHA256(pepper, secret); constant-time compare verified in a unit test.
-
---
-
-### Phase 2 — Auth middleware, rate limit, idempotency  (size: L)
-
-**Goal.** The full request-path middleware chain (auth → rate limit → idempotency → decode/validate/allowlist) wired in front of stub send handlers that return a deterministic fake upstream result. No real provider yet.
-
-**Files to create/modify.**
-
- `internal/httpapi/middleware_auth.go` — bearer parse, prefix lookup, constant-time compare, revoked/expired/disabled rejection, throttled `last_used_at`, per-IP anti-brute-force.
- `internal/ratelimit/limiter.go` + `ratelimit/bucket.lua` — Redis Lua token bucket (per-account + coarse per-token).
- `internal/httpapi/middleware_ratelimit.go` — applies the limiter, emits `429` + `Retry-After`.
- `internal/idempotency/store.go` + `idempotency/idem.lua` (if needed) — `SET NX` lock, replay, 409, 422.
- `internal/httpapi/middleware_idempotency.go` — wraps send handlers.
- `internal/httpapi/decode.go` — `DisallowUnknownFields` decoder + field validation + allowlist enforcement.
- `internal/httpapi/apple.go`, `internal/httpapi/fcm.go` — handler skeletons returning a fake `accepted` result (real upstream in Phase 3/4).
-
-**Implementation notes.**
-
- **Auth** (spec §8.2): parse `Authorization: Bearer rk_<env>_<rest>` (malformed → `401 unauthorized`); derive `key_prefix`; `SELECT … WHERE key_prefix=$1` (unique index); reject if no row / revoked / expired / account disabled (do not distinguish reasons to caller — all `401 unauthorized`); `subtle.ConstantTimeCompare(HMAC(pepper, presented), key_hash)`; throttle `last_used_at` to ≤1/min/key; rate-limit auth failures per resolved client IP (see client-IP resolution below).
- **Constant-time auth path (no enumeration oracle).** On a missing/revoked/expired row, **still** perform a dummy `HMAC-SHA256` against a fixed decoy hash with `subtle.ConstantTimeCompare` before returning the uniform `401`, so "unknown prefix" is not measurably faster than "known prefix, wrong secret." Keep the fine-grained failure reason (`unknown_prefix` vs `hash_mismatch`) in **internal** logs/metrics only — never in a response and never exposed to an untrusted `/metrics` scraper.
- **Client-IP resolution / trusted proxy (security-critical).** The relay sits behind a TLS load balancer, so Go's `http.Request.RemoteAddr` is the LB address, not the caller. Derive the client IP from `RemoteAddr` **unless** the immediate peer is in an **allowlisted trusted-proxy CIDR list** (a config value), in which case take the **right-most untrusted hop** from the LB-set forwarding header. **Caller-supplied `X-Forwarded-For`/`X-Real-IP` headers are ignored** — trusting them would let an attacker spread brute-force across unlimited fake IPs (defeating the per-IP throttle) and poison `egress_ip` in op-logs. Both the per-IP auth-failure limiter and the logged `egress_ip` consume this single resolved IP. Account for shared egress (CGNAT/VPN — multiple self-hosted servers behind one IP, anticipated in spec §3.4): make the brute-force lockout **soft** (added latency / `Retry-After`), not a hard block, so a noisy/compromised neighbor cannot lock out legitimate servers sharing the IP.
- **Bounded fail-open on Redis outage.** The per-account/daily rate limit is the primary cap on a stolen-key attacker's spend (and on shared downstream APNs/FCM quota). A naive fail-open removes that cap entirely during a Redis outage. Instead, when Redis is unreachable, fall back to a conservative **in-process** per-account limiter (`x/time/rate`) so each account is still capped to a small multiple of its normal rate; the allowlist (always enforced from Postgres) remains the hard boundary. A Redis outage pages ops; the cross-replica daily quota cannot be enforced during the outage (documented limitation).
- **Rate limit** (spec §9): Redis HASH `rl:{account_id} = {tokens, last_refill_ts}` with TTL, atomic Lua (refill→check→consume in one `EVAL`). Defaults (spec §9.2): per-account ~10 req/s burst, refill 10/s with burst capacity 20; per-account daily 50,000 req/day; coarse `(account_id, token_hash)` ~1 req/3s. Over limit → `429 rate_limited` with **relative** `Retry-After` (delay-seconds, never an absolute epoch — reference §4.2). On Redis down: **bounded fail-open** (in-process per-account fallback limiter, above — not unlimited), log `rate_limit.degraded`, increment `relay_rate_limit_degraded_total` (spec §9.4).
-  - **Daily quota mechanics.** Store the daily counter as a **separate Redis counter** `rl:day:{account_id}:{yyyymmdd}` with `INCR` + `EXPIRE` to the end of the window — it is **not** the per-second token bucket and **not** a Postgres column. Reset semantics: **fixed UTC calendar day** (`yyyymmdd` in UTC). During a Redis outage the daily counter, like the per-second bucket, falls back to the bounded in-process limiter and the precise cross-replica daily cap cannot be enforced (documented; pages ops). Emit `relay_rate_limited_total{kind="daily"}` and alert on accounts approaching/hitting the cap (a big-release burst can legitimately reach 50k/day; §6.4).
- **Project-level FCM circuit breaker (multi-tenant fairness).** The ~600k msgs/min FCM project quota (reference §2.7) is **shared across all relay accounts**, but the per-account limit is local to each account — one noisy account can exhaust the shared quota for everyone. Add a relay-side **global per-project outbound limiter / circuit breaker** that tracks aggregate FCM send rate against the project quota and **sheds load with `503 upstream_throttled` before hammering FCM** when near quota (the relay is the only aggregation point that can honor reference §2.7's anti-spike / smooth-traffic guidance — avoid sending within a 2-minute window of :00/:15/:30/:45). Export `relay_fcm_project_quota_headroom` and alert (§6.4).
- **Idempotency** (spec §10): require `Idempotency-Key` header on sends; missing → `400 missing_idempotency_key`. Length-limit ≤255 chars; the three-part `<delivery_id>:<device_id>:<attempt>` shape is **opaque** (not strictly parsed). Namespaced `idem:{account_id}:{key}`. `SET … NX EX <lock_ttl>` (`lock_ttl` ≈ 30s) in-flight lock:
-  - NX success → process; on completion overwrite with serialized `{status, body, upstream_id, canonical_hash}` + ~24h TTL (success **and** error recorded).
-  - NX fail + stored completed result → **replay** verbatim (same `apns_id`/`fcm_message_name`).
-  - NX fail + still in-flight → `409 idempotency_conflict`.
-  - Same key + different request payload (compare stored `canonical_hash`) → `422 idempotency_key_reuse`.
-  - **Fails closed**: Redis unavailable → `503 upstream_unavailable` (never risk a double-send; spec §10.2).
-  - **Lock-TTL invariant (no double-send / no clobber).** The upstream APNs/FCM call (plus HTTP/2 setup, JWT/OAuth refresh, GOAWAY reconnect) can otherwise outlast `lock_ttl`, letting a concurrent retry's NX succeed and fire a **second** upstream send. Pin the upstream call with a hard context deadline **strictly shorter than `lock_ttl`** (≈10s upstream vs 30s lock) and refuse to send upstream if the handler's own deadline has already passed the lock TTL. On completion, use a **compare-and-set** that only overwrites the stored value if it is still *this* request's in-flight marker, so a lock stolen by a concurrent request cannot have its result clobbered.
-  - **Privacy invariant (no stored token).** The `canonical_hash` is computed over the validated fields with the device token **replaced by its already-computed `token_hash` (SHA-256)**; the stored idempotency value is exactly `{status, body, upstream_id, canonical_hash}` and holds **no raw token** — matching the op-log no-raw-token guarantee (NG1, spec §3.2/§12).
-  - **Drain interaction.** On handler context-cancellation (e.g. a drain/shutdown that severs an in-flight send), **release or downgrade** the in-flight marker so an immediate caller retry does not get spurious `409 idempotency_conflict` for the full `lock_ttl` (see Phase 6 drain ordering and §5.7 drain test).
- **Decode/validate/allowlist** (spec §5.1/§5.2/§8.4): `DisallowUnknownFields` (unknown key → `400 unexpected_field`). Validate every field per the spec field tables (token shape, environment, mode, ID length caps, collapse-id ≤64 bytes for APNs). Allowlist check **after** auth, **before** payload build: APNs `topic` ∈ account's `relay_apns_allowlist` else `403 topic_not_allowed`; FCM `(project_id, package_name)` ∈ `relay_fcm_allowlist` else `403 project_not_allowed` / `403 package_not_allowed`. Allowlist may be a short-TTL per-account-scoped in-memory cache invalidated on `relayctl allowlist … set`.
-
-**Middleware order (spec §4.1).**
-
-```
-TLS → auth → rate-limit → decode(DisallowUnknownFields) → validate+allowlist → idempotency → [Phase 3/4 upstream] → map → store idem result → op-log + metrics
-```
-
-**Tests.**
-
- Unit: bearer parse edge cases; constant-time compare; revoked/expired/disabled all map to `401`; `last_used_at` throttle.
- Unit: the auth path is **constant-time for unknown-prefix vs wrong-secret** (dummy HMAC + `ConstantTimeCompare` on a missing/revoked row) — no enumeration timing oracle; the fine-grained reason stays internal-only.
- Unit: **trusted-proxy client-IP resolution** — a forged caller `X-Forwarded-For`/`X-Real-IP` is ignored; only the LB-set header from an allowlisted trusted-proxy peer is honored; `RemoteAddr` is used otherwise.
- Integration (Redis): token bucket refill/consume math; `429` + correct relative `Retry-After`; **daily counter** (`rl:day:{account}:{yyyymmdd}`, fixed-UTC reset, `EXPIRE`) trips at 50k; **bounded** fail-open on Redis down (in-process per-account cap engaged, not unlimited).
- Integration (Redis): idempotency first/replay/409/422/missing-key matrix (spec §10.3); fail-closed `503` on Redis down; the stored value carries **no raw token** (canonical hash uses `token_hash`).
- Integration (Redis): **Redis dropped mid-request** (not just down at start) — rate-limit layer degrades to bounded fail-open; idempotency layer fails closed (`503`); a lock whose TTL expires mid-send cannot be stolen into a double-send (upstream deadline < `lock_ttl`).
- Contract: `DisallowUnknownFields` rejects every disallowed field (`title`, `body`, `image_url`, `media_id`, `username`, `server_url`, …) with `400 unexpected_field`.
- Contract: allowlist rejections produce exact codes `topic_not_allowed` / `project_not_allowed` / `package_not_allowed`.
-
-**Acceptance criteria.**
-
- [ ] A request with a valid key, allowlisted topic, and `Idempotency-Key` reaches the (stub) handler and returns `accepted`.
- [ ] Duplicate idempotency key replays the identical body; in-flight → `409`; payload mismatch → `422`; missing → `400`.
- [ ] Over-limit → `429` with relative `Retry-After`; Redis-down rate-limit fails open, idempotency fails closed.
- [ ] Every unknown field and every non-allowlisted topic/project/package is rejected with the exact §5/§8 error code.
-
---
-
-### Phase 3 — APNs client + `POST /v1/apple/send`  (size: L)  · gated on Apple provisioning
-
-**Goal.** A production APNs client (cached ES256 JWT, reused HTTP/2 pool, correct reason→error mapping) and the live `/v1/apple/send` endpoint building the §5.1 payloads via `pushwire`, validated against the APNs **sandbox**.
-
-**Files to create/modify.**
-
- `internal/apns/client.go` — the `APNsClient` interface + concrete impl (apns2 **or** hand-rolled per §3 decision).
- `internal/apns/jwt.go` — ES256 JWT lifecycle (cache, ~50min refresh, never <20min, eager refresh on `ExpiredProviderToken`).
- `internal/apns/transport.go` — per-team HTTP/2 pool with `ReadIdleTimeout`/`PingTimeout`; env→host selection.
- `internal/apns/errors.go` — APNs status+`reason` → caller `error.code` + retryability (spec §6.4 table).
- `internal/pushwire/apns.go` — build `private_alert` / `background_wake` `aps`+`silo` payloads and `apns-*` headers (spec §5.1).
- `internal/httpapi/apple.go` — replace the Phase 2 stub with the real send.
-
-**Implementation notes.**
-
- **JWT** (spec §6.1, reference §1.1): ES256 only; header `{"alg":"ES256","kid":<10-char Key ID>}`, claims `{"iss":<10-char Team ID>,"iat":<epoch s>}`. Cache one JWT behind a mutex; regenerate on a ~50-min timer, never <20-min apart; eager regenerate + **single in-process retry** on `403 ExpiredProviderToken`; back off / slow refresh on `429 TooManyProviderTokenUpdates`. **Per-team pool** keyed by team even though v1 has one team.
- **Single-flighted JWT regeneration (stampede guard).** Under a burst of concurrent sends sharing one cached JWT, an expiry (or a `403 ExpiredProviderToken`) is observed by many in-flight goroutines at once; a naive per-goroutine regenerate-on-403 would trip `429 TooManyProviderTokenUpdates`. Regeneration must therefore be **single-flighted** (e.g. `golang.org/x/sync/singleflight` or a generation/epoch counter under the mutex): a goroutine seeing `ExpiredProviderToken` first checks whether the JWT was already refreshed since *its* request started and reuses the new token rather than triggering another refresh. Exactly **one** refresh happens per ~20-min window regardless of how many concurrent 403s arrive.
- **Endpoint** (spec §6.2): `production` → `https://api.push.apple.com`; `sandbox` → `https://api.sandbox.push.apple.com`. Both `api.sandbox.push.apple.com` and the older alias `api.development.push.apple.com` are **valid, equivalent sandbox hosts that still resolve** — we standardize on `api.sandbox.push.apple.com` (the current canonical name and `apns2` v0.25.0's `HostDevelopment`); `02`'s use of `api.development.*` is not a discrepancy to resolve, just the older alias. The external contract `"environment":"sandbox"` is unchanged. The upstream hosts are **hardcoded constants never derived from request input**. Port 443, 2197 fallback.
- **Connection** (spec §6.3, reference §3.3): one client/pool per process per env per team; never per push. Non-zero `ReadIdleTimeout`(~15s) + `PingTimeout`(~15s). Do not hardcode `SETTINGS_MAX_CONCURRENT_STREAMS`. Handle `GOAWAY` (drop+reconnect). Ensure system trust store includes USERTrust RSA (default in OS/Go pools).
- **Headers** (spec §5.1 table): `apns-topic` = allowlisted topic; `apns-push-type` = `alert` (private_alert) / `background` (background_wake); `apns-priority` = `10` / `5` (background **must** be 5; 10 is an error — reference §1.4.1); `apns-collapse-id` = `collapse_id` if present (≤64 bytes); `apns-id` omitted (Apple generates, echoed back). **`apns-expiration` ships with a finite default** (configurable) rather than 0/omitted: a few hours for `private_alert`, a short TTL for `background_wake`. Omitting it makes Apple store-and-retry an undelivered push for **up to 30 days** (reference §1.4) — for a notification whose content is fetched live on wake, a wake fired days later is useless or confusing. Mirror this on FCM with a finite `android.ttl` (default is otherwise ~4 weeks) for cross-provider parity. (Resolved open Q#5; the exact default values want product input but v1 ships a sane non-30-day default, not an omission.)
- **Payloads** (`pushwire`, spec §5.1): `private_alert` → `aps.alert` with `title-loc-key=SILO_NOTIFICATION_TITLE`, `loc-key=SILO_NOTIFICATION_GENERIC_BODY`, `sound=default`, plus `silo` dict (`v:1`, `wake:"notifications.changed"`, `server_device_id`, `delivery_id`); add `aps.badge` only if `badge` is present, non-null, and within a **bounded range (0–9999)** — out-of-range → `400 invalid_field` (it is the one numeric field that escapes the opaque-ID discipline, so it is bounded rather than copied verbatim). `background_wake` → `aps.content-available:1` + `silo` dict. Uncompressed JSON, far under 4 KB; defensive `400 payload_too_large` if it ever exceeds.
- **Response → caller** (spec §5.1): `200` → `{ "request_id", "apns_id" (Apple's apns-id header), "status":"accepted" }`. Error mapping per spec §6.4 (e.g. `BadDeviceToken`/**`InvalidToken`**/`DeviceTokenNotForTopic`/`MissingDeviceToken` → `422 bad_device_token`; `Unregistered`/`ExpiredToken` → `410 unregistered` with `timestamp` passed through in `error.message`; `403 InvalidProviderToken`/etc → `502 upstream_auth_error` + ops alert; `429 TooManyRequests` → `429 rate_limited` + `Retry-After`; 5xx → `503 upstream_unavailable`). **`InvalidToken` is treated equivalently to `BadDeviceToken` (token-purge, non-retryable)** — Apple has migrated some responses from `BadDeviceToken` to `InvalidToken`, and the `02` contract requires treating them equivalently; omitting it would let a dead device fall through to the catch-all and never be disabled. Add a **default/fallback rule**: any unrecognized 400/403/410 `reason` maps to a safe non-retryable `502 upstream_error` rather than being dropped. **Connection-severed sends** — a request whose HTTP/2 stream is terminated by `GOAWAY` or any connection reset **before** a final APNs response arrives → `503 upstream_unavailable` (retryable), the same as a network timeout; the relay does **not** transparently retry it (the caller's outbox does), preserving at-most-once semantics under the idempotency key. Tag the op-log outcome / metric label `connection_severed` so these are distinguishable. **Environment/token mismatch caveat:** a `sandbox`/`production` mismatch (e.g. a prod token sent with `environment=sandbox`) presents upstream as `BadDeviceToken` → `bad_device_token`, which instructs the caller to purge a perfectly good token; emit a distinct op-log/metric so a systemic misconfig (many `bad_device_token` from one account) is distinguishable from genuinely dead tokens. Network/timeout to APNs → `503 upstream_unavailable`. The relay does **not** retry transient upstream errors across caller requests (the caller's outbox does); the only in-process retry is the JWT-expiry one (single-flighted — see JWT note below).
-
-**Tests.**
-
- Unit: JWT signs valid ES256 with correct header/claims; refresh-timer logic (≥20min, ≤60min, eager-on-expired); single retry on `ExpiredProviderToken`.
- Concurrency: force JWT expiry under a burst of concurrent sends; assert **exactly one** regeneration (single-flight) and **zero** `429 TooManyProviderTokenUpdates`.
- Unit (`pushwire`): golden-file payloads + headers for `private_alert` and `background_wake`, with and without `badge`/`collapse_id` (byte-exact vs spec §5.1). **Same golden files mirrored into `silo-server`.**
- Unit: every row of the spec §6.4 reason→error table maps correctly (table-driven), **including `InvalidToken` → `bad_device_token`** (equivalent to `BadDeviceToken`) and the **default/fallback** rule (unrecognized reason → `502 upstream_error`, non-retryable).
- Fake APNs upstream injecting a **`GOAWAY` / mid-stream reset** before a final response → caller gets `503 upstream_unavailable`, the op-log/metric is tagged `connection_severed`, and there is **no lost or double send** (the relay does not transparently retry).
- Integration (**Apple sandbox**, behind `-tags=integration`, requires `.p8`): real send to `api.sandbox.push.apple.com` returns 200 + `apns_id`; an intentionally bad token returns the expected `bad_device_token`/`unregistered` mapping.
- Integration: `relayctl ping-upstream --provider apns --env sandbox` signs+connects without sending content; optionally captures the sandbox-only `apns-unique-id` response header (reference §1.6) into the ping output for Push-Notifications-Console delivery-log correlation during client QA.
-
-**Acceptance criteria.**
-
- [ ] `/v1/apple/send` builds the exact §5.1 payloads/headers and returns `{request_id, apns_id, status:"accepted"}` on success against sandbox.
- [ ] Background pushes always send `apns-priority: 5` and `apns-push-type: background`.
- [ ] JWT is cached, reused, and refreshed on the ~50-min cadence; `ExpiredProviderToken` triggers one regenerate+retry; concurrent 403s yield exactly one single-flighted regeneration.
- [ ] Every spec §6.4 mapping is covered by a passing table-driven test, **including `InvalidToken` and the unrecognized-reason fallback**; a `GOAWAY`/connection-severed send maps to `503 upstream_unavailable` with no double-send; the `pushwire` golden files match across both repos.
-
---
-
-### Phase 4 — FCM client + `POST /v1/fcm/send`  (size: L)  · gated on Firebase provisioning
-
-**Goal.** A production FCM HTTP v1 client (cached OAuth2 token, tuned HTTP/2, correct status→error mapping) and the live `/v1/fcm/send` endpoint building the §5.2 **data-only** payloads via `pushwire`, validated with FCM `validateOnly:true`.
-
-**Files to create/modify.**
-
- `internal/fcm/client.go` — the `FCMClient` interface + concrete impl (`x/oauth2/google` path per §3).
- `internal/fcm/oauth.go` — `CredentialsFromJSONWithType(ctx, json, google.ServiceAccount, "https://www.googleapis.com/auth/firebase.messaging")` → cached/auto-refreshing `TokenSource`, one per project.
- `internal/fcm/transport.go` — tuned HTTP/2 client; endpoint `POST https://fcm.googleapis.com/v1/projects/{PROJECT_ID}/messages:send`.
- `internal/fcm/errors.go` — FCM `error.status` → caller `error.code` + retryability + Retry-After honoring (spec §7.4).
- `internal/pushwire/fcm.go` — build data-only `message` + `android` config (spec §5.2).
- `internal/httpapi/fcm.go` — replace the Phase 2 stub with the real send.
-
-**Implementation notes.**
-
- **OAuth2** (spec §7.1, reference §2.2): least-privilege scope `firebase.messaging`; `TokenSource` caches + auto-refreshes (~1h tokens; never mint per request). On GCP prefer keyless Workload Identity / attached SA; off-GCP load SA JSON from the secret manager (open Q#4). One token source per Firebase project.
- **Endpoint** (spec §7.2): global host only — no regional endpoints (reference §2.3). The host `fcm.googleapis.com` is a **hardcoded constant never derived from request input**. `{PROJECT_ID}` is the allowlist-checked `project_id`, and `project_id`/`package_name` are validated against a **strict charset** (e.g. `^[a-z0-9-]+$` / reverse-DNS) **before** allowlist lookup and URL interpolation, so an allowlist row can never introduce a path-traversal or host-override (no SSRF / path injection).
- **Payload — data-only** (`pushwire`, spec §5.2): `message.token` = caller token; `message.data` is a **fixed, closed set of string-valued keys only** (`"v":"1"`, `"wake":"notifications.changed"`, `"server_device_id"`, `"delivery_id"`) — no caller-controlled key or value beyond the opaque IDs; **no `notification` block**; `message.android.priority` = `"HIGH"` (private_data) / `"NORMAL"` (background_wake); `message.android.collapseKey` set only if the caller sent `collapse_key`. **Field-casing reconciliation (reference §2.4):** the relay POSTs raw JSON to the real FCM HTTP v1 REST endpoint, whose AndroidConfig field is camelCase **`collapseKey`** (FCM v1 rejects unknown fields with `INVALID_ARGUMENT`, so a literal `collapse_key` inside `android` would fail every collapsible send). The **inbound caller request body field stays `collapse_key`** per `03`; only the relay-built upstream JSON uses `collapseKey`. Likewise `android.priority` is sent as canonical uppercase `"HIGH"`/`"NORMAL"` (reference §2.4 lists these as the enum values, with lowercase also accepted; the relay sends the canonical uppercase to be robust against future enum tightening). Honor the `03` contract's `priority: high`-equivalent (`"HIGH"`) for `private_data` (do not second-guess — spec §5.2 reconciliation note). Set a finite `android.ttl` (default ~4 weeks otherwise) for parity with the APNs `apns-expiration` default (above). Never set `topic`/`condition`. ≤4096 bytes. Use `validateOnly:true` (camelCase REST field — reference §2.5) only for the `relayctl` test path, never production.
-  - **`badge` has no data-only FCM home.** The relay-built FCM payload is strictly data-only (no `notification` block), so a caller-provided `badge` has nowhere legitimate to go. **Drop `badge` from the FCM accepted schema** (it is disabled-by-default and would otherwise have to be smuggled into the closed `data` map, weakening the allowlist). On the APNs side, bound `badge` to a sane range (e.g. 0–9999) and reject otherwise with `400 invalid_field` — it is the one numeric field that escapes the opaque-ID discipline.
-  - **Collapse-key coalescing is best-effort (reference §2.7).** FCM stores at most **4 distinct `collapseKey`s per device** while offline; a 5th evicts one nondeterministically. Since `collapse_key` is a per-series HMAC and a device may follow >4 series, collapsible coalescing is best-effort and excess distinct keys evict nondeterministically — acceptable because the durable inbox + sync (the caller's outbox) covers any dropped collapsible wake. APNs has no equivalent documented per-device collapse-id cap (note the asymmetry).
- **Response → caller** (spec §5.2): `200` → `{ "request_id", "fcm_message_name" (FCM v1 `name`), "status":"accepted" }`. Error mapping per spec §7.4 (e.g. `INVALID_ARGUMENT` → `422 invalid_argument`; `SENDER_ID_MISMATCH` → `403 sender_id_mismatch`; `UNREGISTERED` → `410 unregistered`; `QUOTA_EXCEEDED` → `429 rate_limited` honoring upstream `Retry-After` else default **60s**; `INTERNAL`/`UNAVAILABLE` → `503 upstream_unavailable` honoring `Retry-After` on 503; `UNSPECIFIED_ERROR` → `502 upstream_error`, no auto-purge). Classify on `error.status`/`FcmError.errorCode`, not the bare HTTP code. **Retry-After** forwarded to the caller as relative delay-seconds (reference §4.2). Add a **default/fallback rule** so any unrecognized FCM `error.status`/`errorCode` maps to a safe non-retryable `502 upstream_error` (never an auto-purge), rather than being dropped.
-  - **`THIRD_PARTY_AUTH_ERROR` (401) — re-classified (do NOT page as a relay-credential failure).** Per Firebase's error-codes page this means an invalid/missing **APNs cert/key or Web Push auth credential** and is returned only for iOS-via-APNs or Web Push registration tokens. `/v1/fcm/send` sends **only** Android registration tokens (`message.token`, package `com.continuum.app.android`, data-only), so a legitimate Android send can never produce `THIRD_PARTY_AUTH_ERROR`. If it ever appears, treat it as a **per-token/registration anomaly** → `502 upstream_error`, surface for investigation, and do **not** page on-call as a relay `.p8`/SA misconfig. The relay's **actual** OAuth2/service-account credential failures surface as a non-200 from `oauth2.googleapis.com/token` at mint time, or HTTP `401 UNAUTHENTICATED` / `403 PERMISSION_DENIED` (the `status`, not an `FcmError` code) on `messages:send` — **those** map to `502 upstream_auth_error` + ops alert.
-  - **Per-device rate exceedance (`DeviceMessageRateExceeded`, reference §2.7).** The Android per-device caps (240/min, 5,000/hr) are **distinct** from project-level `QUOTA_EXCEEDED` and surface defensively as a quota/`INVALID_ARGUMENT`-adjacent signal whose exact code/string is not firmly documented; detect on `error.status`/`errorCode` and map to a retryable `429 rate_limited` with a conservative default `Retry-After`, **not** a token purge.
-  - **`UNREGISTERED` caller-facing 410 is an intentional cross-provider normalization.** FCM natively returns `UNREGISTERED` as HTTP **404**; the relay remaps it to caller `410 unregistered` so the caller's device-disable ("purge dead token") logic is uniform with the APNs path (which natively uses 410). This is a deliberate divergence from FCM's native status, not a bug.
-
-**Tests.**
-
- Unit: token source caches; no per-request mint; refresh margin.
- Unit (`pushwire`): golden-file data-only payloads for `private_data` and `background_wake`, with/without `collapse_key` (byte-exact vs spec §5.2; **all data values strings**; **no `notification` block**). Mirrored into `silo-server`.
- Unit: every row of the spec §7.4 status→error table (table-driven), including `Retry-After` honoring + 60s default, the unrecognized-`error.status` fallback (`502 upstream_error`), the per-device-rate (`DeviceMessageRateExceeded`) → `429 rate_limited` (no purge), and `THIRD_PARTY_AUTH_ERROR` → `502 upstream_error` (per-token anomaly, **not** paged as relay-credential).
- Unit/contract: the FCM upstream JSON uses camelCase `collapseKey`, uppercase `priority` (`"HIGH"`/`"NORMAL"`), and `validateOnly`; `badge` is rejected from the FCM schema; the `data` map is the closed key set (no extra keys).
- Integration (**FCM `validateOnly:true`**, `-tags=integration`, requires SA JSON): a valid request validates OK; a malformed token surfaces `invalid_argument`/`unregistered` mapping.
- Integration: `relayctl ping-upstream --provider fcm --env sandbox` mints a token + does a `validateOnly` send.
-
-**Acceptance criteria.**
-
- [ ] `/v1/fcm/send` builds the exact §5.2 data-only payload (string values, no `notification`) and returns `{request_id, fcm_message_name, status:"accepted"}`.
- [ ] OAuth2 token is cached/refreshed, never minted per request; one source per project.
- [ ] Every spec §7.4 mapping is covered (incl. the unrecognized-status fallback, per-device-rate, and `THIRD_PARTY_AUTH_ERROR` as a non-paging per-token anomaly); `QUOTA_EXCEEDED`/`UNAVAILABLE` forward `Retry-After` (default 60s on 429).
- [ ] The upstream FCM JSON uses `collapseKey` (camelCase), `"HIGH"`/`"NORMAL"` priority, `validateOnly` (camelCase), a finite `android.ttl`, and the closed `data` key set; `badge` is not accepted on the FCM path.
- [ ] `validateOnly` test path works; production sends never set `validateOnly`.
-
---
-
-### Phase 5 — Observability, redaction, metrics  (size: M)
-
-**Goal.** Production-grade redacted logging, op-log persistence, the full Prometheus metric catalog, and `/readyz`/`/metrics` wired and network-scoped.
-
-**Files to create/modify.**
-
- `internal/observability/redact.go` — redaction middleware (strips `Authorization`/bearer, raw key, raw token, JWT, OAuth2 token, payload bodies).
- `internal/observability/metrics.go` — Prometheus registry + the spec §13.2 catalog.
- `internal/httpapi/health.go` — `/readyz` (PG `SELECT 1`, Redis `PING`; APNs and FCM reported **per-provider**, not as a single combined gate) and `/metrics` (`promhttp.HandlerFor`), both bound to the internal network.
- `internal/oplog/gc.go` + `cmd/relayctl` `logs --gc` subcommand (or a background sweeper in `cmd/relay`) — the retention GC deliverable; plus the §8.1 partitioning DDL (or a documented partition/offload decision).
- Wire `oplog.Write` into every send path with the redacted subset.
-
-**Implementation notes.**
-
- **Redaction enforced in middleware** so no code path can leak (spec §11/§12/§13.1). Never log: bearer header, raw API key (log prefix or hash only), raw device tokens (log `SHA-256` truncated hash only), payload bodies, relay JWT, OAuth2 tokens. Do log: `request_id`, `account_id`, `status_code`, `error_code`, upstream reason, `token_hash`, `egress_ip`, `latency_ms`.
- **Op-log retention is a concrete Phase 5 deliverable** (spec §8.1/§13.1): every send writes one `relay_op_logs` row (redacted by construction). Ship a real GC — **add `relayctl logs --gc`** (to the §5.6 command table and Phase 1/5 file lists) **or** a built-in background sweeper in `cmd/relay` — with a definite retention query (`DELETE` success rows >14d, failure/reject rows >90d) on a schedule with an owner. Either add **time-partitioning DDL** to the §8.1 schema or document an explicit partition/offload decision here (do **not** defer it to an open question). Add a disk-usage / `relay_op_logs` table-growth alert (at 50k/day/account the table grows unbounded without GC — a classic "works for months then the disk fills" surprise).
- **Metrics catalog** (spec §13.2): `relay_requests_total`, `relay_request_duration_seconds`, `relay_upstream_requests_total`, `relay_upstream_duration_seconds`, `relay_auth_failures_total`, `relay_rate_limited_total` (incl. `kind="daily"`), `relay_rate_limit_degraded_total`, `relay_idempotency_total`, `relay_apns_jwt_refresh_total`, `relay_fcm_token_refresh_total`, `relay_redis_up`, `relay_pg_up`, plus `relay_provider_healthy{provider=...}`, `relay_credential_healthy{provider=...}`, and `relay_fcm_project_quota_headroom`. **Keep labels low-cardinality** (no token, no `request_id`).
- **`/readyz` — per-provider, not all-or-nothing.** Return `200` only when the **core deps** (PG + Redis) are reachable, and report **per-provider** APNs/FCM health separately in `checks` (a `relay_provider_healthy{provider}` gauge). A single provider's credential/init failure must **not** down the whole replica (that would pull a healthy APNs replica from the LB just because FCM creds are temporarily unresolvable, killing Apple push too); instead the send handler for an un-initialized/degraded provider returns `503 upstream_unavailable` for **that provider only**. Surface per-provider circuit-breaker state so operators see "APNs degraded, FCM healthy" rather than a binary not-ready. Body shape: `503 {"status":"not_ready","checks":{...}}` only when a core dep is down (spec §5.4).
- `/readyz` and `/metrics` bound to the internal/scrape network; only `/v1/*` and `/healthz` are public (spec §11/§14.1).
-
-**Tests.**
-
- Unit: redaction middleware drops every disallowed field even when handlers attempt to log them (assert no token/bearer/JWT/OAuth2 string appears in captured log output).
- Unit: a success and a failure path each produce exactly one op-log row with the redacted subset and a `token_hash` (never raw token).
- Unit: metric counters increment with correct labels for first/replay/conflict idempotency, auth-failure reasons, rate-limit kinds, JWT/token refresh results.
- Integration: `/readyz` flips to `503` when PG or Redis is down; `/metrics` exposes the full catalog.
-
-**Acceptance criteria.**
-
- [ ] No log line or op-log row can contain a raw token, bearer header, JWT, OAuth2 token, or payload body (asserted by tests).
- [ ] All spec §13.2 metrics are exported with low-cardinality labels.
- [ ] `/readyz` reflects real dependency + credential health; `/metrics` and `/readyz` are not publicly routable.
-
---
-
-### Phase 6 — Hardening, load test, deploy  (size: L)  · gated on provisioning + secret manager
-
-**Goal.** Production hardening (real secret-manager wiring, TLS, anti-abuse), a hundreds-of-users burst load/pacing test, idempotency-under-concurrency proof, container build, and rollout.
-
-**Files to create/modify.**
-
- `internal/config/secrets_*.go` — real secret-manager integration (KMS/Vault/cloud secret manager); load `.p8`, SA JSON, pepper, DSNs at startup into memory; optional SIGHUP re-read.
- `deploy/Dockerfile` (distroless/minimal), deploy manifests, TLS/HSTS config.
- `test/load/` — k6/vegeta burst scenario + concurrency idempotency test harness.
- Alerting rules (Prometheus → alertmanager / SLO doc).
-
-**Implementation notes.**
-
- **Secrets** (spec §11, reference §4.5): credentials loaded once at startup from the secret manager into memory; never on disk in the image/repo, never logged, never returned by any endpoint. On GCP prefer keyless FCM (Workload Identity). Rolling restart picks up rotated secrets.
- **TLS** (spec §11/§14.1): HTTPS/HTTP-2 only, TLS 1.2+ (prefer 1.3), HSTS on `relay.silo.app`. Terminate at LB or in-process.
- **Anti-abuse** (spec §8.2/§11): per-IP auth-failure rate limiting keyed on the **trusted-proxy-resolved client IP** (caller-supplied `X-Forwarded-For`/`X-Real-IP` ignored — see Phase 2 client-IP resolution; the trusted-proxy CIDR list is config); **soft** lockout (latency / `Retry-After`) to avoid CGNAT/VPN collateral; body size cap; explicit timeouts; graceful shutdown. Document a response runbook for the key-guessing alert.
- **Credential-health validation & rotation runbook** (spec §4.4/§14.3). Add a **startup + periodic synthetic credential check** that proves the loaded credential actually authenticates upstream — not just that a JWT signs / a token mints locally (which `/readyz` already checks). For FCM, a `validateOnly:true` send; for APNs, an auth-exercising send to a known-bad token that still distinguishes an auth-layer `403` (`InvalidProviderToken`) from a token-layer `400` (`BadDeviceToken`). Wire the result into a `relay_credential_healthy{provider=...}` gauge and into `/readyz`'s per-provider health (below). Schedule `relayctl ping-upstream` as a cron for continuous health, and **alert on the first `upstream_auth_error`** (§6.4) — Apple actively revokes leaked `.p8` keys and SA keys/bindings can be rotated out from under the relay. Document the **rotation runbook** (overlap window, dual-key support — APNs allows multiple keys and the relay pools by team).
- **Graceful-shutdown drain ordering** (spec §14.2). On `SIGTERM`: (1) flip `/readyz` to `503` so the LB stops routing **new** requests; (2) keep serving in-flight handlers; (3) bound `srv.Shutdown(ctx)` to **less than `lock_ttl`** so any marker left by a killed-mid-flight handler expires quickly — **and** release/downgrade the in-flight idempotency marker on handler context-cancellation (Phase 2), so a drained-but-incomplete send frees its lock immediately rather than forcing the caller's retry to eat a 30s `409 idempotency_conflict`. A clean drain must leave **no orphaned in-flight idempotency markers**; the relationship between the shutdown grace period and `lock_ttl` is explicit.
- **Load/pacing test** (spec §13 / testing strategy §5 below): simulate a hundreds-of-users burst (e.g. 300–500 concurrent device sends), assert the relay stays under the per-account cap, returns correct `429` + relative `Retry-After`, and one well-tuned upstream connection sustains the throughput (reference §1.3 — thousands/sec). Verify the FCM smooth-traffic guidance does not trip quota (reference §2.7).
- **Idempotency under concurrency**: fire N concurrent requests with the **same** `Idempotency-Key`; assert **at most one** upstream send (count via a fake upstream), the rest replay or `409`.
- **FCM quota-storm shedding**: when the shared project quota is exhausted, the relay-side project circuit breaker sheds with `503 upstream_throttled` before forwarding (Phase 2 / §6.4), rather than hammering FCM into a 429 stampede.
- **HA** (spec §14.2): multiple stateless replicas behind the LB; rolling deploys; kill-safety (a drained/killed replica is covered by the caller's outbox retry). Relay-down delays, never loses.
-
-**Tests.**
-
- Load: hundreds-of-users burst (latency p50/p95/p99, error rate, `429` correctness).
- Concurrency: same-key idempotency → at-most-once upstream (assert against a counting fake).
- Security: secret-manager load path; no secret in image (`docker history`/scan); TLS config (min version, HSTS).
- Security: forged caller `X-Forwarded-For`/`X-Real-IP` does **not** change the resolved client IP / `egress_ip` (only the trusted-proxy header from an allowlisted peer is honored); per-IP throttle cannot be bypassed.
- Drain: rolling-restart drains in-flight requests via `srv.Shutdown` without dropping a completed send, `/readyz` flips to `503` before draining, and **no orphaned in-flight idempotency markers** remain afterward (an immediate caller retry does not get a spurious `409`).
- Resilience: FCM quota-exhaustion → relay sheds with `503 upstream_throttled` (project circuit breaker) instead of forwarding into a 429 storm.
- Credential health: the synthetic startup/periodic check flips `relay_credential_healthy` and `/readyz` when the loaded credential is rejected upstream (auth-layer `403`), distinct from a token-layer `400`.
-
-**Acceptance criteria.**
-
- [ ] Secrets load exclusively from the secret manager; image/repo scans show no embedded `.p8`/SA JSON/pepper.
- [ ] A hundreds-of-users burst is handled within the per-account caps with correct `429`/`Retry-After`; one upstream connection sustains the load.
- [ ] Concurrent identical-key sends produce **at most one** upstream call.
- [ ] A rolling restart drains in-flight requests, flips `/readyz` to `503` first, and leaves **no orphaned in-flight idempotency markers**.
- [ ] The synthetic credential check gates `/readyz`/`relay_credential_healthy` on real upstream acceptance; the first `upstream_auth_error` pages ops; the rotation runbook is documented.
- [ ] Forged caller forwarding headers cannot poison `egress_ip` or bypass the per-IP throttle.
- [ ] TLS 1.2+ enforced, HSTS set; `/metrics`+`/readyz` internal-only; staging deployment validated before production rollout.
-
---
-
-## 5. Testing Strategy
-
-### 5.1 Layers
-
-| Layer | What it covers | Provider creds? |
-|---|---|---|
-| **Unit** | Field validation, JWT/token lifecycle math, key hashing/compare, error-table mappings, redaction, metric labels | No |
-| **Contract** | Exact `02`/`03` request/response shapes: `DisallowUnknownFields` rejects every disallowed field; success/error bodies are byte-exact; `pushwire` golden files | No |
-| **Integration** | Real upstream behavior: APNs **sandbox** sends; FCM **`validateOnly:true`** validation; PG migrations; Redis rate-limit/idempotency | APNs `.p8` / FCM SA (sandbox) |
-| **Redaction assertions** | No raw token/bearer/JWT/OAuth2/payload ever reaches a log or op-log | No |
-| **Load / pacing** | Hundreds-of-users burst; per-account cap + `429`/`Retry-After`; upstream connection reuse sustains throughput | Optional (fake upstream) |
-| **Idempotency-under-concurrency** | Same key, many concurrent requests → at-most-once upstream send | No (fake upstream) |
-| **Failure-mode** | APNs `GOAWAY`/mid-stream reset mapping (no lost/double send); JWT-expiry single-flight (one regen, zero `TooManyProviderTokenUpdates`); Redis dropped mid-request (idempotency fail-closed, rate-limit bounded fail-open); graceful-drain leaves no orphaned idempotency lock; FCM quota-exhaustion shedding | No (fakes) |
-
-### 5.2 Contract tests against the 02/03 shapes
-
-For each endpoint, a golden corpus of requests/responses derived from spec §5.1/§5.2:
-
- **Valid** `private_alert` / `background_wake` (APNs) and `private_data` / `background_wake` (FCM) requests → assert the built upstream payload + headers are **byte-exact** vs the spec (the `pushwire` golden files).
- **Every disallowed field** (`title`, `body`, `image_url`, `media_id`, `username`, `server_url`, `notification`, …) → `400 unexpected_field`.
- **Every validation failure** → its exact `error.code` (`invalid_token`, `invalid_environment`, `invalid_mode`, `invalid_collapse_id`, `topic_not_allowed`, `project_not_allowed`, `package_not_allowed`, `missing_idempotency_key`, …).
- The same `pushwire` golden corpus is shared with `silo-server`'s `custom_apns`/`custom_fcm` tests. Because a copied package in one repo cannot fail the other repo's CI on its own, the mirror is a **checked-in generated artifact with a committed checksum** that **both** repos verify in CI against the canonical hash (see §3 sync runbook) — a divergence fails CI on both sides regardless of which repo changed first.
- **Closed-allowlist assertion (privacy guarantee):** a dedicated test asserts the FCM `data` map keys and the APNs payload key set are **exactly** the closed allowlist, so adding any key (e.g. smuggling content into `data`) fails CI even if golden files are regenerated. The content-free guarantee is enforced structurally, not only by golden equality.
-
-### 5.3 Integration against sandbox / validateOnly
-
- **APNs sandbox** (`api.sandbox.push.apple.com`): a real send returns 200 + `apns_id`; a deliberately invalid token returns the mapped `bad_device_token` / `unregistered`. Run behind `-tags=integration`, only when `.p8` secrets are present (CI `integration` job).
- **FCM `validateOnly:true`** (reference §2.5): a valid request validates without delivering; a malformed token surfaces `invalid_argument`/`unregistered`. **Never** `validateOnly` on production sends.
-
-### 5.4 Redaction assertions
-
-Capture log + op-log output across success and every error path; assert via regex that none of: the bearer value, the raw `rk_` secret, a raw device token, the relay JWT, or an OAuth2 access token ever appears, and that `token_hash` is present where a token was involved (spec §12/§13.1).
-
-### 5.5 Load / pacing test (hundreds-of-users burst)
-
-Simulate a burst of several hundred concurrent device sends (one account, mixed APNs/FCM) against a **fake upstream** that records call counts and timing:
-
- Assert per-account rate limiting holds (10 req/s burst + 50k/day; spec §9.2) and over-limit responses are `429` with a **relative** `Retry-After`.
- Assert one upstream HTTP/2 connection is reused (no connection-per-push) and sustains the burst (reference §1.3/§3.1).
- Assert latency percentiles and zero double-sends.
-
-### 5.6 Idempotency-under-concurrency test
-
-Fire N (e.g. 50) concurrent requests sharing one `Idempotency-Key` at a fake upstream that increments a counter per call. Assert: **exactly one** upstream call; the other N−1 either replay the stored result or receive `409 idempotency_conflict`; a follow-up with a **different** payload but the same key returns `422 idempotency_key_reuse`. This proves at-most-once upstream send under the caller's concurrent outbox retries (spec §10.2).
-
-### 5.7 Failure-mode tests (the exact modes on-call hits)
-
-Beyond the happy path and the error-table mappings, the plan tests every failure mode that actually pages an engineer (all use fakes — no provider creds):
-
- **APNs `GOAWAY` / mid-stream reset.** A fake APNs upstream injects `GOAWAY` (or resets the stream) before a final response mid-burst → the caller-facing result is `503 upstream_unavailable`, the op-log/metric is tagged `connection_severed`, and a counting fake confirms **no lost or double send** (no transparent retry).
- **JWT expiry under concurrency.** Force the cached APNs JWT to expire under a concurrent burst → assert **exactly one** single-flighted regeneration and **zero** `429 TooManyProviderTokenUpdates`.
- **Redis dropped mid-request** (not just down at start) → idempotency fails **closed** (`503`); rate-limit degrades to **bounded** fail-open; a lock whose TTL expires mid-send cannot be stolen (upstream deadline `<` `lock_ttl`).
- **Graceful-drain idempotency.** A rolling restart during in-flight sends leaves **no orphaned in-flight idempotency markers** (an immediate caller retry does not eat a spurious `409`); `/readyz` flips to `503` before draining.
- **FCM quota-exhaustion shedding.** With the shared project quota exhausted, the relay-side project circuit breaker sheds with `503 upstream_throttled` instead of forwarding into a 429 storm.
-
---
-
-## 6. Deployment
-
-### 6.1 Container build
-
- `deploy/Dockerfile`: multi-stage; static `relay` (and `relayctl`) binaries on a distroless/minimal base. **No credentials baked in** (spec §11). Non-root user; read-only filesystem where possible.
- Image carries only the binary + CA roots (ensure USERTrust RSA present — default in `ca-certificates`; spec §6.3).
-
-### 6.2 Secret provisioning
-
-| Secret | Source | Notes |
-|---|---|---|
-| APNs `.p8` + Key ID + Team ID | secret manager (or mounted file) | per official team; never env/image (spec §14.3) |
-| FCM SA JSON **or** Workload Identity | GCP keyless (on-GCP) / secret manager JSON (off-GCP) | open Q#4 (spec §15) |
-| API-key HMAC pepper | secret manager | rotation is heavier (open Q#6) |
-| Postgres DSN, Redis URL | secret manager | privileged `relayctl` DSN held only by operators |
-
-Rotation: issue a new APNs key / FCM credential, deploy, retire the old; the relay loads secrets at startup so a rolling restart picks them up (spec §14.3). Optional SIGHUP re-read.
-
-### 6.3 TLS, health, metrics wiring
-
- TLS 1.2+ (prefer 1.3), HTTP/2, HSTS on `relay.silo.app`; terminate at LB or in-process (spec §14.1).
- **Public:** `/v1/apple/send`, `/v1/fcm/send`, `/healthz`. **Internal-only:** `/readyz`, `/metrics` (spec §11/§14.1).
- Liveness probe → `/healthz`; readiness probe → `/readyz`; Prometheus scrapes `/metrics` on the internal network.
-
-### 6.4 Monitoring / alerting
-
-Alert on (from the §13.2 catalog):
-
- **First `upstream_auth_error` → page ops.** Alert on the caller-facing `upstream_auth_error` reason (the relay's genuine `.p8`/SA/OAuth2 credential failure — a non-200 from `oauth2.googleapis.com/token`, or `401 UNAUTHENTICATED`/`403 PERMISSION_DENIED`/`InvalidProviderToken` on send) > 0 → **credential misconfig, page ops**: never caller-fixable. **Do NOT** key this alert on `THIRD_PARTY_AUTH_ERROR`, which on this pure-Android path indicates a per-token/registration anomaly, not a relay-credential problem (see Phase 4 reclassification) — surface it for investigation at most, never page.
- **Proactive credential-health alert.** Alert if the periodic synthetic credential check (Phase 6: a scheduled `relayctl ping-upstream` / `validateOnly` FCM send + APNs auth-exercising probe, plus the `relay_credential_healthy` gauge wired into `/readyz`) reports the loaded `.p8`/SA/Workload-Identity credential is no longer accepted upstream — Apple actively revokes leaked `.p8` keys and SA keys/bindings can be rotated out from under the relay, so this must fire **before** production sends start failing.
- Sustained `relay_rate_limit_degraded_total` increase → Redis degraded (fail-open active; in-process per-account fallback limiter engaged).
- `relay_redis_up == 0` / `relay_pg_up == 0`; any provider showing `relay_provider_healthy{provider=...} == 0` → that upstream is degraded (per-provider, not a whole-replica outage).
- Elevated `relay_requests_total{status_code="5xx"}` rate; `relay_request_duration_seconds` p99 regression.
- `relay_upstream_requests_total{upstream_reason="QUOTA_EXCEEDED"}` and **low `relay_fcm_project_quota_headroom`** → shared FCM project quota pressure: the relay-side project limiter is shedding with `503 upstream_throttled` before hammering FCM (watch Cloud Console; spec §14.5). Treat as a multi-tenant fairness event — one noisy account must not exhaust the ~600k/min project quota shared across all accounts.
- Accounts approaching/hitting the **per-account daily cap** (`relay_rate_limited_total{kind="daily"}`) → a legitimate big-release burst can hit 50k/day; surface for an operator to consider a temporary cap bump.
- Anomalous `relay_auth_failures_total` rate from an egress IP → possible key-guessing (see §6.4 anti-brute-force; the per-IP limiter consumes the resolved client IP, not a caller-supplied header). Note: the fine-grained `reason` (unknown-prefix vs hash-mismatch) is internal-only and must not be exposed to tenants.
-
-### 6.5 Rollout
-
- **Staging first** (spec §14.4): separate hostname + separate accounts so client QA never touches production quotas. Validate APNs sandbox + FCM `validateOnly` end-to-end.
- **HA / rolling** (spec §14.2): multiple stateless replicas behind the LB; rolling deploy with drain (`srv.Shutdown`); a killed replica is covered by the caller's outbox retry — **relay-down delays, never loses**.
- Single region in v1, close to PG/Redis (spec §14.5).
-
---
-
-## 7. Provisioning Checklist (the long pole — start day 1)
-
-> These gate the phases that touch live providers (Phase 3 APNs, Phase 4 FCM, Phase 6 production). Run them **in parallel** with Phases 0–2, which need no credentials.
-
-### 7.1 Apple (gates Phase 3 + Phase 6)
-
- [ ] Apple Developer **Program account / team** with push entitlement (capture the 10-char **Team ID**).
- [ ] Generate an **APNs Auth Key (`.p8`)** in the developer portal; capture the **Key ID** (10 chars) and download the `.p8` **once** (Apple shows it once). Store in the secret manager (spec §14.3).
- [ ] Consider Feb-2025 **scoped keys** (team-scoped or topic-specific) for least privilege (reference §1.2).
- [ ] Register per-platform **bundle topics** for the official build config and seed the account allowlist (spec §8.4): `com.continuum.app.ios`, `com.continuum.app.tvos`, `com.continuum.app.macos`.
- [ ] Standardize on the **sandbox host** `api.sandbox.push.apple.com` (reference §1.3; `api.development.push.apple.com` is an equivalent still-resolving alias — no build-time resolution needed) and confirm the APNs server TLS root (**USERTrust RSA**, present in standard pools; spec §6.3 / reference §1.7).
- [ ] Decide `apns2` vs hand-rolled client (open Q#3) before Phase 3.
-
-### 7.2 Firebase / Google (gates Phase 4 + Phase 6)
-
- [ ] Firebase **project(s)** for the official build config: `continuum-prod-android` (and a staging project if desired).
- [ ] Register the Android **package** `com.continuum.app.android`; seed the FCM allowlist `(project_id, package_name)` (spec §8.4).
- [ ] Provision a **service account** with the least-privilege `firebase.messaging` scope (reference §2.2). On GCP, prefer keyless **Workload Identity / attached SA**; off-GCP, download the **service-account JSON** and store it in the secret manager — never in repo/image (reference §2.2/§4.5; open Q#4).
- [ ] Confirm the global send host `fcm.googleapis.com` (no regional endpoints; reference §2.3) and the default ~600k msgs/min project quota (reference §2.7 / spec §14.5).
-
-### 7.3 Cross-cutting
-
- [ ] Secret manager chosen and wired (KMS/Vault/cloud secret manager) for `.p8`, SA JSON, pepper, DSNs (spec §11 / Phase 6).
- [ ] DNS + TLS cert for `relay.silo.app` (and the staging hostname).
-
---
-
-## 8. Risks, Mitigations, and Milestone Sequencing
-
-### 8.1 Risks and mitigations
-
-| # | Risk | Likelihood | Impact | Mitigation |
-|---|---|---|---|---|
-| R1 | **Provider provisioning slips** (Apple/Firebase approvals) — the real long pole | Med | High (blocks Phase 3/4/6) | Start §7 on day 1 in parallel; Phases 0–2 + all unit/contract tests need no creds; fakes for upstream |
-| R2 | `sideshow/apns2` is unmaintained (no release since Oct 2024) | Med | Med | Hide behind `internal/apns` interface; prototype hand-rolled `x/net/http2`+`golang-jwt/jwt/v5` in Phase 3; decide per open Q#3 |
-| R3 | **JWT/token mishandling** (over-frequent refresh → APNs `429 TooManyProviderTokenUpdates`; per-request mint → throttling; concurrent-403 stampede) | Med | High | Cache + mutex; ~50-min APNs refresh (never <20min), eager-on-expired; **single-flighted regeneration** so a concurrent burst of `ExpiredProviderToken` yields exactly one refresh per ~20-min window; OAuth2 `TokenSource` auto-refresh; metrics `relay_apns_jwt_refresh_total`/`relay_fcm_token_refresh_total` |
-| R4 | **Double-send** under concurrent caller retries (incl. lock-TTL expiry mid-send, and stale in-flight markers after a killed/drained replica) | Med | High | Redis `SET NX` idempotency, **fail-closed**; pin the upstream call deadline **strictly shorter than `lock_ttl`** (≈10 s upstream vs 30 s lock) and refuse to send if the deadline already passed the lock TTL; release/downgrade the in-flight marker on handler context-cancellation; at-most-once test (§5.6); drain test asserting no orphaned in-flight markers (§5.7); key includes `attempt_number` |
-| R5 | **Redis outage / eviction** | Low | Med | Rate-limit **fails open but bounded** (in-process per-account fallback limiter, logged + metric); idempotency **fails closed** (`503`, retryable via caller outbox); idempotency keyspace requires a **non-evicting `maxmemory-policy` (`noeviction`)** or a dedicated Redis/db so a rate-limit eviction can never silently drop an in-flight idempotency lock (which would violate at-most-once) |
-| R6 | **Content/identity leak** despite design | Low | Critical | Structural: `DisallowUnknownFields`, content-free schema, data-only FCM, badge-off-by-default, redaction in middleware, op-logs hold only `token_hash` |
-| R7 | **Cross-tenant push** (one account targeting another's topic/token) | Low | High | Per-account allowlist enforced after auth; namespaced Redis keys; per-account-scoped allowlist cache |
-| R8 | **Stolen relay API key** (incl. abuse-amplification during a Redis outage, and per-IP-throttle bypass via forged forwarding headers) | Low | Med | Revocable keys (`relayctl key revoke`), per-account rate caps + allowlist bound spend; **bounded** fail-open (in-process per-account cap when Redis is down — never unlimited); per-IP auth-failure throttling keyed on a **trusted-proxy-resolved client IP** (caller-supplied `X-Forwarded-For`/`X-Real-IP` ignored) |
-| R9 | **`pushwire` drift** between relay and `silo-server` | Med | Med | One **canonical source repo**; mirror is a checked-in generated artifact with a committed **checksum** verified in CI on **both** sides; golden-file + closed-allowlist-key tests fail CI on divergence regardless of regeneration order |
-| R10 | **APNs TLS root rotation** (USERTrust) | Low | Low | Use `api.sandbox.push.apple.com` (the `api.development.*` alias is equivalent and still resolves — not a risk); rely on the standard trust store (already includes USERTrust RSA) |
-| R11 | **FCM high-priority deprioritization** over 7-day window (reference §2.8) | Low | Low | Honor `03`'s `priority:high` for `private_data` (app surfaces a notification); caller-side `priority:normal` fallback is the lever (open Q#10) |
-| R12 | **Op-log volume** at 50k/day/account across many accounts (unbounded table → disk fills) | Med | Low | **Shipped** retention GC (`relayctl logs --gc` / background sweeper: 14d success / 90d failure) on a schedule with an owner; time-partitioning DDL (or a documented partition/offload decision); table-growth/disk alert |
-
-### 8.2 Milestone sequencing & rough effort
-
-| Milestone | Phases | Effort | Provider creds needed | Parallelizable |
-|---|---|---|---|---|
-| **M0 — Skeleton green** | Phase 0 | ~M (1 wk) | No | — |
-| **M1 — Storage + admin** | Phase 1 | ~L (1 wk) | No | with §7 provisioning |
-| **M2 — Request path (no upstream)** | Phase 2 | ~L (1 wk) | No | with §7 provisioning |
-| **M3 — APNs live (sandbox)** | Phase 3 | ~L (1 wk) | **Apple `.p8`** | Phase 3 ∥ Phase 4 |
-| **M4 — FCM live (validateOnly)** | Phase 4 | ~L (1 wk) | **Firebase SA** | Phase 4 ∥ Phase 3 |
-| **M5 — Observability** | Phase 5 | ~M (3 d) | No | — |
-| **M6 — Hardened + deployed** | Phase 6 | ~L (1 wk) | All + secret manager | — |
-
-**Rough total:** ~6–7 engineer-weeks of code, with **§7 provisioning running in parallel from day 1** as the gating long pole for M3/M4/M6. Phases 3 and 4 can be split across two engineers once Phase 2 lands. The critical path is: M0 → M1 → M2 → (M3 ∥ M4) → M5 → M6, intersected with provisioning availability.
-
---
-
-## 9. Open Questions (carried from spec §15)
-
-These do not block starting; resolve at the noted phase.
-
-1. **Per-account rate limits — real numbers** (resolve from logs post-M6; spec §9.2). v1 ships ~10 req/s burst + 50k/day.
-2. **APNs sandbox hostname** (resolved — note only). Use `api.sandbox.push.apple.com`; `api.development.push.apple.com` is an equivalent, still-resolving sandbox alias. The two are interchangeable, so no build-time resolution is required — this is a standardization note, not an open question.
-3. **`apns2` vs hand-rolled APNs client** — decide before Phase 3 (§3, reference §3.1).
-4. **FCM credentials: GCP-keyless vs off-GCP JSON** — resolve in deployment design (Phase 6).
-5. **`apns-expiration` / `android.ttl` defaults** (largely resolved). v1 ships a **finite** default (not omitted/30-day): a few hours for `private_alert`, short TTL for `background_wake`, with a matching finite FCM `android.ttl`; both configurable. Only the exact numeric values want product input.
-6. **API-key hashing: HMAC pepper vs plain salted SHA-256** — plan chooses HMAC pepper; confirm rotation tradeoff (Phase 1).
-7. **Idempotency-Key spec status** — header name + Stripe-style semantics are de-facto; re-check for an RFC.
-8. **Op-log volume & retention** (resolved into a Phase 5 deliverable). Ship `relayctl logs --gc` (or a background sweeper): 14d success / 90d failure, on a schedule with an owner, plus time-partitioning DDL (or a documented partition/offload decision) and a table-growth alert — not deferred.
-9. **Multi-region** — out of scope for v1; design later if latency to distant self-hosters matters.
-10. **FCM priority deprioritization** — honor `03`'s `priority:high`; revisit only if metrics show systematic deprioritization.
@@ -1,554 +0,0 @@
-# APNs & FCM 2026 Reference — Privacy-Preserving Push Relay
-
-> **Provenance.** This document reflects **2026-current** Apple (APNs) and Google (FCM HTTP v1) developer documentation, plus the current Go ecosystem and OWASP guidance. Every non-obvious factual claim carries an inline citation in the form `(source: URL, date)`. Where a primary source disagreed with secondary/blog material, the primary source wins and the secondary claim is flagged as inaccurate. Where a fact remains uncertain, it is called out explicitly rather than overstated.
->
-> **Compile date:** _<!-- PLACEHOLDER: set at compile time -->_
->
-> **Commands assume the repository root is the cwd.** No local absolute filesystem paths appear in this document; all repo references are repository-relative.
-
-## Scope
-
-This is the factual foundation for a self-hosted, privacy-preserving push **relay** — a server that accepts notification requests from authenticated tenants and forwards them to Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM) on their behalf, without the providers (or other tenants) learning more than necessary. It captures the wire-level contracts (auth, endpoints, headers, payloads, errors, throttling), the recommended Go libraries and tuning, and the security/ops practices the spec and implementation plan are written against. It does **not** cover client-side SDK integration except where client behavior (token rotation, notification-permission gating) constrains relay design.
-
---
-
-## 1. APNs (2026)
-
-### 1.1 Provider authentication — token-based (JWT, ES256)
-
-APNs supports **both** token-based and certificate-based provider authentication over HTTP/2 + TLS in 2026; Apple does **not** deprecate certificate-based auth. Both have dedicated docs and no deprecation notice (source: https://developer.apple.com/documentation/usernotifications/setting-up-a-remote-notification-server, 2026-06-13). The relay should use **token-based** (`.p8`) auth: the signing key does not expire (it can be revoked), one key covers sandbox + production and all/subset of a team's apps, and there is no yearly certificate renewal.
-
-> **Correction vs. common blog claims:** Third-party posts claiming Apple is "deprecating / shutting down certificate-based auth in 2025" are **inaccurate**. The only confirmed 2025 changes are (a) the APNs **server** TLS root-CA rotation (§1.7) and (b) the optional token-key hardening features (§1.2). Neither deprecates provider auth (source: https://developer.apple.com/documentation/usernotifications/setting-up-a-remote-notification-server, 2026-06-13).
-
-**JWT structure.** APNs supports **only the ES256** algorithm (ECDSA over P-256); no other algorithm is accepted (source: https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns, 2026-06-13).
-
-```jsonc
-// JWT header
-{
-  "alg": "ES256",      // ES256 ONLY
-  "kid": "ABC123DEFG"  // 10-char Key ID from the developer account
-}
-// JWT claims
-{
-  "iss": "DEF123GHIJ", // 10-char Team ID
-  "iat": 1437179036    // issued-at, seconds since Epoch (UTC)
-}
-```
-
-The JWT is signed with the `.p8` ECDSA P-256 private key using ES256. It is sent on **every** notification request as an HTTP/2 header in Base64URL-encoded JWT form (source: https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns, 2026-06-13):
-
-```http
-authorization: bearer eyAia2lkIjog...MEYCIQDz...
-```
-
-**Lifecycle & regeneration cadence (critical):**
-
-| Rule | Value | Source |
-|---|---|---|
-| Max token age (`iat`) | ≤ 1 hour, else `ExpiredProviderToken` (403) | (source: …/establishing-a-token-based-connection-to-apns, 2026-06-13) |
-| Refresh **no more** often than | once every **20 minutes** (per connection) | (same) |
-| Refresh **no less** often than | once every **60 minutes** | (same) |
-| Over-frequent refresh → | `TooManyProviderTokenUpdates` (429) | (source: …/handling-notification-responses-from-apns, 2026-06-13) |
-
-**Relay pattern:** Generate **one** ES256 JWT, cache it in memory behind a mutex, and reuse it across **all** senders/connections/topics. Regenerate on a ~50-minute timer (well inside the 1-hour window, never < 20 min apart), or eagerly on a `403 ExpiredProviderToken`. Never sign a fresh JWT per request.
-
-**One key, many servers.** A single key/token can be reused across multiple provider servers, multiple connections, and all (or a subset) of a team's apps/topics — confirmed verbatim by Apple: "You can use the same token from multiple provider servers" and "You can use one token to distribute notifications for all or a subset of your company's apps" (source: https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns, 2026-06-13). **Caveat:** a connection cannot map to multiple teams — "If you manage APNs for multiple developer accounts, open separate connection pools for each of them" (same source). For a multi-tenant relay, this means **per-team connection pools**.
-
-### 1.2 Token-key hardening (Feb 2025, optional)
-
-On **2025-02-17** Apple added optional scoped token keys; the classic unrestricted team key still works, and "you don't have to update your keys unless you want to take advantage of the new capabilities" (source: https://developer.apple.com/news/?id=wy4tb0uo, 2025-02-17). Two new key types:
-
-| Key type | Scope | Limit |
-|---|---|---|
-| **Team-scoped key** | Sandbox **or** Production only; all topics in the team | max **2 keys per environment** |
-| **Topic-specific (topic-based) key** | Bound to specific bundle IDs (least privilege) | max **200 keys for Sandbox and 200 for Production, with up to 400 topics per topic-based key** |
-
-(source: https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns, 2026-06-13 — verbatim scoped-key limit confirmed). For a multi-tenant relay these are a meaningful isolation lever: issue separately scoped `.p8` keys per environment/app rather than one all-powerful key.
-
-### 1.3 Endpoints & HTTP/2 connection management
-
-| Environment | Host | Ports |
-|---|---|---|
-| Production | `api.push.apple.com` | 443 or 2197 |
-| Development / sandbox | `api.sandbox.push.apple.com` | 443 or 2197 |
-
-(source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13). Port 2197 is functionally equivalent to 443 and exists so firewalls can allow APNs while blocking other 443 traffic — keep it as a fallback. `api.push.apple.com` (production) and `api.sandbox.push.apple.com` (sandbox) are the current canonical hosts named in Apple's docs. The older `api.development.push.apple.com` is a **still-valid equivalent alias for sandbox**: as of 2026-06-13 both names resolve to the same Akamai CNAME (`api-sand-vs.push-apple.com.akadns.net`) and the same IP set (verified by DNS, e.g. `17.188.168.x`), so they hit the identical sandbox backend. We **standardize on `api.sandbox.push.apple.com`** (it matches the canonical docs and `sideshow/apns2` v0.25.0's `HostDevelopment` constant), but the alias is not dead — see §5.
-
- **Transport:** HTTP/2 with **TLS 1.2 or later** (TLS 1.3 acceptable). `:method POST`, `:path /3/device/<device_token>` where the token is the hex bytes of the device token (source: …/sending-notification-requests-to-apns, 2026-06-13).
- **Connection reuse:** "Reuse a connection as long as possible. In most cases, you can reuse a connection for many hours to days. If your connection is mostly idle, you may send a HTTP2 PING frame after an hour of inactivity." Reuse reduces bandwidth/CPU; rapid connect/disconnect is treated as DoS-like behavior (source: …/sending-notification-requests-to-apns, 2026-06-13).
- **Stream multiplexing:** "APNs allows multiple concurrent streams for each connection, but don't assume a specific number of streams." Read the server's `SETTINGS_MAX_CONCURRENT_STREAMS`; do not hardcode. The exact number varies by server load and auth type (same source). A single well-tuned connection handles thousands of pushes/sec.
- **GOAWAY handling:** When APNs terminates a connection it sends an HTTP/2 `GOAWAY` frame whose payload includes JSON with a `reason` key. Apply RFC 9113 §6.8: stop opening new streams, finish in-flight streams with ID ≤ `Last-Stream-ID`, open a new connection for the rest; `NO_ERROR` = graceful shutdown, any other code = connection error (source: https://www.rfc-editor.org/rfc/rfc9113#section-6.8, 2022-06). The relay should drop a GOAWAY'd connection from the pool and transparently reconnect. Go's `net/http2` transport does most of this automatically when one `http.Client` is reused.
-
-```mermaid
-flowchart LR
-  R[Relay sender goroutines] -->|stream 1..N over 1 conn| C{HTTP/2 conn pool}
-  C -->|POST /3/device/token| A[api.push.apple.com:443]
-  A -. GOAWAY reason JSON .-> C
-  C -->|drop + reconnect| C2[new conn]
-  C2 -->|in-flight <= Last-Stream-ID finish on old conn| A
-```
-
-### 1.4 Request headers
-
-`:method = POST`, `:path = /3/device/<device_token>`. Payload is **uncompressed** JSON.
-
-| Header | Required | Allowed values / format | Notes |
-|---|---|---|---|
-| `authorization` | yes (token auth) | `bearer <ES256 JWT>` | Ignored on cert connections |
-| `apns-topic` | yes | bundle ID, optionally with a type suffix (see §1.5) | `MissingTopic`/`BadTopic` (400) on error |
-| `apns-push-type` | required on **watchOS 6+**, strongly recommended elsewhere | `alert`, `background`, `controls`, `fileprovider`, `liveactivity`, `location`, `mdm`, `pushtotalk`, `voip`, `widgets`, `complication` | Must match payload; invalid → `InvalidPushType` (400) |
-| `apns-priority` | no (default 10) | `10`, `5`, `1` | See §1.4.1; invalid → `BadPriority` (400) |
-| `apns-expiration` | no | UNIX epoch seconds (UTC) | `0` = deliver once, no store; nonzero = store & retry up to **30 days**; invalid → `BadExpirationDate` (400) |
-| `apns-collapse-id` | no | ≤ **64 bytes** | Same value merges notifications on-device (latest wins); >64B → `BadCollapseId` (400) |
-| `apns-id` | no | canonical UUID (8-4-4-4-12, lowercase hex) | Echoed in response; auto-generated if omitted; invalid → `BadMessageId` (400) |
-
-(source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13). `apns-push-type` required on watchOS 6+ confirmed (source: https://developer.apple.com/documentation/usernotifications, 2026-06-13).
-
-**`apns-topic` suffixes by push type** (source: …/sending-notification-requests-to-apns, 2026-06-13):
-
-| Push type | `apns-topic` suffix |
-|---|---|
-| `complication` | `.h.complication` |
-| `controls` | `.push-type.controls` |
-| `fileprovider` | `.pushkit.fileprovider` |
-| `liveactivity` | `.push-type.liveactivity` |
-| `location` | `.location-query` |
-| `pushtotalk` | `.voip-ptt` |
-| `voip` | `.voip` |
-| `widgets` | `.push-type.widgets` |
-| `alert` / `background` | (none — bare bundle ID) |
-
-#### 1.4.1 `apns-priority` semantics (corrected)
-
-`apns-priority` is optional; if omitted, APNs sets priority to 10. Three values, with these exact semantics (source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13):
-
-| Value | Meaning |
-|---|---|
-| `10` | Send the notification **immediately** (use for alert/sound/badge). |
-| `5` | Send based on **power considerations** on the user's device. |
-| `1` | Prioritize power over all factors and **do not wake the device** (lowest-power). |
-
- For `apns-push-type=background`, Apple's guidance is explicit and **narrower** than some sources state: "**Always use priority 5. Using priority 10 is an error.**" Apple does **not** list priority `1` as an accepted alternative for background pushes (source: same, 2026-06-13).
- The claim that priority `1` is a "new tier for Live-Activity-style delivery" is **not supported** by Apple's docs. Live Activity updates use `apns-push-type=liveactivity` (typically priority 10 for immediate or 5 for throttled), not a priority-1 mechanism. Priority `1` is simply the lowest-power option (source: same, 2026-06-13).
-
-### 1.5 Payload shapes & size limits
-
-**Size limits** (source: https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification, 2026-06-13):
-
-| Type | Max payload |
-|---|---|
-| Regular (alert/background/etc.) | **4096 bytes (4 KB)** |
-| VoIP (PushKit) | **5120 bytes (5 KB)** |
-
-Oversize → `413 PayloadTooLarge`. Payload must **not** be compressed. Live Activity payloads use the standard 4 KB limit.
-
-**Payload root** = reserved `aps` dictionary + optional custom keys. `aps` keys (source: same, 2026-06-13): `alert`, `badge`, `sound`, `thread-id`, `category`, `content-available`, `mutable-content`, `target-content-id`, `interruption-level`, `relevance-score`, `filter-criteria`.
-
-**Alert (user-facing) example:**
-
-```json
-{
-  "aps": {
-    "alert": { "title": "Title", "subtitle": "Sub", "body": "Body text" },
-    "badge": 1,
-    "sound": "default",
-    "thread-id": "thread-42",
-    "interruption-level": "active",
-    "relevance-score": 0.8
-  },
-  "custom-key": "opaque-relay-payload"
-}
-```
-
-The `alert` sub-dictionary supports `title`/`subtitle`/`body` plus localization keys (`loc-key`/`loc-args`, `title-loc-key`/`title-loc-args`, `subtitle-loc-key`/`subtitle-loc-args`), `launch-image`, and the legacy `action-loc-key` (source: same, 2026-06-13).
-
-`interruption-level` accepts exactly: `passive`, `active` (default), `time-sensitive` (needs Time Sensitive Notifications entitlement), `critical` (needs Critical Alerts entitlement, Apple-approved). Critical sound uses a **dictionary**: `{ "critical": 1, "name": "...", "volume": 0.0–1.0 }` (source: same, 2026-06-13).
-
-**Background (silent) example** — must set `apns-push-type=background`, `apns-priority=5`, and an `aps` containing **only** `content-available: 1` (no `alert`/`badge`/`sound`):
-
-```json
-{ "aps": { "content-available": 1 } }
-```
-
-(source: https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app, 2026-06).
-
-**Live Activity** remote pushes use `apns-push-type=liveactivity`, `apns-topic=<bundleID>.push-type.liveactivity`, **token-based auth only**. The `aps` adds: `event` (`start`|`update`|`end`), `content-state` (decodes into the app's `ActivityAttributes.ContentState`), `timestamp`, `stale-date`, `dismissal-date` (UNIX seconds), optional `relevance-score` and `alert`. `attributes-type` + `attributes` are included **only** for `event: start` (push-to-start). For Live Activities, `relevance-score` is an **unconstrained Double** (Smart Stack ordering), not the 0–1 range used by `UNNotificationContent.relevanceScore` (source: https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications, 2026-06).
-
-### 1.6 Status codes & reason strings
-
-**HTTP status codes** (source: https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns, 2026-06-13): 200, 400, 403, 404, 405, 410, 413, 429, 500, 503.
-
-For unsuccessful requests the body is a JSON object `{"reason":"<String>"}`; for **410** it additionally includes a `timestamp` (Number, **milliseconds** since Epoch) indicating when the token became invalid for the topic (source: same).
-
-| Status | Reason strings | Meaning / handling |
-|---|---|---|
-| 200 | — | Success. Echoed `apns-id` header; in **dev**, `apns-unique-id` header (response-only) for Push Notifications Console Delivery Log. |
-| 400 | `BadCollapseId`, `BadDeviceToken`, `BadExpirationDate`, `BadMessageId`, `BadPriority`, `BadTopic`, `DeviceTokenNotForTopic`, `DuplicateHeaders`, `IdleTimeout`, `InvalidPushType`, `MissingDeviceToken`, `MissingTopic`, `PayloadEmpty`, `TopicDisallowed` | Bad request. **Do not retry.** `BadDeviceToken`/`DeviceTokenNotForTopic` ⇒ purge token. |
-| 403 | `BadCertificate`, `BadCertificateEnvironment`, `ExpiredProviderToken`, `Forbidden`, `InvalidProviderToken`, `MissingProviderToken`, `UnrelatedKeyIdInToken`, `BadEnvironmentKeyIdInToken` | Auth/cert error. `ExpiredProviderToken` ⇒ regenerate JWT & retry once. `Invalid/MissingProviderToken` ⇒ config error (don't blind-retry). `UnrelatedKeyIdInToken` ⇒ open a new connection. |
-| 404 | `BadPath` | Invalid `:path`. Don't retry. |
-| 405 | `MethodNotAllowed` | Only `POST` allowed. Don't retry. |
-| 410 | `Unregistered`, `ExpiredToken` | Token no longer active for topic. **Permanently stop sending** to that token (until app re-registers). Use the `timestamp` (ms): only purge if your registration is older than it. Not a connection error / no disconnection. |
-| 413 | `PayloadTooLarge` | Payload exceeds 4 KB (5 KB VoIP). Don't retry. |
-| 429 | `TooManyProviderTokenUpdates`, `TooManyRequests` | Back off. `TooManyProviderTokenUpdates` ⇒ slow JWT refresh (≤ once/20 min). `TooManyRequests` ⇒ per-device-token backoff. |
-| 500 | `InternalServerError` | Transient. Retry after ~15 min with backoff. |
-| 503 | `ServiceUnavailable`, `Shutdown` | Transient. Retry after ~15 min with backoff. |
-
-(source: https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns, 2026-06-13).
-
-**Retry policy summary.** Never retry permanent errors (`BadDeviceToken`, `Unregistered`, `ExpiredToken`, `PayloadTooLarge`, `DeviceTokenNotForTopic`, `Forbidden`); back off on 429; retry 5xx after ~15 min with backoff. 410 is **not** treated as a connection error (source: same, 2026-06-13). Always parse the JSON `reason`, not just the status code.
-
-### 1.7 APNs server TLS root rotation (2025) — trust-store only
-
-APNs migrated its **server** TLS certificate to a new SHA-2 root, **USERTrust RSA Certification Authority** (a Sectigo root): sandbox **2025-01-20**, production **2025-02-24** (source: https://developer.apple.com/news/?id=09za8wzy, 2024-10-17; effective per https://developer.apple.com/news/upcoming-requirements/?id=02242025a, 2025-02-24).
-
- This affects only how the relay **validates the APNs server TLS chain** — it does **not** require updating the APNs SSL provider certificates Apple issued you, nor app/account certs.
- Standard OS / Go system root pools (macOS/iOS, Linux `ca-certificates`, Go `crypto/x509` system pool) **already trust** USERTrust RSA, so no action is needed unless the relay **pins** or ships a **custom/minimal** trust store — in which case it must add this root or TLS handshakes fail after the cut-over dates.
- No newer APNs cert/infrastructure requirement is published on Apple's Upcoming Requirements page as of June 2026 (source: https://developer.apple.com/news/upcoming-requirements/?id=02242025a, 2025-02-24).
-
-### 1.8 Background-push throttling
-
-Background (`content-available`) pushes are best-effort and throttled. Apple's verbatim guidance: "The number of background notifications allowed by the system depends on current conditions, but don't try to send more than **two or three per hour**." The system may delay, coalesce, or drop them based on battery/network/usage (source: https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app, 2026-06). The older "throttle disabled when a debugger is attached" behavior is Apple-Forums developer-experience guidance, **not** in the current spec — do not rely on it.
-
-### 1.9 Legacy binary protocol — dead
-
-The legacy binary (TCP, ports 2195/2196) APNs protocol is fully retired; Apple set the migration deadline to the HTTP/2 provider API at **March 31, 2021** (source: https://developer.apple.com/news/?id=c88acm2b, 2020-10-09; earlier announced https://developer.apple.com/news/?id=11042019a, 2019-11-04). **Do not implement it.** There is no binary fallback in 2026.
-
-### 1.10 Broadcast push (Live Activity channels) — situational
-
-Broadcast push for Live Activities (channels) is current (iOS/iPadOS 18+). You `POST /4/broadcasts/apps/<bundleID>` over HTTP/2 + TLS 1.2+. Required headers: `apns-channel-id` (base64), `apns-push-type=liveactivity`, `apns-priority` (10/5/1), `apns-expiration`; optional `apns-request-id` (UUID, echoed back). Channels are managed via a **separate** channel-management API (`/1/apps/<bundleId>/channels`, `/1/apps/<bundleId>/all-channels`); limit 10,000 channels per app per environment (source: https://developer.apple.com/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns, 2026-06-13).
-
-> **Hostname nuance (correction):** Apple's broadcast **send** code samples use broadcast-specific hosts `api-broadcast.push.apple.com` (prod) / `api-broadcast.sandbox.push.apple.com` (sandbox) — **not** the plain `api.push.apple.com` used for `/3/device`. Channel **management** uses a third host pair `api-manage-broadcast(.sandbox).push.apple.com` on ports 2195/2196. Apple's own connection-section text confusingly lists the plain hosts (a documented inconsistency) (source: same, 2026-06-13). If broadcast is in scope, verify the exact host against Apple's code samples at build time.
-
---
-
-## 2. FCM HTTP v1 (2026)
-
-### 2.1 Legacy-API shutdown status
-
-Sending with the legacy FCM HTTP and XMPP APIs was **deprecated 2023-06-20**, and **shutdown began 2024-07-22** — verbatim: "Sending messages (including upstream messages) with the FCM legacy APIs for HTTP and XMPP was deprecated on June 20, 2023, and shutdown begins on July 22, 2024" (source: https://firebase.google.com/docs/cloud-messaging/migrate-v1, 2025-05-29). The legacy HTTP endpoint (`fcm.googleapis.com/fcm/send`), XMPP (`fcm-xmpp.googleapis.com`), and legacy "server key" string auth are **gone**. Only **HTTP v1** remains.
-
-The **batch send** endpoint (`fcm.googleapis.com/batch`) was also discontinued, shutdown date **2024-06-20** (source: same, 2025-05-29). For a raw-protocol relay there is **no batch endpoint** — send one `POST` per registration token and fan out via HTTP/2 multiplexing or a bounded concurrency pool.
-
-### 2.2 OAuth2 service-account authentication
-
-Auth is **OAuth2 service-account bearer tokens**. Recommended (least-privilege) scope: `https://www.googleapis.com/auth/firebase.messaging` (the broader `cloud-platform` works but is a superset) (source: https://firebase.google.com/docs/cloud-messaging/auth-server, 2025-05-29). Send the token as:
-
-```http
-Authorization: Bearer <oauth2_access_token>
-```
-
-**Token minting (RFC 7523 JWT-bearer grant):** build a JWT signed **RS256** with the service-account private key, then exchange it (source: https://developers.google.com/identity/protocols/oauth2/service-account, 2025):
-
-```jsonc
-// JWT claims for the token exchange
-{
-  "iss": "<service-account-email>",
-  "scope": "https://www.googleapis.com/auth/firebase.messaging",
-  "aud": "https://oauth2.googleapis.com/token",
-  "iat": 1700000000,
-  "exp": 1700003600  // iat + up to 3600s (max 1 hour)
-}
-```
-
-```http
-POST https://oauth2.googleapis.com/token
-Content-Type: application/x-www-form-urlencoded
-
-grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<signed_JWT>
-```
-
-Response: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }`. **Access tokens are valid 3600s (1 hour).** Cache and re-mint before expiry (≈5-minute safety margin); never mint per request (source: same, 2025). Prefer a maintained Google auth library over hand-rolling.
-
-**Credential resolution (ADC):** `GOOGLE_APPLICATION_CREDENTIALS` env var (path to SA JSON) → platform attached/default SA → error. Firebase: the JSON "should be kept private. Do not add it to public repos!" (source: https://firebase.google.com/docs/cloud-messaging/send/v1-api, 2026-06). On GCP, prefer keyless auth (§4.5).
-
-### 2.3 Endpoint & message JSON
-
-```http
-POST https://fcm.googleapis.com/v1/projects/{PROJECT_ID}/messages:send
-Authorization: Bearer <oauth2_access_token>
-Content-Type: application/json
-```
-
-The path accepts the project ID **or** project number. Host is global `fcm.googleapis.com`; **no** regional/data-residency send endpoints exist as of June 2026, and no new required top-level fields were introduced through 2025–2026 (source: https://firebase.google.com/docs/cloud-messaging/send/v1-api, 2026-06-12).
-
-**Request body** = `{ "validateOnly"?: bool, "message": Message }`. `message` is **required** and must carry **exactly one** target: `token`, `topic`, or `condition` (source: https://pkg.go.dev/google.golang.org/api/fcm/v1, current). For a relay sending to one device, use `message.token`.
-
-```jsonc
-{
-  "message": {
-    "token": "<registration_token>",
-    "data": { "k1": "v1", "k2": "v2" },     // map<string,string> ONLY
-    "android": { "priority": "HIGH", "ttl": "0s", "collapseKey": "sync" },
-    "apns": { "headers": { "apns-priority": "10" }, "payload": { "aps": { /* ... */ } } }
-  }
-}
-```
-
-**Data-only emphasis (relay-critical):** A message with a `notification` block is **auto-displayed** by the FCM SDK when the app is backgrounded/killed, and the app code does **not** run until the user taps it. A **data-only** message (no `notification` block) is **always** delivered to the app's handler (`onMessageReceived` / background handler) and never auto-displayed — full app control in foreground and background. **A relay that needs its own logic/custom display on every message should send DATA-ONLY messages** (source: https://firebase.google.com/docs/cloud-messaging/customize-messages/set-message-type, 2025-05-29).
-
-**`message.data` is `map<string,string>` — all values MUST be strings** (no nested objects/numbers/booleans; JSON-stringify anything structured). Reserved/forbidden keys: `from`, `message_type`, `notification`, and any key prefixed `google.`/`gcm.` (or reserved words) → `INVALID_ARGUMENT`. `android.data` overrides top-level `data` for Android (source: https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages, 2025-05-29; https://firebase.google.com/docs/cloud-messaging/error-codes, 2026-06-12).
-
-**Payload size:** max **4096 bytes** for token/device sends, **2048 bytes** for topic sends; over → `INVALID_ARGUMENT` (source: https://firebase.google.com/docs/cloud-messaging/error-codes, 2026-06-12).
-
-### 2.4 AndroidConfig
-
-`message.android` (REST camelCase) (source: https://pkg.go.dev/google.golang.org/api/fcm/v1, current):
-
-| Field | Type / values | Notes |
-|---|---|---|
-| `priority` | `"NORMAL"` \| `"HIGH"` (lowercase also accepted) | Default: NORMAL for data messages, HIGH for notification messages. HIGH attempts immediate delivery and can wake a dozing device. |
-| `collapseKey` | string | Group id; only the last queued message delivered on reconnect. **Not** a request-validation limit: FCM *stores* at most **4** distinct collapse keys per device while the device is offline; a 5th evicts one nondeterministically (a delivery/storage behavior — see §2.7). The API does **not** reject a request for using a 5th distinct key. |
-| `ttl` | Duration string in seconds with `s` suffix, e.g. `"3s"`, `"3.000000001s"` | `"0s"` = deliver-now-or-drop. Range **0 – 2,419,200s (28 days)**; out-of-range → `INVALID_ARGUMENT`. |
-| `restrictedPackageName` | string | Deliver only if the token's app package matches. |
-| `directBootOk` | bool | Allow delivery during Direct Boot. |
-| `data` | map<string,string> | Overrides `message.data` for Android. |
-
-Newer **optional** fields exist (`bandwidthConstrainedOk`, `restrictedSatelliteOk`); admin-SDK support landed ~March 2026; both are documented Optional and do not change the required contract (source: https://firebase.google.com/docs/cloud-messaging/send/v1-api, 2026-06-12).
-
-### 2.5 `validateOnly` (dry-run)
-
-Set top-level `validateOnly: true` to fully validate the request (token format, payload size, field correctness) and return a message-id-shaped response **without delivering**. Default `false` (source: https://pkg.go.dev/google.golang.org/api/fcm/v1, current). Use in CI/tests.
-
-### 2.6 Error model
-
-Error body shape (source: https://firebase.google.com/docs/cloud-messaging/error-codes, 2026-06-12):
-
-```json
-{ "error": { "code": 404, "message": "...", "status": "UNREGISTERED",
-  "details": [ { "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError", "errorCode": "UNREGISTERED" } ] } }
-```
-
-Classify on `error.status` / the FcmError `errorCode`, not just the HTTP code.
-
-| HTTP | `error.status` | Meaning | Handling |
-|---|---|---|---|
-| 400 | `INVALID_ARGUMENT` | Malformed payload **or** bad token (bad format, mismatched package, oversize, reserved data key, bad TTL). `details` = `google.rpc.BadRequest`. | **Do not retry.** Delete token **only** if payload is independently known-valid; otherwise fix payload. |
-| 401 | `THIRD_PARTY_AUTH_ERROR` | Invalid/missing APNs cert/key or Web Push auth credential. | Fix credentials (ops alert). **Do not retry.** |
-| 403 | `SENDER_ID_MISMATCH` | Authenticated sender ID ≠ sender that registered the token. | Send from the correct project; permanent. **Do not retry.** |
-| 404 | `UNREGISTERED` | App unregistered (uninstall, APNs token invalid, 270-day Android inactivity, restore). | **Permanently delete the token.** Never retry. |
-| 429 | `QUOTA_EXCEEDED` (RESOURCE_EXHAUSTED) | Project / device / topic rate quota exceeded. `details` = `google.rpc.QuotaFailure` naming which quota. | Retry with exponential backoff; min initial delay **1 minute** for project- and topic-rate cases. |
-| 500 | `INTERNAL` | Unknown internal error. | Retry per "Handling retries"; **no** documented `Retry-After`. |
-| 503 | `UNAVAILABLE` | Server overloaded / temporarily unavailable. | Retry with backoff + jitter; **honor `Retry-After`** if present. |
-| (none) | `UNSPECIFIED_ERROR` | Catch-all; "No more information is available about this error." | Conservative: **do not** auto-delete token; surface for investigation. |
-
-(source: https://firebase.google.com/docs/cloud-messaging/error-codes, 2026-06-12 / 2026-06-13).
-
-> **Corrections / precision notes:**
-> - `QUOTA_EXCEEDED` does **not** carry a `google.rpc.RetryInfo` per FCM's own page — only `google.rpc.QuotaFailure` is promised. General Google API guidance allows `RetryInfo`; treat its presence as optional and fall back to `Retry-After`/60 s (source: same, 2026-06-13).
-> - `INVALID_ARGUMENT` (400) is **ambiguous**: it can mean malformed payload **or** bad token. Only treat it as a dead token when the payload is independently validated (source: same, 2026-06-12).
-> - Strictly, `UNSPECIFIED_ERROR` is the `FcmError.errorCode` inside `details[]`, not the top-level google.rpc `status` — operationally equivalent (source: same, 2026-06-13).
-
-### 2.7 Retry-After, backoff, quotas, throttling
-
-**Retry classification at scale** (source: https://firebase.google.com/docs/cloud-messaging/scale-fcm, 2026-06-12):
-
- **Never retry** 400 / 401 / 403 / 404 — "abort, and do not retry."
- **429:** "retry after waiting for the duration set in the retry-after header. If no retry-after header is set, default to **60 seconds**."
- **500 / 503:** "retry with exponential back-off" (+ jitter; honor `Retry-After` on 503 if present).
- "Wait at least **10 seconds** before retrying a failed request"; set ≥10 s send timeout; cap retries; a request still failing after **60 minutes** is an outage/miscategorization, not something to retry forever.
-
-**Exponential backoff must use jitter** ("varying the retry delays through a random process"). **Smooth traffic:** ramp 0→max RPS over ≥60 s, and "avoid sending messages within a 2 minute window of each of the :00, :15, :30, and :45 minute marks" to dodge synchronized spikes (source: same, 2026-06-12).
-
-**Project quota.** Default per-project downstream quota is **600,000 messages per minute** ("covers over 99% of FCM developers"), enforced via a **600K-token 1-minute token bucket that refills to full at the end of each (non-clock-aligned) minute**. Over quota → `429 RESOURCE_EXHAUSTED` (`QUOTA_EXCEEDED`) until refill. **The quota measures messages, not requests.** Client errors (HTTP 400–499) count against quota **except 429s** (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-13; corroborated https://firebase.google.com/docs/cloud-messaging/scale-fcm, 2026-06-12).
-
-> **Correction:** The research claim that "different message types cost different token amounts" is **not** documented and is treated as inaccurate — quota is counted **per message** regardless of type; topics are merely more efficient because one request fans out to many subscribers (source: https://firebase.google.com/docs/cloud-messaging/scale-fcm, 2026-06-12).
-
-**Per-device Android limits:** up to **240 messages/minute** and **5,000 messages/hour** to a single device (headroom for bursts, e.g. rapid chat). On iOS, FCM returns an error when APNs per-device limits are exceeded (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-13).
-
-> **Correction:** Exceeding the **per-device** Android caps is **not** reported as `QUOTA_EXCEEDED` (429). `429 / QUOTA_EXCEEDED` is the **project-level** per-minute quota. Firebase's throttling/quotas page does **not** specify a particular error code or status string for the per-device caps — it only says "For iOS, we return an error when the rate exceeds APNs limits." Secondary sources name the per-device signal `DeviceMessageRateExceeded`, but this string is **not** firmly documented on a primary Google page, so **classify it defensively** rather than matching an exact literal (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-13).
->
-> **Relay handling (per-device rate).** Because the exact code/string is uncertain, the relay should treat any per-device-rate signal — whether surfaced as an `INVALID_ARGUMENT`-adjacent error, a quota-style `RESOURCE_EXHAUSTED` that names a per-device (not project) quota in `details`, or a `DeviceMessageRateExceeded`-shaped string — as a **transient, retryable rate condition**: map it to a caller-facing **429 with a conservative default `Retry-After`** and **never** as a token purge (the token is healthy; only the rate is too high). Detect on `error.status` / the `FcmError.errorCode` and the `QuotaFailure` scope, not on a hardcoded string. The relay's whole purpose is fanning bursty per-device wakes, so this is a plausible real outcome that must have a defined mapping rather than falling through to `UNSPECIFIED_ERROR`/502.
-
-**Collapsible-message throttling:** burst of **20 per app per device**, refill **1 every 3 minutes** (source: same, 2026-06-13).
-
-> **Correction:** Exceeding the collapsible burst is a **silent delay** (battery protection), **not** a `QUOTA_EXCEEDED` error: "we delay messages to reduce the impact on a user's battery" (source: same, 2026-06-13).
-
-**Distinct collapse keys:** FCM stores at most **4** different collapsible messages per device (one per distinct `collapse_key`); a 5th evicts a key nondeterministically. Default `collapse_key` = app package name (source: https://firebase.google.com/docs/cloud-messaging/customize-messages/collapsible-message-types, 2026-06-12).
-
-> **Design implication (collapse-key cap vs. per-series keys).** If the relay derives `collapse_key` per notification series (e.g. a per-series HMAC), a single device that follows **more than 4 active series** will exceed FCM's 4-distinct-key store, and excess distinct keys evict each other nondeterministically — so **collapsible coalescing is best-effort**, not guaranteed, once a device crosses 4 series. This is acceptable only if a dropped collapsible wake is recoverable (e.g. the caller's durable inbox + sync covers it); otherwise the caller should cap distinct `collapse_key`s per device. **Asymmetry to note:** APNs has **no** documented per-device cap on the number of distinct `apns-collapse-id` values, so this 4-key eviction behavior is FCM-only — the two providers are not symmetric here, and the cross-provider design docs should reconcile this rather than assume parity.
-
-**Non-collapsible offline storage (Android):** up to **100** messages stored while offline; beyond that, **all** stored messages are discarded and the device gets a single "contact your server" signal on reconnect. Do not treat FCM as a durable queue; the app must re-sync (source: same, 2026-06-12).
-
-**Quota increases:** self-serve up to **+25%** in Google Cloud Console (gated on ≥80% usage for ≥5 consecutive minutes/day, <5% client-error ratio at peak, scale best practices). Larger/temporary bumps via Firebase Support: ≥15 days lead (≥30 days for >18M msgs/min), ≤2 events/year, ≤30-day total duration (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-13).
-
-### 2.8 High-priority data-message behavior & power management
-
- **Normal priority:** delivered immediately when awake; in Doze, batched to maintenance windows. **High priority:** FCM attempts immediate delivery, can wake a sleeping device, grants temporary network + a partial wakelock (source: https://developer.android.com/training/monitoring-device-state/doze-standby, 2024-07-28).
- **Deprioritization:** A high-priority message that does **not** produce a user-facing notification gets **deprioritized to normal** (and may be throttled): "If FCM detects a pattern in which messages don't result in user-facing notifications, your messages may be deprioritized to normal priority." FCM evaluates ~7 days of per-app-instance behavior (source: https://firebase.blog/posts/2025/04/fcm-on-android/, 2025-04-17). **Do not use high priority for silent data-only syncs; use normal priority and reserve high priority for messages that produce a notification.**
- **App Standby Buckets:** high-priority delivery is still subject to the device's standby-bucket quota; once exhausted, further high-priority messages are effectively treated as normal. Exact per-bucket numeric caps are **not published** by Google and are dynamic/OEM-dependent (source: https://firebase.blog/posts/2019/02/life-of-a-message/, 2019-02-26).
- **Background-restricted apps:** receive **no** FCM messages (any priority, any state) until launched to the foreground (source: https://developer.android.com/training/monitoring-device-state/doze-standby, 2024-07-28).
- **Android 13+ (`POST_NOTIFICATIONS`):** notifications require the runtime `POST_NOTIFICATIONS` permission; without it, delivered notification messages are silently dropped. If the app's first notification channel is created while in the background (which the FCM SDK does on first receipt), Android won't display or prompt until the next app open — so early notifications are **lost**. **Data-message delivery to `onMessageReceived` is unaffected** (source: https://developer.android.com/develop/ui/views/notifications/notification-permission, 2024-08-08).
-
-### 2.9 Registration-token lifecycle
-
- **Rotation hook:** `onNewToken()` fires on initial generation and every refresh (including FCM-initiated refresh when "the security of the previous token had been compromised"). Tokens also change on reinstall, data-clear, device restore. Persist the token to your server inside `onNewToken` (source: https://firebase.google.com/docs/cloud-messaging/manage-tokens, 2026-06-13).
- **Android inactivity expiry:** "When stale tokens reach **270 days** of inactivity, FCM considers them expired." iOS/web rely on APNs/Web Push (no inactivity-based expiry), so cleanup there is driven by send-time error responses (source: same, 2026-06-13).
- **Freshness strategy:** store each token **with a server timestamp** (FCM SDKs don't provide one), refresh ~**monthly** (no benefit more often than weekly), skip tokens outside your staleness window before sending, and delete on `UNREGISTERED` (404) or on `INVALID_ARGUMENT` (400) **when the payload is verified valid** (source: same, 2026-06-13).
-
---
-
-## 3. Go ecosystem (2026)
-
-> **Version targeting:** `jackc/pgx v5.10` and `firebase.google.com/go/v4 v4.20` both require **Go 1.25+**, so target **Go 1.25+** for the whole relay (source: https://pkg.go.dev/github.com/jackc/pgx/v5, 2026-06-03; https://pkg.go.dev/firebase.google.com/go/v4/messaging, 2026-05-14).
-
-### 3.1 APNs client
-
-| Choice | Version | Rationale |
-|---|---|---|
-| `github.com/sideshow/apns2` | **v0.25.0** (tagged 2024-10-25 UTC; pkg.go.dev shows "Oct 24, 2024" due to TZ rounding) | De-facto Go APNs HTTP/2 client. Auto-manages ES256 JWT generation/refresh and HTTP/2 connection reuse. Host constants match Apple. **Hold ONE `*apns2.Client` per process/environment; never recreate per push** (TLS setup is slow). One client "can potentially do 4,000+ pushes per second." (source: https://github.com/sideshow/apns2/blob/v0.25.0/client.go, 2024-10-25) |
-| Hand-rolled (alternative) | `net/http` + `golang.org/x/net/http2` (**v0.56.0**, 2026-06-09) + `golang-jwt/jwt/v5` (**v5.3.1**) | Full control of the HTTP/2 transport; mirror apns2: parse `.p8` EC key, sign one ES256 JWT, cache ~50 min, reuse one `*http2.Transport` with `ReadIdleTimeout`/`PingTimeout` set. (source: https://pkg.go.dev/github.com/golang-jwt/jwt/v5, 2026-01-01; https://pkg.go.dev/golang.org/x/net/http2, 2026-06-09) |
-
-`apns2` internals (verified against v0.25.0 source): `HostProduction = "https://api.push.apple.com"`, `HostDevelopment = "https://api.sandbox.push.apple.com"`; `NewTokenClient(*token.Token{AuthKey, KeyID, TeamID})` / `NewClient(cert)`; chain `.Production()`/`.Development()`. `token.TokenTimeout = 3000` (50 min, deliberately under Apple's 1-hour window); `GenerateIfExpired()` regenerates under a mutex. Timeouts: `HTTPClientTimeout=60s`, `ReadIdleTimeout=15s`, `TCPKeepAlive=15s`, `TLSDialTimeout=20s`. `ClientManager` (MaxSize 64, MaxAge 10m) pools clients across multiple certs/keys (source: https://github.com/sideshow/apns2/blob/v0.25.0/client.go, 2024-10-25; token/token.go, same).
-
-> **Maintenance caveat:** `apns2` has had no release since v0.25.0 (Oct 2024); bus-factor risk. Verify recent commit/issue activity before committing vs. the hand-rolled path (see §5, item 2).
-
-### 3.2 FCM / OAuth2
-
-Pick **exactly one** of these two FCM approaches, not both:
-
-| Choice | Version | Rationale |
-|---|---|---|
-| `golang.org/x/oauth2/google` (lighter) | **v0.36.0** (2026-02-11) | Best for a **fixed/known payload**: `CredentialsFromJSONWithType(ctx, jsonKey, google.ServiceAccount, "https://www.googleapis.com/auth/firebase.messaging")` → `creds.TokenSource` already caches+auto-refreshes; POST your own JSON to the v1 endpoint with a tuned HTTP/2 client. Fewer deps; full control of connection reuse; **you implement retries/error-classification**. Note: `CredentialsFromJSON` is deprecated in favor of `CredentialsFromJSONWithType`. (source: https://pkg.go.dev/golang.org/x/oauth2/google, 2026-02-11) |
-| `firebase.google.com/go/v4/messaging` (batteries-included) | **v4.20.0** (2026-05-14, Go 1.25+) | Auto-mints/caches OAuth token, auto-retries transient errors, rich error helpers: `IsUnregistered` (drop token), `IsQuotaExceeded`, `IsUnavailable`, `IsInvalidArgument`, `IsThirdPartyAuthError`, `IsSenderIDMismatch`. Use `Send` / `SendEach` / `SendEachForMulticast` (each = one HTTP call per message, ≤500). **`SendAll`/`SendMulticast` are deprecated (and removed in newer SDK majors)** — do not use. (source: https://pkg.go.dev/firebase.google.com/go/v4/messaging, 2026-05-14) |
-
-For a privacy-preserving relay forwarding opaque tenant payloads, the **`x/oauth2/google` + custom HTTP/2 client** path is usually preferable: it avoids the heavy Admin SDK and gives direct control of connection reuse and error handling.
-
-### 3.3 HTTP/2 tuning (both transports)
-
-`golang.org/x/net/http2.Transport` (**v0.56.0**, 2026-06-09) knobs (source: https://pkg.go.dev/golang.org/x/net/http2, 2026-06-09):
-
- `ReadIdleTimeout` (~10–15 s): if no frame received for this duration, send a PING health check (0 = disabled).
- `PingTimeout` (~15 s, default): close the conn if no PING response arrives.
- `WriteByteTimeout`: close if no bytes can be written within the timeout.
- `StrictMaxConcurrentStreams` (bool): if `false` (default) new TCP conns open to stay under each conn's `SETTINGS_MAX_CONCURRENT_STREAMS`; if `true` the server limit is global and callers block.
-
-**Setting a non-zero `ReadIdleTimeout` + `PingTimeout` is the single most important tuning for a long-lived relay** — it reaps half-open APNs/FCM connections. Do not hardcode max-concurrent-streams; let the transport read the server SETTINGS (the exact APNs/FCM advertised value is not a published primary-source constant — measure at runtime; see §5, item 3).
-
-**Inbound server:** `net/http` gets HTTP/2 automatically over TLS and supports graceful shutdown. **Set explicit timeouts** — the zero value means no timeout: `ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout`, `MaxHeaderBytes` (default 1 MiB). On SIGTERM call `srv.Shutdown(ctx)` with a bounded context (source: https://pkg.go.dev/net/http, 2026-06-01).
-
-### 3.4 Storage
-
-| Choice | Version | Rationale |
-|---|---|---|
-| `github.com/jackc/pgx/v5` + `pgxpool` | **v5.10.0** (2026-06-03, Go 1.25+) | Recommended Postgres driver/pool. Use `pgxpool.New(ctx, dsn)` (not `pgx.Connect`) for a server — concurrency-safe, health-checked. Token store, API-key store, idempotency. (source: https://pkg.go.dev/github.com/jackc/pgx/v5, 2026-06-03) |
-| `github.com/redis/go-redis/v9` | **v9.20.1** (2026-06-11) | Context-first Redis client with built-in pooling. Distributed rate-limiting, idempotency in-flight locks, dedup/queue state. (source: https://pkg.go.dev/github.com/redis/go-redis/v9, 2026-06-11) |
-
-### 3.5 Observability
-
-| Choice | Version | Rationale |
-|---|---|---|
-| `log/slog` (stdlib) | Go 1.21+ | Structured logging, no third-party dep. `slog.NewJSONHandler` for production aggregation; redaction middleware (§4.6). (source: https://pkg.go.dev/log/slog, 2026-06-01) |
-| `github.com/prometheus/client_golang` | **v1.23.2** (2025-09-05) | Prometheus instrumentation; custom registry + `promhttp.HandlerFor` for `/metrics`. Instrument per-provider send latency (histogram) and outcome counters labeled by provider + status/reason. (source: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus, 2025-09-05) |
-
-### 3.6 Reference pattern (not a dependency)
-
-`github.com/appleboy/gorush` is a maintained reference push **server** (built on `sideshow/apns2`, supports FCM) with a notification queue, worker pool, and pluggable stats storage — useful as a **pattern reference** for worker pools and retry/queue design, but it is a full server, not a library to embed (source: https://github.com/appleboy/gorush, 2025-11-20).
-
-### 3.7 Pinned versions (summary)
-
-```
-github.com/sideshow/apns2            v0.25.0
-github.com/golang-jwt/jwt/v5         v5.3.1
-golang.org/x/net                     v0.56.0   // http2
-golang.org/x/oauth2                  v0.36.0
-firebase.google.com/go/v4            v4.20.0   // only if using the Admin SDK path
-github.com/prometheus/client_golang  v1.23.2
-github.com/jackc/pgx/v5              v5.10.0
-github.com/redis/go-redis/v9         v9.20.1
-golang.org/x/time                    (rate — see §4.2)
-// Go 1.25+ required
-```
-
---
-
-## 4. Security & ops (2026)
-
-### 4.1 API-key storage & comparison
-
- **Generate** 32 bytes from `crypto/rand`; format as `<prefix>_<base62/base64url>` where the **prefix** (8–12 chars, optionally tenant/env-tagged) is **non-secret**, stored in cleartext, and **indexed**. The remaining 32 bytes are the secret. This GitHub/Stripe-style design lets you `SELECT` the row by indexed prefix in O(1), then constant-time-compare the hash — no full-table scan, no SQL index over the secret (engineering consensus aligned with OWASP API2:2023, source: https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/, 2023).
- **Hashing:** Store **SHA-256** (or **HMAC-SHA-256** with a server-side pepper kept in the secret manager) of the secret — never plaintext. For **high-entropy random keys** (≥128, ideally 256 bits), a fast hash is acceptable; OWASP's slow-KDF warning is scoped to **low-entropy human passwords**, where "Fast hashing algorithms such as SHA-256 are not suitable" — that warning does **not** apply to 256-bit random API keys, and `argon2id` per-request would needlessly throttle the relay (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06). _Note: this passwords-vs-keys distinction is engineering consensus consistent with OWASP, not a single verbatim OWASP line — see §5, item 12._
- **If** you ever store a low-entropy password (not API keys), OWASP's current argon2id minimum is **m=19456 KiB (19 MiB), t=2, p=1** with a unique per-secret salt (source: same, 2026-06). Do **not** apply argon2id to per-request API-key verification.
- **Comparison:** use `crypto/subtle.ConstantTimeCompare(x, y []byte)` on the fixed-length (32-byte) hashes. Never use `==` or `bytes.Equal` on raw secret material (source: https://pkg.go.dev/crypto/subtle, current).
- **OWASP API2:2023:** "API keys should not be used for user authentication. They should only be used for API clients authentication." Never put keys in URLs/query strings; implement anti-brute-force on auth endpoints (source: https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/, 2023).
- **Metadata per key:** `account_id`, `key_hash`, `prefix` (indexed), `created_at`, `last_used_at` (written throttled, e.g. ≤ once/min, to avoid a DB write per request), `expires_at` (optional), `revoked_at`. Support **multiple live keys per account** for zero-downtime rotation; reject revoked/expired keys on every request (aligned with OWASP API2:2023, source: same, 2023).
-
-### 4.2 Rate limiting
-
- **Single instance:** `golang.org/x/time/rate` token bucket — `NewLimiter(r Limit, b int)`. Use `Allow()` to drop/reject (return 429) on inbound; `Wait(ctx)`/`Reserve()` to pace outbound APNs/FCM calls. `Reservation.Delay()` gives the wait → use it to compute `Retry-After`. Per-account: `map[accountID]*Limiter` with eviction (per-instance only) (source: https://pkg.go.dev/golang.org/x/time/rate, current).
- **Multi-instance (behind LB):** per-instance limiters no longer enforce a global limit — use a **Redis-backed distributed limiter** with an **atomic Lua** script (refill → check → consume in one `EVAL`), state as a Redis HASH `{tokens, last_refill_ts}` + TTL for idle-account eviction. Alternatives: `redis-cell` (GCRA, `CL.THROTTLE` returns remaining quota + retry-after) or `redis-gcra` Lua scripts. Decide **fail-open vs fail-closed** when Redis is down (fail-open for availability; fail-closed for abuse-sensitive endpoints) (source: https://github.com/Losant/redis-gcra, current).
- **Response:** on limit exceeded, return **`429 Too Many Requests`** (RFC 6585 §4, 2012-04) with a **`Retry-After`** header. ABNF: `Retry-After = HTTP-date / delay-seconds`, `delay-seconds = 1*DIGIT` (RFC 9110 §10.2.3, 2022-06). **Common bug to avoid:** do **not** emit an absolute Unix epoch integer — `delay-seconds` is a **relative** count of seconds; an HTTP-date must use the full date format. Prefer an integer relative-seconds value from `Reservation.Delay()` (source: https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3, 2022-06).
- **OWASP API4:2023** (renamed "Unrestricted Resource Consumption"): enforce rate limits, "Define and enforce a maximum size of data on all incoming parameters and payloads," cap per-account push volume, and "Configure spending limits for all service providers/API integrations" — directly relevant to capping per-tenant APNs/FCM spend (source: https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/, 2023).
-
-### 4.3 Idempotency
-
-Accept an **`Idempotency-Key`** header (UUIDv4, **scoped per account**). _Status note:_ this is an IETF **draft** (`draft-ietf-httpapi-idempotency-key-header-07`, 2025-10-15), **not** a ratified RFC, and that version **expired 2026-04-18** — treat the header **name** and pattern as the de-facto standard (Stripe uses the same header), but do not cite it as an RFC (source: https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header-07, 2025-10-15).
-
-Status-code lifecycle from the draft:
-
-| Situation | Response |
-|---|---|
-| First request | Process; record the response. |
-| Duplicate, original **completed** | Replay the previously completed result (success or error). |
-| Duplicate, original **in-flight** | **409 Conflict** (RFC 7807 body, type `.../idempotency`). |
-| Same key, **different payload** | **422 Unprocessable Content**. |
-| Missing key where required | **400 Bad Request**. |
-
-(source: same, 2025-10-15).
-
-**Stripe-style production model** (de-facto reference): header `Idempotency-Key`, value up to 255 chars, recommend UUIDv4; saved result (status + body) replayed for **≥24 hours** for both success and failure; same key + different params → error; concurrent in-flight → not saved, client may retry; applies to POST (GET/DELETE ignore it) (source: https://docs.stripe.com/api/idempotent_requests, 2026-06).
-
-**Relay implementation:** atomic `SET idem:{account}:{key}` with **NX + TTL** as an in-flight lock. NX success → process, then overwrite the marker with the serialized `{status, body}` and a ~24 h TTL. NX fail + stored response → replay it with the original status. NX fail + still in-flight → return **409**. Same key + different payload → **422**. This prevents double-sends to APNs/FCM under concurrent retries.
-
-### 4.4 Provider auth recap (security view)
-
- **APNs:** cache one ES256 JWT, regenerate on a ~50-min timer (never < 20 min apart) under a mutex, reuse across senders; refresh on `403 ExpiredProviderToken`; back off on `429 TooManyProviderTokenUpdates`. Prefer team-scoped + topic-specific `.p8` keys (Feb 2025) for least privilege. Ensure the TLS trust store includes USERTrust RSA / SHA-2 root (§1.7). (sources as cited in §1.)
- **FCM:** cache the OAuth2 access token (~1 h) rather than minting per message. On GCP, prefer keyless auth (§4.5). (sources as cited in §2.)
-
-### 4.5 Secret management
-
-OWASP Secrets Management ranking — **KMS/Vault/secret-manager (best) > tightly-permissioned mounted secret file (acceptable) > plain env var (discouraged) > in image/repo (forbidden)**. Verbatim: "environment variables are generally accessible to all processes and may be included in logs or system dumps. Using environment variables is therefore not recommended unless the other methods are not possible." Encrypt at rest (AES-256-GCM or ChaCha20-Poly1305); "You should not store keys next to the secrets they encrypt" (envelope encryption / KMS); least privilege; prefer dynamic/short-lived secrets (source: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html, 2026-06). Store the APNs `.p8` and FCM SA JSON in a secret manager; never commit or bake into the image.
-
-**Google keyless direction (2025):** prefer Workload Identity / service-account impersonation / attached SA over downloadable JSON keys; org policy `constraints/iam.disableServiceAccountKeyCreation` blocks new keys. If the relay runs **on GCP**, use an attached SA / Workload Identity. If **off-GCP**, a JSON key is sometimes unavoidable — then it **must** live in a secret manager, not a repo or plain env var (source: https://docs.cloud.google.com/iam/docs/keys-disable-enable, 2026-06).
-
-### 4.6 Log redaction
-
-OWASP Logging exclude-list (verbatim items): "Access tokens"; "Authentication passwords"; "Session identification values"; "Database connection strings"; "Encryption keys and other primary secrets"; payment/PII. Redact by remove/mask/sanitize/hash/encrypt (source: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html, 2026-06).
-
-For the relay specifically — **never log**: the `Authorization`/bearer header, the raw API key (log only the non-secret **prefix** or a hash), full APNs/FCM **device tokens** (truncate/hash), or **notification payload bodies**. **Do log**: request ID, `account_id`/tenant ID, status code, error `reason`/`status`, and Retry-After/idempotency decisions for triage. Implement redaction in logging middleware so it can't be bypassed.
-
-### 4.7 Multi-tenant isolation
-
-Combine **noisy-neighbor resource control** (per-tenant rate/volume quotas at gateway/service/data tiers) with **per-tenant scoping** of every stored API key, rate-limit bucket, idempotency key, cached provider token, and **log line**. "Attach a tenant ID to every request, log entry, metric, and trace." Namespace all shared-store keys by `account_id` to prevent cross-tenant collision/replay. Cap downstream APNs/FCM spend per tenant (OWASP API4:2023). For APNs, recall the per-team connection-pool constraint (§1.1) (source: https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/, 2023).
-
-```mermaid
-flowchart TB
-  T[Tenant request + API key + Idempotency-Key] --> AUTH[Auth middleware: prefix lookup + ConstantTimeCompare]
-  AUTH --> RL[Per-tenant rate limit: Redis Lua token bucket]
-  RL -->|429 + Retry-After| T
-  RL --> IDEM[Idempotency: Redis SET NX lock / replay / 409 / 422]
-  IDEM --> ROUTE{Provider}
-  ROUTE -->|APNs| APNS[ES256 JWT cached ~50m, per-team HTTP/2 pool]
-  ROUTE -->|FCM| FCM[OAuth2 token cached ~1h, v1 messages:send]
-  APNS --> STORE[(pgx: tokens / keys / idempotency)]
-  FCM --> STORE
-  AUTH -. redacted .-> LOG[slog JSON: tenant, req-id, status, reason]
-```
-
---
-
-## 5. Open questions / re-verify before implementation
-
-1. **APNs token page exact wording.** `establishing-a-token-based-connection-to-apns` is a JS-rendered SPA; content was confirmed via Apple's JSON data endpoint and corroborating sources. Re-read the live page to confirm exact 20/60-minute refresh wording and the scoped-key limits ("200 keys per env, up to 400 topics per topic-based key") near build time.
-2. **`apns2` maintenance / bus factor.** No release since v0.25.0 (Oct 2024). Check recent commit/issue activity before committing to it vs. a hand-rolled `net/http2` + `golang-jwt/jwt/v5` client.
-3. **APNs `SETTINGS_MAX_CONCURRENT_STREAMS`.** Intentionally variable and not documented by Apple. Measure at runtime; do not hardcode connection sizing.
-4. **APNs sandbox hostname alias (resolved — interchangeable).** `api.sandbox.push.apple.com` and `api.development.push.apple.com` are interchangeable sandbox aliases: as of 2026-06-13 both resolve to the same Akamai CNAME and IP set (DNS-verified, §1.3), so either reaches the same sandbox backend. We standardize on `api.sandbox.push.apple.com` (canonical in Apple's docs and `apns2`'s `HostDevelopment`). No build-time blocker — this is a naming preference, not a discrepancy.
-5. **APNs broadcast hosts.** If Live Activity broadcast/channels are in scope, confirm the broadcast-specific hosts (`api-broadcast.*`, `api-manage-broadcast.*` on 2195/2196) against Apple's code samples; the connection-section text in Apple's docs is internally inconsistent.
-6. **Future APNs requirements.** None published after Feb 2025 as of June 2026 — re-check Apple's Upcoming Requirements page (e.g. a future TLS-1.3 minimum or another CA rotation) close to deployment.
-7. **FCM `RetryInfo` on 429.** FCM's error-codes page promises only `google.rpc.QuotaFailure`, not `RetryInfo`. Treat `RetryInfo` as optional; fall back to `Retry-After` / 60 s default.
-8. **FCM data-residency endpoints.** None for FCM as of June 2026 (global `fcm.googleapis.com` only). Re-check release notes if EU/other data-residency requirements emerge.
-9. **FCM project quota tiers above 600K/min.** Confirm a project's real ceiling via Google Cloud Console quotas rather than assuming a secondary-source tier.
-10. **App Standby Bucket caps.** Per-bucket high-priority wake-up caps are unpublished and OEM/version-dependent; confirm via on-device testing (`adb shell am set-standby-bucket` / `get-standby-bucket`) if precise behavior matters.
-11. **Android 270-day token expiry.** Currently documented (manage-tokens, 2026-06-13) but a platform constant that can change — re-verify at build time.
-12. **API-key "fast hash OK" citation.** Engineering consensus consistent with OWASP's passwords-vs-keys threat model, but not a single verbatim OWASP line for API keys; if a hard citation is required, point to that distinction, and decide plain salted SHA-256 vs HMAC-SHA-256 pepper (pepper adds defense-in-depth but complicates rotation).
-13. **Idempotency-Key draft status.** Draft 07 expired 2026-04-18 without becoming an RFC; re-check for an 08+/RFC before relying on its exact status-code semantics as "standard."
-14. **GCP vs off-GCP for FCM credentials.** Whether the relay runs on GCP (keyless Workload Identity) or off-GCP (JSON key in a secret manager) changes the recommended FCM credential approach — resolve in the deployment design.
@@ -1,268 +0,0 @@
-# Silo Push Relay — Decision Record
-
-> **Provenance.** This is the decision record for the Silo Push Relay. It resolves the implementation decisions that the engineering spec ([`00-relay-spec.md`](./00-relay-spec.md)) left open in **§15 ("Open questions needing human / product input")**, building on the phased build plan ([`01-implementation-plan.md`](./01-implementation-plan.md)) and the cited 2026 factual foundation ([`02-apns-fcm-2026-reference.md`](./02-apns-fcm-2026-reference.md)). Each decision below is **firm** and **implementer-followable**: pick it, build it. The external wire contract in [`../02-apns-relay.md`](../02-apns-relay.md) and [`../03-fcm-relay.md`](../03-fcm-relay.md) is authoritative and unchanged — no decision here adds, renames, or repurposes a caller-visible field. Commands assume the repository root is the cwd.
-
-These decisions reflect **2026-current** APNs and FCM behavior and a deliberately narrow v1 cut line: a single-region, self-hosted-ecosystem relay whose two priorities are **reliability** and **custody of the official Apple/Google push credentials**. Where the spec already leaned a direction, this record ratifies and operationalizes it; where it left a real fork, this record picks one decisively and says exactly what that commits the team to.
-
---
-
-## Summary
-
-| Decision | Recommendation (one line) | Confidence | Gates |
-|---|---|---|---|
-| APNs Go client (§15 #3) | Hand-roll on `net/http` + `x/net/http2` + `golang-jwt/jwt/v5` behind `internal/apns`; do **not** take a production dep on `sideshow/apns2`. | High | Phase 3 |
-| FCM credentials (§15 #4) | Default **keyless** via ADC (attached SA on GCP, WIF off-GCP); SA-JSON-in-secret-manager is the explicit last-resort fallback. | High | Phase 4 / Phase 6 |
-| `apns-expiration` policy (§15 #5) | Relay-set **finite** TTL: 4h `private_alert`, 1h `background_wake`, parallel FCM `android.ttl`; relay-owned config, **not** a caller field. | High | Phase 3 (APNs) / Phase 4 (FCM) |
-| Per-account rate limits (§15 #1) | Ship **hard-coded global defaults** (config constants + env overrides); add per-account columns + `relayctl quota` only when logs prove need. | High | Phase 2 |
-| API-key hashing (§15 #6) | `HMAC-SHA256(pepper, secret)` — fast keyed hash, pepper in secret manager; **not** argon2id, **not** salted SHA-256. | High | Phase 1 / Phase 2 |
-| Op-log retention (§15 #8) | Native PostgreSQL **declarative RANGE partitioning** by day, retention by **partition DROP** via `pg_partman`; not bulk `DELETE`, not external offload. | High | Phase 1 / Phase 5 |
-
---
-
-## Decision 1 — APNs Go client: hand-roll, do not depend on `sideshow/apns2`
-
-**Decision.** Should the relay's APNs client adopt `sideshow/apns2`, or hand-roll the client on `net/http` + `golang.org/x/net/http2` + `golang-jwt/jwt/v5`? (Spec §15 #3; plan §3 "Decision to make before Phase 3".)
-
-**Resolution.** **Hand-roll the APNs client** on `net/http` with `x/net/http2` and `golang-jwt/jwt/v5`, behind the existing `internal/apns` interface. Do **not** take a production dependency on `sideshow/apns2`. Mirror its verified internals — production host `api.push.apple.com`, sandbox host `api.sandbox.push.apple.com`, token TTL 3000 s with a 20-minute refresh floor, an HTTP/2 transport with `ReadIdleTimeout`/`PingTimeout` near 15 s, one client per process per (env, team) — and add the behavior `apns2` lacks: single-flighted JWT regeneration keyed by team, an (env, topic) → `.p8` key-selection map for Apple's Feb 2025 scoped keys with startup validation, a finite `apns-expiration` policy (Decision 3), and a connection-severed → `503` mapping with no transparent retry. Optionally keep `apns2 v0.25.0` as a throwaway Phase 3 oracle, then drop it before Phase 6.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **Hand-roll (chosen)** | No dependency on a stalled library; relay owns its whole upstream transport. Surface is small and fully specified. `jwt/v5` and `x/net/http2` are maintained and already needed (FCM, HTTP/2 tuning). Enables single-flight JWT regen, scoped-key selection, finite expiration, and connection-severed mapping that `apns2` lacks. | More code/tests up front for the JWT lifecycle, HTTP/2 pool, GOAWAY handling, and reason mapping. Must re-earn `apns2`'s production hardening through tests. |
-| Adopt `sideshow/apns2 v0.25.0` | Fastest path to a working client; de-facto library with verified internals, battle-tested at throughput, MIT, small, vendorable. | Maintenance drift: no release since Oct 2024, one untagged commit in twelve months, none in 2026; 25 open issues / 8 PRs with no maintainer response in 2025–2026, including an unaddressed connection-leak issue (#238). Lacks single-flight regen, scoped-key selection, expiration policy, connection-severed semantics — so it would be wrapped anyway. Bus-factor risk. |
-| Adopt a fork (e.g. `ad-mos/apns2`) | In principle routes around the inactive upstream; adds Live Activity. | Less current than upstream (untagged pseudo-version from Jul 2024, no stable tags) — bus factor is worse. Live Activity is out of scope. |
-
-**Rationale.** Three points decide it for a reliability-first, multi-year, self-hosted relay. First, **maintenance health is poor**: `v0.25.0` (Oct 2024) is still the newest tag (source: https://github.com/sideshow/apns2/releases, 2026-06-13), the only commit to master in twelve months is one untagged dep-bump PR #239 dated 2025-07-22 (source: https://github.com/sideshow/apns2/commits/master, 2026-06-13), and an open issue (#238, 2024-11-11) reports exactly the failure class that matters here — an HTTP/2 connection/goroutine leak in a process holding long-lived connections for days — with no maintainer response in 2025 or 2026 (source: https://github.com/sideshow/apns2/issues, 2026-06-13). Second, **relay requirements already exceed `apns2`**: single-flight JWT regen (to avoid `429 TooManyProviderTokenUpdates`), the (env, topic) → `.p8` scoped-key map with startup validation for Apple's Feb 2025 scoped keys, a finite `apns-expiration`, connection-severed → `503` with no transparent retry, and sandbox-only `apns-unique-id` capture — `apns2` has none of these, so it would be wrapped regardless, leaving only small JWT/HTTP-2 glue. Third, **that glue is low risk to own**: the 2026 reference verified every constant, `jwt/v5` and `x/net/http2` are maintained and already needed, and Go's `net/http2` handles GOAWAY and reconnect transparently on a reused client. Compatibility is a non-issue — `apns2` master pins `x/net v0.33.0` / go 1.18 but module MVS resolves up to the relay's `x/net v0.56.0` and `jwt v5.3.1` and builds under Go 1.25/1.26 (source: https://github.com/sideshow/apns2/blob/master/go.mod, 2026-06-13) — so the disqualifier is maintenance and missing behavior, not versions.
-
-**Consequences (what this commits).**
-
- **Deps.** `go.mod` takes `golang-jwt/jwt/v5 v5.3.1` and `golang.org/x/net v0.56.0` as production deps (both already planned in plan §3). `apns2` is **not** a production dep — at most a Phase 3 prototype dropped before Phase 6.
- **Code (`internal/apns`).**
-  - `jwt.go` — ES256 `.p8` sign; in-memory cache; ~50-minute regen timer; 20-minute floor; eager regen on `403 ExpiredProviderToken` with a single retry; **single-flight regen keyed by team**.
-  - `transport.go` — per-(env, team) HTTP/2 transport with non-zero `ReadIdleTimeout`/`PingTimeout`, hardcoded host constants by environment enum, GOAWAY reconnect, USERTrust RSA via the system trust store.
-  - `client.go` — the `internal/apns` interface implementation.
-  - `errors.go` — the spec §6.4 reason table, including `InvalidToken` → `BadDeviceToken`, unrecognized reason → `502`, connection-severed → `503`.
-  - Key-selection map and startup validation live in `internal/config`.
-  - Everything else depends only on the `APNsClient` interface, so the choice is reversible.
- **Ops.** A CVE or HTTP/2 bug is patched by bumping `x/net` rather than waiting on an inactive repo. Test against a fake APNs upstream for GOAWAY and mid-stream reset, a JWT-expiry burst that must yield **exactly one** regen, plus the Apple sandbox integration test (Phase 3).
- **Schema.** None — upstream-client-only; no Postgres/Redis or external-contract change.
-
-**Revisit if.** Reverse toward `apns2` only if, **before Phase 3 ships**, `sideshow/apns2` cuts a fresh tagged release newer than `v0.25.0` and shows sustained maintainer responsiveness — clearing the backlog and addressing the #238 leak class — over two to three months, resolving the bus-factor concern. Conversely, **re-validate the hand-rolled JWT/HTTP-2 internals** if Apple changes APNs provider auth (a new required header, a non-ES256 algorithm, a host change, or deprecating token auth), since the hand-rolled client now owns those mechanics.
-
-**Sources.**
- `apns2` latest release/tag is `v0.25.0` (Oct 24–25 2024); no newer tag exists (source: https://github.com/sideshow/apns2/releases, 2026-06-13).
- Only commit to master in twelve months is untagged dep-bump PR #239 (2025-07-22); no 2026 commits (source: https://github.com/sideshow/apns2/commits/master, 2026-06-13).
- 25 open issues / 8 PRs; issue #238 (potential HTTP/2 connection/goroutine leak, 2024-11-11) has no maintainer response in 2025–2026 (source: https://github.com/sideshow/apns2/issues, 2026-06-13).
- pkg.go.dev flags `v0.25.0` as not the latest module version; newest released version is ~20 months old (source: https://pkg.go.dev/github.com/sideshow/apns2, 2026-06-13).
- `apns2` master `go.mod` declares go 1.18, pins `x/net v0.33.0` and `jwt v5.2.1`; MVS resolves to the relay's `x/net v0.56.0` / `jwt v5.3.1`, builds under Go 1.25/1.26 (source: https://github.com/sideshow/apns2/blob/master/go.mod, 2026-06-13).
- Fork `ad-mos/apns2` (Live Activity) is less current: untagged pseudo-version 2024-07-30, no stable tags (source: https://pkg.go.dev/github.com/ad-mos/apns2, 2026-06-13).
- `x/net v0.56.0` (HTTP/2 `ReadIdleTimeout`/`PingTimeout` tuning) published 2026-06-09, actively maintained (source: https://pkg.go.dev/golang.org/x/net, 2026-06-13).
- Verified `apns2 v0.25.0` internals to mirror: `HostProduction api.push.apple.com`, `HostDevelopment api.sandbox.push.apple.com`, `TokenTimeout 3000` under a mutex, `ReadIdleTimeout 15s`, one client per process per env (source: https://github.com/sideshow/apns2/blob/v0.25.0/client.go, 2026-06-13).
-
---
-
-## Decision 2 — FCM credentials: default keyless via ADC, SA-JSON-in-secret-manager as last resort
-
-**Decision.** Should the relay authenticate to FCM HTTP v1 via GCP keyless identity (Workload Identity Federation / attached service account) or via a service-account JSON key stored in a secret manager? (Spec §4.4, §15 #4; reference §4.5.)
-
-**Resolution.** **Default to keyless.** The relay MUST authenticate via Application Default Credentials (ADC) using `golang.org/x/oauth2/google` with scope `https://www.googleapis.com/auth/firebase.messaging`, with the concrete credential **source** chosen by deployment:
-
-1. **On GCP compute (GCE/GKE/Cloud Run):** use an **attached service account** — zero key material; the metadata server mints short-lived tokens.
-2. **Off-GCP (self-hosted LXC/VM — the documented Silo home-hosting reality):** use **Workload Identity Federation** with a **non-secret** credential-configuration file plus an OIDC token from the host's own IdP — still no exported key.
-3. **Only if WIF cannot be stood up** (no usable OIDC issuer for the host): fall back to a **service-account JSON key**, which MUST live in a secret manager loaded once at startup into memory — **never** as a literal-key env var, **never** baked into the image, **never** on disk in the repo.
-
-In all three cases the code path is identical: `google.FindDefaultCredentials` / `DefaultTokenSource(ctx, "…/firebase.messaging")` returns an auto-caching, auto-refreshing `TokenSource`; the relay does **not** branch on credential type. This makes keyless the default and JSON-in-secret-manager the explicit last resort, matching spec §4.4 / reference §4.5 with one refinement: even the off-GCP case is keyless via WIF first.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **Keyless via ADC — attached SA on GCP, WIF off-GCP; SA-JSON-in-secret-manager last resort (chosen)** | No long-lived exportable secret in the common path — eliminates the highest-severity leak vector for a service whose whole reason to exist is custody of the official Google push credential (spec G3). Aligns with Google's current guidance that SA keys are "an exception rather than the norm" and that orgs created on/after 2024-05-03 block key creation by default. WIF's credential-config file carries no private key and need not be confidential. Tokens are short-lived (~1h) and auto-rotated — no manual rotation, no rotation-induced outage mode. Single code path through `x/oauth2/google` regardless of source. Org-policy `iam.disableServiceAccountKeyCreation` can be enforced relay-wide with no impact. | WIF off-GCP requires the host to expose a usable OIDC token (or a supported IdP: AWS/Azure/GitHub/GitLab/K8s/AD/OIDC/SAML/X.509); a bare LXC with no IdP must stand one up or fall back to JSON. Slightly more one-time setup (pool + provider + attribute mapping). |
-| Service-account JSON key in a secret manager (loaded at startup, never env/in-image) | Works on any host with no IdP or GCP compute — the universal fallback for a self-hosted ecosystem. Simple mental model. Same `x/oauth2/google` minting code via `CredentialsFromJSONWithType`. Secret-manager custody (vs env/in-image) is itself OWASP-aligned hardening, acceptable when keyless is genuinely unavailable. | A long-lived, exportable private key is exactly what Google now treats as an exception and blocks by default for 2024-05-03+ orgs — if the official Silo Firebase project lives in such an org, the policy must be relaxed just to create it. Single high-value theft target (full FCM send authority), manual rotation burden, rotation-induced outage window. The untyped `CredentialsFromJSON` loader is deprecated; must use the typed variant. Fallback, not default. |
-| Use the Firebase Admin SDK and let it resolve ADC | Batteries-included: auto token mint/cache/refresh, rich error helpers, also resolves ADC (inherits keyless transparently). | Orthogonal to the credential decision and explicitly **not** the relay's chosen client — plan §3 / reference §3.2 deliberately pick the lighter `x/oauth2/google` path for a fixed payload and direct control of connection reuse and error classification. Adopting it to "solve credentials" re-opens a settled client-library decision for no credential benefit (ADC resolution is identical either way). |
-
-**Rationale.** The relay's single most sensitive asset is the official Google push credential (spec G3, §4.4); a fully compromised relay must not hand an attacker a portable, long-lived FCM send key. Keyless removes that artifact in the common path: on GCP the key never exists; off-GCP, WIF replaces it with a non-secret credential-config file plus a short-lived host-issued OIDC token that Google STS exchanges for a ~1h access token. Google's own current guidance is unambiguous — SA keys are "an exception rather than the norm," and organizations created on or after 2024-05-03 enforce `iam.disableServiceAccountKeyCreation` / `disableServiceAccountKeyUpload` by default (source: https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys, 2026-06-13) — so a brand-new project should treat keyless as the baseline. Reliability-first reinforces this: long-lived keys add a manual-rotation outage mode and a "key silently revoked/expired" failure class that keyless does not have. Crucially, the **implementation cost of defaulting to keyless is near-zero**, because `x/oauth2/google` ADC already resolves all three sources — GCE/GKE metadata, `external_account` WIF config files, and SA JSON — behind one `TokenSource` with the same scope, so the relay does not branch (source: https://pkg.go.dev/golang.org/x/oauth2/google, 2026-02-11). JSON-in-secret-manager remains an honest fallback for a host with no IdP, but is the exception: secret-manager-held and loaded once into memory, never an env-var key or image layer (spec §4.4 ranking secret-manager > mounted file > env var > in-image). This is a refinement, not a contradiction, of spec §4.4 ("On GCP, prefer keyless …; off-GCP, the JSON lives in the secret manager") — the verified addition is that **off-GCP can and should try WIF (keyless) first**, because WIF explicitly targets non-Google-Cloud workloads and its config file carries no secret.
-
-**Consequences (what this commits).**
-
- **Code.** `internal/fcm/oauth.go` builds the `TokenSource` exclusively through ADC — `google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/firebase.messaging")` (or `FindDefaultCredentials` + `creds.TokenSource`) — and does **not** special-case credential type. The fallback SA-JSON path uses `CredentialsFromJSONWithType(ctx, json, google.ServiceAccount, scope)` (**not** the deprecated `CredentialsFromJSON`) with the JSON sourced from the secret manager.
- **Config.** `internal/config` gains a single `fcm_credential_mode` resolution: attached-SA (no config) > WIF credential-config file path > secret-manager SA JSON, mapped onto ADC (set `GOOGLE_APPLICATION_CREDENTIALS` to a mounted, non-secret WIF config, or inject the SA JSON into the secret-manager-backed loader).
- **Ops/deploy.** On GCP: bind an attached SA with rights to send to the official Firebase project, and apply org policy `iam.disableServiceAccountKeyCreation`. Off-GCP: stand up a workload-identity pool + provider, configure the host's OIDC issuer, deploy the WIF `external_account` credential-configuration file (it may be mounted/baked because this specific file contains **no private key** and need not be kept confidential, per Google's WIF docs — **it is the only artifact exempt, and only because it carries no secret**). **This refines, not overrides, spec §11: the no-in-image rule still applies in full to every actual secret — the APNs `.p8`, the FCM service-account JSON, the HMAC pepper, and DB/Redis credentials remain strictly forbidden in the image under spec §11.** The startup credential health-check (`relayctl ping-upstream --provider fcm`, spec §5.4, plan Phase 4/6) validates the resolved `TokenSource` mints a token regardless of source. Removes the manual key-rotation runbook in the common path; documents the WIF pool/provider setup and the JSON-fallback secret-manager procedure for the exception case.
- **Schema/contract.** No DB schema change; no change to the external `02`/`03` contract or to `pushwire` payloads.
-
-**Revisit if.** (1) The relay must deploy on a host with **neither** GCP attached-SA **nor** any WIF-compatible identity source — then the SA-JSON-in-secret-manager fallback becomes the de facto default for that deployment and its rotation runbook must be activated. (2) The official Silo Firebase project is created under / moved into a Google org that enforces `iam.disableServiceAccountKeyCreation` by default (org created on/after 2024-05-03), making the JSON fallback unavailable without a policy exception — then keyless is mandatory. (3) `x/oauth2/google` changes its ADC resolution order or deprecates the typed-credentials API, requiring a client-library re-verification.
-
-**Sources.**
- Google: "consider the use of service account keys as an exception rather than the norm"; recommended constraints Disable SA key creation/upload; "If your organization was created on or after May 3, 2024, these constraints are enforced by default." (source: https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys, 2026-06-13).
- WIF lets external workloads (AWS/Azure/GitHub/GitLab/K8s/on-prem AD/OIDC/SAML 2.0/X.509) access GCP without SA keys via OAuth2/STS exchange; "eliminates the maintenance and security burden associated with service account keys." (source: https://docs.cloud.google.com/iam/docs/workload-identity-federation, 2026-06-13).
- For off-GCP workloads, WIF uses a credential-config file that "doesn't contain a private key and doesn't need to be kept confidential"; ADC auto-discovers it via `GOOGLE_APPLICATION_CREDENTIALS`; supported in Go (source: https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers, 2026-06-11).
- `x/oauth2/google v0.36.0` `FindDefaultCredentials` / `DefaultTokenSource` resolves, in order: `GOOGLE_APPLICATION_CREDENTIALS` JSON (incl. WIF/`external_account`), gcloud user creds, then GCE/GKE metadata (attached SA); `CredentialsType` includes `ServiceAccount` and `ExternalAccount`; `CredentialsFromJSON` is deprecated — use `CredentialsFromJSONWithType`; same `TokenSource` regardless of source (source: https://pkg.go.dev/golang.org/x/oauth2/google, 2026-02-11).
- FCM HTTP v1 auth docs recommend ADC on Compute Engine/GKE/App Engine/Functions, warn that referencing the SA JSON file "should be done with extreme care," recommend `GOOGLE_APPLICATION_CREDENTIALS` as "more secure and … strongly recommended," cite Workload Identity as an alternative to downloaded keys, and specify scope `https://www.googleapis.com/auth/firebase.messaging` (source: https://firebase.google.com/docs/cloud-messaging/auth-server, 2026-06-13).
-
---
-
-## Decision 3 — `apns-expiration` policy: relay-set finite TTL for WAKE pushes
-
-**Decision.** Should the relay set a finite `apns-expiration` (and parallel FCM `android.ttl`) on `private_alert` WAKE pushes so a stale wake doesn't deliver days later, or omit it and accept Apple's ~30-day store-and-retry? What concrete default, and does the policy live in the relay or stay caller-controlled per the `02`/`03` contract? (Spec §5.1, §15 #5; resolves spec open question 5.)
-
-**Resolution.** **Set a FINITE `apns-expiration` by default in the relay.** Ship `apns-expiration = now + 4 hours` for the APNs `private_alert` mode and `now + 1 hour` for `background_wake`, with a parallel FCM `android.ttl` keyed by the FCM wire mode — `"14400s"` for `private_data` (the FCM counterpart of the APNs `private_alert`) / `"3600s"` for `background_wake` — for cross-provider parity. Both values are **per-deployment config** (relay-owned defaults, not caller-supplied) and do **not** change the external `02`/`03` wire contract, which has no expiration field — the relay sets the upstream header itself. Do **not** use `apns-expiration=0` (single-attempt, no store) and do **not** omit it (Apple stores/retries up to ~30 days). This confirms and operationalizes spec open question 5; the firm refinement is to keep it relay-owned with config-tunable defaults rather than promoting it to a caller field.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **Finite relay-set default (~4h `private_alert` / ~1h `background_wake`), config-tunable, parallel FCM `ttl` (chosen)** | A WAKE is only useful while it can still produce a near-real-time fetch; the inbox ([`../01-release-events-and-inbox.md`](../01-release-events-and-inbox.md)) is the source of truth, so a wake missed for hours is re-driven by the caller outbox or the next foreground sync, not by a stale push. Avoids a device buzzing for an event already read/deleted server-side days ago. Bounds APNs/FCM store-and-retry use. Keeps the content-free posture intact (no new caller field, no contract change). A multi-day-offline device just gets a clean expiry. With `collapse-id`, a finite TTL compounds correctly: a newer wake supersedes the old one and the old one self-expires. Config-tunable so product can re-tune without a code/contract change. | Bakes a partly product/UX call into infra: a device back online at hour 5 gets no wake and relies on its next foreground sync (acceptable — inbox is authoritative — but a real behavioral choice). One hardcoded default per mode cannot suit future urgency tiers. APNs (absolute epoch) vs FCM (duration) asymmetry means the relay must compute the APNs epoch from `now()+TTL` per request. |
-| Omit `apns-expiration` / omit `android.ttl` (Apple ~30-day store-and-retry; FCM 4-week default) | Maximizes raw delivery probability; simplest code; matches provider default (no per-request epoch math). | Verified behavior: omitted `apns-expiration` → store/retry up to ~30 days; omitted FCM `ttl` → 4 weeks. For a content-free WAKE that exists only to trigger a live fetch, a wake fired days later is useless at best, confusing at worst. Spends store-and-retry budget on valueless pushes. Contradicts the "inbox is the source of truth" premise. Spec explicitly rejects the 30-day default. |
-| `apns-expiration = 0` / `android.ttl = 0s` (deliver-once-now-or-discard) | Strongest guarantee against stale wakes; trivial constant. | `0` means no storage at all: a device merely briefly offline (locked, poor signal, Doze) loses the wake entirely, defeating the point. Background pushes are already APNs-throttled (~2–3/hr) and may be delayed; with `TTL=0` too many legitimate wakes drop. FCM `ttl=0` also disables collapsible-message throttling — a behavior change with no upside. |
-| Promote expiration to a caller-controlled `02`/`03` field | Maximum flexibility: the self-hosted server, which alone knows true urgency, picks the TTL per push; future-proofs urgency tiers without a relay redeploy. | Violates the locked `02`/`03` contract (additive-only, not a listed v1 capability) and widens the content-free surface with a new caller-controlled numeric channel visible to Apple/Google — exactly what §5.1 bounds (cf. the badge field). Adds validation/clamping burden. Premature: v1 has exactly one wake semantic. Can be added later additively if a real urgency-tier requirement emerges. |
-
-**Rationale.** The decision hinges on what a `private_alert` IS in Silo: a content-free **WAKE** whose only job is to make the device fetch fresh notifications from the user server, where the **inbox**, not the push, is the source of truth (spec §5.1, [`../01-release-events-and-inbox.md`](../01-release-events-and-inbox.md)). That framing makes a wake's value decay with time — once hours old, the device's own next foreground sync (or a fresher wake in the same collapse series) has already reconciled state, so a late wake yields no benefit and a small confusion cost. Both extremes are verified-wrong for this use case: omitting the header invokes Apple's ~30-day store-and-retry (verbatim: stored "for 30 days or less") and FCM's 4-week default — far too long; `expiration=0` / `ttl=0s` means deliver-once-or-discard with no storage, dropping wakes for a device merely briefly offline (especially bad given APNs already throttles background pushes). A finite few-hours TTL is the correct middle: long enough to ride out normal transient offline windows (Doze, locked phone, brief signal loss), short enough that a multi-day-offline device gets a clean expiry and relies on its authoritative next sync. `background_wake` gets the shorter ~1h TTL because it is even more time-sensitive and even more throttled (APNs requires `apns-priority 5` for background pushes; priority 10 is an error). The `collapse-id` interaction reinforces this: collapse already means latest-wins on-device, and a finite expiration is the complementary mechanism for the cross-series / no-newer-wake case, so the two together ensure stale wakes neither pile up nor fire late. Keeping it relay-owned and config-tunable (not a caller field) preserves the locked `02`/`03` contract and the structural content-free guarantee while letting product re-tune durations — which is how the spec already resolved open question 5.
-
-**Consequences (what this commits).**
-
- **Code.** `internal/pushwire/apns.go` computes `apns-expiration = now()+TTL` as a UNIX epoch (UTC, seconds) per request from config, per APNs mode (`private_alert` vs `background_wake`). `internal/pushwire/fcm.go` sets `android.ttl` as the parallel duration string keyed by the **FCM** wire mode — `"14400s"` for `private_data` (the FCM counterpart of the APNs `private_alert`; spec §5.2 lists FCM modes as `private_data` | `background_wake`) / `"3600s"` for `background_wake`. Note the mode-name asymmetry: an implementer building `internal/pushwire/fcm.go` must key on `private_data`, not `private_alert`, on the FCM path. Because the value is `now()`-relative, the golden-file payload/header tests in Phase 3/4 must **inject a fixed clock** or assert the header is present and within tolerance rather than byte-exact; the mirrored `silo-server` `pushwire` copy and its checksum/golden tests must use the same clock-injection approach so the two repos do not drift.
- **Config.** Two new non-secret tuning values (`apns_expiration_private_alert`, `apns_expiration_background_wake`) in `internal/config`, with the FCM `ttl` paired/derived, defaulted in code, env/flag-overridable, loaded and validated at startup (reject values exceeding the APNs storage max or FCM 28-day max; reject `<=0` if omit/0 is disallowed by policy).
- **Contract.** No change to the `02`/`03` wire contract and no new caller field — preserving additive-only API rules and the content-free guarantee.
- **Ops.** A stale-wake or missed-wake-rate concern becomes a **config tune, not a logic redeploy**. No schema change, no new dependency.
- **Tests.** Assert `background_wake` never emits `apns-priority 10` alongside its shorter TTL, and that an out-of-range configured TTL fails startup validation.
-
-**Revisit if.** (1) Silo introduces more than one wake semantic or an urgency/priority tier (today there is exactly one: `wake = notifications.changed`), at which point per-mode or per-request TTL — possibly an additive `02`/`03` caller field with a bounded max — becomes justified. (2) Production metrics show a material missed-wake rate attributable to the ~4h/~1h window being too short for the real offline distribution of Silo devices. (3) Apple or Google changes `apns-expiration` / `android.ttl` semantics or the storage-policy maximum (re-verify the cited pages near deployment). (4) The durable-inbox + foreground-sync assumption weakens (e.g., a future notification type whose value is NOT recoverable from the inbox), which would change whether a missed wake is truly harmless.
-
-**Sources.**
- APNs verbatim: "If the value is 0, APNs attempts to deliver the notification only once and doesn't store it." and "If the value is nonzero, APNs stores the notification and tries to deliver it at least once, repeating the attempt as needed until the specified date." (source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13).
- Omitted `apns-expiration` → Apple stores per its storage policy: "it may store the notification for 30 days or less … APNs attempts to deliver … the next time the device activates and is available online." (source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13).
- `apns-expiration` carries UNIX epoch seconds (UTC); an invalid value yields `400 BadExpirationDate`; `apns-priority` for background pushes MUST be 5 (priority 10 is an error) (source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13).
- `apns-collapse-id` merges notifications on-device (latest of the same id wins), ≤ 64 bytes, independent of expiration — so finite expiration + collapse means a newer wake supersedes an older queued one AND an undelivered wake self-expires (source: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns, 2026-06-13).
- FCM `android.ttl`: default when omitted is four weeks; max 2,419,200 s (28 days); `ttl=0` discards messages that can't be delivered immediately and disables collapsible-message throttling (source: https://firebase.google.com/docs/cloud-messaging/customize-messages/setting-message-lifespan, 2026-06-13).
- FCM collapse: with a collapse key, an offline-stored message is replaced by the newer one; without one, both are stored; at most 4 distinct collapse keys per device while offline (source: https://firebase.google.com/docs/cloud-messaging/customize-messages/setting-message-lifespan, 2026-06-13).
- Spec already resolved this as open question 5: v1 ships finite, configurable defaults (~4h `private_alert`, ~1h `background_wake`; parallel FCM `android.ttl`), relay-owned and tunable; the external `02`/`03` contract is unchanged (source: ./00-relay-spec.md, 2026-06-13).
-
---
-
-## Decision 4 — Per-account rate limits: hard-coded global defaults in v1
-
-**Decision.** Ship hard-coded global rate-limit defaults (~10 req/s burst, 50k/day), or add per-account quota columns (`rate_per_sec`, `burst`, `daily_quota`) on `relay_accounts` settable via `relayctl`, seeded with the documented defaults? (Spec §9.2, §15 #1.)
-
-**Resolution.** **Ship hard-coded global defaults for v1**: ~10 req/s burst (capacity-20 token bucket), 50,000 req/day (fixed-UTC), coarse per-(account, token) ~1 req/3s — enforced as **named config constants with env-var overrides**, NOT per-account DB columns. Keep all per-account **enforcement** plumbing exactly as specified (Redis bucket keyed `rl:{account_id}`, daily counter `rl:day:{account_id}:{yyyymmdd}`, the §9.5 shared-FCM-project circuit breaker). Add per-account override columns only when production logs prove at least one account legitimately needs a different cap. This matches the relay's own stated lean in spec §9.2 ("v1 ships a single global default and tunes from logs") and open Q#1, so it ratifies the plan rather than reopening it.
-
-Make the later per-account path cheap by: (1) reading the three limit values from a single typed struct `accountLimits{RatePerSec, Burst, DailyQuota}` resolved per request, defaulting to the global constants, so introducing a per-account source later is a one-function change, not a call-site sweep; (2) keeping the Redis bucket/daily keys labeled by `account_id` already (done). When the trigger fires, add columns `rate_per_sec int`, `burst int`, `daily_quota int` (all **NULLABLE**, NULL = inherit global) to `relay_accounts` in one timestamped Goose migration, plus a `relayctl quota set --account <id> [--rate-per-sec N] [--burst N] [--daily-quota N]` / `quota show` / `quota reset` subcommand — a backward-compatible, additive change.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **Hard-coded global defaults (config constants + env overrides), no per-account columns in v1 (chosen)** | Matches the relay's own documented lean (spec §9.2, open Q#1). Zero new schema/CLI surface — less code, fewer tests, smaller attack surface for a reliability-first first release. The abuse-containment requirement (OWASP API4:2023) is **already** met: the global default is enforced per-account (keyed by `account_id` in Redis) plus the §9.5 shared-project circuit breaker, so a stolen/misbehaving key is capped whether the number is a constant or a column. Operators still adjust globally via env var. Adding columns later is genuinely cheap (PG metadata-only `ADD COLUMN`). | A single hot account legitimately exceeding 50k/day must be handled by raising the GLOBAL default (env var, affects all) or an emergency change — until override columns exist. Slightly less satisfying day-one operability. Mitigated by the §9.2 alert at ≥80% of the daily cap. |
-| Per-account columns on `relay_accounts`, settable via `relayctl`, seeded with defaults — in v1 | Per-account tuning from day one; cleanest long-term shape; NULL-default inheritance is clean; avoids any future migration. | Builds an override surface against zero production evidence (the client already paces at 5 req/s, half the 10 req/s default, so real traffic won't press the limit). Adds schema + `relayctl quota` subcommands + tests + an inheritance/precedence rule and its edge cases to a reliability-first v1. More surface for a misconfiguration (`daily_quota=0`, absurd burst) to cause an outage or remove the abuse cap. The migration it "saves" is nearly free anyway. |
-| Per-account columns now but NOT exposed via `relayctl` (DB-only `UPDATE`) | Future-proof schema without building/testing the CLI; emergency override via privileged DSN. | Worst of both: pays the schema + inheritance cost yet has no safe, audited workflow — raw `UPDATE`s bypass the `relay_op_logs` `admin.*` audit trail that `relayctl` provides (spec §5.6), contradicting the "all admin ops audited" posture. No advantage over adding columns + CLI together when the trigger fires. |
-
-**Rationale.** Four things make global defaults the right v1 call. (1) The migration-cost argument for "add columns now to avoid pain later" does not hold: PostgreSQL `ALTER TABLE ADD COLUMN` with a **constant** default is a metadata-only operation (no row rewrite) since PG 11, and `relay_accounts` holds one row per opt-in installation — hundreds at most — so even a full rewrite is trivial; NULLABLE columns (NULL = inherit) avoid even needing a default, and adding columns + a `relayctl quota` subcommand later is backward-compatible (source: https://www.postgresql.org/docs/current/ddl-alter.html, 2026-06-13). (2) The security requirement (OWASP API4:2023, Unrestricted Resource Consumption) is satisfied by a per-account **cap**, which the global default already provides — every bucket is keyed by `account_id`, and the §9.5 shared-FCM-project circuit breaker bounds cross-tenant blast radius; OWASP recommends per-client throttling and business-tuned limits but does not require per-account **configurability** (source: https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/, 2026-06-13). (3) Real traffic won't press the default: the Silo server paces client-side at 5 req/s (`02`/`03`), half the 10 req/s relay backstop, so the relay limit exists to catch a misbehaving/compromised caller, not to be tuned per well-behaved tenant (source: ./00-relay-spec.md, 2026-06-13). (4) This is a reliability-first first release; the §15/§9 text already leans "single global default, tune from logs," so shipping that ratifies the plan and minimizes v1 surface. The correct sequencing is: ship one default, watch the ≥80%-of-daily-cap alert and per-account `429` metrics, and add targeted overrides only when a real account demands one — at which point the change is cheap and evidence-driven. The shared-project risk is unavoidable regardless of limit shape: FCM's default per-project quota is 600,000 messages/minute enforced **per project** (shared across all tenants using it), returning `429 RESOURCE_EXHAUSTED` over quota — which is exactly why the §9.5 circuit breaker is required no matter whether the per-account number is a constant or a column (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-12).
-
-**Consequences (what this commits).**
-
- **Schema.** NO change to the spec §8.1 v1 schema — `relay_accounts` ships **without** `rate_per_sec` / `burst` / `daily_quota` columns.
- **Code.** Limit values live as named config constants in `internal/config` (per plan §2.4, "non-secret defaults … live as constants with env overrides") with env-var overrides; the rate-limit middleware (`internal/ratelimit`) reads them through a single `accountLimits` struct resolved per request, defaulting to the globals, so a future per-account source is a one-function swap, not a call-site sweep.
- **Redis.** Keys remain account-scoped (`rl:{account_id}`, `rl:day:{account_id}:{yyyymmdd}`) — already specified, so enforcement granularity is unchanged.
- **CLI.** NO new `relayctl quota` subcommand in v1; the §5.6 command table is unchanged.
- **Ops.** Operators tune the SINGLE global default via env var + rolling restart; the §9.2 ≥80%-of-daily-cap alert and the `relay_rate_limited_total{kind=account|daily}` / `relay_daily_quota_used_ratio` metrics are the feedback loop. The §9.5 shared-FCM-project circuit breaker is unaffected and still required.
- **Commits the team** to a later additive migration + `relayctl quota set/show/reset` CLI **only if/when** the revisit trigger fires (columns NULL = inherit global).
-
-**Revisit if.** Add the per-account columns + `relayctl quota set/show/reset` CLI as soon as ANY of: (a) production metrics show one or more **legitimate** accounts repeatedly hitting the 50k/day cap or 10 req/s burst (`relay_rate_limited_total{kind=daily|account}` or `relay_daily_quota_used_ratio >= 0.8` sustained for a real, non-abusive account) such that raising the GLOBAL default would over-provision everyone else and erode the abuse cap; (b) operators need to throttle or temporarily zero a SPECIFIC misbehaving account without affecting others (today only all-or-nothing revoke/disable exists); (c) the relay onboards tenant tiers with deliberately different quotas — at which point per-account quotas become a product requirement, not a tuning convenience.
-
-**Sources.**
- PostgreSQL `ALTER TABLE ADD COLUMN` with a CONSTANT default is a fast metadata-only operation (no table rewrite; default materialized lazily); only a VOLATILE default forces a per-row update (source: https://www.postgresql.org/docs/current/ddl-alter.html, 2026-06-13).
- OWASP API4:2023 recommends rate limiting per client/operation and business-tuned limits; it does NOT prescribe per-client configurable quota columns or a specific multi-tenant quota architecture — a per-tenant cap satisfies the control (source: https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/, 2026-06-13).
- FCM default per-project downstream quota is 600,000 messages/minute, enforced PER PROJECT (shared across tenants) via a per-minute token bucket; over quota returns `429 RESOURCE_EXHAUSTED` — hence the shared-project circuit breaker is required regardless of per-account limit shape (source: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas, 2026-06-12).
- Spec §9.2 states the v1 intent: "These are tunable per account (future column on `relay_accounts`); v1 ships a single global default and tunes from logs," and lists per-account columns as open question #1 (source: ./00-relay-spec.md, 2026-06-13).
- The Silo server already paces relay calls client-side at a default 5 req/s shared token bucket (`02`/`03` "Relay pacing"), half the 10 req/s relay backstop (source: ./00-relay-spec.md, 2026-06-13).
-
---
-
-## Decision 5 — API-key hashing: `HMAC-SHA256(pepper, secret)`
-
-**Decision.** For high-entropy random relay API keys (`rk_<env>_<random>`, ≥128 bits), what is the correct at-rest hashing in 2026: `HMAC-SHA256(pepper)` vs salted SHA-256 vs argon2id? (Spec §8.2, §15 #6; plan Phase 1; reference §4.1.)
-
-**Resolution.** **Store API keys as `HMAC-SHA256(pepper, secret)`** — a fast keyed hash with a server-side pepper held in the secret manager, separate from PostgreSQL. The spec/plan already lean this way (spec §8.2, plan Phase 1, reference §4.1); keep it. Concretely: generate the secret as ≥32 bytes from `crypto/rand`, format `rk_<env>_<base62/base64url>`; store a non-secret, uniquely-indexed prefix (`rk_<env>_<first 6–8 chars>`) cleartext for O(1) lookup; store `key_hash = HMAC-SHA256(pepper, presented_secret)` (32 bytes, `bytea`); verify with `crypto/subtle.ConstantTimeCompare` against the stored hash (and against a fixed decoy hash on prefix-miss to keep the path constant-time). Do **not** use argon2id/bcrypt here — they are for low-entropy human passwords and only add per-request latency and (for bcrypt) a 72-byte input-truncation hazard with no security gain against a 256-bit keyspace. No per-key random salt is required because the full-entropy secret already makes the hash input unique and rainbow tables infeasible; the pepper is the deliberate, shared defense-in-depth lever instead.
-
-**Rotation note (load-bearing):** a pepper change cannot be done in place — it requires re-hashing every live key (impossible without the plaintext, which is never stored) or, the workable path, a **dual-pepper verification window** (try the new pepper, fall back to the old) plus a `pepper_version` column, then re-issuing keys under the new pepper and retiring the old pepper once all live keys are re-issued. Because key secrets are unrecoverable, "re-hash all keys" is really "re-issue all keys," so v1 must (a) tag each `key_hash` row with a `pepper_version`, (b) support reading under N peppers during overlap, and (c) treat pepper rotation as a make-before-break, multi-key-reissue operation aligned with the existing credential-rotation runbook (spec §14.3). Pepper rotation should be rare (compromise-driven), not scheduled.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **`HMAC-SHA256(pepper, secret)` — fast keyed hash with secret-manager pepper (chosen)** | Fast: sub-microsecond verify, no per-request CPU/RAM tax on the hot auth path (the only synchronous DB touch is the prefix lookup). Correct for high-entropy keys: a 256-bit random secret is ~2^256 keyspace, infeasible to brute-force regardless of hash speed. Defense-in-depth: if PostgreSQL leaks but the pepper does not, the stolen `key_hash` values are inert to an offline attacker. Matches OWASP's pepper guidance (shared secret, stored separately, applied via HMAC-SHA256). Plays naturally with prefix-indexed O(1) lookup + constant-time compare. Already the spec/plan choice — zero rework. | Pepper rotation is heavier: cannot re-hash in place, so it needs a dual-pepper overlap window + `pepper_version` column + key re-issuance. The pepper is a single shared secret whose compromise affects all keys at once (mitigated: secret-manager-only, never in DB/image). Slightly more moving parts than plain SHA-256. |
-| Per-key salted SHA-256 (fast hash, random salt per key, no pepper) | Also fast and correct for high-entropy keys; trivially simple; no pepper to provision/rotate; salt defeats cross-key precompute (near-moot at 256-bit). | No defense-in-depth on a DB-only leak: with salt+hash an attacker can verify guesses offline — but at 256-bit entropy that offline attack is itself infeasible, so the practical delta is small. The real loss is the cheap, high-value "DB leak but pepper intact ⇒ stolen hashes inert" property, which is exactly this design's headline threat (hostile/compromised relay operator with full DB, spec §3.5). For a credential-custody-focused service holding official Apple/Google push credentials, paying the modest rotation cost to keep that property is the right trade. |
-| argon2id (or bcrypt) — slow memory-hard KDF | Industry-default "correct" answer for password storage; unimpeachable if these were human-chosen secrets; brute-force resistance for low-entropy inputs. | Wrong tool. OWASP's slow-KDF requirement is scoped to passwords ("Fast hashing algorithms such as SHA-256 are not suitable for password storage…") — the threat is low password entropy, which does not exist for a 256-bit `crypto/rand` key. Adds real per-request cost (argon2id at OWASP's m=19 MiB, t=2 is tens of ms and tens of MB per verification — a self-inflicted DoS/memory-amplification vector on an auth endpoint). bcrypt additionally truncates input at 72 bytes (needs an HMAC/SHA pre-hash anyway). No security benefit: cannot make an already-infeasible 2^256 search more infeasible. Spec and reference explicitly reject it. |
-
-**Rationale.** The decision turns on one fact: the secret is **high-entropy and machine-generated, not a human password**. Slow KDFs (argon2id/bcrypt) exist to compensate for low password entropy by making each guess expensive — their entire value is throttling a feasible offline guessing attack. Against a ≥128-bit (here 256-bit) `crypto/rand` secret the guessing attack is not feasible to begin with (~2^256 ≈ 10^77 candidates), so the slow hash protects against nothing while imposing real cost; the GPU gap that justifies slow KDFs for an 8-char password (≈180 billion SHA-256 h/s vs ≈1000 argon2 h/s) is irrelevant when the keyspace itself is unreachable (source: https://www.thesslstore.com/blog/what-is-256-bit-encryption/, 2026-06-13). OWASP confines the fast-hash prohibition to "password storage" (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06-13), and OWASP API2:2023 treats API keys as a distinct category requiring anti-brute-force at the endpoint — which the relay supplies via per-IP throttle + per-account rate limits, not a slow hash (source: https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/, 2026-06-13). So a **fast** hash is the correct family. Within fast hashes, the pepper-vs-salt choice is a defense-in-depth-vs-rotation-cost trade, and the pepper buys a property that maps directly onto this service's threat model: the headline adversary is a compromised relay operator / DB leak (spec §3.5), and the relay holds the official Apple `.p8` and Google SA credentials for the whole ecosystem. With the pepper in the secret manager (never in PG, never in the image), a Postgres-only compromise yields `key_hash` values that are inert without the pepper key — an attacker cannot even mount the (already-infeasible) offline search, and cannot forge or recognize valid keys. OWASP defines a pepper as a secret "shared between stored passwords," stored separately, applied as an HMAC where "the pepper is acting as the HMAC key" — exactly this design (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06-13). The rotation cost is real but bounded and rare (compromise-driven), and reuses the existing make-before-break credential-rotation runbook (spec §14.3). Salted SHA-256 is a defensible simpler fallback if the team judges pepper rotation not worth it, but it forfeits the DB-leak-resistance property that is this design's reason to care; argon2id is the only genuinely wrong choice and both spec and reference already reject it.
-
-**Consequences (what this commits).**
-
- **Schema/DB — amends spec §8.1 / plan Phase 1.** `relay_api_keys` stores `key_hash bytea = HMAC-SHA256(pepper, secret)` (32 bytes), a cleartext uniquely-indexed `key_prefix`, and `account_id` / `created_at` / `last_used_at` / `expires_at` / `revoked_at` (spec §8.1). No salt column. **This decision adds one column the reproduced §8.1 `relay_api_keys` table does not have: `pepper_version smallint NOT NULL DEFAULT 1` (a `key_id` column is an acceptable equivalent), included in the Phase 1 init migration from the start** so dual-pepper rotation is possible later without a migration under pressure. This is an **additive, backward-compatible deviation** from the §8.1 schema reproduced in the spec and the plan's "exact schema from spec §8.1" Phase 1 statement — an implementer must add the column up front rather than discovering the gap during pepper rotation.
- **Code.** `internal/accounts/keys.go`: `crypto/rand` secret generation; HMAC-SHA256 hashing. `internal/httpapi/middleware_auth.go`: `crypto/subtle.ConstantTimeCompare` for verification; a fixed decoy-hash compare on prefix-miss to keep the auth path constant-time (no enumeration oracle); verification tries the active pepper and, during a rotation window, falls back to prior pepper(s) keyed by `pepper_version`.
- **Ops / secret management.** The pepper is a first-class secret in the secret manager (KMS/Vault/cloud), never in PG, never in the image/env where avoidable, loaded once at startup (spec §11, reference §4.5); it must be **backed up / escrowed** because losing it invalidates every live key.
- **Rotation runbook.** Pepper rotation = make-before-break (provision new pepper alongside old, verify under both, re-issue all keys under the new pepper, retire old) — reuse the §14.3 credential-rotation pattern; document that "re-hash all keys" is really "re-issue all keys."
- **Performance.** Auth stays a sub-microsecond hash + one indexed lookup, preserving the stateless-fast hot path (spec §4.1). Commits to NOT pulling argon2/bcrypt onto the request path.
- **Tests.** Unit tests asserting the hash is `HMAC-SHA256(pepper, ·)`, constant-time compare, plaintext never stored, and unknown-prefix vs wrong-secret are timing-indistinguishable (plan Phase 1/2 acceptance criteria).
-
-**Revisit if.** (1) The relay ever accepts a LOW-entropy or human-chosen secret (an operator passphrase, basic-auth admin password, shortened/customer-supplied key) — then a slow KDF (argon2id at OWASP's m=19 MiB, t=2, p=1 minimum) becomes mandatory for that credential class. (2) The pepper would have to live in the same trust boundary as PostgreSQL (same host/backup, in the DB) — its defense-in-depth value evaporates and plain salted SHA-256 becomes the honest, simpler choice. (3) A hard, citable, API-key-specific standard later prescribes a different at-rest scheme. (4) Pepper rotation proves operationally painful and pepper-compromise risk is judged low — drop to per-key salted SHA-256. (5) Key entropy is ever reduced below ~128 bits.
-
-**Sources.**
- OWASP: "Fast hashing algorithms such as SHA-256 are not suitable for **password** storage because they allow attackers to perform large numbers of guesses quickly." (scoped to passwords) (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06-13).
- OWASP argon2id recommended configs (e.g. m=19456 KiB, t=2, p=1) are a per-verification CPU/RAM tax that would hit every relay auth if wrongly applied to API keys (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06-13).
- OWASP defines a pepper as a secret "shared between stored passwords," "stored separately from the password database," applied via HMAC where "the pepper is acting as the HMAC key" (source: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html, 2026-06-13).
- OWASP API2:2023 flags weakly-hashed credentials, requires anti-brute-force mechanisms on auth endpoints, and states "API keys should not be used for user authentication … only for API clients authentication." (source: https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/, 2026-06-13).
- A 256-bit random key has ~2^256 (~10^77) values — computationally infeasible to brute-force regardless of hash speed; security derives from key entropy, not hash slowness; the ~180-billion-vs-~1000 h/s gap is irrelevant when the keyspace is unreachable (source: https://www.thesslstore.com/blog/what-is-256-bit-encryption/, 2026-06-13).
- bcrypt truncates input at 72 bytes (a long `rk_` key would be silently shortened, needing an HMAC/SHA pre-hash anyway), making a slow KDF not merely unnecessary but operationally hazardous for long high-entropy keys; fast HMAC-SHA256/SHA-256 is appropriate for quick auth checks on high-entropy tokens (source: https://mojoauth.com/compare-hashing-algorithms/hmac-sha256-vs-bcrypt, 2026-06-13).
-
---
-
-## Decision 6 — `relay_op_logs` retention: PostgreSQL daily RANGE partitioning, retention by partition DROP
-
-**Decision.** For `relay_op_logs` at ~50k/day/account scale with 14-day-success / 30–90-day-failure retention, use native PostgreSQL declarative time partitioning (with partition drop), a simple indexed table with a periodic `DELETE` job, or offload to a log pipeline (Loki/ELK) — and what is the exact retention mechanism for v1? (Spec §8.1, §15 #8; plan Phase 5.)
-
-**Resolution.** **Ship v1 with native PostgreSQL declarative RANGE partitioning** of `relay_op_logs` by `occurred_at`, using **DAILY** partitions, and enforce retention by **DROPPING whole partitions** on a schedule — not by row-level `DELETE`, and not by offloading to a log pipeline. Pre-create partitions ahead of time and drop those older than the retention horizon. Run the maintenance (create-ahead + drop-old) with **`pg_partman 5.4.3`** invoked from a scheduled `relayctl logs --gc` / cron `SELECT run_maintenance()`, configured to **DROP (not just DETACH)** expired partitions. Keep retention simple in v1: a single uniform **90-day** drop horizon for the whole table (the failure-retention ceiling), so no partition straddles two policies. The differential 14-day-success vs 90-day-failure trim is then a cheap row-level `DELETE` **within the youngest partitions only** (success rows older than 14 days), where the working set is tiny and bloat is bounded — the bulk reclamation that matters comes free from dropping 90-day-old partitions. This is the partition-drop mechanism the spec already calls "the recommended store strategy" (§8.1) and resolves open question §15 #8 in favor of partitioning over a plain `DELETE` job or external offload.
-
-**Alternatives considered.**
-
-| Option | Pros | Cons |
-|---|---|---|
-| **Native declarative RANGE partitioning by `occurred_at` (daily), retention by partition DROP via `pg_partman`/cron (chosen)** | Retention is metadata-only: `DROP TABLE` on a day partition "can very quickly delete millions of records" and "entirely avoids the VACUUM overhead caused by a bulk DELETE." No dead-tuple/index churn from the append workload — the exact failure mode a daily bulk-DELETE on a high-write table hits. Stays inside the existing Postgres dependency (no new store), honoring "operational simplicity that still scales." `pg_partman` (5.4.3, PG14+) automates create-ahead + drop and runs from plain cron via `run_maintenance()` with no background worker, fitting the Goose + scheduled-job model. Inserts still target one parent table; the redacted-by-construction write path is unchanged. Scales linearly; old partitions drop in O(1). | Schema change: a partitioned table's PRIMARY KEY must include the partition key, so the current `id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY` becomes composite `(occurred_at, id)`. Adds `pg_partman` (or hand-rolled DDL) plus a create-ahead job whose failure (no future partition) would block inserts — needs a monitor. Differential 14d/90d retention is no longer one query; a small DELETE runs inside recent partitions. `DROP TABLE` on a partition briefly needs an ACCESS EXCLUSIVE lock on the parent (mitigated by `DETACH … CONCURRENTLY` first, or accepting a sub-second lock on a low-contention audit table). |
-| Simple indexed table + periodic `DELETE` job (the spec's `relayctl logs --gc` baseline, as the only mechanism) | Zero schema change — keeps the §8.1 table and surrogate bigint PK. Trivially expresses differential policy in one statement. Already a Phase 5 deliverable, so lowest-effort and a correct *fallback*. Fine at low account counts. | At 50k/day/account across accounts this is the anti-pattern the PG docs warn against: a large recurring DELETE leaves dead tuples and index bloat that standard VACUUM marks reusable but does not return to disk, so the table and its two `occurred_at` indexes bloat and slow the very append path. Reclaiming space needs `VACUUM FULL` (ACCESS EXCLUSIVE) or `pg_repack` — ongoing toil. The delete competes with hot-path inserts for I/O and locks. Works for months then the disk-growth surprise hits — exactly risk R12. |
-| Offload to a log pipeline (Loki/ELK), Postgres holds only recent rows | Purpose-built for high-volume append-only logs with cheap time-based retention and rich ad-hoc querying; removes write pressure from Postgres; scales far past 50k/day/account. | Violates v1's operational-simplicity / self-hosted brief: a whole new stateful system to deploy, secure, scope per-account, and back up for a single-region relay. `relay_op_logs` is an audit/forensics table queried by `relayctl` and joined to `relay_accounts` (FK `account_id`); moving it out breaks the in-Postgres admin/audit model and the single-point redaction guarantees. Over-engineered for the stated scale; reintroduces a deliberately-avoided dependency. The right answer later, not for v1. |
-
-**Rationale.** The workload is unambiguously a high-write, append-only, time-ordered table whose only deletes are time-based retention — the textbook case for declarative range partitioning. PostgreSQL's own current (v18) docs state the decision plainly: dropping a partition "is far faster than a bulk operation" and "entirely avoids the VACUUM overhead caused by a bulk DELETE," and recommend sizing partitions to match the retention cadence (source: https://www.postgresql.org/docs/current/ddl-partitioning.html, 2026-06-13). Reliability-first means the hot push path must not contend with a daily bulk DELETE or pay for its dead-tuple/index bloat; partition DROP makes retention a metadata operation that touches neither autovacuum nor the live indexes — whereas recurring large DELETEs accumulate bloat that VACUUM marks reusable but does not shrink on disk, requiring `VACUUM FULL` or `pg_repack` to reclaim (source: https://www.tigerdata.com/learn/how-to-reduce-bloat-in-large-postgresql-tables, 2026-06-13). **Daily** (not weekly/monthly) granularity is chosen because the success horizon is only 14 days and the failure horizon 90 days — daily children keep each partition small, make the 90-day drop precise, and keep the create-ahead window short. The plain-DELETE option is kept as the differential-trim tool inside young partitions and as a degraded fallback, not as bulk reclamation. A log pipeline is the correct answer at much larger multi-region scale, but for a single-region self-hosted v1 it adds a new stateful dependency that contradicts the "stays in Postgres" posture and severs the FK/audit/redaction model that lives in one place. `pg_partman` is the pragmatic automation: de-facto standard, current (5.4.3, 2026-03-05), PG14+, **defaults to DETACH** (so retention must be explicitly configured to DROP via `retention_keep_table = false`), and runs from ordinary cron via `run_maintenance()` so no background worker is required — matching the relay's Goose + scheduled-job model (source: https://github.com/pgpartman/pg_partman, 2026-06-13). The spec already names partitioning "the recommended store strategy"; this decision firms that into "partition + drop, daily, single 90-day horizon."
-
-**Consequences (what this commits).**
-
- **Schema (§8.1) — amends the plan.** `relay_op_logs` becomes `PARTITION BY RANGE (occurred_at)` with daily child partitions; the surrogate `id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY` must become a composite PRIMARY KEY `(occurred_at, id)` (id remains identity for ordering/correlation; `occurred_at` carries the partition key). The two indexes — `(account_id, occurred_at DESC)` and `(occurred_at DESC)` — are created on the partitioned parent and propagate to children; the `account_id` FK with `ON DELETE SET NULL` is unaffected. **This decision explicitly supersedes spec §8.1's non-partitioned `relay_op_logs` DDL (its single-column `id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY`) and the plan's "exact schema from spec §8.1" Phase 1 statement: the partitioned-from-birth design only works if the structural DDL lands in the Phase 1 init migration.** Converting an already-populated non-partitioned table to partitioned later is exactly the painful full-table rewrite that partitioning exists to avoid, so it must **not** be deferred to Phase 5.
- **Migrations — Phase 1 (structural, amending the §8.1 reproduction).** The Phase 1 init migration creates the partitioned parent + an initial window of daily partitions **in place of** the non-partitioned spec §8.1 `relay_op_logs` DDL and its single-column PK; `pg_partman` is added via `CREATE EXTENSION` + a `part_config` row (parent table, daily interval, premake N future days, `retention = '90 days'`, `retention_keep_table = false` to DROP). The composite `(occurred_at, id)` PK and the `CREATE EXTENSION pg_partman` + `part_config` row are part of this Phase 1 init migration, not a later Phase 5 add-on.
- **Code / ops.** The oplog writer is unchanged (still `INSERT` into the parent). A scheduled job — `relayctl logs --gc` or cron `SELECT run_maintenance()` — must run at least daily to (a) pre-create upcoming day partitions and (b) drop partitions older than 90 days; its **failure** (missing future partition) would reject inserts on the hot path, so it needs a dedicated alert in addition to the existing table-growth/disk alert (R12). The differential 14d-success trim runs as a bounded `DELETE` within recent partitions only.
- **Deps.** Adds `pg_partman 5.4.3` (PG14+) as a Postgres extension dependency; if the deployment cannot install extensions, fall back to hand-rolled create-ahead/drop DDL in `relayctl` (same partition design, no extension).
- **Locking.** Schedule drops at low-traffic times and/or `DETACH … CONCURRENTLY` then `DROP` to avoid the brief ACCESS EXCLUSIVE lock on the parent.
- **Phase split (amends the plan).** The plan's Phase 5 "partitioning DDL (or documented partition/offload decision)" line item is **resolved** by this decision, but the structural DDL itself moves **into Phase 1** (per the Schema/Migrations items above). **Phase 5 owns only** the operational pieces: the scheduled `run_maintenance()` / `relayctl logs --gc` create-ahead+drop job, the create-ahead-failure alert (a missing future partition rejects inserts on the hot path), and the bounded 14d-success differential `DELETE` within recent partitions. The plan's Phase 1 "exact schema from spec §8.1" line and Phase 5 "partitioning DDL" deferral are both superseded.
-
-**Revisit if.** (a) Sustained ingest materially exceeds the v1 envelope — e.g. tens of accounts pushing near 50k/day each so `relay_op_logs` exceeds ~100M live rows, or Postgres shows I/O/bloat pressure from op-log writes — at which point offloading to a dedicated log pipeline (Loki/ELK/ClickHouse) with Postgres keeping a short hot window becomes worth its added ops cost. (b) The deployment target cannot install `pg_partman` AND hand-rolled partition DDL proves error-prone. (c) The differential success/failure retention needs to grow into many distinct per-event horizons such that a single uniform partition-drop horizon no longer fits. (d) Operators need rich ad-hoc/full-text forensic search over op-logs beyond indexed Postgres queries.
-
-**Sources.**
- PostgreSQL: "Dropping an individual partition using DROP TABLE, or doing ALTER TABLE DETACH PARTITION, is far faster than a bulk operation. These commands also entirely avoid the VACUUM overhead caused by a bulk DELETE." (PG 18) (source: https://www.postgresql.org/docs/current/ddl-partitioning.html, 2026-06-13).
- PostgreSQL: dropping the no-longer-needed partition "can very quickly delete millions of records because it doesn't have to individually delete every record"; `DROP TABLE` on a partition needs ACCESS EXCLUSIVE on the parent, while `DETACH PARTITION CONCURRENTLY` needs only SHARE UPDATE EXCLUSIVE (source: https://www.postgresql.org/docs/current/ddl-partitioning.html, 2026-06-13).
- A unique/primary-key constraint on a declaratively partitioned table must include all partition-key columns — so partitioning by `occurred_at` requires the composite key (source: https://www.postgresql.org/docs/current/ddl-partitioning.html, 2026-06-13).
- `pg_partman` latest is 5.4.3 (2026-03-05); requires PostgreSQL ≥ 14; third-party extension; can run maintenance from external cron via `run_maintenance()`; by default DETACHes rather than DROPs expired partitions, so drop-on-retention must be configured (`retention_keep_table = false`) (source: https://github.com/pgpartman/pg_partman, 2026-06-13).
- For high-churn tables, recurring large DELETEs accumulate dead tuples and index bloat; VACUUM marks them reusable but does not shrink files, requiring `VACUUM FULL` or `pg_repack`; partition DETACH+DROP needs no vacuum at all (source: https://www.tigerdata.com/learn/how-to-reduce-bloat-in-large-postgresql-tables, 2026-06-13).
- `pg_partman` retention: "By default, partitions are not dropped (DROP), but are detached (DETACH)"; the configured interval drops partitions older than that interval; pg_partman never drops the last remaining child (source: https://www.keithf4.com/partman-retention/, 2026-06-13).
-
---
-
-## What this unblocks
-
-Each decision retires a spec §15 open question and clears a specific implementation-plan phase to proceed without further product/architecture input:
-
-| Decision | Retires | Unblocks |
-|---|---|---|
-| 1 — APNs client (hand-roll) | §15 #3, plan §3 "decision before Phase 3", risk R2 | **Phase 3** — `internal/apns` (`jwt.go`/`transport.go`/`client.go`/`errors.go`) and `POST /v1/apple/send` can be built directly against `net/http2` + `jwt/v5` with no library evaluation gating the work; the Apple provisioning checklist item "decide `apns2` vs hand-rolled" (plan §7.1) is closed. |
-| 2 — FCM credentials (keyless-first) | §15 #4 | **Phase 4** (`internal/fcm/oauth.go` builds the ADC `TokenSource`; `POST /v1/fcm/send`) and **Phase 6** (secret-manager wiring, the GCP attached-SA / off-GCP WIF deploy paths, and the `relayctl ping-upstream --provider fcm` credential-health gate). |
-| 3 — `apns-expiration` policy (finite, relay-owned) | §15 #5 (spec open question 5) | **Phase 3** (APNs `apns-expiration` epoch in `internal/pushwire/apns.go`) and **Phase 4** (parallel FCM `android.ttl` in `internal/pushwire/fcm.go`); the two new `internal/config` TTL values and their clock-injected golden tests are now specified. |
-| 4 — Rate limits (global defaults) | §15 #1 | **Phase 2** — `internal/ratelimit` ships the global constants + env overrides and the `accountLimits` resolution struct with no new schema, no `relayctl quota` CLI, and no inheritance-precedence edge cases; spec §8.1 schema and §5.6 command table are unchanged. |
-| 5 — API-key hashing (HMAC-pepper) | §15 #6 | **Phase 1** (`relay_api_keys` schema with `key_hash bytea` + a `pepper_version smallint NOT NULL DEFAULT 1` column added to the reproduced §8.1 table; the pepper as a first-class secret-manager secret) and **Phase 2** (`internal/httpapi/middleware_auth.go` constant-time verify with decoy-hash and dual-pepper fallback). |
-| 6 — Op-log retention (daily partition + DROP) | §15 #8 | **Phase 1** (the structural DDL — partitioned `relay_op_logs` parent, composite `(occurred_at, id)` PK, `CREATE EXTENSION pg_partman` + `part_config` row — lands in the init migration, **amending** the plan's "exactly spec §8.1" Phase 1 statement and superseding the non-partitioned §8.1 DDL) and **Phase 5** (only the `relayctl logs --gc` / `run_maintenance()` schedule, the create-ahead-failure alert, and the bounded differential 14d-success trim). |
@@ -1,71 +0,0 @@
-# Silo Push Relay — Design Index
-
-> **Provenance:** Authored 2026-06-13 from a research-and-review workflow (live primary-source research against Apple Developer / Firebase / Google / RFC / pkg.go.dev docs, adversarial fact-checking of time-sensitive claims, draft, multi-lens review, and revision). Reflects **2026-current** APNs and FCM behavior. These design docs live here in `silo-server` alongside the `02`/`03` notification contracts purely for **co-location** — the relay **code** lives in its own repository (provisional name `silo-push-relay`).
-
-This folder specifies the **Silo Push Relay**: the small Silo-operated service that holds the official Apple (`.p8` APNs auth key) and Google (Firebase service-account JSON) push credentials and forwards **opaque, content-free** push requests to APNs and FCM on behalf of opted-in self-hosted Silo servers.
-
-It is the **server counterpart** to the relay-client contracts in [`../02-apns-relay.md`](../02-apns-relay.md) and [`../03-fcm-relay.md`](../03-fcm-relay.md). Those documents define the wire contract from the self-hosted Silo server's perspective (`POST /v1/apple/send`, `POST /v1/fcm/send`); this folder specifies the service that answers it. **That external contract is authoritative and reproduced byte-for-byte; these docs add only the server-internal design (`02`/`03` deliberately left it "to a separate repo").**
-
-## Reading order
-
-1. **[`00-relay-spec.md`](./00-relay-spec.md)** — Engineering spec. Scope, trust/threat model, architecture, the full public API contract (both send endpoints + health/metrics + the `relayctl` admin CLI), the upstream APNs and FCM clients, the PostgreSQL account/key/allowlist schema, rate limiting, idempotency, security, privacy, observability, deployment.
-2. **[`01-implementation-plan.md`](./01-implementation-plan.md)** — Phased Go build plan. Repo bootstrap and layout, pinned dependency choices with rationale, seven implementation phases (each with files, tasks, tests, acceptance criteria), testing strategy, deployment, and the Apple/Firebase provisioning checklist.
-3. **[`02-apns-fcm-2026-reference.md`](./02-apns-fcm-2026-reference.md)** — The cited 2026 factual foundation. APNs (token/ES256 auth, endpoints, headers, payloads, status/reason tables, throttling) and FCM v1 (legacy-shutdown status, OAuth2 auth, endpoint, message JSON, error model, quotas) plus the recommended Go ecosystem and security/ops practices. Every non-obvious claim carries an inline source + date.
-4. **[`03-decisions.md`](./03-decisions.md)** — Decision record resolving the spec's open implementation questions (APNs client, FCM credentials, `apns-expiration`, rate limits, API-key hashing, op-log retention), each with a firm recommendation, alternatives, rationale, consequences, and cited current sources.
-
-## Status
-
-| Doc | Status |
-|---|---|
-| 00-relay-spec | Draft (implementation-grade) |
-| 01-implementation-plan | Draft (implementation-grade, phased) |
-| 02-apns-fcm-2026-reference | Reference (2026-current, cited) |
-| 03-decisions | Decided (6 resolutions, high confidence) |
-
-**Implementation status:** Phases 0–2 are built in the separate `silo-push-relay` repository. Phase 0 = the service skeleton (`/healthz` + `/readyz`, config, JSON logging, §5.5 envelope, graceful shutdown). Phase 1 = storage + admin (PostgreSQL schema via embedded Goose migrations, the `accounts` data-access layer with `HMAC-SHA256(pepper)` key hashing, the `relayctl` admin CLI with audited actions). Phase 2 = the full request pipeline on `POST /v1/apple/send` + `/v1/fcm/send` — bearer auth (constant-time compare with decoy, throttled `last_used_at`, soft per-IP brute-force cap, trusted-proxy client-IP resolution), Redis token-bucket rate limiting (per-account + daily + coarse per-token) with bounded in-process fail-open, `DisallowUnknownFields` decode/validate/allowlist, and fail-closed idempotency (NX lock + nonce, replay/409/422, compare-and-set). Upstream APNs/FCM calls are **stubbed** pending Phases 3–4. Two Phase-2-listed items were deferred to Phase 4 because they need the live FCM send path: the shared FCM-project circuit breaker (§9.5) and anti-spike smoothing. Phases 3–6 not started; provider-touching phases gated on Apple/Firebase provisioning (see `01` §7). `relay_op_logs` partitioning (Decision 6) is a dedicated later migration so migrations run on stock PostgreSQL.
-
-## Key design decisions
-
- **Faithful external contract.** `POST /v1/apple/send` and `POST /v1/fcm/send` — request fields, validation, response shapes, relay-built payloads, and APNs headers — are reproduced exactly from `02`/`03`. Only the relay's server-internal design is newly specified.
- **Content-free by construction.** The send structs admit only the opaque `02`/`03` fields; JSON is decoded with `DisallowUnknownFields`, so any unexpected key is a hard `400`. FCM is always data-only (no `notification` block); badge omitted by default.
- **Stateless request path.** The only synchronous DB touch is an indexed API-key prefix lookup plus a throttled (`≤1/min`) `last_used_at` write; idempotency and rate-limit state live entirely in Redis, so replicas scale horizontally and are kill-safe.
- **Admin = CLI, not HTTP.** Account/key/allowlist administration is `relayctl` writing directly to PostgreSQL; there is **no public admin HTTP API** in v1 (minimal attack surface).
- **API keys.** `rk_<env>_<random>` with a non-secret indexed prefix + `HMAC-SHA256(pepper, secret)` stored, constant-time compare, revocable, multi-live-key rotation; the full token is shown exactly once.
- **Upstream mechanics (2026-correct).** One cached ES256 JWT per APNs team (regenerate ~50 min, never < 20 min apart, eager refresh on `ExpiredProviderToken`); one cached OAuth2 token per FCM project (~1 h); HTTP/2 connection reuse with PING health checks.
- **Idempotency fails closed; rate limiting fails open.** If Redis is unavailable, sends are refused (`503`) rather than risk a double-send; rate limiting degrades to allow (availability over perfect enforcement), with a metric.
- **"Relay-down delays, never loses."** The self-hosted server-side outbox (`push_delivery_attempts` pending rows in `../01-release-events-and-inbox.md`) guarantees re-delivery, so ordinary stateless-replica HA suffices.
-
-### Reconciliations where the 2026 reference corrects the 2026-04 contracts
-
-These are upstream-only details; the **external `02`/`03` contract is unchanged**:
-
- **APNs sandbox host** is `api.sandbox.push.apple.com` (the canonical name); `02`'s `api.development.push.apple.com` is a still-valid alias (same backend). Internal detail; the external `"environment":"sandbox"` field is untouched.
- **FCM 429** honored with `Retry-After` (60 s fallback) while still surfacing `Retry-After` to the caller as `03` expects.
- **FCM data values** forced to strings (`map<string,string>`).
- **FCM `priority:high`** honored for `private_data`; provider deprioritization is the caller's concern.
-
-## Decisions (resolved in `03-decisions.md`)
-
-The spec's open implementation questions are now decided (all high confidence):
-
-1. **APNs client** — **hand-roll** on `net/http` + `x/net/http2` + `golang-jwt/jwt/v5` behind an `internal/apns` interface; do **not** take a production dependency on `sideshow/apns2` (no release since Oct 2024). Optionally keep apns2 as a throwaway Phase-3 oracle.
-2. **FCM credentials** — **keyless by default** via Application Default Credentials: attached service account on GCP, Workload Identity Federation off-GCP; service-account JSON in a secret manager only as a last resort. Identical code path in all three cases.
-3. **`apns-expiration`** — relay sets a **finite TTL** (4 h for `private_alert`, 1 h for `background_wake`) with a parallel FCM `android.ttl`; relay-owned config, external `02`/`03` contract unchanged.
-4. **Per-account rate limits** — **hard-coded global defaults** for v1 (~10 req/s burst, 50k/day), resolved through a typed `accountLimits` struct so per-account override columns are a cheap additive migration later.
-5. **API-key hashing** — `HMAC-SHA256(pepper, secret)` with a `pepper_version` column and a make-before-break dual-pepper rotation window. No argon2id (keys are high-entropy).
-6. **Op-log retention** — native PostgreSQL **daily RANGE partitioning**, retention by **partition DROP** (pg_partman), uniform 90-day horizon with a cheap row-level success-trim inside young partitions.
-
-## Confirmed (2026-06-13)
-
- **Module org** — `github.com/Silo-Server/silo-push-relay` (matches the real org in `silo-server`'s `go.mod`; the plan's `silo-app` was provisional).
- **Deployment target** — the relay is **not** deployed to GCP. Per Decision 2 this selects the off-GCP credential path: **Workload Identity Federation** (keyless, non-secret credential-config + OIDC token) preferred, with **service-account JSON in a secret manager** as the last-resort fallback. No attached-GCP-SA path.
-
-## Still needs human / operational input
-
-1. **Provider provisioning** (the real long pole) — Apple Developer account + APNs `.p8` key + per-platform bundle topics; Firebase project(s) + the WIF binding (or SA JSON in a secret manager). Gates Phases 3/4/6. See `01` §7.
-2. **Off-GCP OIDC issuer for WIF** — confirm the relay host has a usable OIDC issuer for Workload Identity Federation; if none, fall back to SA-JSON-in-secret-manager (Decision 2).
-3. **Multi-region** — out of scope for v1 (single region); revisit a regional Redis/Postgres strategy if latency to distant self-hosters matters.
-
-## Relationship to the parent notifications design
-
-This relay corresponds to phases 7–8 of the parent plan ([`../README.md`](../README.md) "Phasing"): `notifications.apple_push_enabled` and `notifications.android_push_enabled`. Those phases require Silo to provision Apple Developer + Firebase accounts and operate this service. The self-hosted server side (registration, dispatcher, pacing, retry, the dispatch outbox) is specified in `../02-apns-relay.md`, `../03-fcm-relay.md`, and `../01-release-events-and-inbox.md`.
@@ -41,10 +41,9 @@ Go application. Eliminate it as a plugin. User-visible outcome:
 ### Out

 - Audiobook requests flow (`silo-plugin-audiobook-requests` untouched).
- Smart collections, share links, content restrictions, metadata-provider integration.
+- Smart collections, share links, content restrictions, custom metadata providers.
 - Embedding-powered "similar books" recommender.
- External enrichment through the audiobook metadata plugin/provider — deferred;
-  scanner extracts local tags and identifiers for v1.
+- External enrichment (OpenLibrary / Google Books) — deferred; file tags only for v1.
 - Group listening / cowatch parity for audiobooks (silo already has cowatch for
  video; revisit later if needed).

@@ -54,7 +53,7 @@ Go application. Eliminate it as a plugin. User-visible outcome:

 New top-level Go package: `internal/audiobooks/`.

-```text
+```
 internal/audiobooks/
  abs/          ← ported from plugin's internal/abs/         (~6.8k LOC)
                  ABS-compatible REST handlers, mounted under /abs/* and the
@@ -91,9 +90,7 @@ media-token signing, CDN, streaming, event bus, migrations runner).
 - ~7.4k LOC ported from the plugin.
 - ~1.5–2k LOC new TypeScript/TSX in silo's SPA.
 - ~400 LOC of new Go glue (scanner branches, router wiring, service.go).
- Three new SQL migrations in the current stack (`147_abs_sessions`,
-  `157_podcast_feeds`, `160_audiobooks_feature_flag`) plus one documented
-  no-op migration for the already-present media-folder type column.
+- Two new SQL migrations (134, 135) and at most one column-add migration.

 ## Data model

@@ -114,9 +111,9 @@ media-token signing, CDN, streaming, event bus, migrations runner).

 ### New tables (two migrations)

-1. **`abs_sessions`** (migration 147) — parallel to existing `jellycompat_sessions`. Tracks ABS client device, token hash, last-seen so ABS apps reconnect without re-auth. Columns: `id`, `user_id`, `token_hash`, `device_id`, `device_name`, `abs_client_version`, `created_at`, `last_seen_at`. Same shape as `jellycompat_sessions` plus the `abs_client_version` text.
+1. **`abs_sessions`** (migration 134) — parallel to existing `jellycompat_sessions`. Tracks ABS client device, token, last-seen so ABS apps reconnect without re-auth. Columns: `id`, `user_id`, `token`, `device_id`, `device_name`, `abs_client_version`, `created_at`, `last_seen_at`. Same shape as `jellycompat_sessions` plus the `abs_client_version` text.

-2. **`podcast_feeds`** (migration 157) — one row per subscribed podcast. Columns: `media_item_id` (FK to the podcast `media_items` row), `feed_url`, `etag`, `last_refreshed_at`, `refresh_interval_seconds`. Episode rows live in the reused `episodes` table.
+2. **`podcast_feeds`** (migration 135) — one row per subscribed podcast. Columns: `media_item_id` (FK to the podcast `media_items` row), `feed_url`, `etag`, `last_refreshed_at`, `refresh_interval_seconds`. Episode rows live in the reused `episodes` table.

 ### Schema-touch column add

@@ -127,8 +124,8 @@ media-token signing, CDN, streaming, event bus, migrations runner).

 ### Plugin migrations NOT ported

-Smart collections, share links, embeddings, content restrictions,
-metadata-provider integration, request provider, file cache, listening stats aggregates,
+Smart collections, share links, embeddings, content restrictions, custom
+metadata providers, request provider, file cache, listening stats aggregates,
 reading goals, notification prefs, standalone-mode tables, recommender
 embeddings. All represent features dropped from scope.

@@ -228,9 +225,8 @@ and directors. No new code, just two more role string constants.

 ### External enrichment

-Deferred. The scanner extracts local tags and identity hints only. Canonical
-enrichment remains the responsibility of the audiobook metadata plugin/provider
-path and is not ported in this foundation pass.
+Deferred. The plugin's `enrich/` package (OpenLibrary / Google Books lookup)
+is not ported in v1. File tags only. Add later if needed.

 ### Scheduled task

@@ -1,143 +0,0 @@
-# Resilient Library Deletion Design
-
-## Goal
-
-Make `delete_library` survive concurrent database writers and large libraries. Today it deletes an entire library inside a single multi-minute transaction; on a large library this deadlocks against ordinary background writes and rolls back, making zero progress. Rewrite the deletion to run in small, autocommitted batches with per-batch deadlock retry, so it completes reliably, holds only short locks, and resumes cleanly if interrupted.
-
-## Background
-
-A `delete_library` admin job repeatedly failed with:
-
-```
-deleting orphaned items: ERROR: deadlock detected (SQLSTATE 40P01)
-```
-
-Diagnosis on a library of ~249K items / ~339K media files:
-
- The whole deletion runs in one transaction in `FolderRepository.DeleteWithStats` (`internal/catalog/folder_repo.go`): collect orphan IDs, drop the folder (CASCADE), then `DELETE FROM media_items WHERE content_id = ANY($1)`.
- `media_items` cascades to 15 child tables, so a bulk delete holds a very large lock set for minutes.
- The Postgres deadlock log shows the cycle: the delete cascade into `media_item_provider_ids` versus a concurrent `INSERT INTO media_item_provider_ids` from a routine background task. Each ~7-minute attempt was guaranteed to overlap an ordinary write and lose.
- Because it is one transaction, every failure rolls back completely: no progress, not resumable.
-
-The fix targets the deletion mechanism only. Coordinating or pausing background writers is explicitly out of scope (see Out of Scope) — a batched, retrying delete is robust against *any* concurrent writer, not just today's tasks.
-
-## Approach
-
-Replace the single transaction with a sequence of phases. Each phase deletes in bounded batches, and each batch is one autocommit statement wrapped in a deadlock-retry helper. Short lock windows make deadlocks rare; when one occurs, only that small batch retries.
-
-Scope of the rewrite:
-
- Rewrite `FolderRepository.DeleteWithStats` in `internal/catalog/folder_repo.go`.
- Add an unexported `retryOnDeadlock` helper in the `catalog` package.
- `FolderRepository.Delete` (thin wrapper), the `DeleteFolderStats` struct, and the `delete_library` executor in `internal/adminjob/library_delete.go` keep their current signatures and behavior. S3 image-cleanup queueing and generated-home-section cleanup are untouched.
-
-## Deletion phases
-
-`DeleteWithStats(ctx, id, progress)` performs, in order:
-
-### Phase 0 — preflight (reads only)
-
- Load the folder name; return `ErrFolderNotFound` if the row is gone.
- `COUNT` media files (`WHERE media_folder_id = $1`), item links (`WHERE media_folder_id = $1`), and orphans, to populate the result payload and the progress denominator.
-
-### Phase 1 — orphaned `media_items` (batched loop)
-
-Repeat until no rows are returned:
-
-```sql
-SELECT mil.content_id
-FROM media_item_libraries mil
-WHERE mil.media_folder_id = $1
-  AND NOT EXISTS (
-    SELECT 1 FROM media_item_libraries other
-    WHERE other.content_id = mil.content_id
-      AND other.media_folder_id <> $1
-  )
-LIMIT $2          -- orphanDeleteBatch
-```
-
-For each returned batch: collect S3 image dirs for those IDs (existing `collectImageDirs`, accumulated into a deduped set), then
-
-```sql
-DELETE FROM media_items WHERE content_id = ANY($1)
-```
-
-The FK cascade removes each item's `media_item_libraries` (including this folder's), `media_item_provider_ids`, episodes, seasons, embeddings, and the rest of the 15 child tables. Deleting orphan items first also clears their junction rows, so the next iteration's detection query naturally advances. Orphan detection must run before Phase 3 touches shared junctions, so the "only in this folder" test stays valid.
-
-### Phase 2 — folder `media_files` (batched loop)
-
-`media_files` is folder-tied (`media_folder_id` FK, `ON DELETE CASCADE`), not item-tied, so it is deleted by folder. Repeat until a batch deletes fewer than the batch size:
-
-```sql
-DELETE FROM media_files
-WHERE id IN (
-  SELECT id FROM media_files WHERE media_folder_id = $1 LIMIT $2  -- folderChildDeleteBatch
-)
-```
-
-### Phase 3 — remaining shared-item junctions (batched loop)
-
-After Phase 1, the only `media_item_libraries` rows left for this folder belong to items that also live in other folders. Delete them in batches (dropping the membership only, never the shared item):
-
-```sql
-DELETE FROM media_item_libraries
-WHERE ctid IN (
-  SELECT ctid FROM media_item_libraries WHERE media_folder_id = $1 LIMIT $2  -- folderChildDeleteBatch
-)
-```
-
-### Phase 4 — folder row
-
-```sql
-DELETE FROM media_folders WHERE id = $1
-```
-
-Now lightweight. Tolerates 0 rows affected (a resumed re-run may already have removed it) — it does not re-raise `ErrFolderNotFound` here. The folder row is deleted **last**, so a partial deletion leaves the library present-but-disabled and a re-run continues.
-
-## Deadlock-retry helper
-
-New unexported helper in the `catalog` package:
-
-```go
-func retryOnDeadlock(ctx context.Context, op func() error) error
-```
-
- Retries when the error is a `*pgconn.PgError` with code `40P01` (deadlock) or `40001` (serialization failure).
- Up to 5 attempts, exponential backoff starting at 50ms, doubling each retry.
- Honors `ctx` cancellation between attempts (returns `ctx.Err()`).
- Any non-retryable error returns immediately; the final retryable error is returned after the cap.
-
-Every batch statement runs through `retryOnDeadlock`. It has a single caller today, so it stays package-local; it can be promoted to a shared DB utility if a second caller appears.
-
-## Batch sizes
-
-Named constants in `internal/catalog/folder_repo.go`, tunable:
-
- `orphanDeleteBatch = 1000` — small, because each `media_items` row cascades across 15 tables.
- `folderChildDeleteBatch = 5000` — for the lighter folder-scoped `media_files` and junction deletes.
-
-## Transaction model, stats, progress
-
- No surrounding transaction. Each batch is a single `pool.Exec` (its own implicit transaction), mirroring the existing batched-cleanup pattern in `internal/opslog/cleanup.go`. This is the core change that eliminates the multi-minute lock window.
- Stats: `MediaFiles` and `MediaItemLinks` come from the Phase 0 counts; `OrphanedItems` accumulates across Phase 1 batches; `OrphanedImageDirs` is the accumulated deduped dir set. Image-dir volume for the affected workloads is modest; the deduped set is the bounded-memory point of note.
- Progress: the callback reports orphan items processed against the Phase 0 orphan total, plus phase-transition messages. The admin-job runner's existing 10s heartbeat keeps the job alive across the drain.
-
-## Error handling & resumability
-
- Because batches autocommit, a failure or cancellation persists partial progress. There is no rollback of hundreds of thousands of rows and no long lock hold.
- The job is resumable by re-running it: the folder still exists (deleted last), and Phase 1 re-detects whatever orphans remain.
- New items inserted concurrently during deletion are picked up by the loop's re-detection.
-
-## Testing
-
-The `catalog` package uses pure-Go unit tests; there is no Postgres integration harness, so tests avoid a live database.
-
- **`retryOnDeadlock` unit test:** a fake `op` returns a `*pgconn.PgError{Code: "40P01"}` N times then `nil` — assert it retries, respects the attempt cap, backs off, and returns immediately on a non-retryable error; a separate case asserts `ctx` cancellation stops retries.
- **Batch-loop unit test:** extract the "loop until a batch is under the batch size" iteration behind a small injected exec function so the looping/chunking logic is testable without Postgres.
- **Integration verification on dev:** deploy and re-trigger the deletion against the real stuck library; confirm it drains to completion via application logs and database row counts. This is the integration test, given the absence of a catalog DB harness. (Commands assume the repository root is the cwd and follow the deployment-debugging runbook.)
-
-## Out of scope
-
- Pausing or coordinating background writers (e.g., having metadata/scan tasks skip disabled or pending-deletion libraries). The batched, retrying delete is robust against any concurrent writer; writer coordination is a separate potential improvement.
- Changing the admin-job runner, the executor's image-cleanup queueing, or home-section cleanup.
- Schema or FK changes.
@@ -1,141 +0,0 @@
-# Calendar Presets & Personalized Default — Design
-
- **Date:** 2026-05-29
- **Status:** Approved (design); ready for implementation planning
- **Scope:** `silo-server` (Go backend + web admin UI). Client follow-ups in `silo-android` / `silo-apple` are additive and optional.
- **Note:** All paths are repository-relative. Commands assume the repository root is the cwd.
-
-## Problem
-
-The calendar works but is not practical. It defaults to *every* upcoming airing in the catalog, so it is noisy and undifferentiated — the user has to mentally filter out shows they don't care about. We want a Simkl-style preset switcher with a personalized default, powered by the server's real watch data rather than a manually curated list.
-
-## Goals
-
- Default the calendar to a personalized **Following** view (shows the profile actually engages with).
- Offer a small set of presets, including a **server-wide** popularity view and an **external trending** view.
- Keep it cheap under load (hundreds of concurrent users): presets must **filter, not compute**.
- Make "what do I still need to watch this week" visible via a watched overlay.
- Preserve backward compatibility for existing clients.
-
-## Non-Goals
-
- No cross-user caching of the windowed airing query yet (phased — add only if metrics show strain).
- No pulling in external content that isn't in the library (e.g. a followed show whose next season hasn't been added). The calendar stays catalog-scoped.
- No change to the week-view layout, timezone handling, or event ordering (recently tuned; left intact).
- No region/country or "For Kids" presets (considered and cut).
-
-## Presets
-
-The selector replaces today's `All / Favorites / Watchlist` toggles.
-
-| Preset | Shows | Source |
-|---|---|---|
-| **Following** *(default)* | Upcoming airings for series the profile has watched, favorited, or watchlisted | per-profile: `user_favorites` ∪ `user_watchlist` ∪ watched-series rollup |
-| **Popular here** | Airings for what is most-watched server-wide | cached `recommendation_cache` (`RecTypePopular`, global key) |
-| **Trending** | Airings for externally-trending shows that exist in the library | `trending_discover_snapshots` |
-| **Everything** | All catalog airings (today's behavior) | no restriction |
-
-Per-profile vs server-wide is split cleanly across two presets: **Following** is personal (this profile), **Popular here** is the server-wide aggregate.
-
-## Core principle: filter, don't compute
-
-Every preset resolves to **the windowed airing candidate list ∩ a small id-set**. No preset triggers a fresh aggregation at request time.
-
-1. **Step 1 — windowed candidate fetch** (unchanged from today): the 3-branch UNION in `internal/catalog/calendar_repo.go` over movies/episodes/season-premieres, scoped only by library access + content rating, across the ±2-day-padded window. Its result depends only on the access signature, not on viewer identity, so it remains cacheable across users later.
-2. **Step 2 — intersect with one id-set**, chosen by preset:
-   - **Following** → resolve the profile's followed id-set once per request, then filter `itemIDExpr = ANY($set)`.
-   - **Popular / Trending** → read the already-cached global id-set and intersect.
-   - **Everything** → no restriction.
-3. **Step 3 — group by day, sort by viewer-local wall-clock time, respond** (unchanged).
-
-The only heavy SQL is Step 1, which already runs today for every calendar load. Presets add a bounded id-set intersection, never a new aggregation.
-
-### Unify the filter mechanism
-
-All personal/preset filters resolve to "an id-set, then `itemIDExpr = ANY($set)`". This replaces the special-cased favorites/watchlist `EXISTS` subqueries in `appendPersonalFilterClause` with a single code path (favorites and watchlist become id-sets resolved from their tables — they are subsets of Following). One mechanism is easier to reason about and removes duplicated clause-building.
-
-`itemIDExpr` continues to be `mi.content_id` for movies and `e.series_id` / `s.series_id` for episodes / season premieres, so a watched/favorited **movie** matches by its own content_id while a followed **series** matches by series id.
-
-### Following id-set
-
-Resolved per request as the DISTINCT union of:
-
- `SELECT media_item_id FROM user_favorites WHERE user_id = $u AND profile_id = $p`
- `SELECT media_item_id FROM user_watchlist WHERE user_id = $u AND profile_id = $p`
- `SELECT DISTINCT COALESCE(e.series_id, wp.media_item_id) FROM user_watch_progress wp LEFT JOIN episodes e ON e.content_id = wp.media_item_id WHERE wp.user_id = $u AND wp.profile_id = $p`
-
-"Engaged" = the presence of a `user_watch_progress` row (you've started it); no completion threshold required for Following. The rollup mirrors the established pattern in `GetPopularItems` (`internal/recommendations/repo.go`) — reuse that rollup expression rather than duplicate it.
-
-The candidate list (Step 1) is small (one week of airings), so intersecting against a bounded array is cheap. Caveat: a pathologically large followed-set (a profile that has watched thousands of distinct series) makes the array large; if that ever shows up as hot, switch the Following preset to correlated `EXISTS` against the user's tables. Not building that now.
-
-### Popular / Trending id-sets
-
- **Popular**: `GetRecommendationCache(ctx, GlobalCacheUserID, GlobalCacheProfileID, RecTypePopular, "")` → `[]ScoredItem`; use `MediaItemID` values (already series-level via the `GetPopularItems` rollup). Refreshed by the recommendations worker on a TTL; readers never aggregate live.
- **Trending**: `TrendingSnapshotRepository.Get(ctx, source, window)` → `TrendingSnapshot.ContentIDs` (pre-resolved to catalog content_ids, viewer-agnostic). The calendar reads the canonical default snapshot (`tmdb` / `week`). Unioning multiple sources/windows is possible but out of scope.
-
-**Access is preserved automatically:** Popular/Trending id-sets are viewer-agnostic and may include items a given profile cannot access. Because we intersect them with the access-scoped Step-1 candidates (library scoping + `MaxContentRating` already applied there), inaccessible items drop out naturally. No extra access check needed on the id-sets.
-
-**Cold/empty cache:** if the Popular cache or Trending snapshot is empty (fresh server, worker hasn't run, provider unconfigured), the id-set is empty and the preset returns no rows. This must render the empty state, not an error.
-
-## Watched overlay
-
-After Step 1, decorate the windowed events with per-profile watched status:
-
- One bounded lookup: `SELECT media_item_id FROM user_watch_progress WHERE user_id = $u AND profile_id = $p AND completed = true AND media_item_id = ANY($episodeContentIds)` over the window's episode/movie content_ids.
- Watched items render dimmed + ✓. This is a per-profile overlay applied after Step 1 (like the Following filter), so it does not affect the shareability of the Step-1 candidate set.
- Premiere / finale / new-season badges extend the existing `buildBadges` logic in `internal/api/handlers/calendar.go`.
-
-## UI / UX
-
- **Selector** (`web/src/pages/Calendar.tsx`): segmented pills on desktop, collapsing to a dropdown on narrow viewports — the same responsive swap the week navigator already uses. The library picker stays beside it. Both presentations bind to one selected-preset state.
- **Empty state**: when **Following** has no upcoming airings (new or sparse profile), show a nudge with quick switches to Popular / Trending / Everything instead of a blank week.
- **Persistence**: remember the profile's last-chosen preset in `localStorage` (keyed by profile id) so the calendar reopens where the user left it. Server-side profile preference is a possible future enhancement.
- **Card cues** (`web/src/components/calendar/CalendarEventCard.tsx`, `web/src/lib/upcomingEventPresentation.ts`): badges + watched overlay as above.
-
-## API contract
-
- Extend `/calendar`'s `filter` parameter to accept `following | popular | trending | everything`.
- **Keep `all | favorites | watchlist` valid** so existing `silo-android` / `silo-apple` clients keep working unchanged. `all` and `everything` are equivalent. This is purely additive.
- Add an additive `watched: bool` field (and any new badge string) to each event item. Older clients ignore unknown fields.
- Default when `filter` is omitted: today it is `all`. The **web client** will request `following` explicitly; the server default stays `all` to avoid changing behavior for existing API consumers. (Default-view personalization is a client choice, not a server-contract change.)
- **Profile requirement:** the `/calendar` route already runs behind `RequireProfile`, so a profile is always present. `following` (and legacy `favorites` / `watchlist`) plus the watched overlay are per-profile and resolve against it; `popular` / `trending` / `everything` / `all` are profile-agnostic and ignore it.
-
-### Multi-repo coordination (per CLAUDE.md)
-
- `silo-android` / `silo-apple`: may adopt the new presets and the watched cue as independent follow-ups. Nothing here forces a lockstep change because old filter values and response shape remain valid.
-
-## Implementation surface
-
-Backend:
- `internal/catalog/calendar_repo.go` — add an id-set restriction to `CalendarFilter`; generalize `appendPersonalFilterClause` into a single `ANY($set)` path; keep library/rating clauses intact.
- A followed-id-set resolver, `ListFollowedSeriesIDs(ctx, userID, profileID)`, placed in the package that owns the favorites/watchlist/episode join; reuse the `GetPopularItems` rollup expression.
- `internal/api/handlers/calendar.go` — validate the expanded `filter` set; orchestrate preset → id-set resolution (Following resolver, Popular cache read, Trending snapshot read); apply the watched overlay; extend `buildBadges`.
-
-Frontend:
- `web/src/pages/Calendar.tsx` — responsive selector + preset persistence + empty state.
- `web/src/hooks/queries/calendar.ts` — new `filter` values; `watched` field on the event type.
- `web/src/components/calendar/CalendarEventCard.tsx` — watched overlay + badge rendering.
- `web/src/lib/upcomingEventPresentation.ts` — badge/treatment helpers.
-
-## Edge cases
-
- Cold/empty Popular cache or Trending snapshot → empty preset → empty state, never an error.
- Profile with no follows → Following empty → empty state with preset nudges.
- Large followed-set → bounded array today; correlated-`EXISTS` fallback noted for later.
- Movie vs episode/season id matching (`content_id` vs `series_id`) handled by the existing `itemIDExpr` selection per branch.
- Specials (`season_number = 0`) remain excluded.
- Access control (`MaxContentRating`, library scoping, disabled libraries) still enforced for every preset via Step 1; viewer-agnostic id-sets cannot leak inaccessible items because of the intersection.
- Backward-compat filter values (`all | favorites | watchlist`) still resolve through the unified id-set path with identical results.
-
-## Testing strategy
-
- **Repo** (`internal/catalog/calendar_repo_test.go`): each preset's id-set filter (following / popular / trending / everything), empty id-set → zero rows, access + rating enforcement preserved across presets, movie-by-content_id vs series-by-series_id matching, legacy favorites/watchlist parity.
- **Handler** (`internal/api/handlers/calendar_test.go`): filter validation accepts new + legacy values; Popular/Trending cold cache degrades to empty gracefully; `watched` field populated correctly; watched lookup bounded to the window.
- **Frontend**: selector responsive swap (pills ↔ dropdown), preset persistence across reloads, watched overlay + badge rendering, Following empty state.
-
-## Future work
-
- Cross-user cache of the Step-1 windowed candidate set keyed by (window, access-signature), if load metrics justify it.
- External enrichment of followed shows whose next season is not yet in the library.
- Server-side persisted preset preference per profile.
- Optional union of multiple Trending sources/windows.
@@ -1,208 +0,0 @@
-# Trending Discover — Persistent Snapshot Design
-
-Status: Approved (design)
-Date: 2026-05-29
-
-Commands assume the repository root is the cwd.
-
-## Problem
-
-The `trending_discover` home section pulls global trending (TMDB or Trakt),
-matches it to titles in the viewer's libraries, and renders the result. Today
-the external fetch + external-ID resolution are memoised in an **in-process
-map** (`editorialCandidateCache`) keyed by `source|window|fetchLimit` with a
-1-hour TTL and a `singleflight` group to collapse concurrent misses
-(`internal/sections/fetcher.go`, `loadTrendingDiscoverContentIDs`).
-
-That cache has three weaknesses, two of which we explicitly want to fix:
-
-1. **No resilience to upstream failure.** At TTL expiry a request still blocks
-   on the TMDB/Trakt call, and a slow or down provider degrades the home page.
-   There is no concept of "serve the last good list."
-2. **No observability.** Nothing records when trending last refreshed, whether
-   it succeeded, or how many trending titles matched the catalog.
-3. (Secondary) It is per-process and volatile — lost on restart, and each
-   server instance fetches independently.
-
-## Goals
-
- Reads of the trending section **never call the upstream provider** and never
-  block on it. They serve a persisted, last-good list.
- A persisted, inspectable record with refresh history (the same "synced
-  record" shape used by library collections).
-
-## Non-goals
-
- Reusing the library-collection machinery. `library_collections.library_id` is
-  `NOT NULL` (collections are library-scoped); trending is deliberately
-  library-agnostic and appears once. Making collections library-agnostic is a
-  large, separate change and is out of scope.
- An admin UI for the snapshot. The persisted columns make this possible later,
-  but it is not part of this work.
- A shared/distributed cache (Redis). The DB is the single source of truth.
-
-## Approach
-
-Replace the lazy in-process cache with a **background-refreshed persistent
-snapshot**. A scheduled task refreshes the trending list on an interval; the
-read path only ever reads the persisted snapshot. This mirrors the
-collection-sync *pattern* (`CollectionSyncScheduler` + `SyncCollectionsTask`)
-without reusing its library-scoped storage.
-
-The change cleanly separates **read** from **refresh**:
-
- The refresh path owns the upstream call and external-ID resolution.
- The read path owns only a primary-key snapshot lookup plus the existing
-  per-viewer access filtering.
-
-## Data model
-
-New migration `167_trending_discover_snapshots`. (Originally numbered 166, but
-the shared dev DB had already recorded version 166 from another branch's
-`166_trending_blend_collection_type`; the migration runner dedupes by integer
-version, so 166 was silently skipped. Renumbered to 167, the next free version.)
-
-```
-trending_discover_snapshots
-  source          text         NOT NULL          -- 'tmdb' | 'trakt'
-  window          text         NOT NULL          -- 'day' | 'week' (trakt canonicalized to 'week')
-  content_ids     text[]       NOT NULL DEFAULT '{}'  -- ordered, resolved to library catalog, capped at 200
-  entry_count     int          NOT NULL DEFAULT 0     -- raw provider entries fetched (matched-vs-trending observability)
-  refreshed_at    timestamptz                     -- last successful refresh
-  last_attempt_at timestamptz
-  last_status     text                            -- 'ok' | 'empty' | 'error'
-  last_error      text
-  PRIMARY KEY (source, window)
-```
-
-Notes:
-
- One row per canonical `(source, window)` — at most a handful of rows.
- `content_ids` is catalog-matched but **viewer-agnostic**, exactly like the
-  value the current cache holds. Per-viewer access filtering still happens at
-  read time in `fetchItemsByContentIDs`, so a single row serves all viewers.
- The list is stored at the over-fetch cap (200). The read path truncates to the
-  section's `ItemLimit`, decoupling the snapshot from per-section limits (the old
-  `fetchLimit` cache-key dimension goes away).
- **Reliability invariant:** a failed refresh updates `last_attempt_at`,
-  `last_status`, and `last_error` but **never clears `content_ids`**. The last
-  good list keeps serving through an upstream outage.
-
-The paired `.down.sql` drops the table.
-
-## Components
-
-All new server code lives in `internal/`.
-
-### `TrendingSnapshotRepository` (new, `internal/sections/`)
-
-Thin repository over the new table:
-
- `Get(ctx, source, window) (TrendingSnapshot, error)` — PK lookup.
- `Upsert(ctx, snapshot) error` — insert/update on `(source, window)`.
- `ListAll(ctx) ([]TrendingSnapshot, error)` — for future admin/inspection use
-  and tests.
-
-`Upsert` distinguishes a successful refresh (writes `content_ids`,
-`refreshed_at`, `entry_count`, `last_status='ok'|'empty'`) from a failed one
-(touches only `last_attempt_at`/`last_status='error'`/`last_error`, leaving
-`content_ids` intact).
-
-### `TrendingRefresher` (new, `internal/sections/trending_refresher.go`)
-
-Owns the upstream call. Holds `TMDBTrending`, `TraktTrending`, `ItemRepo`, the
-section repository (to enumerate used combos), and the snapshot repository. The
-existing `fetchTrendingDiscoverEntries` and `resolveTrendingDiscoverIDs` logic
-**moves here** from `fetcher.go`.
-
-`RunOnce(ctx) (json.RawMessage, error)`:
-
-1. Enumerate the distinct canonical `(source, window)` pairs from **enabled**
-   `trending_discover` sections across all scopes (parse each section's
-   `TrendingDiscoverParams`, apply the same source/window normalization the
-   section uses, collapse Trakt to `week`).
-2. For each pair: fetch the cap-200 list from the provider, resolve external IDs
-   to library content IDs, and `Upsert`.
-3. Return a JSON summary (e.g. `{combos, refreshed, empty, failed}`), mirroring
-   `CollectionSyncResult`.
-
-No used combos → no upstream calls (a dormant feature costs nothing). A
-configured-but-empty provider yields `last_status='empty'` (no error noise). A
-per-pair failure is recorded and does not abort the other pairs.
-
-### `RefreshTrendingDiscoverTask` (new, `internal/taskmanager/tasks/`)
-
-Mirrors `SyncCollectionsTask`: delegates to `TrendingRefresher.RunOnce` and
-reports progress/result data. Default trigger: hourly interval (matches the
-recipe's `DefaultCacheTTL` of 1h), plus a one-shot run at startup so the first
-snapshot lands quickly rather than after a full interval.
-
-### `Fetcher` (modified, `internal/sections/fetcher.go`)
-
- `loadTrendingDiscoverContentIDs` now reads the snapshot row via the snapshot
-  repository and returns its `content_ids`. It drops the upstream fetch, the
-  `singleflight` group, and the `editorialCandidateCache` usage **for trending**
-  (the editorial-candidate cache remains for the editorial sections that still
-  use it).
- `fetchTrendingDiscover` keeps its read-time responsibilities: access
-  filtering, re-ordering to trending rank, truncation to `ItemLimit`. It no
-  longer computes a `fetchLimit` for the read path.
- The `TMDBTrending`, `TraktTrending`, and trending-only use of `ItemRepo`
-  migrate out of the read path into the refresher. The fetcher gains the
-  snapshot repository dependency.
-
-### Wiring (`cmd/silo/main.go`, `internal/api/router.go`)
-
- Construct `TrendingSnapshotRepository` and `TrendingRefresher` (wired with the
-  TMDB/Trakt fetchers, `ItemRepo`, section repo, snapshot repo).
- Register `RefreshTrendingDiscoverTask` alongside the other task registrations.
- Hand the snapshot repository to the section `Fetcher`; move the upstream
-  fetchers from the fetcher wiring to the refresher wiring.
-
-## Data flow
-
-**Refresh (background, hourly + startup):**
-task → `Refresher.RunOnce` → enumerate distinct canonical `(source, window)`
-from enabled `trending_discover` sections → per pair: fetch cap-200 → resolve
-external IDs → `Upsert` snapshot.
-
-**Read (per home render):**
-`fetchTrendingDiscover` → `loadTrendingDiscoverContentIDs` reads the snapshot
-row → `fetchItemsByContentIDs` applies the viewer's access filter → re-order to
-trending rank → truncate to `ItemLimit`. No upstream call. A single PK lookup on
-a ≤6-row table — negligible next to the queries `FetchAll` already runs, so no
-in-process read cache is added (it would re-muddy the single-source-of-truth and
-is premature).
-
-## Edge behavior
-
- **Before first sync:** snapshot absent → section renders empty (no blocking,
-  no upstream call). The startup task run closes this gap to roughly one fetch
-  duration.
- **Provider unconfigured but a section exists:** `last_status='empty'`, no
-  error.
- **Upstream failure on a pair that already has a snapshot:** prior
-  `content_ids` keep serving; only the attempt/status/error columns update.
- **Trakt `day` vs `week`:** collapse to a single `week` row (Trakt ignores the
-  window).
-
-## Testing
-
- **Repository round-trip:** upsert then get; `content_ids` ordering preserved;
-  success vs failure upsert paths.
- **Refresher `RunOnce`:** fake `TMDBTrending`/`TraktTrending`, fake section
-  enumerator, in-memory `ItemRepo`. Assert ordered IDs upserted; `ok`/`empty`/
-  `error` transitions; and the reliability invariant — a failed refresh
-  preserves prior `content_ids`.
- **Read path:** inject nil upstream fetchers into the fetcher and assert the
-  trending read still works from the snapshot (proves reads never call upstream).
- **Canonicalization:** Trakt `day` and `week` resolve to one row.
-
-## Risks / follow-ups
-
- The data captured (`refreshed_at`, `last_status`, `last_error`, `entry_count`)
-  enables a future admin/inspection surface; not built here.
- If multiple sections request very different `ItemLimit`s, all share the cap-200
-  list and truncate — intended, and strictly more data than the old per-limit
-  cache held.
-```
@@ -1,353 +0,0 @@
-# Multi-Instance Sonarr/Radarr Routing for Requests (Seerr-style)
-
-**Status:** Design approved, ready for implementation plan
-**Date:** 2026-06-01
-**Area:** `internal/requests`, `migrations/`, `web/src` (admin settings + request queue)
-
-## Summary
-
-Silo's request system today fulfills every approved request through a single
-Radarr (movies) or single Sonarr (series) instance, at whatever quality that
-one instance's profile is configured for. There is no 4K concept, no anime
-handling, and exactly one instance per kind (`request_integrations.kind` is the
-primary key).
-
-This work replicates Seerr's Sonarr/Radarr management model *inside* Silo's own
-request system (no external Seerr dependency):
-
- **Many instances per kind** — N Radarr and N Sonarr servers, each with its own
-  connection, root folder, quality profile, and tags.
- **Default HD + Default 4K routing** — one HD-default and one 4K-default
-  instance per kind; requests route to the matching default(s).
- **Per-server anime overrides** (Overseerr-style) — each instance carries an
-  optional anime profile / root folder / tags applied when a title is detected
-  as anime.
- **Entitlement-driven dual-quality fan-out** — a single user request can be
-  fulfilled in **both** 1080p and 2160p when the requester's `MaxPlaybackQuality`
-  allows 4K, or when an admin global toggle forces it for everyone.
-
-The end-user request action is unchanged: quality is derived from the user's
-existing entitlement, not a per-request choice.
-
-## Goals
-
- Support multiple Radarr/Sonarr instances per kind.
- Route by quality (HD vs 4K) to per-kind default instances.
- Fan a single request out to both 1080p and 2160p targets based on the
-  requester's `MaxPlaybackQuality` entitlement, with an admin override that
-  forces dual-quality regardless of role.
- Apply per-instance anime overrides using Seerr-exact anime detection.
- Keep the request lifecycle (quotas, approval, reconcile) coherent under
-  one-to-many fulfillment.
-
-## Non-Goals
-
- No integration *with* a Seerr instance (an earlier idea, dropped). Silo
-  remains the system of record.
- No per-request manual server/profile picker (Overseerr's advanced UI). Routing
-  is automatic from defaults + entitlement.
- No separate 1080p/4K *availability* tracking. The pre-request presence check
-  stays binary ("is this title in the Silo library at all").
- No admin-configurable anime keyword list (the heuristic is isolated so one can
-  be added later).
- No dedicated-anime-instance flag — anime is handled by per-instance overrides
-  (decided during design).
-
-## Background: current flow
-
-When a user requests a movie today (`internal/requests/service.go`):
-
-1. **Browse/discover** via TMDB; each result carries a `RequestState`.
-2. `CreateRequest` validates: requests enabled, not already available
-   (presence), not already actively requested (dedup by `tmdb_id`), computes the
-   requester's `EffectivePolicy` (quota, blocked, auto-approve), enforces quota.
-3. Auto-approve users with a configured integration → row created `approved`,
-   else `pending` for the admin queue.
-4. `submitApprovedRequest` → `integrationForMediaType(mediaType)` finds the
-   single instance by kind → `radarr.Client.SubmitMovie` POSTs to Radarr using
-   that instance's root folder / quality profile / tags → request goes `queued`.
-5. `ReconcileRequests` polls the instance: `queued → downloading → completed`
-   (or `failed`).
-
-The single insertion point that changes is step 4's instance selection.
-
-## Design
-
-### 1. Data model
-
-**`request_integrations` — reworked from one-row-per-kind to many instances:**
-
-| column | purpose |
-|---|---|
-| `id` (text PK, via `idgen`) | replaces `kind` as PK |
-| `kind` (text, `radarr`\|`sonarr`) | now a plain column, keeps its CHECK |
-| `name` (text) | admin-facing label |
-| `enabled` (bool) | |
-| `base_url`, `api_key_ref` | connection; API key stays a Fernet secret ref, never plaintext |
-| `root_folder`, `quality_profile_id`, `tags[]` | standard (non-anime) defaults |
-| `is_4k` (bool) | marks this as a 4K server |
-| `is_default` (bool) | the HD default for its kind |
-| `is_default_4k` (bool) | the 4K default for its kind |
-| `anime_enabled` (bool) | apply anime overrides on this instance |
-| `anime_quality_profile_id`, `anime_root_folder`, `anime_tags[]` | anime overrides |
-| `options` (jsonb) | kind-specific extras (Radarr min-availability, Sonarr season-folders/series-type) |
-| `last_check_*`, `created_at`, `updated_at` | unchanged |
-
-**Invariants** (partial unique indexes + service validation):
-
- At most one `is_default` per kind; at most one `is_default_4k` per kind.
- `is_default ⇒ NOT is_4k` and `is_default_4k ⇒ is_4k`. The HD default is an HD
-  server; the 4K default is a 4K server. HD and 4K defaults are therefore always
-  distinct instances.
-
-**New `media_request_targets`:**
-
-| column | purpose |
-|---|---|
-| `id` (bigint identity PK) | |
-| `request_id` (text → `media_requests` ON DELETE CASCADE) | |
-| `integration_id` (text → `request_integrations` ON DELETE SET NULL) | |
-| `integration_kind` (text snapshot) | survives instance deletion for history |
-| `quality` (text, `1080p`\|`2160p`) | reuses `internal/access` presets |
-| `is_anime` (bool) | which profile set was applied |
-| `external_id`, `external_status`, `status`, `last_error` | per-target Radarr/Sonarr lifecycle |
-| `created_at`, `updated_at` | |
-| UNIQUE `(request_id, quality)` | one target per quality per request |
-
-**`media_requests` changes:** the per-fulfillment columns
-(`integration_kind`, `external_id`, `external_status`) move out to
-`media_request_targets`. Add `is_anime` (bool). The request's `status` becomes an
-**aggregate** over its targets (see §3). `idx_media_requests_active_tmdb` stays —
-dedup is still one active request per title regardless of quality, and a
-dual-quality request counts as **one** row against the user's quota.
-
-### 2. Routing engine
-
-A pure function `routeTargets(req, entitlement, settings, instances) -> []plannedTarget`
-replaces `integrationForMediaType` as the selection point in
-`submitApprovedRequest`.
-
-**Inputs:** the request (incl. detected `is_anime`), the requester's
-`MaxPlaybackQuality`, the global `force_dual_quality` setting, the configured
-instances for the kind.
-
-**Algorithm:**
-
-1. **Kind** = `movie → radarr`, `series → sonarr`.
-2. **Desired qualities:**
-   - `1080p` is always desired (baseline for everyone).
-   - Add `2160p` if `access.QualityAllowed("2160p", user.MaxPlaybackQuality)`
-     **OR** `force_dual_quality` is on (the toggle overrides role).
-3. **Pick the default instance per desired quality:** `1080p → is_default`,
-   `2160p → is_default_4k` (for that kind).
-4. **Profile selection per chosen instance:** if `req.is_anime` **and** the
-   instance has `anime_enabled` → use its anime profile / root folder / tags
-   (and, for Sonarr, `seriesType: anime`); otherwise the standard set.
-5. Emit one `plannedTarget{instance, quality, isAnime, profile, rootFolder, tags}`
-   per resolved quality.
-
-**Edge cases:**
-
- A desired quality with **no default instance assigned** is silently skipped
-  (cannot route 4K without a 4K default — matches "when both are assigned").
- **Zero** resolved targets (e.g. no HD default configured): the request stays
-  `approved` but unfulfilled, with `last_error` = "no Radarr/Sonarr instance
-  configured for this quality" so it surfaces in the admin queue.
- No dedup needed: the `is_default`/`is_default_4k` invariants guarantee HD and
-  4K defaults are distinct instances.
-
-### 3. Fulfillment & reconcile lifecycle
-
-The adapter interfaces (`SubmitMovie`/`SubmitSeries`,
-`CheckMovieStatus`/`CheckSeriesStatus`) are **unchanged** — they already take
-`(req, integration)`. We call them **once per target**, passing a *resolved*
-`Integration` whose `RootFolder`/`QualityProfileID`/`Tags` are filled from the
-standard or anime block. Radarr/Sonarr's notion of "4K" is just that instance's
-quality profile + root folder, so adapters stay quality-agnostic. (The Sonarr
-adapter additionally sets `seriesType: anime` for anime targets.)
-
-**On approval (`submitApprovedRequest`):**
-
-1. `routeTargets(...)` → planned targets.
-2. For each: insert a `media_request_targets` row, then call the matching
-   adapter with the resolved instance + decrypted key.
-3. On success → target `queued` with its `external_id`/`external_status`; on
-   error → target `failed` + `last_error`.
-4. **Recompute the request aggregate** in the same transaction as the target
-   writes.
-
-**Reconcile loop (`ReconcileRequests`):** for each candidate request, iterate its
-**non-terminal targets**, load each target's instance by `integration_id`, call
-the status adapter, update the target, then recompute the aggregate. Targets
-reconcile independently.
-
-**Aggregate recompute (single source of truth):**
-
- all targets `completed` → request `completed` (+ `completed_at`)
- any target `downloading` → `downloading`; else any `queued` → `queued`
- all targets `failed` → `outcome = failed`; **some** failed while others active
-  → request stays active, `last_error` set from the failed target(s)
-
-**Retry** is target-aware: an admin retry re-submits only the `failed` targets
-(re-routing if instance config changed), leaving healthy targets alone.
-
-### 4. Anime detection (Seerr-exact)
-
-Detection matches upstream Seerr exactly — a single TMDB keyword id, no genre or
-language fallback:
-
- `server/api/themoviedb/constants.ts`: `ANIME_KEYWORD_ID = 210024`
- `server/entity/MediaRequest.ts`: anime ⇔ `keywords.results` contains that id.
-
-Implementation:
-
- A named constant `animeKeywordID = 210024`.
- `detectAnime(detail) bool` → true iff the TMDB keyword **ids** contain
-  `210024`. Matching by id (not the name string) avoids false positives from
-  neighboring keywords like "based on anime".
- Detected once at `CreateRequest` time and stored on `media_requests.is_anime`,
-  so routing, reconcile, and retries stay consistent.
- Applies to both movies and series; ignored if no instance for that kind has
-  `anime_enabled`.
-
-**Supporting TMDB-client change:** extend `tmdb.MediaDetail` to carry keyword
-**ids** (add `append_to_response=keywords` to the detail fetch). `GetMediaDetail`
-is already called in the request path, so no extra round-trip beyond the append.
-(`OriginalLanguage` is not needed under the parity-only decision but may be
-mapped opportunistically since it is already in the response.)
-
-The heuristic is isolated in one function so an admin-configurable keyword list
-can be added later without touching routing.
-
-### 5. Admin UI
-
-`web/src/pages/admin-settings/IntegrationsSettings.tsx` and the setup wizard
-`web/src/pages/setup-wizard/steps/IntegrationsStep.tsx` move from a single
-Radarr/Sonarr form to an **instance-list manager** per kind:
-
-**Per kind — list of instance cards** (add / edit / delete):
-
- Connection: name, base URL, API key (write-only; shows "configured" once set,
-  never echoes the secret), **Test connection** → `LoadIntegrationOptions`
-  populates root-folder and quality-profile **dropdowns**.
- Standard block: root folder, quality profile, tags.
- Quality role: `is_4k` switch, **Default (HD)** toggle, **Default 4K** toggle.
-  The form enforces invariants client-side (no Default-HD on a 4K server;
-  selecting a new default clears the prior one visually); server is source of
-  truth.
- Anime block (collapsible, `anime_enabled`): anime quality profile, anime root
-  folder, anime tags — dropdowns from the same test-connection options.
-
-**Request settings panel** gains the **"Always fulfill in both 1080p and 4K"**
-toggle (`force_dual_quality`) with helper text: applies to all requests when both
-a Default HD and Default 4K instance exist, regardless of user role.
-
-**`web/src/pages/AdminRequests.tsx`** (queue): each request row expands to show
-its **targets** — quality badge (1080p/2160p), instance name, per-target status,
-and per-target **retry** on failed ones. The aggregate status stays the headline.
-
-**Setup wizard** stays minimal: add one Radarr + one Sonarr, auto-marked Default
-HD. Advanced multi-instance/4K/anime config lives in the full settings page.
-
-### 6. API contract & multi-repo coordination
-
-**End-user request flow is unchanged** — quality is derived from
-`MaxPlaybackQuality`, so the request action and payload are identical (no 4K
-toggle, no new permission).
-
-**`Request` response model** gains `is_anime` and a `targets[]` array
-(`quality`, `instance_name`, `status`, `external_status`, `last_error`); the
-top-level `integration_kind`/`external_id`/`external_status` are removed in favor
-of the aggregate `status` + `targets`.
-
- Per `CLAUDE.md`'s multi-repo rule: end-user `silo-android` / `silo-apple`
-  clients show a single aggregate status, so they likely need **no change** —
-  but this is flagged as explicit Apple/Android follow-up to verify the request
-  model tolerates the removed fields and ignores/parses the new `targets`.
-
-**Admin endpoints** change from "upsert by kind" to instance CRUD:
-
- `GET/POST/PUT/DELETE` request integrations **by `id`**; `LoadIntegrationOptions`
-  (test-connection) stays, keyed by instance.
- Default-toggle handled server-side transactionally (a new HD/4K default clears
-  the prior one for that kind).
- `request_settings` gains `force_dual_quality`.
- Admin-web-only; no mobile client surface.
-
-### 7. Migration & backfill
-
-Next migration number: **169** (`169_request_multi_instance.{up,down}.sql`).
-
-**Up:**
-
-1. `ALTER request_integrations`: add `id`, `name`, `is_4k`, `is_default`,
-   `is_default_4k`, `anime_enabled`, `anime_quality_profile_id`,
-   `anime_root_folder`, `anime_tags[]`. Backfill existing rows: `id = gen`,
-   `name = initcap(kind)`, `is_default = enabled` (the lone existing instance
-   becomes that kind's HD default), everything else default/false. Swap the PK
-   from `kind` to `id`; keep `kind` as a plain column with its CHECK.
-2. Partial unique indexes: one `is_default` per kind, one `is_default_4k` per
-   kind.
-3. `CREATE media_request_targets` (per §1).
-4. Backfill targets: for any `media_requests` row with an `external_id`, insert a
-   target `(quality='1080p', is_anime=false, integration_id = that kind's
-   instance, integration_kind, external_id, external_status, status = request's
-   current status)`. Rows never submitted get no target yet.
-5. `ALTER media_requests`: add `is_anime bool DEFAULT false`; drop
-   `integration_kind`, `external_id`, `external_status`.
-6. `idx_media_requests_active_tmdb` stays unchanged.
-
-**Down:** re-add the three columns to `media_requests` and copy back the **1080p**
-target's external fields; drop `media_request_targets`; drop `is_anime`; collapse
-`request_integrations` to `kind`-PK by keeping each kind's `is_default` instance
-and discarding extras; drop the new columns/indexes.
-
-**Caveat (explicit):** the down migration is **lossy** — rollback discards any
-additional instances (beyond one default per kind) and any 4K/anime target
-history. This is the unavoidable cost of collapsing a one-to-many back to
-one-to-one and is acceptable for a down migration.
-
-**Go-side data access** (implementation, not SQL): `Integration` struct +
-`scanIntegration` gain the new fields; the `Store` interface gains target CRUD +
-`ListInstances(kind)`; `scanRequest` drops the external fields; `UpsertIntegration`
-becomes id-based CRUD with default-toggle handling in-transaction.
-
-### 8. Testing
-
- **`routeTargets` — table-driven (core of the feature):** matrix of
-  {1080p vs 2160p entitlement} × {`force_dual_quality` on/off} × {which defaults
-  exist} × {anime vs not} → expected target set.
- **`detectAnime`:** keyword `210024` present/absent; no name-substring false
-  positives.
- **Aggregate recompute:** all-complete, partial-failure (request stays active +
-  `last_error`), all-failed (`outcome=failed`), mixed downloading/queued.
- **Repository:** target CRUD; single-default-per-kind invariant rejects a second
-  default; migration backfill yields exactly one 1080p target per previously
-  submitted request.
- **Adapter:** Sonarr `SubmitSeries` sets `seriesType=anime` only for anime
-  targets on anime-enabled instances.
- **Service:** extend `service_test.go` fakes — a 4K-entitled user's single
-  request fans out to two adapter submissions with the right resolved instances;
-  target-scoped retry re-submits only the failed target.
- **Frontend:** instance-form default-invariant enforcement; queue renders
-  per-target rows + retry.
-
-## Risks & open considerations
-
- **Reconcile cost** scales with targets, not requests (≤2× today). Bounded and
-  acceptable; the reconcile loop already batches.
- **Anime keyword imperfection** is inherited from Seerr by design (parity
-  choice). Mitigated by isolating `detectAnime` for future tuning.
- **Client model drift**: removing top-level external fields from `Request` must
-  be verified against `silo-android` / `silo-apple` deserialization before
-  release (flagged in §6).
-
-## References
-
- Seerr upstream: https://github.com/seerr-team/seerr
-  (`server/api/themoviedb/constants.ts`, `server/entity/MediaRequest.ts`)
- Overseerr anime discussions: #2876 (Sonarr for anime only), #3777 (configurable
-  series type)
- Existing code: `internal/requests/{service,repository,types,store}.go`,
-  `internal/requests/{radarr,sonarr,arrclient}`, `internal/access/quality.go`,
-  `migrations/139_media_requests.up.sql`
@@ -1,222 +0,0 @@
-# Autoscan: Polling Radarr/Sonarr to Trigger Targeted Library Scans
-
-**Status:** Design approved, ready for implementation plan
-**Date:** 2026-06-02
-**Area:** new `internal/autoscan`, `internal/taskmanager/tasks`, `migrations/`, `internal/api`, `web/src/pages/AdminRequests.tsx`
-
-## Summary
-
-Silo currently learns about new media via scheduled/manual library scans. When
-Radarr/Sonarr import a download, the new file only appears in Silo on the next
-scan. This adds an **autoscan poller**: a periodic background task that polls the
-configured Radarr/Sonarr instances for newly-imported files and enqueues
-**targeted folder scans** into Silo's existing scan queue, so requested (and
-non-requested) content shows up promptly.
-
-The design follows the established autoscan pattern — poll arr import history,
-translate the imported paths, and trigger targeted scans — but kept deliberately
-simple. That pattern is normally built to orchestrate scans across many separate
-media-server boxes, which needs a bounded fan-out guard and a retry queue. Silo
-is a single service scanning *itself*, so the cross-node fan-out machinery is
-unnecessary — imported paths become folder jobs in Silo's own worker-bounded
-`scanqueue`.
-
-## Goals
-
- Poll autoscan-enabled Radarr/Sonarr instances on an interval for import events.
- Translate arr import paths into Silo media folders and enqueue targeted scans.
- Reuse the Radarr/Sonarr instances already configured for requests
-  (`request_integrations`) — no duplicate URLs/keys.
- Coalesce bursts (a season's episodes) into minimal redundant scans.
- Admin-configurable: global enable, interval, debounce, per-instance toggle,
-  optional path rewrites, on-demand "poll now".
-
-## Non-Goals
-
- No cross-node scan fan-out or bounded-concurrency semaphore (single service;
-  the `scanqueue` workers are the bound).
- No separate retry queue (a failed source poll simply does not advance its
-  high-water mark, so the next cycle retries the window).
- No arr webhook/"Connect" push integration (polling only, as requested; webhook
-  push is a possible future add-on).
- No separate autoscan source credential store — sources are existing
-  `request_integrations`.
-
-## Background
-
- **`internal/scantrigger`** already maps a filesystem path to a Silo
-  `MediaFolder` and scan path: `Resolver.Resolve(Request{Path}) -> Target{Folder,
-  Mode, Path}` (via `LongestMatchingRoot` / `MatchFolderForPath`).
- **`internal/scanqueue`** executes scans through a worker-bounded queue:
-  `Queuer.EnqueueScan(ctx, folderID, mode, path, trigger)` /
-  `EnqueueScans(targets)`.
- **`internal/requests/arrclient`** is a thin Radarr/Sonarr HTTP client
-  (`New(baseURL, apiKey, httpClient)`, `GetJSON`, `DoJSON`) — reused for the new
-  history call.
- **`request_integrations`** holds each instance's `id`, `kind`, `base_url`, and
-  Fernet-encrypted `api_key_ref`, resolved via the same secret resolver the
-  request service uses.
- The **task manager** runs periodic tasks via the `taskmanager.Task` interface
-  with interval `DefaultTriggers()` (e.g. `ReconcileRequestsTask`).
-
-## Design
-
-### 1. Data model & config
-
-A new `internal/autoscan` package owns its own schema; `request_integrations`
-stays focused on fulfillment.
-
-**`autoscan_settings`** (singleton, mirrors `request_settings`):
-
-| column | type / default | purpose |
-|---|---|---|
-| `id` | bool PK default true, singleton CHECK | |
-| `enabled` | bool, default false | master on/off |
-| `poll_interval_minutes` | int, default 10 | poll task interval |
-| `debounce_seconds` | int, default 60 | folder re-scan suppression window |
-| `created_at`, `updated_at` | timestamptz | |
-
-**`autoscan_sources`** (one row per autoscan-enabled instance):
-
-| column | type | purpose |
-|---|---|---|
-| `integration_id` | text PK → `request_integrations(id)` ON DELETE CASCADE | the source instance |
-| `enabled` | bool, default false | per-instance autoscan toggle |
-| `path_rewrites` | jsonb, default `[]` | `[{from, to}]` prefix overrides |
-| `last_poll_at` | timestamptz, null | `history/since` high-water mark |
-| `created_at`, `updated_at` | timestamptz | |
-
-**Reused, not duplicated:** `base_url` / `api_key_ref` come from
-`request_integrations`. Debounce/suppression state lives in **Redis**
-(`autoscan:scanned:{folder_id}`, TTL = `debounce_seconds`), not Postgres.
-
-### 2. Poll cycle
-
-`autoscan.Service.PollOnce(ctx)` (invoked by the periodic task):
-
-1. Load `autoscan_settings`; if `!enabled`, return immediately (no-op).
-2. Load `autoscan_sources WHERE enabled`, joined to `request_integrations` for
-   `kind` / `base_url` / `api_key_ref`.
-3. For each source (sequential — a handful of instances):
-   1. Decrypt the API key via the secret resolver.
-   2. Record `cycleStart := now`.
-   3. `arrclient.GetJSON("/api/v3/history/since?date={last_poll_at}&eventType=downloadFolderImported")`
-      — both Radarr and Sonarr expose this. `last_poll_at` null → a sane floor
-      (do not scan all history on first enable; floor at `cycleStart`).
-   4. Extract the imported **file path** per event (Radarr: movie file path;
-      Sonarr: episode file `outputPath`); take its **parent directory**.
-   5. On success, advance that source's `last_poll_at = cycleStart`. On failure
-      (arr unreachable, decode error), log and **do not** advance — next cycle
-      retries the window.
-4. For each extracted directory: apply path rewrites (§3), resolve via
-   `scantrigger.Resolver` → `Target{Folder, Mode, Path}`. Unresolvable paths
-   (outside Silo's media folders) are logged and skipped.
-5. **Dedupe to unique folders** for this cycle; for each, check the Redis
-   suppression key — if absent, `EnqueueScan(..., trigger="autoscan")` and set
-   the key with TTL `debounce_seconds`; if present, skip (already scanned this
-   window).
-
-**Debounce rationale:** because the poller batches a whole interval of imports
-per `history/since` call, within-cycle folder dedup does most of the work. The
-Redis suppression key only prevents re-enqueuing the same folder on back-to-back
-cycles. Silo's scanner is idempotent, so a season importing across two cycles
-simply gets a second (cheap) scan that picks up the rest. This is simpler than a
-"collect-expired" debounce plus a retry queue, which the polling + idempotent
-re-scan model makes unnecessary.
-
-### 3. Path resolution & scan enqueue
-
-A small pipeline in front of the existing scan plumbing — no new scan logic:
-
-1. **Rewrite** (per source, optional): apply the first matching `path_rewrites`
-   entry as a prefix replacement (e.g. `/data/media -> /mnt/media`). No rewrites
-   → path used as-is (shared-mount common case).
-2. **Resolve** via `scantrigger.Resolver.Resolve(Request{Path: rewrittenDir})`
-   → `Target{Folder, Mode, Path}`. No matching media folder → log + skip.
-3. **Enqueue** deduped targets via `scanqueue` `EnqueueScans` with
-   `trigger="autoscan"` (attributable in scan history, flows through the same
-   worker-bounded queue).
-
-### 4. Scheduling & concurrency
-
- **`internal/taskmanager/tasks/autoscan_poll.go`** implements `taskmanager.Task`
-  (`Key: "autoscan_poll"`, name/description/category, `DefaultTriggers` = interval
-  trigger seeded from `poll_interval_minutes`). Its run body calls
-  `autoscan.Service.PollOnce(ctx)`.
- **Disabled = cheap no-op:** the task stays registered; `PollOnce` returns early
-  when `enabled` is false. Toggling autoscan never (de)registers tasks.
- **Interval changes:** updating `poll_interval_minutes` reconfigures the task's
-  interval trigger via the task manager's existing trigger-config path; if a live
-  update is unavailable it applies on next start.
- **No overlap, no semaphore:** the task manager serializes a task's executions;
-  sources are polled sequentially; scan execution is bounded by `scanqueue`. The
-  single-service simplification: no bounded-fan-out semaphore is needed.
- **Primary/integrated server only** (same as the request reconcile task), not on
-  standalone transcode/proxy worker nodes.
-
-### 5. Admin API & UI
-
-**API** (admin-gated, `/api/v1/admin/autoscan`, mirroring the request-settings
-handlers; never echoes API keys):
-
- `GET/PUT /autoscan/settings` — `{enabled, poll_interval_minutes, debounce_seconds}`
- `GET /autoscan/sources` — per autoscan-eligible instance (joined from
-  `request_integrations`): `{integration_id, name, kind, enabled, path_rewrites,
-  last_poll_at}`
- `PUT /autoscan/sources/{integration_id}` — set `{enabled, path_rewrites}`
- `POST /autoscan/trigger` — run `PollOnce` once on demand; tight per-admin rate
-  limit so it cannot hammer the arr instances
- `GET /autoscan/status` — `{enabled, per-source last_poll_at, last scan summary}`
-
-**UI:** a new **"Autoscan" tab** in `web/src/pages/AdminRequests.tsx` (alongside
-Queue / Settings / Integrations / User Overrides):
-
- Global controls: enable switch, poll interval, debounce window.
- Per-source list — one row per Radarr/Sonarr instance with an autoscan toggle,
-  an optional `from → to` path-rewrite editor, and a read-only "last polled".
- A **"Poll now"** button → `POST /autoscan/trigger`.
-
-Rate limits and admin-auth follow Silo's existing request-admin conventions.
-
-### 6. Testing
-
- **Path rewrite:** prefix replacement, first-match ordering, no-match
-  passthrough, trailing-slash handling.
- **arr history client:** table-driven `httptest` fixtures for both Radarr and
-  Sonarr import-event JSON shapes; asserts the correct file path is extracted and
-  its parent folder taken.
- **Dedupe + suppression:** many paths in one folder → one target; folder with a
-  live suppression key skipped; absent/expired key enqueues.
- **`PollOnce` (integration seam):** fakes for source store, arr history client,
-  `scantrigger.Resolver`, `scanqueue.Queuer`, Redis — asserts deduped folder
-  scans enqueued with `trigger="autoscan"`, `last_poll_at` advanced on success,
-  **not** advanced on per-source failure, clean no-op when disabled.
- **Unresolvable path:** logged + skipped, never enqueued or fatal.
- **Repository / migration:** `autoscan_settings` singleton + `autoscan_sources`
-  CRUD and the `request_integrations` join; migration applies + rolls back
-  (sidecar table, `ON DELETE CASCADE`).
- **Frontend:** Autoscan tab renders, per-source toggle / path-rewrite editor
-  round-trips, "Poll now" calls the trigger endpoint.
-
-## Risks & open considerations
-
- **First-enable floor:** `last_poll_at` null must floor at "now" (not epoch) so
-  enabling autoscan doesn't enqueue a scan for every historical import.
- **history/since shape differences:** Radarr vs Sonarr import-event payloads
-  differ; the path extraction is per-kind and covered by fixtures.
- **Path rewrites vs scantrigger roots:** if neither rewrites nor Silo's media
-  folders match the arr path, the import is silently skipped (logged) — this is
-  the expected "content outside Silo's libraries" behavior, but a misconfigured
-  rewrite will look like "autoscan does nothing"; the `last_poll_at` + status
-  endpoint and skip logs are the debugging surface.
- **Idempotent re-scan:** relies on Silo's scanner being safe to run repeatedly
-  on a folder (it is — re-scan finds new files).
-
-## References
-
- Existing Silo plumbing reused by this design: `internal/scantrigger/scantrigger.go`,
-  `internal/scanqueue/`, `internal/requests/arrclient/`,
-  `internal/taskmanager/tasks/reconcile_requests.go`
- Prior art: the general autoscan pattern (poll arr import history → translate
-  paths → trigger targeted scans). Silo's variant drops the cross-node fan-out
-  guard and retry queue, which only a multi-box orchestrator needs.
@@ -1,262 +0,0 @@
-# Autoscan as a Pluggable Scan-Source Category — Design Spec
-
-**Date:** 2026-06-02
-**Status:** Approved design, pre-implementation
-**Goal:** Turn autoscan from a Requests-coupled, arr-only feature into a standalone **Autoscan** category whose change-detection providers are out-of-process Silo plugins, with Sonarr/Radarr as the first provider.
-
-**Architecture (one sentence):** Silo's host keeps a thin, provider-agnostic engine that resolves changed paths to library folders and enqueues rescans; each *way of noticing change* (arr, later inotify/ceph) is an installable plugin that Silo pulls on a timer through a new additive `scan_source.v1` capability.
-
-**Tech stack:** Go (silo-server host + plugins), `silo-plugin-sdk` (protobuf capability contract, consumed as a tagged module), existing `internal/plugins` + `internal/pluginhost` runtime, existing `scantrigger`/`scanqueue` scan pipeline, React/TS admin UI.
-
-Commands assume the repository root is the cwd.
-
---
-
-## 1. Background & motivation
-
-The current autoscan implementation (delivered in the now-closed PR #43, still on local `main`) is in-process Go that:
-
- polls Sonarr/Radarr `/api/v3/history/since` on a host timer,
- rewrites arr-side paths to Silo paths, dedups to parent dirs,
- resolves each to a `MediaFolder` and enqueues a targeted scan,
- is configured against `request_integrations` rows (hard FK, `ON DELETE CASCADE`), living as a tab inside the **Requests** admin page.
-
-Two structural problems:
-
-1. **It is arr-only and not extensible.** Adding inotify, Ceph notifications, or any other change source means more bespoke host code.
-2. **It is subordinate to Requests.** A source cannot exist without a Requests integration row; deleting the row destroys the source.
-
-Silo already ships a full out-of-process plugin runtime (`internal/plugins`, `internal/pluginhost`): manifests, an installer, typed capability descriptors (`metadata_provider.v1`, `request_router.v1`, `media_analyzer.v1`, `scheduled_task.v1`, `event_consumer.v1`, …), a host-driven scheduled-task mechanism, and a rate-limited plugin→host event path. This design uses that runtime to make change-detection pluggable.
-
-## 2. Goals / non-goals
-
-**Goals**
-
- A new **Autoscan** admin category, independent of Requests.
- A new additive `scan_source.v1` plugin capability — **breaks no existing plugin**.
- A **client-pull** contract: Silo asks each source "what changed since `<marker>`?" on a timer.
- Sonarr/Radarr re-implemented as the first scan-source plugin; the closed PR's arr logic relocates into it.
- A provider-agnostic host engine reusable by every future scan source.
- Optional reuse of Requests' arr connection details, *or* standalone connection entry.
-
-**Non-goals (this design)**
-
- inotify / Ceph / other providers (the contract must *accommodate* them; we do not build them).
- A push (plugin-initiated) delivery mode. Pull only; push sources buffer internally and answer on pull (see §6).
- Refactoring the Requests subsystem itself.
-
-## 3. Architecture overview
-
-```
-┌──────────────────────────── Silo (host) ────────────────────────────┐
-│  Autoscan category (new; not under Requests)                         │
-│    • Sources: which scan_source plugin instance, on/off, interval    │
-│    • Connections: reuse a Requests arr server, or enter own          │
-│    • Per-source state: opaque marker, last-run status                │
-│                              │                                       │
-│                              ▼                                       │
-│  AutoscanStore — generic engine (provider-agnostic)                  │
-│    per tick, per enabled source:                                     │
-│      call plugin PollChanges(marker)                                 │
-│        → resolve each Silo-native path → MediaFolder                 │
-│        → suppress duplicates → enqueue scan (existing scanner)       │
-│        → store returned next_marker                                  │
-│                              │  scan_source.v1 (pull)                │
-└──────────────────────────────┼───────────────────────────────────────┘
-                               ▼
-              ┌──────── Sonarr/Radarr scan-source plugin ────────┐
-              │  (new installable repo, like silo-plugin-tmdb)   │
-              │  receives resolved arr address + key             │
-              │  polls /history (imports + renames)              │
-              │  returns RAW source paths + next marker          │
-              │  (host applies the source's rewrites)            │
-              └──────────────────────────────────────────────────┘
-```
-
-**Five components**
-
-1. **`scan_source.v1`** (in `silo-plugin-sdk`) — the pull contract. §5.
-2. **AutoscanStore** (host) — generic resolve→suppress→enqueue→marker engine. §7.
-3. **Connection resolution** (host) — reference-or-inline → concrete credentials. §8.
-4. **Autoscan category + data model** (host) — sources, connections, decoupled from Requests. §9.
-5. **arr scan-source plugin** (new repo) — first provider. §10.
-
-## 4. Responsibility split (the dividing line)
-
-| Concern | Owner | Rationale |
-|---|---|---|
-| Talk to arr; poll `/history`; imports + renames; bounded window; first-run | **Plugin** | Provider-specific I/O. |
-| **Path rewrites** (per-source config + application) | **Host** | _(Revised post-merge: the SDK landed host-owned rewrites.)_ The plugin returns RAW source-namespace paths in `source_paths`; the host applies each source's rewrite rules (longest-`From`-first) before resolving. Keeps every provider dumb and rewrite behavior uniform. Rewrites are edited per-source in the Autoscan UI and stored in `autoscan_sources.path_rewrites`. |
-| Resolve Silo-native path → `MediaFolder`; dedupe; **enqueue rescan** | **Host** | Touches Silo internals (scan queue, DB, library map) that plugins cannot and must not reach. |
-| Opaque per-source marker; poll interval; enabled; last-run status | **Host** | Scheduling and bookkeeping are the engine's job. |
-| Connection selection (reuse-from-Requests vs own) and credential resolution | **Host** | Only the host knows about Requests; the plugin receives resolved creds. |
-
-The plugin's responsibility ends at **"here are the changed paths, in Silo's terms."** Everything past that is the host engine, which is provider-agnostic.
-
-## 5. The `scan_source.v1` contract (centerpiece)
-
-A new, additive capability in `silo-plugin-sdk`. Existing plugins never declare it and are unaffected (§11).
-
-### Protobuf (as implemented in silo-plugin-sdk)
-
-```proto
-// scan_source.v1 — host pulls changed paths from a provider on a timer.
-service ScanSource {
-  // Host calls this on each poll tick for a configured scan_source capability.
-  rpc PollChanges(PollChangesRequest) returns (PollChangesResponse);
-}
-
-message PollChangesRequest {
-  string capability_id = 1;          // which configured scan_source instance
-  string marker        = 2;          // opaque; empty string on first run
-  ResolvedConnection connection = 3; // resolved upstream credentials (see §8)
-}
-
-// Concrete upstream credentials the host resolves and hands to the plugin each
-// poll, so the plugin stays credential-source-agnostic and stores no secrets.
-message ResolvedConnection {
-  string base_url = 1;
-  string api_key  = 2;
-}
-
-message PollChangesResponse {
-  // Absolute changed paths in the provider/source namespace (RAW — NOT yet
-  // rewritten). Files or directories. The host applies the source's rewrite
-  // rules and validates before enqueueing.
-  repeated string source_paths = 1;
-  // Opaque continuation token. Host stores verbatim and echoes it back
-  // on the next PollChanges. The plugin never assumes the host parses it.
-  string next_marker = 2;
-}
-```
-
-### Contract rules
-
- **Pull only.** The host owns the timer and calls `PollChanges`. The plugin never initiates.
- **Opaque marker.** The host stores and echoes `next_marker` without interpreting it. arr uses an RFC3339 timestamp; a future provider may use a sequence number or event id — no host change required.
- **First run.** `marker == ""` ⇒ the plugin starts from "now" (do not replay full history).
- **Idempotent, at-least-once.** The host may re-issue the same `marker` if it failed to persist `next_marker`; providers must tolerate returning overlapping paths. The host's suppression layer (§7) absorbs duplicates.
- **Error semantics.** A failed `PollChanges` (e.g. arr unreachable) ⇒ the host keeps the *old* marker and retries next tick; nothing is skipped or advanced.
- **Raw source paths.** `source_paths` are in the provider's namespace, NOT rewritten. The host applies each source's path-rewrite rules (host-owned, per-source) before resolving to a library folder.
- **Credentials per call.** The host resolves the source's connection (§8) and passes the concrete `{base_url, api_key}` in `PollChangesRequest.connection` on every poll. The plugin reads them from the request — it stores no credentials and never knows whether they came from its own config or a reused Requests link. Delivered over the local host↔plugin gRPC channel only.
-
-The capability needs **only** `PollChanges` for v1. A `TestConnection`/validate RPC is explicitly deferred (YAGNI; connection validity surfaces as a failed poll).
-
-## 6. Marker & delivery semantics
-
- One opaque marker stored per source, host-side.
- Pull-only does **not** exclude push-style providers: an inotify/Ceph plugin maintains its own internal buffer of observed changes and flushes it (and advances its marker) on each `PollChanges`. Cost: up to one poll-interval of latency. This keeps a single uniform contract.
-
-## 7. Host: AutoscanStore engine
-
-Provider-agnostic. Per enabled source, per tick:
-
-1. `paths, next := plugin.PollChanges(marker)`; on error, log + keep marker + continue.
-2. For each `dir` in `uniqueParentDirs(paths)`:
-   - `target := scantrigger.Resolve(dir)`. Unresolvable (outside Silo's media folders) ⇒ quiet skip.
-   - Suppression key `fmt.Sprintf("%d|%s", folderID, target.Path)` with debounce TTL; already-claimed ⇒ skip.
-   - Accumulate `target`; record claimed key.
-3. `scanqueue.EnqueueScans(targets)`. On failure, release claims and **do not** advance the marker.
-4. On success, persist `next_marker`.
-
-This is the salvaged core of PR #43 (`internal/autoscan/service.go` resolve/suppress/enqueue, `dedupe.go`, `suppress.go`), generalized so its input is "paths from a provider" rather than "paths from arr." Path-rewrite helpers (`rewrite.go`, `suggest.go`, `history.go`, the arr history client) leave the host and move into the plugin (§10).
-
-## 8. Host: Connections (reuse or own)
-
-A **connection** is "an arr server Silo can reach," created two ways:
-
- **Own:** name + base URL + API key, entered in the Autoscan category; the key is Fernet-encrypted at rest (same mechanism as existing service credentials — never plaintext in JSONB).
- **Linked (reuse):** a live reference to an existing Requests `request_integrations` arr server. Resolved at use-time, so edits in Requests propagate.
-
-**Resolution:** on each poll the host resolves the chosen connection (own or linked) into concrete `{base_url, api_key}` and passes them in `PollChangesRequest.connection` (§5). The plugin is credential-source-agnostic — it only ever sees resolved values, fresh each poll, so a change to a reused Requests credential propagates immediately with no re-push. This "reuse or own" behaviour is therefore free for every future provider. (Resolving per-call rather than caching in plugin config also means no decrypted secret is ever stored at rest in the plugin.)
-
-**Decoupling from Requests:** the link is **soft and optional** — `SET NULL` / surfaced-as-"needs attention", never cascading. Requests has no knowledge of Autoscan. Autoscan and Requests are peers; Autoscan merely *offers* to borrow a Requests connection.
-
-## 9. Host: Autoscan category & data model
-
-New top-level **Autoscan** admin section (its own nav entry, not a Requests tab). Manages **Connections** (§8) and **Sources**.
-
-A **source** corresponds to one configured `scan_source.v1` capability instance and carries:
-
- **Host-owned per-source config:** path rewrites (`autoscan_sources.path_rewrites`, edited in the Autoscan Sources UI) and any provider-specific settings. _(Revised post-merge: rewrites moved host-side; the plugin has no config.)_
- **Host-owned per-source state:** the chosen connection, enabled on/off, poll interval (per-source, not one global timer), the opaque marker, and last-run status/error.
-
-**Install flow + source auto-discovery (resolves §14 risk #1).** A scan-source plugin (Sonarr/Radarr, etc.) is installed through the **normal `/admin/plugins`** page — there is no separate install path; the installer doesn't special-case the capability type. Source rows are then never created by hand: the host enumerates every installed `scan_source.v1` capability (via the plugin installation store) and *seeds a disabled, connection-less row* per capability (`INSERT … ON CONFLICT (installation_id, capability_id) DO NOTHING`, never disturbing existing config). Discovery runs **both on each poll cycle AND when the Autoscan sources list is viewed** (so a freshly-installed plugin appears in Autoscan immediately, even when autoscan is disabled and nothing is polling). The operator then binds a connection and enables it. Consequently **`connection_id` is nullable**: a freshly-discovered source has none, and the engine skips any enabled source with no connection (recording a "no connection bound" status). The admin API rejects enabling a source that has no effective connection.
-
-**Per-source interval** is honoured as a floor: the global poll task runs at `default_poll_interval_seconds`, and within a cycle the engine skips a source whose `last_run_at` is newer than its own `poll_interval_seconds` (falling back to the default). A source therefore polls *at most* every N seconds, never more often than the global cadence.
-
-### Schema changes (host)
-
-Rework the PR #43 tables; **no FK into `request_integrations`**:
-
- `autoscan_connections` — `id`, `name`, `kind` (e.g. `sonarr`/`radarr`), and *either* own credentials (`base_url`, `api_key_ref` encrypted) *or* a nullable soft link `request_integration_id` (`ON DELETE SET NULL`).
- `autoscan_sources` — `id`, `(installation_id, capability_id)` (unique; the discovered identity), **nullable** `connection_id → autoscan_connections` (`ON DELETE RESTRICT`; null until the operator binds one), `enabled`, `poll_interval_seconds` (nullable; null = use default), `marker` (opaque text, nullable), `last_run_at`, `last_error`. Creation-time validity for connections (own creds OR a link) is enforced at the application layer (the DB CHECK would conflict with `ON DELETE SET NULL` on the reuse link).
- `autoscan_settings` (optional) — retain a global enable + default interval; per-source interval overrides it.
-
-A migration supersedes PR #43's `171_autoscan` schema (which is not yet upstream, so this is a forward redefinition, not a production migration of live data on `origin/main`).
-
-## 10. Plugin: Sonarr/Radarr scan-source
-
-A new installable repo structured like `silo-plugin-tmdb` (standalone Go module, `manifest.json` declaring `scan_source.v1`, gRPC `main.go`, depends on the new tagged `silo-plugin-sdk`). Receives resolved arr `{base_url, api_key}` as config. Implements `PollChanges`:
-
-1. Treat `marker` as the "since" timestamp (empty ⇒ now).
-2. Call arr `/api/v3/history/since`, capped by a bounded window (24h max-lookback floor + overlap buffer — relocated from PR #43) so a long outage cannot pull an oversized response.
-3. Extract paths: **imports** (`downloadFolderImported.importedPath`) and **renames** (`episodeFileRenamed`/`movieFileRenamed`: both new `path` and old `sourcePath`). Deletes ignored (upgrade-deletes are covered by the paired import; standalone deletes carry no path).
-4. Return `{source_paths = the RAW arr paths, next_marker = newest history timestamp}`. The plugin does NOT rewrite — the host normalizes separators and applies the source's rewrite rules. _(Revised post-merge.)_
-
-**Rewrite config + "Sync from arr":** the rewrite list and the suffix-match suggester (which matches arr root folders to Silo media folders) live in the plugin. The suggester needs Silo's media-folder list, obtained via the existing host library-listing service (`internal/pluginhost` library lister) exposed to plugins. The relocated logic is PR #43's `suggest.go`/`suggest_deps.go`/`rewrite.go`/`history.go`.
-
-## 11. Backward compatibility (hard requirement)
-
-Adding `scan_source.v1` **must not break existing plugins.** It doesn't, by construction:
-
- Capabilities are independent opt-in declarations. Each host subsystem **filters for its own type and ignores the rest** (verified: `metadata_provider.v1`, `scheduled_task.v1`, `event_consumer.v1`, … each use `if type != mine { skip }`). There is **no global allowlist that rejects unknown capability types.**
- **Additive-only rule:** the SDK change *adds* new proto messages/service + a new capability string. It never modifies the shape of an existing capability. (Mutating an existing capability is the only thing that would break plugins; we forbid it.)
- **No forced upgrades:** existing plugin repos stay pinned to their current SDK version and build unchanged. Only a plugin that *wants* to be a scan source adopts the new SDK version.
-
-## 12. Build order & repo decomposition
-
-One shared contract, three repos (+ catalog), in dependency order:
-
-1. **`silo-plugin-sdk`** (long pole): define `scan_source.v1` (proto + generated code + manifest helper + runtime server scaffold), tag a new version (e.g. `v0.5.0`). The tagged release is a hard serialization point — host and plugin cannot build against the contract until it exists.
-2. **silo-server (host)** — bump SDK dep; build AutoscanStore (generalized), the `scan_source.v1` caller (timer → `PollChanges`), connections + resolution, the Autoscan category UI, retire the in-process arr autoscan, add the reworked migration. *Parallelizable with (3) once (1) is tagged.*
-3. **arr plugin (new repo)** — depends on SDK `v0.5.0`; implement `PollChanges`, rewrites, "Sync from arr", bounded window.
-4. **`silo-plugins`** (catalog) — add the entry so the arr plugin is installable.
-
-Each repo gets its **own implementation plan** (separate `writing-plans` pass); this single spec defines the shared contract and per-side responsibilities they all build against.
-
-**Local logistics:** only `silo-server` and `silo-plugin-tmdb` are currently checked out. Implementation will require `silo-plugin-sdk` and a new arr-plugin repo (and later `silo-plugins`) available locally.
-
-## 13. Salvage map (from closed PR #43)
-
-| PR #43 code | Destination |
-|---|---|
-| arr `/history` client, imports + renames, bounded window (`history.go`) | arr plugin |
-| path rewrite apply (`rewrite.go`) + "Sync from arr" suggester (`suggest.go`, `suggest_deps.go`) | arr plugin |
-| `last_poll_at` cursor | host, generalized to opaque per-source `marker` |
-| resolve + dedupe + suppress + enqueue (`service.go`, `dedupe.go`, `suppress.go`) | host AutoscanStore (generic) |
-| `171_autoscan` schema (FK → `request_integrations`) | host, reworked: `autoscan_connections` + `autoscan_sources`, no requests FK |
-| Autoscan admin tab under Requests (`AdminRequests.tsx`) | host, as its own Autoscan category |
-
-## 14. Risks & open questions
-
-1. **Plugin multiplicity for multiple arr servers.** Does the runtime support multiple configured instances of one plugin (one per arr server), or is config per-installation only? If the latter, "two Sonarrs + one Radarr" implies either multiple installations or a plugin that manages several connections internally. *Resolve before the host/plugin plans by reading `internal/plugins` installation + capability-instance handling.*
-2. **Plugin config UI richness.** The rewrite table + a "Sync from arr" action are richer than typical key-value plugin config. Verify the plugin config-schema/admin-config UI can host a structured list and an action button; if not, design a minimal affordance (e.g. suggester runs on first configure, or a dedicated plugin HTTP route via `http_routes.v1`).
-3. **Library-folder list exposure to plugins.** Confirm the `internal/pluginhost` library lister is reachable by a `scan_source` plugin for the suggester. If not, add a host service method.
-4. **Marker persistence vs at-least-once.** Ensure marker write happens only after successful enqueue, matching PR #43's "don't advance on failure" guarantee.
-5. **Closed PR disposition.** The in-process autoscan on local `main` (34 commits) should be removed/replaced rather than shipped; sequence the host plan to retire it cleanly.
-
-## 15. Testing strategy
-
- **SDK:** proto compiles; manifest helper round-trips `scan_source.v1`; runtime scaffold serves `PollChanges`.
- **Host engine:** table-driven tests for resolve→suppress→enqueue→marker (port PR #43's `service_test.go`, generalized to a fake `ScanSource` client): dedupe, distinct-paths-same-folder, disabled no-op, poll failure keeps marker, enqueue failure releases claims + keeps marker, opaque-marker pass-through. Run in the libvips-equipped environment (host handler tests link libvips via CGO — see workspace note).
- **Connections:** resolution of own vs linked; linked falls back gracefully when the Requests row is deleted (`SET NULL`).
- **arr plugin:** history parsing (imports + renames, ignores unrelated events), rewrite application, bounded window, first-run "from now"; suffix-match suggester cases (unique/ambiguous/covered/no-op/normalization) ported from PR #43.
- **Compat:** an existing-style plugin manifest with no `scan_source.v1` is unaffected by host scan-source dispatch.
-
-## 16. Out of scope / future
-
- inotify and Ceph-notify scan-source plugins (the contract accommodates them via the buffer-and-flush pattern of §6).
- A push/event delivery mode, if pull latency ever proves insufficient.
- A `TestConnection` RPC on the capability.
- Migrating Requests onto a shared connection abstraction (today's reuse is a one-directional soft link only).
@@ -1,173 +0,0 @@
-# Autoscan: Sync Path Rewrites from Arr Root Folders
-
-**Status:** Design approved, ready for implementation plan
-**Date:** 2026-06-02
-**Area:** `internal/autoscan`, `internal/api`, `web/src/pages/AdminRequests.tsx`
-**Extends:** the autoscan feature (`docs/superpowers/specs/2026-06-02-autoscan-arr-polling-design.md`)
-
-## Summary
-
-Autoscan resolves an imported file path against Silo's media folders, but
-Radarr/Sonarr often report files under paths that differ from how Silo mounts
-the same content — so operators must hand-author per-root `path_rewrites`. For a
-multi-instance, many-root deployment this can be dozens of rows.
-
-This adds a **"Sync rewrites from arr"** convenience: for one instance, query its
-root folders, match each root to a Silo media folder by **shared trailing path
-segments**, and present the resulting `{from, to}` rewrites as a **preview** the
-admin reviews and commits. Manual rewrites remain the source of truth; sync only
-*fills the editor* — nothing persists until the admin saves.
-
-The matcher is purely structural (no assumptions about any particular path
-layout) so it helps any deployment whose arr and Silo share folder names at some
-depth, and degrades gracefully (no shared names → "unmatched" → manual entry)
-when they do not.
-
-## Goals
-
- One-click suggestion of `path_rewrites` for an instance from its arr root folders.
- Correct disambiguation when multiple Silo folders share a leaf name.
- Preview-then-commit: the admin sees proposed/unmatched/ambiguous and saves
-  through the existing per-source save. Manual rows are never removed or overwritten.
- Deployment-agnostic: no hard-coded paths; works for any structure; surfaces
-  match confidence so weak matches can be rejected.
-
-## Non-Goals
-
- No automatic/background writing of rewrites — the admin always commits.
- No new persistence path — apply is the existing `PUT /sources/{id}`.
- No case-insensitive matching (case-sensitive segments; correct on Linux). A
-  toggle can be added later if needed.
- No "sync all instances at once" — per-instance, matching the editor UI.
-
-## Design
-
-### 1. Matching function (core, pure)
-
-A single side-effect-free function in `internal/autoscan`:
-
-```go
-func suggestRewrites(arrRoots []string, siloFolderPaths []string, existing []PathRewrite) RewriteSuggestions
-```
-
-```go
-type RewriteSuggestions struct {
-    Proposed  []ProposedRewrite `json:"proposed"`
-    Unmatched []string          `json:"unmatched"`
-    Ambiguous []AmbiguousRoot   `json:"ambiguous"`
-    Covered   []string          `json:"covered"`
-}
-type ProposedRewrite struct {
-    From       string `json:"from"`         // arr root
-    To         string `json:"to"`           // matched Silo folder path
-    MatchDepth int    `json:"match_depth"`  // trailing segments shared (confidence)
-}
-type AmbiguousRoot struct {
-    Root       string   `json:"root"`
-    Candidates []string `json:"candidates"`
-}
-```
-
-**Normalization** (applied to every path before comparison): backslashes → `/`
-(reuse `normalizeSeparators`), strip a trailing `/`, collapse duplicate slashes.
-This makes any path format (POSIX, Windows, single- or many-root) comparable.
-
-**Per arr root:**
-1. **Covered-first:** if any `existing` rewrite's `From` already matches the root
-   (exact, or root starts with `From + "/"`, using the same boundary rule as
-   `applyRewrites`), classify as **Covered** and skip — so sync never re-proposes
-   what a manual or broad rule already handles.
-2. Split both the root and each Silo folder path into segments; compute the
-   **longest common trailing-segment suffix** (full-segment equality, so `4ktv7`
-   does not match `4ktv70`).
-3. Among Silo folders, take the maximum suffix length `> 0` and the folders that
-   achieve it:
-   - exactly one → **Proposed** `{From: root, To: folder, MatchDepth: n}`
-   - more than one → **Ambiguous** `{root, candidates}`
-   - zero → **Unmatched**
-
-No deployment constants appear in the function; it operates only on the string
-slices it is given.
-
-### 2. Preview endpoint & service
-
-**Endpoint:** `GET /api/v1/admin/autoscan/sources/{id}/rewrite-suggestions` →
-`RewriteSuggestions` JSON (admin-gated, like the other autoscan routes).
-
-**Service method** `Service.SuggestRewrites(ctx, integrationID) (RewriteSuggestions, error)`:
-1. `Repository.GetSource(id)` — a new single-source variant of the existing join
-   that returns `kind`/`base_url`/`api_key_ref`/`path_rewrites` even when the
-   source is disabled. Not found → `ErrIntegrationNotFound`.
-2. Decrypt the API key via the existing `SecretResolver`.
-3. `RootFolderClient.RootFolders(ctx, baseURL, apiKey)` → arr root paths.
-4. `FolderLister.ListFolderPaths(ctx)` → all Silo media-folder paths.
-5. Return `suggestRewrites(arrRoots, siloPaths, source.PathRewrites)`.
-
-**Two new narrow `Service` dependencies** (injected like `history`/`resolver`):
- `RootFolderClient.RootFolders(ctx, baseURL, apiKey string) ([]string, error)` —
-  an `arrclient`-backed impl reusing `arrclient.ListRootFolders` (returns paths only).
- `FolderLister.ListFolderPaths(ctx) ([]string, error)` — a thin adapter over
-  `catalog.FolderRepository.List()` flattening each folder's `Paths`.
-
-**Wiring:** both constructed where the autoscan handler is built in `router.go`
-(`deps.FolderRepo` already in scope; the arr client is trivial). The handler's
-service interface gains `SuggestRewrites`.
-
-**Errors:** instance not found → 404; arr unreachable / bad key → 502 with the
-arr error surfaced; Silo folder-list failure → 500.
-
-No new write path — the frontend merges `proposed` into the editor and the admin
-saves via the existing `PUT /sources/{id}`.
-
-### 3. Frontend (preview UI)
-
-In `AutoscanSourceEditor` (`web/src/pages/AdminRequests.tsx`), add a **"Sync from
-arr"** button beside Save. On click, a new hook
-(`useAutoscanRewriteSuggestions`) calls the endpoint and opens a preview panel:
-
- **Proposed** — each row: `From → To` + a **confidence badge** from `match_depth`
-  (e.g. "3 segments" strong, "1 segment — weak"), with a checkbox (default checked).
- **Unmatched** — info-only list of arr roots with no Silo match ("add manually").
- **Ambiguous** — arr root + candidate Silo paths (info-only; admin adds a manual row).
-
-**"Add selected to rewrites"** merges the checked proposals into the editor's
-existing rewrite rows, **deduped by `from`, never removing manual rows**. The
-admin then clicks the normal **Save**. New types in `web/src/api/types.ts`
-(`AutoscanRewriteSuggestions`, `ProposedRewrite`, `AmbiguousRoot`) and hook in
-`web/src/hooks/queries/useAutoscan.ts`. Reuse existing
-`Button`/`Badge`/`Dialog`/`Field` primitives.
-
-### 4. Testing
-
- **`suggestRewrites`** — table-driven, fixtures spanning layouts: multi-segment
-  match, single-segment unique, longest-suffix disambiguation (`Anime/Subs` vs
-  `Anime2/Subs`), unmatched (no shared segment), already-covered via a broad
-  prefix rule, an ambiguous tie, plus **unlike-this-deployment** cases
-  (`/data/Movies` arr vs `/library/Films` Silo → unmatched; `/srv/tv/Show` vs
-  `/tank/television/Show` → leaf match) and normalization (trailing slash,
-  backslashes, duplicate slashes).
- **`Service.SuggestRewrites`** — fakes for source store / `RootFolderClient` /
-  `FolderLister` / secrets: asserts proposed/unmatched/ambiguous; arr-unreachable
-  surfaces the error.
- **Handler** — returns the JSON; 404 for missing instance; 502 when the arr is
-  unreachable.
- **Frontend** — the button hits the endpoint; the preview renders all three
-  buckets with confidence badges; "Add selected" merges deduped rows; Save
-  persists via the existing mutation.
-
-## Risks & open considerations
-
- **Weak (1-segment) matches** can be coincidental across very different layouts;
-  mitigated by surfacing `match_depth` so the admin rejects them before saving.
- **Case-sensitivity** means case-mismatched mounts produce Unmatched rather than
-  a wrong auto-match — a deliberate safe default; revisit only if requested.
- **Arr reachability** is required for sync (unlike the rest of autoscan which
-  polls on a schedule); a 502 with the arr error tells the admin to check the
-  instance, and manual entry still works.
-
-## References
-
- Reused: `internal/requests/arrclient.ListRootFolders`,
-  `internal/catalog/FolderRepository.List`, `internal/autoscan` (`PathRewrite`,
-  `normalizeSeparators`, `Repository`, `Service`, the existing
-  `PUT /autoscan/sources/{id}` save).
@@ -1,161 +0,0 @@
-# Autoscan source labels — design
-
-**Date:** 2026-06-05
-**Status:** Approved, pending implementation plan
-**Scope:** Admin UI labeling of autoscan scan sources, generic across plugins, plus an operator-editable per-source label.
-
-Commands assume the repository root is the cwd.
-
-## Problem
-
-Autoscan sources are labeled in the admin UI (Sources tab and Activity tab) by their
-`capability_id` plus `plugin #<installation_id>`. The `arr` scan-source plugin fans out
-one source per connection (Sonarr, Sonarr4k, Radarr, Radarr4k) under a single generic
-`arr` capability, so every row rendered an identical "arr (plugin #4)" label. A prior
-change made the Sources/Activity labels lead with the bound connection name, which fixes
-`arr`, but the fallback for any other plugin is still the cryptic `capability_id` +
-`plugin #N`.
-
-Two gaps remain:
-
-1. **Other plugins look cryptic.** A connectionless plugin (e.g. cephfs) or any future
-   plugin still falls back to the raw `capability_id`, ignoring the human-friendly
-   `display_name` the plugin already declares in its manifest.
-2. **No operator control.** An operator cannot name a source themselves. This is the only
-   fully-general answer for plugin shapes the automatic chain cannot disambiguate (e.g. a
-   single plugin installation creating several connectionless sources distinguished only
-   by their `source_config`).
-
-## Goals
-
- Generic, plugin-agnostic labels driven by metadata that already exists
-  (manifest `display_name`, connection `name`), so future plugins look good with **no
-  host code per plugin**.
- An optional operator-editable label per source that overrides the automatic chain.
- A single shared label-resolution helper, consumed by both the Sources and Activity
-  panels, so the logic is not duplicated.
-
-## Non-goals
-
- Plugin-declared label templates in the manifest/SDK (the "option C" from brainstorming).
-  Deferred: it requires a cross-repo SDK/manifest contract change. The chain below leaves a
-  clean seam for it.
- Backend-side label resolution returned on API payloads. The resolution stays in the
-  frontend helper for now; promote it to the backend only if the mobile clients need the
-  same labels.
-
-## Resolution chain
-
-A source's display label resolves through four rungs, most-specific first:
-
-```
-operator label  ->  connection name  ->  manifest display_name  ->  capability_id
-```
-
- **operator label** — the optional per-source text the admin sets (this design's new field).
- **connection name** — the operator-named `autoscan_connections.name` bound to the source.
- **manifest display_name** — from the plugin manifest, surfaced by the
-  `scan-source-plugins` endpoint (`AutoscanAvailableSource.display_name`).
- **capability_id** — last-resort raw identifier; never worse than today.
-
-The chosen rung is the **title**. The remaining identity (plugin display name / capability +
-`plugin #<installation_id>`) renders as a **subtitle**, so no information is lost when a
-higher rung wins. Example: operator label `4K Movies` as title, `Radarr4k · plugin #4` as
-subtitle.
-
-### Per-plugin behavior
-
-| Source shape | Title | Subtitle |
-| --- | --- | --- |
-| arr, connection bound, no operator label | `Radarr4k` (connection) | `arr · plugin #4` |
-| arr, operator label set | `4K Movies` (operator) | `Radarr4k · plugin #4` |
-| cephfs, no connection | `CephFS Watcher` (manifest display_name) | `plugin #5` |
-| future plugin, nothing declared | `capability_id` | `plugin #N` |
-| Activity event whose source was deleted (`source_id` null) | manifest display_name or `capability_id` from the event's stored fields | `plugin #N` |
-
-## Components
-
-### Shared helper — `web/src/lib/autoscanLabels.ts` (new)
-
-Pure, React-free, unit-tested.
-
- `composeSourceLabel({ operatorLabel, connectionName, displayName, capabilityId, installationId })`
-  `=> { name: string; detail: string }` — implements the four-rung chain and the
-  subtitle composition.
- `pluginDisplayNameKey(installationId, capabilityId) => string` — stable map key.
- `buildPluginDisplayNames(available: AutoscanAvailableSource[]) => Map<string, string>` —
-  builds the `installation_id + capability_id -> display_name` lookup both panels use.
-
-Future seam: `composeSourceLabel` may later accept an optional `configLabel` rung (for the
-deferred plugin-template option) without changing either panel's call shape.
-
-### Migration — `migrations/174_autoscan_source_label.{up,down}.sql` (new)
-
-```sql
-- up
-ALTER TABLE public.autoscan_sources ADD COLUMN label text NOT NULL DEFAULT '';
-- down
-ALTER TABLE public.autoscan_sources DROP COLUMN label;
-```
-
-`label` empty string = unset; the resolution chain falls through to the automatic rungs.
-174 is a fresh, unused migration number (no collision with the reused-172 history).
-
-### Backend (Go)
-
- `internal/autoscan/types.go` — add `Label string` to the `Source` struct and the source
-  input type.
- `internal/autoscan/repository.go` — add `label` to `sourceColumns`, `scanSource`, and the
-  create/update statements.
- `internal/api/handlers/autoscan.go` — accept `label` on source update; include it in the
-  `autoscanStatusSource` and source responses. Trim whitespace and cap length at 120
-  characters server-side.
-
-### Frontend
-
- `web/src/api/types.ts` — add `label` to `AutoscanSource` and `AutoscanSourceInput`.
- `web/src/pages/admin/autoscan/SourcesPanel.tsx` — replace the inline `sourceIdentity`
-  block with a call to `composeSourceLabel`. Add an optional "Label" text input to the
-  source row, saved on blur via the existing `fullBody` PATCH path (mirrors the interval
-  field's `handleIntervalBlur` auto-save). Build the display-name map from the existing
-  `useAvailableScanSources()` query.
- `web/src/pages/admin/autoscan/ActivityPanel.tsx` — add `useAvailableScanSources()`, build
-  the display-name map, map `source_id -> source` to obtain the operator label and
-  connection, and route `pollSourceName` / `scanSourceName` through `composeSourceLabel`,
-  returning `.name`. Preserve the existing `"Autoscan"` fallback for scans with no
-  capability.
-
-## Edit UX
-
-Inline per-row, reusing the existing on-blur auto-save pattern (no modal, no new
-interaction model). The label input is blank by default with placeholder text indicating
-it is optional. Saving sends the full row state through the same source-update mutation
-used for connection/interval/rewrites.
-
-## Error handling and edge cases
-
- **Deleted source on an Activity event** — `autoscan_events.source_id` is
-  `ON DELETE SET NULL`; with a null `source_id` there is no operator label or connection,
-  so the chain resolves from the event row's own stored `capability_id` / `installation_id`
-  (plus manifest display_name if the plugin is still installed).
- **Uninstalled plugin** — `display_name` does not resolve; the chain falls to
-  `capability_id`.
- **Bound connection** — `autoscan_sources.connection_id` is `ON DELETE RESTRICT`, so a
-  bound connection always resolves to a name.
- **Length / whitespace** — the operator label is trimmed and capped at 120 characters
-  server-side; an all-whitespace label normalizes to empty (unset).
-
-## Testing
-
- `web/src/lib/autoscanLabels.test.ts` — covers each rung of the chain: operator label
-  wins, connection name wins, manifest display_name wins, capability fallback, and the
-  subtitle composition.
- Extend the existing autoscan repository/handler Go tests to cover the `label` column
-  round-trip (create/update/read) and the server-side trim + length cap.
-
-## Scope summary
-
-One migration pair, three Go files, four frontend files (one new). No SDK changes, no
-multi-repo coordination. Operator-editable labels (this design) and the automatic chain
-share the same helper, so the deferred plugin-template option layers on later with no
-rework.
@@ -1,472 +0,0 @@
-# Marker sources & TheIntroDB contribution — design
-
-**Date:** 2026-06-06
-**Status:** Draft (rev 2), pending review
-**Scope:** Review the current TheIntroDB marker integration, formalize a multi-source
-marker-provider model (query-all / best-wins), and add the ability to contribute Silo's own
-markers back to TheIntroDB. This round designs the **server-side API and data model only** —
-web-admin and mobile surfaces are deferred to a UI-only follow-up. No client (Android/Apple)
-changes required.
-
-Commands assume the repository root is the cwd.
-
-**Rev 2 changes:** contribution is configured **per provider** (off by default); all new web
-UI is **deferred** and the backend API is specified in full instead.
-
-## Decisions locked for this design
-
-These were chosen up front and constrain everything below:
-
-1. **Deliverable now:** design/plan only. No source changes land from this document; it is
-   the blueprint a follow-up implementation plan expands.
-2. **What we contribute:** *both* local auto-detected markers *and* manual corrections. Local
-   detection only produces **intro markers for episodes**, so credits/recap/preview and all
-   movies can only be contributed via manual correction — this asymmetry drives the design.
-3. **Account model:** a single server-wide TheIntroDB account, reusing the existing
-   `introdb.api_key` server setting. Per-user accounts are a noted future seam, not built now.
-4. **Multi-source dispatch:** query all enabled online sources and keep the highest-quality
-   result per segment ("best wins"). This makes *real per-segment confidence* (gap #2 below)
-   a hard prerequisite, not an optional nicety.
-5. **Contribution is configured per provider, off by default.** Every contribution-capable
-   provider has its own enable switch and submit settings, so when more providers exist an
-   operator chooses *which* ones to submit to. Both the master contribute switch and the
-   auto-submit-local-detections switch default to off; a single setting flips each on.
-6. **API-first, UI deferred.** This round fully specifies the backend (manual marker
-   read/write/clear, contribution trigger + status, per-provider provider config, key
-   validation and stats) so any future surface — web admin or mobile — builds on a complete
-   contract. No new web UI is designed here beyond noting where it will eventually attach.
-
-## Problem
-
-Silo currently detects intro/recap/credits/preview markers from two places — a local
-chromaprint/chapter analyzer (`internal/intromarkers`) and the online TheIntroDB provider
-(`internal/markers/introdb`) — reconciled by a source-priority ladder at write time. The
-online side is cleanly abstracted behind a `markers.Provider` interface and a
-`markers.Registry`, which is good, but three things are missing:
-
-1. The current TheIntroDB provider has **correctness gaps** measured against the real v3 API
-   contract (TVDB lookups dropped, real confidence discarded — see "Review findings").
-2. There is **no path to contribute** Silo's markers back to TheIntroDB, even though the v3
-   API exposes a submission endpoint and the package was deliberately built read-only.
-3. The provider abstraction is **fetch-only and first-hit**, so it does not yet support
-   "several online sources, keep the best answer" or "this source can also accept
-   contributions, and I choose which sources to submit to."
-
-## Review findings — current implementation
-
-### What is already right (keep it)
-
- **Clean source abstraction.** `markers.Provider` (`ID()`, `FetchMarkers()`) + `markers.Registry`
-  with `FetchFirstHit` (`internal/markers/types.go`). TheIntroDB is *not* hardcoded; a second
-  provider is one `Register()` call (`cmd/silo/main.go`).
- **Multi-source-aware schema.** `media_files` carries per-segment provenance for all four
-  kinds: `{intro,credits,recap,preview}_markers_{source,provider,confidence,algorithm,detected_at}`
-  (migrations 108/109/137).
- **Write-time reconciliation across source classes.** `CanWriteMarker`
-  (`internal/markers/write.go`) + `MarkerSourcePriority` (`internal/models/marker_source.go`):
-  `manual(4) > online/plugin(3) > s3(2) > scanner(1)`, confidence breaks ties. Local detection
-  uses its own priority-gated path (`intromarkers.Repository.PatchIntroMarker`).
- **Solid HTTP hygiene** in `internal/markers/introdb/client.go`: conservative rate limiter
-  (2 req/s, burst 5; documented limit is 30 req/10s), retry with exponential backoff,
-  `Retry-After` handling, 24h TTL cache with negative caching, hot-reloadable API key over
-  Redis pub/sub.
-
-### Gaps (measured against TheIntroDB's own v3 client + Jellyfin plugin)
-
-| # | Gap | Evidence | Impact |
-|---|-----|----------|--------|
-| 1 | **TVDB lookups silently dropped.** Provider reads only TMDB+IMDB; client can't send `tvdb_id`. | `internal/markers/introdb/provider.go` (reads `ExternalIDKeyTMDB`/`IMDB` only); `client.go` `FetchEpisode/FetchMovie` build `tmdb_id` else `imdb_id`. | Titles matched only by TVDB (very common for anime / TheTVDB-first libraries) get **zero** markers, even though the resolver already populates `TvdbID` and the v3 API + both official clients support `tvdb_id`. Correctness bug. |
-| 2 | **Real confidence + submission_count discarded; hardcoded 0.9.** | `internal/markers/introdb/types.go` `segmentTimestamps` has only `start_ms`/`end_ms`; `pickMarker` sets `Confidence: 0.9`. | The `/media` response carries per-segment `confidence` and `submission_count`. Without them, "best wins" merging can't rank sources, and write-time confidence tie-breaks are meaningless. Hard blocker for the chosen dispatch model. |
-| 3 | **Naive multi-candidate selection.** `pickMarker` takes the *first* usable entry. | `internal/markers/introdb/provider.go`. | When several candidates remain (e.g. no duration match), first-usable may not be the most-submitted/highest-confidence. Minor today (duration narrows the set), but compounds once we rank by confidence. |
-| 4 | **No contribution path** (by design). | `internal/markers/introdb/types.go` package doc: "Submissions are intentionally not supported." | The whole point of this effort. |
-| 5 | **Provider is fetch-only.** No submit capability in the interface. | `markers.Provider` in `internal/markers/types.go`. | Contribution needs an optional `Submitter` capability so non-contributing sources don't have to implement it, and so submission is per provider. |
-| 6 | **No key validation / contribution stats.** | `IntroDBCredentialCard` in `web/src/pages/admin-settings/IntegrationsSettings.tsx` only sets the key. | v3 exposes `GET /v3/user/stats` to validate a key and show contribution totals/streaks. Useful "connect & verify" probe, currently absent from the API. |
-| 7 | **Single collapsed confidence in the write payload.** `BuildUpdatePayload` promotes one max confidence across all segments. | `internal/markers/write.go`. | The DB has *per-segment* confidence columns, but a merged result (intro from source A, credits from source B) can't populate them independently until per-segment confidence is threaded through the payload. Coupled to gap #2. |
-
-## Authoritative API contract (TheIntroDB v3)
-
-Confirmed from TheIntroDB's own `theintrodb` npm client (`src/funcs.ts`, `src/types.ts`) and
-the official Jellyfin plugin (`TheIntroDbClient.cs`). Base URL: `https://api.theintrodb.org/v3`.
-
-### `GET /media` — read (public; optional key)
-
-Query: one of `tmdb_id` / `tvdb_id` / `imdb_id` (preference order tmdb → tvdb → imdb),
-plus `season` + `episode` together for TV, plus optional `duration_ms` (selects the closest
-release version). Optional `Authorization: Bearer <key>` additionally includes that user's
-*pending* submissions.
-
-Response — each segment kind is an array of:
-```jsonc
-{ "start_ms": 30000|null, "end_ms": 90000|null, "confidence": 0.93|null, "submission_count": 7|null }
-```
-`start_ms:null` = "from the beginning" (intro/recap); `end_ms:null` = "to the end"
-(credits/preview). Arrays may hold multiple entries (multiple release versions) — pick by
-duration match, then by `submission_count`/`confidence`.
-
-### `POST /submit` — contribute (requires key)
-
-`Authorization: Bearer <user key>` required; submissions are credited to that account.
-Body (one segment per call):
-```jsonc
-{
-  "tmdb_id": 1234,            // required
-  "imdb_id": "tt0903747",     // optional
-  "type": "tv" | "movie",
-  "segment": "intro" | "recap" | "credits" | "preview",
-  "season": 1,                // TV only (number, or "1,2,3" multi-select)
-  "episode": 1,               // TV only
-  "video_duration_ms": 2760000, // optional, strongly recommended (release-version match)
-  "start_ms": 0|null,         // intro/recap may be null (= beginning)
-  "end_ms": 90000|null        // credits/preview may be null (= end)
-}
-```
-Response: `{ "submissions": [ { "id": uuid, "status": "pending"|"accepted"|"rejected",
-"weight": number, ... } ] }`. Submissions enter as `pending`; the backend weight-averages
-timestamps across submissions and moderates to accepted/rejected.
-
-Validation rules to mirror client-side: intro/recap require an **end**; credits/preview
-require a **start**; TV requires season+episode; movies omit them; max timestamp 6h
-(21,600,000 ms); `video_duration_ms` is 0 (unknown) or ≥ 300,000 ms.
-
-### `GET /user/stats` — validate key + contribution stats
-
-`Authorization: Bearer <key>`. Returns `{ total, accepted, pending, rejected,
-acceptance_rate, current_streak, best_streak, total_time_saved_ms, top_media }`. A 2xx with no
-`error` means the key is valid. This is both our key-validation probe and the stats display.
-
-### Rate / usage limits
-
-429 responses carry `X-RateLimit-{Limit,Remaining,Reset}` and `X-UsageLimit-{Limit,Remaining,Reset}`.
-Reads count against the rate limit; **submissions count against the usage limit**. The
-contribution pipeline must honor `X-UsageLimit-Reset` and back off — reuse the existing
-limiter and add usage-limit awareness.
-
-## Target architecture
-
-Three layers, each independently shippable. Layer A is pure correctness and unblocks B and C.
-
-### Layer A — Correctness foundation (gaps #1, #2, #3, #7)
-
- **TVDB in the client + provider.** Add `tvdb_id` to the query builder in
-  `internal/markers/introdb/client.go` (`FetchEpisode`/`FetchMovie` gain a `tvdbID` arg,
-  preference tmdb → tvdb → imdb, cache keys extended). Provider reads
-  `req.ExternalIDs[markers.ExternalIDKeyTVDB]`. Resolver already supplies it — no resolver
-  change.
- **Capture confidence + submission_count.** Extend `segmentTimestamps` with
-  `Confidence *float64` and `SubmissionCount *int`; add `SubmissionCount int` to
-  `markers.Marker`; `pickMarker` uses the real confidence (fallback to a named default
-  constant, e.g. `0.9`, only when the field is null) instead of hardcoding.
- **Best-candidate selection.** `pickMarker` ranks candidates by `(submission_count desc,
-  confidence desc)` after duration filtering, instead of first-usable.
- **Per-segment confidence in the payload.** Replace the single `Confidence *float64` on
-  `markers.MarkerUpdatePayload` with per-segment confidence (e.g. `IntroConfidence`,
-  `CreditsConfidence`, …) so a merged multi-source result writes the correct
-  `{kind}_markers_confidence` per kind. Update `BuildUpdatePayload` and the
-  `scanner.FileRepository.UpsertMarkers` column mapping accordingly.
-
-### Layer B — Multi-source dispatch ("query all, best wins")
-
- **`Submitter` capability (optional interface).**
-  ```go
-  // internal/markers/types.go
-  type Submitter interface {
-      Provider
-      SubmitMarker(ctx context.Context, req SubmissionRequest) (SubmissionResult, error)
-      // FetchUserStats validates the configured key and returns contribution stats.
-      FetchUserStats(ctx context.Context) (UserStats, error)
-  }
-  ```
-  Only `introdb.Provider` implements it; the contribution service type-asserts
-  `provider.(markers.Submitter)`. This is also what makes contribution per-provider: the
-  service only ever submits to registered providers that satisfy `Submitter` *and* are enabled
-  in `marker_provider_config` (C6).
-
- **Merge dispatch.** Add `Registry.FetchMerged(ctx, req) (Result, bool, error)` that fans out
-  to all *fetch-enabled* providers concurrently (bounded), then merges **per segment kind**
-  keeping the candidate with the highest `(submission_count, confidence)`. `FetchFirstHit`
-  stays as the trivial single-provider path / fallback. With only TheIntroDB enabled,
-  `FetchMerged` behaves identically to today — zero behavior change until a second source
-  exists.
-
- **Cross-source-class reconciliation is unchanged.** `FetchMerged` reconciles *within* the
-  online class; `CanWriteMarker` still arbitrates online vs scanner vs manual at write time.
-  No double logic.
-
- **Provider enable/order config.** Driven by the `marker_provider_config` table (C6):
-  `fetch_enabled` selects which providers are queried, `fetch_priority` is the merge
-  tiebreaker. The metadata `library_provider_chains` DB pattern (`internal/metadata/chain.go`)
-  is the upgrade path *if* per-library control is ever needed — noted, not built.
-
- **Future plugin sources (deferred seam).** A `marker_provider.v1` plugin capability would let
-  third-party sources plug in. The clean seam is a `PluginMarkerProvider` adapter implementing
-  `markers.Provider` (mirroring `internal/metadata/plugin_provider.go`), so the registry never
-  changes. Cross-repo (silo-plugin-sdk) — explicitly out of scope here.
-
-### Layer C — Contribution to TheIntroDB
-
-#### C1. Submission client
-
-Add to `internal/markers/introdb/client.go`:
- `SubmitSegment(ctx, SubmissionRequest) (SubmissionResult, error)` → `POST /v3/submit`,
-  Bearer key **required** (error early if `introdb.api_key` is empty), usage-limit aware.
- `FetchUserStats(ctx) (UserStats, error)` → `GET /v3/user/stats`.
-`introdb.Provider` implements `markers.Submitter` by delegating to these.
-
-#### C2. What is eligible to contribute
-
-A marker is contributable iff:
- the target provider is a registered `Submitter` with `contribute_enabled = true` (C6), and
- its segment source ∈ `{scanner, manual}` (**never** `online` — that came *from* an online
-  provider; contributing it back is circular), and
- the file resolves to a usable external ID (tmdb/tvdb/imdb) via the existing resolver, and
- for **auto** contribution: provider `contribute_auto_local = true`, source = `scanner`,
-  kind = `intro`, confidence ≥ that provider's `contribute_min_confidence`. (Local detection is
-  intro-only/episodes-only.)
- for **manual** contribution: any kind, episodes or movies, source = `manual`.
-
-#### C3. Manual marker API (write path; UI deferred)
-
-Markers live on `media_files`, and an item can have several versions, so the manual API is
-**file-scoped** for precision, with an item-level convenience resolver. All under the existing
-`RequireAdmin` group (`internal/api/middleware/auth.go`). New `internal/api/handlers/admin_markers.go`:
-
- `GET /admin/files/{fileId}/markers` — current per-segment values **plus full provenance**
-  (`source`, `provider`, `confidence`, `algorithm`, `detected_at`) for each of
-  intro/recap/credits/preview. The read side an editor (or a script) needs.
- `PUT /admin/files/{fileId}/markers` — upsert the **manual** layer. Body carries, per segment,
-  either `{start, end}` (seconds) or `null` to clear that segment's manual value. Writes
-  `source = manual` (priority 4, beats every other source) through the existing priority-gated
-  `scanner.FileRepository.UpsertMarkers` path, then notifies live sessions via
-  `playback.MarkerUpdateNotifier.MarkersUpdated` (mirrors `admin_intro.go`).
- `DELETE /admin/files/{fileId}/markers/{segment}` — explicit single-segment clear.
- `GET|PUT /admin/items/{id}/markers` — item-level convenience that resolves to the primary
-  file (and reports the per-version set), for callers that don't track file IDs.
-
-**Clear semantics.** Clearing a manual segment nulls that segment's value and provenance;
-`markers_source` drops to the next-highest segment still present. A subsequent local
-re-detection or online lazy-fetch can repopulate it. (We can't "un-overwrite" a value a manual
-edit replaced, so clearing means "remove the manual value," not "restore the previous source.")
-
-**Validation** mirrors the contribution rules so a manual edit can always be contributed:
-`end > start`; intro/recap may omit start (= 0); credits/preview may omit end (= file
-duration); values within [0, file duration].
-
-A web editor (player-chrome control with a "use current time" helper) attaches to this API
-later; its UX is intentionally **out of scope** for this round.
-
-#### C4. Contribution tracking (idempotency + audit)
-
-The audit log that makes submission idempotent and lets us report status. Per-provider by
-construction (the `provider` column), so the same marker can be tracked/submitted to several
-providers independently.
-
-```sql
-- migrations/<next>_marker_contributions.up.sql  (next free number at implementation time)
-CREATE TABLE public.marker_contributions (
-    id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-    media_file_id      integer NOT NULL REFERENCES media_files(id) ON DELETE CASCADE,
-    provider           text    NOT NULL,                 -- 'introdb'
-    segment_kind       text    NOT NULL,                 -- intro|recap|credits|preview
-    source             text    NOT NULL,                 -- what we contributed: 'scanner'|'manual'
-    submitted_start_ms bigint,
-    submitted_end_ms   bigint,
-    video_duration_ms  bigint,
-    content_hash       text    NOT NULL,                 -- hash(segment_kind,start_ms,end_ms,duration_ms)
-    submission_id      uuid,                             -- returned by /submit
-    status             text    NOT NULL,                 -- pending|accepted|rejected|error
-    http_status        integer,
-    error              text,
-    submitted_at       timestamptz NOT NULL DEFAULT now(),
-    updated_at         timestamptz NOT NULL DEFAULT now(),
-    UNIQUE (media_file_id, provider, segment_kind, content_hash)
-);
-CREATE INDEX marker_contributions_file_idx ON public.marker_contributions(media_file_id);
-```
-
-`content_hash` over the *value* gives idempotency: the same times are never resubmitted to the
-same provider, but a manual correction (different times → different hash) submits the new
-value — which is exactly how TheIntroDB's weighted averaging expects corrections to arrive.
-
-#### C5. Contribution service + triggers
-
-A single `internal/markers/contribute.go` `ContributionService` funnels both triggers:
-`resolve enabled submitter providers (C6) → per provider: eligibility (C2) → idempotency check
-(hash vs marker_contributions) → Submitter.SubmitMarker → persist result`. Triggers:
- **Manual / on-demand:** `POST /admin/files/{fileId}/contribute` (C7) submits a file's eligible
-  markers to enabled providers (optionally scoped to one provider/segments).
- **Auto local detections:** a daily `ContributeMarkersTask` (`internal/taskmanager/tasks/`)
-  that, for each provider with `contribute_enabled && contribute_auto_local`, scans for episode
-  files with `intro_markers_source = 'scanner'` and `intro_markers_confidence ≥` that provider's
-  `contribute_min_confidence` lacking a current-hash `marker_contributions` row, and submits
-  them rate/usage-limited. Runs after the existing 03:30 detection task.
-
-#### C6. Per-provider configuration
-
-Contribution and fetch behavior is **per provider**, so a single global toggle won't do.
-Credentials stay in `server_settings` (sensitive handling: `introdb.api_key`); behavioral
-config moves to a new table keyed by provider id:
-
-```sql
-- migrations/<next>_marker_provider_config.up.sql
-CREATE TABLE public.marker_provider_config (
-    provider                  text PRIMARY KEY,                -- 'introdb'
-    fetch_enabled             boolean NOT NULL DEFAULT true,   -- queried during reads (Layer B)
-    fetch_priority            integer NOT NULL DEFAULT 100,    -- merge tiebreaker
-    contribute_enabled        boolean NOT NULL DEFAULT false,  -- master submit switch (off)
-    contribute_auto_local     boolean NOT NULL DEFAULT false,  -- auto-submit local detections (off)
-    contribute_min_confidence double precision NOT NULL DEFAULT 0.95,
-    updated_at                timestamptz NOT NULL DEFAULT now()
-);
-INSERT INTO public.marker_provider_config (provider, fetch_enabled) VALUES ('introdb', true);
-```
-
- A provider's submissions require `contribute_enabled = true`. With it on, **manual**
-  corrections submit on demand; **auto** submission of local detections additionally requires
-  `contribute_auto_local = true`. Both contribute flags default off — "easily enabled with a
-  setting," exactly one row per provider.
- This same table carries the Layer B fetch enable/order, so "which providers do we read from"
-  and "which do we submit to" live in one place. New providers insert a row (contribute off).
- Surfaced and edited through the provider API (C7), so the future admin surface lists
-  providers generically rather than hard-coding `introdb`.
-
-The `markers.mode` / `markers.lazy_playback` globals and the `introdb.api_key` credential are
-unchanged.
-
-#### C7. Admin provider + contribution API (fully fledged)
-
-The complete backend surface, all under `RequireAdmin`, so a UI is purely additive later:
-
- `GET /admin/markers/providers` — list every registered provider: id, whether it is a
-  `Submitter`, its `marker_provider_config` row, and (best-effort, cached) live `/user/stats`
-  for submitter providers that have a key.
- `PUT /admin/markers/providers/{provider}` — update that provider's config row
-  (`fetch_enabled`, `fetch_priority`, `contribute_enabled`, `contribute_auto_local`,
-  `contribute_min_confidence`). Validated; unknown provider → 404.
- `POST /admin/markers/providers/{provider}/validate` — validate the configured key and return
-  fresh `UserStats` (calls `Submitter.FetchUserStats`). Non-submitter → 400.
- `POST /admin/files/{fileId}/contribute` — submit this file's eligible markers (C2) to enabled
-  submitter providers; optional body `{provider?, segments?[]}` to scope to one provider /
-  specific kinds. Returns per (provider, segment) `SubmissionResult`. Honors idempotency (C4):
-  unchanged values are skipped, not resubmitted.
- `GET /admin/files/{fileId}/contributions` — contribution history for the file from
-  `marker_contributions` (per provider/segment: status, submitted_at, error).
-
-Plus the manual marker endpoints from C3. Together these cover read, edit, submit, and audit
-without any web code.
-
-## Data model summary
-
- **New table `marker_contributions`** (C4) — idempotent submission audit, keyed per
-  (file, provider, segment, value-hash).
- **New table `marker_provider_config`** (C6) — per-provider fetch + contribute behavior,
-  seeded with `introdb` (fetch on, contribute off).
- **No new flat server settings.** `introdb.api_key`, `markers.mode`, `markers.lazy_playback`
-  are unchanged; behavioral provider config lives in `marker_provider_config`, not string keys.
- **No new marker columns.** Per-segment confidence columns already exist; Layer A only changes
-  how they're *populated* (per-segment instead of collapsed). `submission_count` stays
-  transient (merge-ranking only) unless a later need appears.
-
-## Client / cross-repo impact
-
- **No Android/Apple changes required.** This adds no new marker *kinds* and no new
-  client-facing read contract: markers still flow to clients via the existing `WatchDetail`
-  fields, the jellycompat `GET /MediaSegments` endpoint, and the `markers_updated` realtime
-  event. Manual editing and contribution are server-side (admin API); their eventual UI is
-  deferred web-admin work.
- **Plugin SDK:** untouched. `marker_provider.v1` is a deferred future capability (Layer B
-  seam), not part of this work.
- A future *per-user* contribution model (each user links their own TheIntroDB account) *would*
-  be client work (a "Connect TheIntroDB" screen) — explicitly deferred.
-
-## Build sequence
-
-Each phase is shippable on its own; later phases depend only on earlier ones. Every phase is
-**backend-only** — no web UI.
-
-1. **Phase 1 — Correctness foundation (Layer A).** TVDB lookups; capture
-   confidence/submission_count; best-candidate selection; per-segment confidence in the
-   payload. *Directly answers "are we doing this properly," low risk, no new surface.*
-2. **Phase 2 — Multi-source dispatch + provider config (Layer B + C6).** `Submitter` interface;
-   `FetchMerged` query-all/best-wins; `marker_provider_config` table + repo driving fetch
-   enable/order. *No behavior change with only TheIntroDB enabled.*
-3. **Phase 3 — Submission client + tracking + service (C1, C4, C5 core).** `SubmitSegment` /
-   `FetchUserStats`; `marker_contributions` migration + repo; `ContributionService` (eligibility,
-   idempotency, per-provider gating).
-4. **Phase 4 — Manual marker API (C3) + provider/contribution API (C7).** File- and item-level
-   manual read/write/clear; provider list/config/validate; per-file contribute + history. The
-   full admin contract, no UI.
-5. **Phase 5 — Auto-contribution (C5 task).** `ContributeMarkersTask`: per provider, when
-   `contribute_enabled && contribute_auto_local`, submit episode intro markers above the
-   provider's `contribute_min_confidence`, usage-limit aware, idempotent.
-
-Deferred (separate UI-only follow-up): web admin surfaces over C3/C6/C7 — a marker editor in
-the player chrome and a provider/contribution panel in admin settings.
-
-## Risks & trade-offs
-
- **Data-quality / pollution.** Auto-submitting chromaprint detections (confidence 0.65–0.90)
-  risks polluting a provider's data. Mitigation: `contribute_enabled` and `contribute_auto_local`
-  default **off** per provider, and the default `contribute_min_confidence` of 0.95 admits only
-  chapter / chapter+silence detections even once enabled. Manual, high-trust corrections are the
-  intended first contribution. Revisit chromaprint auto-submission after watching acceptance
-  rates via `/user/stats`.
- **Single-account weighting.** All contributions credit one server account; TheIntroDB's
-  weighting may treat a single account's mass submissions differently than many users'. Note
-  the per-user seam; acceptable for v1.
- **Circular contribution.** Never contribute `source = online`. Enforced in C2 eligibility and
-  worth a unit test.
- **Usage limits.** Bulk auto-submission can hit the submission usage limit; the task must obey
-  `X-UsageLimit-Reset` and resume next run. Idempotency means an interrupted run safely resumes.
- **"Query all" cost.** `FetchMerged` issues one lookup per fetch-enabled provider; with only
-  TheIntroDB it's identical to today, and per-provider caching bounds the cost as sources are
-  added.
- **Movies & non-intro segments** have no local detector, so their only contribution route is
-  manual correction — acceptable and explicit.
-
-## Open questions for review
-
-1. **Contribute to all enabled providers, or require explicit per-call selection?** The design
-   defaults `POST /admin/files/{id}/contribute` to "every enabled submitter," with an optional
-   `provider` scope. Acceptable, or should submission always name its target provider?
-2. **Manual-clear behavior.** Clearing a manual segment removes the manual value and lets a
-   later detection/fetch repopulate it (we can't restore the exact pre-edit value). Is
-   "remove, then re-detect" the right contract, or do you want a marker history/undo stack?
-3. **Per-provider config home.** This design uses a `marker_provider_config` table (clean for N
-   providers, future per-library override) rather than flat `server_settings` keys. Confirm the
-   table is the direction you want.
-
-## File-level blueprint
-
-**Backend (Go) — Layer A**
- `internal/markers/introdb/client.go` — *modify*: `tvdb_id` query support; cache-key extension.
- `internal/markers/introdb/types.go` — *modify*: `confidence`/`submission_count` fields.
- `internal/markers/introdb/provider.go` — *modify*: read TVDB; real confidence; best-candidate pick.
- `internal/markers/types.go` — *modify*: per-segment confidence in `Marker`/Result plumbing.
- `internal/markers/write.go` — *modify*: per-segment confidence in `MarkerUpdatePayload` + `BuildUpdatePayload`.
- `internal/scanner/file_repo.go` — *modify*: map per-segment confidence in `UpsertMarkers`.
-
-**Backend (Go) — Layer B + per-provider config**
- `internal/markers/types.go` — *modify*: `Submitter` interface; `SubmissionRequest`/`Result`, `UserStats`; `Registry.FetchMerged`.
- `internal/markers/provider_config.go` — *create*: `marker_provider_config` repo (load/update; drives fetch enable/order + contribute gating).
- `migrations/<next>_marker_provider_config.{up,down}.sql` — *create*.
-
-**Backend (Go) — Layer C**
- `internal/markers/introdb/client.go` — *modify*: `SubmitSegment` (`POST /v3/submit`), `FetchUserStats` (`GET /v3/user/stats`), usage-limit handling.
- `internal/markers/introdb/provider.go` — *modify*: implement `markers.Submitter`; drop the "submissions not supported" note in `types.go`.
- `internal/markers/contribute.go` — *create*: `ContributionService` (eligibility, idempotency, per-provider gating, submit, persist).
- `internal/markers/contribution_repo.go` — *create*: `marker_contributions` CRUD + value-hash check.
- `migrations/<next>_marker_contributions.{up,down}.sql` — *create*.
- `internal/api/handlers/admin_markers.go` — *create*: manual marker read/write/clear (C3) + per-file contribute + history (C7 file endpoints).
- `internal/api/handlers/admin_marker_providers.go` — *create*: provider list/config/validate (C7 provider endpoints).
- `internal/api/router.go` — *modify*: register the new `RequireAdmin` routes.
- `internal/taskmanager/tasks/contribute_markers.go` — *create*: daily auto-contribution task.
- `cmd/silo/main.go` — *modify*: wire `ContributionService`, provider-config repo, the task, and the `Submitter`.
-
-**Frontend (React/TS) — deferred (not this round)**
- Marker editor over `PUT /admin/files/{id}/markers`; provider/contribution panel over the C7
-  endpoints; `IntroDBCredentialCard` "validate key & show stats". Listed for traceability only.
-
-**Reference (read-only, not in this repo)**
- TheIntroDB v3 contract verified against `github.com/TheIntroDB/theintrodb-npm`
-  (`src/funcs.ts`, `src/types.ts`, `docs/`) and `github.com/TheIntroDB/jellyfin-plugin`
-  (`TheIntroDB/Api/*.cs`).
@@ -1,311 +0,0 @@
-# AI services: shared core, metadata translation, Whisper ASR — design
-
-**Date:** 2026-06-10
-**Status:** Draft, pending review
-**Scope:** Extract the AI subtitle translation engine into a shared AI core, add AI translation of movie/series/season/episode descriptions into the existing localization tables, and add Whisper ASR subtitle generation (`transcribe`, `transcribe_translate`). One PR.
-
-Commands assume the repository root is the cwd.
-
-## Problem
-
-`internal/subtitles/ai` ships an on-demand LLM subtitle translator. The LLM plumbing inside
-it (OpenAI-compatible chat client with retry/backoff, batched indexed-JSON translation,
-job lifecycle with idempotency/heartbeat/reaper/bounded concurrency) is generic, but it is
-buried in a subtitle-specific package, so nothing else can use it.
-
-Two features want exactly that plumbing:
-
-1. **Metadata translation.** Libraries whose `metadata_language` the providers cannot fully
-   serve end up with overviews/taglines in the item's default language (usually English).
-   The localization tables (`media_item_localizations`, `season_localizations`,
-   `episode_localizations`) and the serving path (`LocalizeItemModel` and friends in
-   `internal/catalog/detail.go`) already exist — the gap is producing rows for languages the
-   providers don't have.
-2. **Whisper ASR.** `subtitle_ai_jobs.kind` already reserves `transcribe` and
-   `transcribe_translate`; media with no usable text subtitle track (foreign audio with only
-   bitmap subs, or no subs at all) currently has no AI path to a subtitle track.
-
-## Goals
-
- One shared AI core: a single OpenAI-compatible endpoint configuration (chat + audio
-  transcription), one retry/backoff implementation, one generic batched text translator,
-  one job-lifecycle runner — consumed by subtitle translation, metadata translation, and ASR.
- AI-translated overviews and taglines stored in the **existing** localization tables, so
-  web, Android, Apple, and jellycompat clients get them through the current serving path
-  with **zero client changes**.
- Provenance on AI-writable localization fields so refreshes never regress data quality:
-  `manual` beats `provider` beats `ai`. A later provider localization overwrites an AI
-  translation; the reverse never happens.
- Two metadata-translation triggers: a manual admin action, and an opt-in per-library
-  fallback ("provider had no localization for the library language → AI-translate") wired
-  into metadata ingestion.
- ASR jobs that produce ordinary `downloaded_subtitles` rows (provider `transcribed`),
-  with `transcribe_translate` chaining the existing LLM translator for a target-language
-  track; live cue streaming to the requesting playback session, same as translation today.
- Total AI load on the configured endpoint bounded by **one** shared semaphore.
-
-## Non-goals
-
- **Episode/movie/series title translation.** Titles often have official localized forms
-  that are not literal translations; provider data only.
- **Collection names or descriptions.** Deferred: collections have no localization table
-  yet. The metadata translation service is written against content-ID + field-list inputs,
-  so a `collection_localizations` table can be added in a follow-up without reshaping it.
- **Genre translation.** If ever wanted, that is a static mapping, not an LLM call.
- **Per-profile metadata language.** Presentation language stays library-scoped
-  (`media_folders.metadata_language`); changing that is an orthogonal feature.
- **A localization editor UI.** The `manual` provenance value is honored by the write
-  rules but no UI sets it yet (the existing metadata editor edits base fields, not
-  localizations).
- **Whisper word-level timing, diarization, VAD-aligned chunking.** v1 uses fixed-length
-  chunks; boundary-word artifacts are an accepted limitation noted for follow-up.
-
-## Architecture
-
-### Package layout
-
-```
-internal/ai/llm        Client: OpenAI-compatible /v1/chat/completions (moved from
-                       internal/subtitles/ai/client.go) + new /v1/audio/transcriptions.
-                       Shared retry/backoff/429 handling. Config for the endpoint(s).
-internal/ai/translate  Generic batched text translation: []Segment{ID, Text} in,
-                       translated segments out. Indexed-JSON protocol, context
-                       neighbors, malformed-response retries — moved from
-                       internal/subtitles/ai/translator.go and de-subtitled.
-internal/ai/jobrunner  Generic job lifecycle: bounded dispatch off a shared semaphore,
-                       heartbeat loop, stale-job reaper, cancel registry — extracted from
-                       internal/subtitles/ai/service.go behind a small repo interface.
-internal/subtitles/ai  Stays: subtitle job semantics. Translate path becomes a thin
-                       adapter (cues ↔ segments); gains the transcribe paths.
-internal/metadata/translation
-                       New: metadata translation job service + repo + provenance-aware
-                       writes into the localization repos.
-```
-
-Package names: `llm`, `aitranslate`, `jobrunner` (import paths above; `aitranslate` avoids
-a name collision when imported from package `ai`).
-
-### Shared semaphore
-
-`cmd/silo` builds one `chan struct{}` of size `ai.max_concurrent_jobs` and hands it to both
-job services via `jobrunner`. Subtitle, metadata, and ASR jobs all draw from it, so the
-operator's endpoint sees a bounded number of concurrent jobs regardless of job mix.
-(An ASR job holds one slot for its whole pipeline: extract → transcribe → translate.)
-
-## Settings
-
-Connection settings move to a shared `ai.*` namespace. Because encrypted values are
-GCM-bound to their setting key (see `internal/catalog/encrypted_settings_repo.go`), the
-legacy rows are **not renamed**; the loader falls back to them, following the precedent of
-`recommendations.embedding_auth_token` → `recommendations.openai_api_key` in
-`internal/config/db_loader.go`.
-
-| Key | Default | Fallback | Notes |
-| --- | --- | --- | --- |
-| `ai.base_url` | `https://api.openai.com` | `subtitle_ai.base_url` | |
-| `ai.api_key` | `""` | `subtitle_ai.api_key` | sensitive |
-| `ai.chat_model` | `gpt-4o-mini` | `subtitle_ai.chat_model` | |
-| `ai.max_concurrent_jobs` | `2` | `subtitle_ai.max_concurrent_jobs` | shared semaphore size |
-| `ai.asr_model` | `whisper-1` | — | |
-| `ai.asr_base_url` | `""` (= `ai.base_url`) | — | separate local Whisper server |
-| `ai.asr_api_key` | `""` (= `ai.api_key`) | — | sensitive |
-| `subtitle_ai.enabled` | `false` | — | existing; subtitle translation toggle |
-| `subtitle_ai.transcribe_enabled` | `false` | — | new; ASR toggle |
-| `subtitle_ai.batch_size` | `40` | — | existing; cues per chat request |
-| `subtitle_ai.context_neighbors` | `2` | — | existing |
-| `metadata_ai.enabled` | `false` | — | new; metadata translation toggle |
-
-`ai.api_key` and `ai.asr_api_key` join `sensitiveSettingKeys`. The admin UI reads through
-the same fallback (effective values come from the loaded config) and writes the new keys.
-
-Config structs: `AIConfig` (connection + concurrency), `SubtitleAIConfig` (slims down to
-toggles + batch tuning), new `MetadataAIConfig`. Readiness: subtitle translate requires
-`subtitle_ai.enabled` + chat config; ASR requires `subtitle_ai.transcribe_enabled` + ASR
-config; metadata requires `metadata_ai.enabled` + chat config.
-
-## Metadata translation
-
-### What gets translated
-
-| Target | Fields |
-| --- | --- |
-| movie / series (`media_item_localizations`) | `overview`, `tagline` |
-| season (`season_localizations`) | `overview` |
-| episode (`episode_localizations`) | `overview` |
-
-Titles, sort titles, and artwork columns in those rows are never written by AI.
-
-### Provenance
-
-New columns (default `'provider'`, check-constrained to `provider|ai|manual`):
-
- `media_item_localizations.overview_source`, `media_item_localizations.tagline_source`
- `season_localizations.overview_source`
- `episode_localizations.overview_source`
-
-Write rules, enforced in the localization repos (single-statement upserts with CASE):
-
-| Writer | May overwrite | Sets source | Notes |
-| --- | --- | --- | --- |
-| provider ingestion | `provider`, `ai` | `provider` | a non-empty provider value always replaces an AI value; an **empty** provider value never blanks an existing one |
-| AI translation | `ai`, empty | `ai` | with `force`, may also overwrite `provider` (admin explicitly re-translating) — never `manual` |
-| manual (future editor) | anything | `manual` | |
-
-Serving hardening: `LocalizeItemModel` / `LocalizeSeasonModel` / `LocalizeEpisodeModel`
-must only override base fields with **non-empty** localization values, since AI-created
-rows legitimately carry empty titles. (Verify current behavior; fix if it clobbers.)
-
-### Job model
-
-New table `metadata_translation_jobs`, mirroring `subtitle_ai_jobs` conventions
-(status enum, progress, idempotency partial-unique index, heartbeat):
-
- `target_kind` (`item` | `season` | `episode`), `content_id`, `include_children`
- `target_language`, `source_language` (default language of the base row)
- `engine`, `model`, `status`, `progress`, `progress_message`, `fields_done`, `fields_total`
- `error_message`, `idempotency_key`, `requested_by`, `force`, timestamps, `heartbeat_at`
-
-A job for a series item with `include_children` expands to: item overview + tagline, every
-season overview, every episode overview. All fields become segments
-(`item:overview`, `season:<content_id>:overview`, `episode:<content_id>:overview`, …) fed
-to the generic translator in batches (metadata batch size constant, smaller than the
-subtitle one — paragraphs, not cue lines), so episode descriptions share terminology in one
-prompt context. The system prompt names the series/movie and year for grounding.
-
-Skip logic in the run loop (not at enqueue): a field whose localization value is already
-non-empty is skipped unless `force` — so the auto trigger costs zero LLM calls on repeat
-refreshes. If every field is skipped the job completes immediately.
-
-Idempotency key: `content_id | target_kind | target_language | model`, active-only partial
-unique index (completed/failed rows never block a retry).
-
-### Triggers
-
-1. **Manual.** Admin action on the item detail metadata editor: pick target language
-   (defaults to the library's `metadata_language`), `include_children`, `force`. Gated by
-   the same permission as metadata editing.
-2. **Auto fallback.** New `media_folders.auto_translate_metadata boolean NOT NULL DEFAULT
-   false`. At the end of a metadata refresh for an item (after provider localizations are
-   persisted in `internal/metadata/service.go`), if the folder has the flag, has a
-   `metadata_language`, that language differs from the item's default metadata language,
-   and the localization row for it is missing a translated field — enqueue a non-force job
-   for the item (children included for series). Enqueue is fire-and-forget; refresh latency
-   is unaffected.
-
-### API
-
-Admin-gated, mirroring the subtitle AI handler shapes:
-
- `GET  /api/v1/metadata/ai/status`
- `POST /api/v1/metadata/ai/translate` `{content_id, target_kind, target_language, include_children, force}`
- `GET  /api/v1/metadata/ai/jobs/{job_id}` / `POST …/cancel`
- `GET  /api/v1/metadata/ai/jobs?content_id=…`
-
-Progress UI polls the job endpoint (jobs are short; no websocket events in v1).
-
-## Whisper ASR
-
-### Kinds
-
-`subtitle_ai_jobs.kind` gains its reserved values:
-
- `transcribe` — audio track → subtitle track in the spoken language.
- `transcribe_translate` — `transcribe`, then the existing LLM translation chained to
-  `target_language`. Both the transcript track and the translated track are stored (the
-  transcript is a cache: a second target language skips ASR entirely because the transcript
-  is now a selectable text source for a plain `translate` job). `result_subtitle_id`
-  points at the translated track.
-
-For ASR kinds, `source_index` holds the **audio** track index (`-1` = default/first audio
-track); `source_language` is an optional hint passed to Whisper, else taken from the
-detected `verbose_json.language`.
-
-### Pipeline
-
-1. Resolve the audio track from `media_files`; reject files with no audio.
-2. Extract once with ffmpeg into fixed chunks in a job temp dir
-   (`-vn -map 0:a:<idx> -ac 1 -ar 16000 -c:a pcm_s16le -f segment -segment_time 600`):
-   16 kHz mono WAV, 10-minute chunks (~19 MB, under typical 25 MB API limits). Temp dir
-   removed on every exit path.
-3. Per chunk: `POST /v1/audio/transcriptions` (multipart: file, model,
-   `response_format=verbose_json`, optional `language`, `temperature=0`) via the shared
-   `llm.Client` with the shared retry/backoff. Segment timestamps are offset by the chunk
-   start and merged.
-4. Cue building: one cue per Whisper segment; text wrapped to at most two lines
-   (~42 chars/line). Empty/whitespace segments dropped.
-5. Store as `downloaded_subtitles` (provider `transcribed`, SRT, release name
-   `"<Language> (AI transcribed)"`), notify `SubtitleReady`.
-6. `transcribe_translate`: feed the cues to the existing `Translator`; store the translated
-   track (provider `translated`) and complete.
-
-Chunks are processed starting from the chunk containing the viewer's playhead, then
-wrapping — same UX as translation — and cues stream live to the requesting session through
-the existing notifier. Progress bands: extract 0–10 %, transcribe 10–70 % (per chunk),
-translate 70–95 %.
-
-Known v1 limitation: fixed chunk boundaries can clip a word at the seam; acceptable, noted
-for a silence-aligned follow-up.
-
-### API / UI
-
-The existing enqueue endpoint `POST /api/v1/subtitles/ai/translate` gains an optional
-`kind` (default `translate`; backward compatible). `GET /api/v1/subtitles/ai/status` gains
-`transcribe_enabled`. The player's translate modal gains a "Generate from audio" mode that
-lists audio tracks and a target language — the natural path when the only subtitle tracks
-are bitmap (today's hard error) or none exist.
-
-## Frontend
-
- **AI Services settings page** (`web/src/pages/admin-settings/`): connection card
-  (base URL, API key, chat model, ASR model, optional ASR base URL/key), features card
-  (subtitle translation, ASR, metadata translation toggles; concurrency; batch tuning).
-  The AI card currently inside `SubtitlesSettings.tsx` moves here; subtitle settings keep
-  the download-provider config.
- **Metadata editor**: "Translate with AI" action in `EditMetadataDialog.tsx` (language,
-  include children, force), with job-poll progress and query invalidation on completion.
- **Library settings**: `auto_translate_metadata` toggle next to the metadata-language
-  field.
- **Player**: "Generate from audio" mode in `SubtitleTranslateModal.tsx`.
-
-## Client (Android / Apple) impact
-
-None required. Translated overviews/taglines arrive through the existing localized detail
-responses; ASR/translated tracks arrive as ordinary downloaded subtitles. Optional
-follow-ups in the client repos: surface "Generate from audio" in their subtitle menus
-(the jobs API is shared) and the library auto-translate toggle in their admin surfaces.
-
-## Reliability
-
- All jobs: idempotency dedup of in-flight work, heartbeat + stale reaper (crash-safe,
-  multi-instance safe), terminal-state handling on cancel/shutdown — one implementation in
-  `jobrunner`, no copy-paste between the two services.
- Provider-wins/manual-wins provenance is enforced in SQL (single-statement upserts), not
-  in racy read-modify-write Go code.
- The shared semaphore bounds total endpoint load; ASR temp space is cleaned on success,
-  failure, cancel, and shutdown.
- Auto-translate re-runs are free: skip-if-filled happens before any LLM call.
-
-## Migrations
-
-One Goose migration (`make migrate-create NAME=ai_metadata_translation_and_asr`):
-
-1. `metadata_translation_jobs` table + active-idempotency / content / status indexes.
-2. Provenance columns on the three localization tables (+ check constraints).
-3. `media_folders.auto_translate_metadata`.
-
-Down: drop the table, columns, and constraint.
-
-## Risks / open questions
-
- **Whisper-endpoint compatibility.** OpenAI, Groq, faster-whisper-server/speaches all
-  speak `verbose_json`, but segment quality varies; the cue builder must tolerate missing
-  segment arrays (fall back to one cue per chunk worth of `text` is *not* acceptable —
-  fail the job with a clear message instead).
- **`LocalizeItemModel` empty-field semantics** must be verified before AI rows (empty
-  titles) ship; this is called out as an explicit plan task.
- **Long-running ASR on slow local Whisper servers** can exceed the 10-minute HTTP client
-  timeout per chunk; the transcription call uses a per-request timeout sized for chunk
-  duration rather than the client default.
- **Settings sprawl.** The `ai.*`/legacy fallback leaves old `subtitle_ai.*` connection
-  rows in place indefinitely; harmless, but a future settings-GC could prune them once the
-  new keys are written.
@@ -1,78 +0,0 @@
-# On-view description translation + per-profile metadata language — design
-
-**Date:** 2026-06-10
-**Status:** Approved direction (per-profile preference; auto with button fallback; any user behind an opt-in setting)
-**Builds on:** `docs/superpowers/specs/2026-06-10-ai-translation-and-asr-design.md`
-
-Commands assume the repository root is the cwd.
-
-## Problem
-
-Metadata translation currently triggers from the admin editor or the per-library
-refresh fallback, always targeting the library's metadata language. A viewer whose
-language differs from the library's (or whose library was never auto-translated) has
-no way to get descriptions in their language, and there is no per-person language
-preference at all — presentation language is library-scoped.
-
-## Design
-
-### Per-profile preferred metadata language
-
- New column `user_profiles.preferred_metadata_language text NOT NULL DEFAULT ''`
-  (empty = inherit the library's metadata language). Threaded through the profile
-  model/repo/API exactly like the existing `language` (UI language) field, plus a
-  picker in the profile settings UI with an "Inherit library default" option.
- `access.Scope` gains `PreferredMetadataLanguage`, populated when the access
-  resolver loads the profile, so every request already carries it.
- `catalog.AccessFilter` gains `ProfilePreferredLanguage`, and presentation language
-  resolution becomes: explicit `PresentationLanguage` (request param) →
-  **profile preference** → library `metadata_language`. Applied wherever the scope
-  is available (native API and jellycompat), so all clients get profile-localized
-  metadata server-side.
-
-### "Not in your language" signal
-
-`ItemDetail` gains `pending_translation_language` (omitted when empty): set when the
-resolved presentation language differs from the item's default metadata language,
-the base overview is non-empty, and no localization overview exists for that
-language. It is pure data — clients combine it with the AI feature status to decide
-what to render.
-
-### On-view trigger
-
- New setting `metadata_ai.on_view`: `off` (default) | `button` | `auto`, surfaced
-  on `GET /api/v1/metadata/ai/status` as `on_view`.
- New authenticated endpoint `POST /api/v1/items/{id}/translate-description`
-  `{target_language}` — any profile, gated by `metadata_ai` readiness +
-  `on_view != off`, item access enforced with the same `EnsureAccessible` check the
-  watched-state endpoints use. The client echoes back the language the server
-  reported in `pending_translation_language`.
- The endpoint goes through a new `Service.RequestOnView`, which adds one guard on
-  top of the existing pipeline: if the latest job for (content, language) failed
-  within a cooldown window, return it instead of enqueuing — a broken endpoint must
-  not be retried on every page view. Existing guarantees do the rest: in-flight
-  idempotency collapses concurrent viewers onto one job, skip-if-filled makes
-  repeats free, and the shared semaphore caps endpoint load.
-
-### Web UX
-
-On the detail page, when `pending_translation_language` is set:
-
- `on_view=auto`: fire the request on view (once per item), pulse-animate the
-  description while waiting, and poll the detail query until the flag clears (the
-  job's first batch translates the item's own overview, so this lands in seconds
-  even when a series job continues episodes in the background). Time out after ~45 s
-  and show the original text — no error states in the viewer's face.
- `on_view=button`: a small "Translate" chip near the description triggers the same
-  flow on click.
-
-No job-status endpoint for viewers: completion is observed as the flag clearing on
-refetch; failures surface only as the shimmer timing out (the cooldown stops
-re-triggering).
-
-## Non-goals
-
- Per-profile language in the Android/Apple UIs (server-side serving means they
-  already *receive* localized metadata; surfacing the trigger there is a client
-  follow-up using the same endpoint).
- Translating titles, or any admin-side behavior changes.
@@ -1,6 +1,6 @@
 module github.com/Silo-Server/silo-server

-go 1.26.4
+go 1.26.3

 require (
 	github.com/aws/aws-sdk-go-v2 v1.41.5
@@ -14,13 +14,12 @@ require (
 	github.com/prometheus/client_golang v1.23.2
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/redis/go-redis/v9 v9.18.0
-	golang.org/x/crypto v0.52.0
-	golang.org/x/sys v0.45.0
+	golang.org/x/crypto v0.50.0
+	golang.org/x/sys v0.43.0
 	gopkg.in/yaml.v3 v3.0.1
 )

 require (
-	github.com/SherClockHolmes/webpush-go v1.4.0
 	github.com/abadojack/whatlanggo v1.0.1
 	github.com/go-chi/cors v1.2.2
 	github.com/gorilla/websocket v1.5.3
@@ -30,40 +29,32 @@ require (
 	github.com/mmcdole/gofeed v1.3.0
 	github.com/oklog/ulid/v2 v2.1.0
 	github.com/pgvector/pgvector-go v0.3.0
-	github.com/pressly/goose/v3 v3.27.1
-	github.com/wneessen/go-mail v0.7.3
 	github.com/zishang520/socket.io/v2 v2.5.0
 	go.n16f.net/thumbhash v1.1.0
-	golang.org/x/image v0.41.0
-	golang.org/x/net v0.55.0
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529
+	golang.org/x/image v0.39.0
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 )

 require (
 	github.com/PuerkitoBio/goquery v1.8.0 // indirect
-	github.com/andybalholm/brotli v1.2.1 // indirect
+	github.com/andybalholm/brotli v1.2.0 // indirect
 	github.com/andybalholm/cascadia v1.3.1 // indirect
-	github.com/dunglas/httpsfv v1.1.0 // indirect
 	github.com/fatih/color v1.13.0 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/gookit/color v1.5.4 // indirect
 	github.com/hashicorp/yamux v0.1.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/compress v1.18.5 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
 	github.com/mattn/go-colorable v0.1.12 // indirect
-	github.com/mattn/go-isatty v0.0.21 // indirect
-	github.com/mfridman/interpolate v0.0.2 // indirect
+	github.com/mattn/go-isatty v0.0.17 // indirect
 	github.com/mmcdole/goxpp v1.1.1-0.20240225020742-a0c311522b23 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/oklog/run v1.1.0 // indirect
-	github.com/quic-go/qpack v0.6.0 // indirect
-	github.com/quic-go/quic-go v0.60.0 // indirect
-	github.com/quic-go/webtransport-go v0.10.0 // indirect
+	github.com/quic-go/qpack v0.5.1 // indirect
+	github.com/quic-go/quic-go v0.53.0 // indirect
 	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
-	github.com/sethvargo/go-retry v0.3.0 // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
 	github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778 // indirect
@@ -72,11 +63,15 @@ require (
 	github.com/zishang520/socket.io-go-parser/v2 v2.5.0 // indirect
 	github.com/zishang520/webtransport-go v0.9.1 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.41.0 // indirect
-	go.uber.org/multierr v1.11.0 // indirect
+	go.uber.org/mock v0.5.0 // indirect
+	golang.org/x/mod v0.34.0 // indirect
+	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 // indirect
 )

 require (
-	github.com/Silo-Server/silo-plugin-sdk v0.6.0
+	github.com/Silo-Server/silo-plugin-sdk v0.4.0
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 // indirect
@@ -95,16 +90,15 @@ require (
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/prometheus/common v0.66.1 // indirect
-	github.com/prometheus/procfs v0.20.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/sony/sonyflake v1.3.0
+	go.opentelemetry.io/otel v1.41.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/sync v0.20.0
-	golang.org/x/text v0.37.0
+	golang.org/x/text v0.36.0
 	golang.org/x/time v0.14.0
-	google.golang.org/grpc v1.80.0
+	google.golang.org/grpc v1.79.3
 	google.golang.org/protobuf v1.36.11
 )
-
-replace github.com/zishang520/webtransport-go => ./internal/compat/zishang520-webtransport-go
@@ -2,14 +2,12 @@ entgo.io/ent v0.14.3 h1:wokAV/kIlH9TeklJWGGS7AYJdVckr0DloWjIcO9iIIQ=
 entgo.io/ent v0.14.3/go.mod h1:aDPE/OziPEu8+OWbzy4UlvWmD2/kbRuWfK2A40hcxJM=
 github.com/PuerkitoBio/goquery v1.8.0 h1:PJTF7AmFCFKk1N6V6jmKfrNH9tV5pNE6lZMkG0gta/U=
 github.com/PuerkitoBio/goquery v1.8.0/go.mod h1:ypIiRMtY7COPGk+I/YbZLbxsxn9g5ejnI2HSMtkjZvI=
-github.com/SherClockHolmes/webpush-go v1.4.0 h1:ocnzNKWN23T9nvHi6IfyrQjkIc0oJWv1B1pULsf9i3s=
-github.com/SherClockHolmes/webpush-go v1.4.0/go.mod h1:XSq8pKX11vNV8MJEMwjrlTkxhAj1zKfxmyhdV7Pd6UA=
-github.com/Silo-Server/silo-plugin-sdk v0.6.0 h1:Gi9TdH9kt7b8X4xRXH493/nSYb9n0GO4VCWmlll0hKI=
-github.com/Silo-Server/silo-plugin-sdk v0.6.0/go.mod h1:etqmxLTwjxpFH9goAjBDfNDoqHMv2/sqUXu8yx3hNfA=
+github.com/Silo-Server/silo-plugin-sdk v0.4.0 h1:DJkRROQfr/kfwnF5dUdkhmbCso1KDLZc7uK7YfJnaO0=
+github.com/Silo-Server/silo-plugin-sdk v0.4.0/go.mod h1:etqmxLTwjxpFH9goAjBDfNDoqHMv2/sqUXu8yx3hNfA=
 github.com/abadojack/whatlanggo v1.0.1 h1:19N6YogDnf71CTHm3Mp2qhYfkRdyvbgwWdd2EPxJRG4=
 github.com/abadojack/whatlanggo v1.0.1/go.mod h1:66WiQbSbJBIlOZMsvbKe5m6pzQovxCH9B/K8tQB2uoc=
-github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
-github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/andybalholm/cascadia v1.3.1 h1:nhxRkql1kdYCc8Snf7D5/D3spOX+dBgjA6u8x004T2c=
 github.com/andybalholm/cascadia v1.3.1/go.mod h1:R4bJ1UQfqADjvDa4P6HZHLh/3OxWWEqc0Sk8XGwHqvA=
 github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
@@ -53,12 +51,10 @@ github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/r
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
 github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/dunglas/httpsfv v1.1.0 h1:Jw76nAyKWKZKFrpMMcL76y35tOpYHqQPzHQiwDvpe54=
-github.com/dunglas/httpsfv v1.1.0/go.mod h1:zID2mqw9mFsnt7YC3vYQ9/cjq30q41W+1AnDwH8TiMg=
-github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
-github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/fatih/color v1.13.0 h1:8LOYc1KYPPmyKMuN8QV2DNRWNbLo6LZ0iLs8+mlH53w=
 github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
+github.com/francoispqt/gojay v1.2.13 h1:d2m3sFjloqoIUQU3TsHBgj6qg/BVGlTBeHDUmyJnXKk=
+github.com/francoispqt/gojay v1.2.13/go.mod h1:ehT5mTG4ua4581f1++1WLG0vPdaA9HaiDsoyrBGkyDY=
 github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
 github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
 github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
@@ -71,12 +67,10 @@ github.com/go-pg/pg/v10 v10.11.0 h1:CMKJqLgTrfpE/aOVeLdybezR2om071Vh38OLZjsyMI0=
 github.com/go-pg/pg/v10 v10.11.0/go.mod h1:4BpHRoxE61y4Onpof3x1a2SQvi9c+q1dJnrNdMjsroA=
 github.com/go-pg/zerochecker v0.2.0 h1:pp7f72c3DobMWOb2ErtZsnrPaSvHd2W4o9//8HtF4mU=
 github.com/go-pg/zerochecker v0.2.0/go.mod h1:NJZ4wKL0NmTtz0GKCoJ8kym6Xn/EQzXRl2OnAe7MmDo=
-github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -114,8 +108,8 @@ github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
-github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
-github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
 github.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBFYa4=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -131,12 +125,10 @@ github.com/mattn/go-colorable v0.1.12 h1:jF+Du6AlPIjs2BiUiQlKOX0rt3SujHxPnksPKZb
 github.com/mattn/go-colorable v0.1.12/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
 github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
 github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94=
-github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
-github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-isatty v0.0.17 h1:BTarxUcIeDqL27Mc+vyvdWYSL28zpIhv3RoTdsLMPng=
+github.com/mattn/go-isatty v0.0.17/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
 github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
-github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
-github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
 github.com/mmcdole/gofeed v1.3.0 h1:5yn+HeqlcvjMeAI4gu6T+crm7d0anY85+M+v6fIFNG4=
 github.com/mmcdole/gofeed v1.3.0/go.mod h1:9TGv2LcJhdXePDzxiuMnukhV2/zb6VtnZt1mS+SjkLE=
 github.com/mmcdole/goxpp v1.1.1-0.20240225020742-a0c311522b23 h1:Zr92CAlFhy2gL+V1F+EyIuzbQNbSgP4xhTODZtrXUtk=
@@ -148,8 +140,6 @@ github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9G
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
-github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
-github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/oklog/run v1.1.0 h1:GEenZ1cK0+q0+wsJew9qUg/DyD8k3JzYsZAi5gYi2mA=
 github.com/oklog/run v1.1.0/go.mod h1:sVPdnTZT1zYwAJeCMu2Th4T21pA3FPOQRfWjQlk7DVU=
 github.com/oklog/ulid/v2 v2.1.0 h1:+9lhoxAP56we25tyYETBBY1YLA2SaoLvUFgrP2miPJU=
@@ -159,36 +149,26 @@ github.com/pgvector/pgvector-go v0.3.0 h1:Ij+Yt78R//uYqs3Zk35evZFvr+G0blW0OUN+Q2
 github.com/pgvector/pgvector-go v0.3.0/go.mod h1:duFy+PXWfW7QQd5ibqutBO4GxLsUZ9RVXhFZGIBsWSA=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/pressly/goose/v3 v3.27.1 h1:6uEvcprBybDmW4hcz3gYujhARhye+GoWKhEWyzD5sh4=
-github.com/pressly/goose/v3 v3.27.1/go.mod h1:maruOxsPnIG2yHHyo8UqKWXYKFcH7Q76csUV7+7KYoM=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
 github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
 github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
-github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
-github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
-github.com/quic-go/go-ossfuzz-seeds v0.1.0 h1:APacT+iIaNF6fd8AGEiN3bT/Jtkd2jz4v4TzM7MFjy0=
-github.com/quic-go/go-ossfuzz-seeds v0.1.0/go.mod h1:3IOHRbJIc+L6YKMwfDtJAM9Vj9k0YY4muhuyUYk5tbk=
-github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
-github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
-github.com/quic-go/quic-go v0.60.0 h1:xcQioE8OM66UQLeUMHltK1CCcOu3JbVB4JAQdDQSB+0=
-github.com/quic-go/quic-go v0.60.0/go.mod h1:wpKpjmPpftl30sL6pFh7REVpjbcCVy4zt2vDyK1TuJk=
-github.com/quic-go/webtransport-go v0.10.0 h1:LqXXPOXuETY5Xe8ITdGisBzTYmUOy5eSj+9n4hLTjHI=
-github.com/quic-go/webtransport-go v0.10.0/go.mod h1:LeGIXr5BQKE3UsynwVBeQrU1TPrbh73MGoC6jd+V7ow=
+github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
+github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
+github.com/quic-go/qpack v0.5.1 h1:giqksBPnT/HDtZ6VhtFKgoLOWmlyo9Ei6u9PqzIMbhI=
+github.com/quic-go/qpack v0.5.1/go.mod h1:+PC4XFrEskIVkcLzpEkbLqq1uCoxPhQuvK5rH1ZgaEg=
+github.com/quic-go/quic-go v0.53.0 h1:QHX46sISpG2S03dPeZBgVIZp8dGagIaiu2FiVYvpCZI=
+github.com/quic-go/quic-go v0.53.0/go.mod h1:e68ZEaCdyviluZmy44P6Iey98v/Wfz6HCjQEm+l8zTY=
 github.com/redis/go-redis/v9 v9.18.0 h1:pMkxYPkEbMPwRdenAzUNyFNrDgHx9U+DrBabWNfSRQs=
 github.com/redis/go-redis/v9 v9.18.0/go.mod h1:k3ufPphLU5YXwNTUcCRXGxUoF1fqxnhFQmscfkCoDA0=
-github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
-github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
 github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
-github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
-github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
 github.com/sony/sonyflake v1.3.0 h1:tiB4Dlp0lnmKp/h6BLXA14P8Qi+LYS9+0QRpcrKHvg4=
 github.com/sony/sonyflake v1.3.0/go.mod h1:LORtCywH/cq10ZbyfhKrHYgAUGH7mOBa76enV9txy/Y=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -213,15 +193,12 @@ github.com/vmihailenco/tagparser v0.1.2 h1:gnjoVuB/kljJ5wICEEOpx98oXMWPLj22G67Vb
 github.com/vmihailenco/tagparser v0.1.2/go.mod h1:OeAg3pn3UbLjkWt+rN9oFYB6u/cQgqMEUPoW2WPyhdI=
 github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
 github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
-github.com/wneessen/go-mail v0.7.3 h1:g3DravXC5SMlVdboFrQA8Jx95A8sOzoBeS5F+vzNRK0=
-github.com/wneessen/go-mail v0.7.3/go.mod h1:QGhBX0yNbc1J+Mkjcu7z2rpj4B4l+BmDY8gYznPC9sk=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
 github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778 h1:QldyIu/L63oPpyvQmHgvgickp1Yw510KJOqX7H24mg8=
 github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778/go.mod h1:2MuV+tbUrU1zIOPMxZ5EncGwgmMJsa+9ucAQZXxsObs=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
-github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
 github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
 github.com/zishang520/engine.io-go-parser v1.3.2 h1:aEVrhQVhfk99Ct6htNffgHydUBC4dGclO/OXPz5CSy0=
@@ -232,120 +209,66 @@ github.com/zishang520/socket.io-go-parser/v2 v2.5.0 h1:uGKTwcH2qrrs9uwzfCo3ems+q
 github.com/zishang520/socket.io-go-parser/v2 v2.5.0/go.mod h1:GK9GIIs/KQbBKfnxgZJMBYSlsFemB2rL7EFUn0kmTfM=
 github.com/zishang520/socket.io/v2 v2.5.0 h1:+KdZLbl4wWVzyI84RG+h21t8OY4ifz/Oo6qwgt9zHl8=
 github.com/zishang520/socket.io/v2 v2.5.0/go.mod h1:+GyoPyakXDS6KsW81RAQpDA9+mJBXbcYcQ+Itx2D+rU=
+github.com/zishang520/webtransport-go v0.9.1 h1:Y3gqPM8cIDvQILsTyXJ5G9fp2PYqGqLI2z+QXpgboQc=
+github.com/zishang520/webtransport-go v0.9.1/go.mod h1:IgNAD6qLe3oWu7MSSkjusRNftpvjYxWjI4LmoH4VEyY=
 go.n16f.net/thumbhash v1.1.0 h1:aBEvuAd4yiwzeQ7Sm4BZoHJYbrQ1ewjrmrRlCE79snk=
 go.n16f.net/thumbhash v1.1.0/go.mod h1:mo9pP7WtfdV9ojIamGFR/Vc0PaPA2l0CUtmYQf/SweU=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
-go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
-go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
-go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
+go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
+go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
+go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
 go.opentelemetry.io/otel/sdk v1.41.0 h1:YPIEXKmiAwkGl3Gu1huk1aYWwtpRLeskpV+wPisxBp8=
 go.opentelemetry.io/otel/sdk v1.41.0/go.mod h1:ahFdU0G5y8IxglBf0QBJXgSe7agzjE4GiTJ6HT9ud90=
 go.opentelemetry.io/otel/sdk/metric v1.41.0 h1:siZQIYBAUd1rlIWQT2uCxWJxcCO7q3TriaMlf08rXw8=
 go.opentelemetry.io/otel/sdk/metric v1.41.0/go.mod h1:HNBuSvT7ROaGtGI50ArdRLUnvRTRGniSUZbxiWxSO8Y=
-go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
-go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
+go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
 go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-go.uber.org/mock v0.5.2 h1:LbtPTcP8A5k9WPXj54PPPbjcI4Y6lhyOZXn+VS7wNko=
-go.uber.org/mock v0.5.2/go.mod h1:wLlUxC2vVTPTaE3UD51E0BGOAElKrILxhVSDYQLld5o=
-go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
-go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/mock v0.5.0 h1:KAMbZvZPyBPWgD14IrIQ38QCyjwpvVVV6K/bHl1IwQU=
+go.uber.org/mock v0.5.0/go.mod h1:ge71pBPLYDk7QIi1LupWxdAykm7KIEFchiOqd6z7qMM=
 go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
 go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
-golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
-golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
-golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
-golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
-golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
-golang.org/x/image v0.41.0 h1:8wS72eGJMJaBxK6okTzd4WaXumUlTVlb753MlsSvTCo=
-golang.org/x/image v0.41.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=
-golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
-golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
-golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
+golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+golang.org/x/image v0.39.0 h1:skVYidAEVKgn8lZ602XO75asgXBgLj9G/FE3RbuPFww=
+golang.org/x/image v0.39.0/go.mod h1:sIbmppfU+xFLPIG0FoVUTvyBMmgng1/XAMhQ2ft0hpA=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
 golang.org/x/net v0.0.0-20210916014120-12bc252f5db8/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
-golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
-golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
-golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
-golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
-golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
-golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
-golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
-golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
-golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210927094055-39ccf1dd6fa6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220503163025-988cb79eb6c6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
-golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
-golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
-golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
-golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
-golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
-golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
-golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
-golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
-golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
-golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
-golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
 golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
 golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
-golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
-golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
-gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529 h1:XF8+t6QQiS0o9ArVan/HW8Q7cycNPGsJf6GA2nXxYAg=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
-google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
+gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 h1:gRkg/vSppuSQoDjxyiGfN4Upv/h/DQmIR10ZU8dh4Ww=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217/go.mod h1:7i2o+ce6H/6BluujYR+kqX3GKH+dChPTQU19wjRPiGk=
+google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
+google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -362,11 +285,3 @@ gorm.io/gorm v1.25.5 h1:zR9lOiiYf09VNh5Q1gphfyia1JpiClIWG9hQaxB/mls=
 gorm.io/gorm v1.25.5/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
 mellium.im/sasl v0.3.1 h1:wE0LW6g7U83vhvxjC1IY8DnXM+EU095yeo8XClvCdfo=
 mellium.im/sasl v0.3.1/go.mod h1:xm59PUYpZHhgQ9ZqoJ5QaCqzWMi8IeS49dhp6plPCzw=
-modernc.org/libc v1.72.1 h1:db1xwJ6u1kE3KHTFTTbe2GCrczHPKzlURP0aDC4NGD0=
-modernc.org/libc v1.72.1/go.mod h1:HRMiC/PhPGLIPM7GzAFCbI+oSgE3dhZ8FWftmRrHVlY=
-modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
-modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
-modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
-modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/sqlite v1.49.1 h1:dYGHTKcX1sJ+EQDnUzvz4TJ5GbuvhNJa8Fg6ElGx73U=
-modernc.org/sqlite v1.49.1/go.mod h1:m0w8xhwYUVY3H6pSDwc3gkJ/irZT/0YEXwBlhaxQEew=
@@ -73,7 +73,6 @@ func (r *Resolver) Resolve(ctx context.Context, input ResolveInput) (Scope, erro

 		scope.MaxContentRating = profile.MaxContentRating
 		scope.MaxPlaybackQuality = MinQuality(scope.MaxPlaybackQuality, NormalizePlaybackQuality(profile.MaxPlaybackQuality))
-		scope.PreferredMetadataLanguage = profile.PreferredMetadataLanguage
 		scope.AllowedLibraryIDs, scope.LibrariesRestricted = effectiveLibraries(user.LibraryIDs, profile)
 		scope.ProfileVerified = profile.PINHash == "" || input.SkipPINVerification

@@ -9,11 +9,8 @@ type Scope struct {
 	LibrariesRestricted bool
 	MaxContentRating    string
 	MaxPlaybackQuality  string
-	// PreferredMetadataLanguage is the profile's metadata (presentation)
-	// language; "" inherits the library's metadata language.
-	PreferredMetadataLanguage string
-	PolicyRevision            int64
-	ProfileVerified           bool
+	PolicyRevision      int64
+	ProfileVerified     bool
 }

 // ResolveInput is the request input for resolving a viewer access scope.
@@ -1,55 +0,0 @@
-package adminjob
-
-import (
-	"context"
-	"sync"
-)
-
-// CancelRegistry bridges HTTP cancellation requests to in-process job contexts.
-// Queued jobs are cancelled in the repository; running jobs need their active
-// context cancelled so executors stop doing work before the row is finalized.
-type CancelRegistry struct {
-	mu      sync.Mutex
-	cancels map[string]cancelEntry
-}
-
-type cancelEntry struct {
-	cancel context.CancelFunc
-	token  *struct{}
-}
-
-func NewCancelRegistry() *CancelRegistry {
-	return &CancelRegistry{cancels: make(map[string]cancelEntry)}
-}
-
-func (r *CancelRegistry) Register(jobID string, cancel context.CancelFunc) func() {
-	if r == nil || jobID == "" || cancel == nil {
-		return func() {}
-	}
-	token := &struct{}{}
-	r.mu.Lock()
-	r.cancels[jobID] = cancelEntry{cancel: cancel, token: token}
-	r.mu.Unlock()
-
-	return func() {
-		r.mu.Lock()
-		if entry := r.cancels[jobID]; entry.token == token {
-			delete(r.cancels, jobID)
-		}
-		r.mu.Unlock()
-	}
-}
-
-func (r *CancelRegistry) Cancel(jobID string) bool {
-	if r == nil || jobID == "" {
-		return false
-	}
-	r.mu.Lock()
-	cancel := r.cancels[jobID].cancel
-	r.mu.Unlock()
-	if cancel == nil {
-		return false
-	}
-	cancel()
-	return true
-}
@@ -542,19 +542,17 @@ func (e *ItemRefreshExecutor) Execute(ctx context.Context, req ItemRefreshReques
 	e.publish(cache.EventMetadataUpdated, refreshContentID)
 	if e.realtimeHub != nil {
 		if scanResult != nil && (scanResult.New > 0 || scanResult.Updated > 0 || scanResult.Missing > 0 || matched > 0) {
-			_ = e.realtimeHub.PublishCatalogLibraryChanged(ctx, notifications.LibraryChangeEvent{
+			_ = e.realtimeHub.PublishLibraryChanged(ctx, notifications.LibraryChangeEvent{
 				LibraryID:    req.ScanFolderID,
-				Reason:       "item_refresh",
 				New:          scanResult.New,
 				Updated:      scanResult.Updated,
 				Missing:      scanResult.Missing,
 				MatchedFiles: matched,
 			})
 		}
-		_ = e.realtimeHub.PublishCatalogItemChanged(ctx, notifications.MetadataUpdateEvent{
+		_ = e.realtimeHub.PublishMetadataUpdated(ctx, notifications.MetadataUpdateEvent{
 			LibraryID: req.ScanFolderID,
 			ContentID: refreshContentID,
-			Change:    "metadata_updated",
 		})
 	}

@@ -251,9 +251,8 @@ func (e *LibraryRefreshExecutor) Execute(
 	if result.RefreshedOK > 0 || result.PipelineOK > 0 {
 		e.publish(cache.EventMetadataUpdated, strconv.Itoa(req.LibraryID))
 		if e.realtimeHub != nil {
-			_ = e.realtimeHub.PublishCatalogItemChanged(ctx, notifications.MetadataUpdateEvent{
+			_ = e.realtimeHub.PublishMetadataUpdated(ctx, notifications.MetadataUpdateEvent{
 				LibraryID: req.LibraryID,
-				Change:    "metadata_updated",
 			})
 		}
 	}
@@ -322,7 +321,6 @@ func (e *LibraryRefreshExecutor) refreshItemsWithIDs(
 				result.RefreshedFailed++
 			} else {
 				result.RefreshedOK++
-				e.publishCatalogItemChanged(ctx, result.LibraryID, itemResult.contentID)
 			}
 			advance("Refreshing items with external IDs")
 		}
@@ -388,7 +386,6 @@ func (e *LibraryRefreshExecutor) refreshUnmatchedItem(ctx context.Context, libra
 	if err := e.refresher.RefreshItemForLibrary(ctx, req.RefreshContentID, req.ScanFolderID); err != nil {
 		return fmt.Errorf("refresh metadata: %w", err)
 	}
-	e.publishCatalogItemChanged(ctx, libraryID, req.RefreshContentID)
 	return nil
 }

@@ -402,17 +399,6 @@ func (e *LibraryRefreshExecutor) publish(eventType, payload string) {
 	})
 }

-func (e *LibraryRefreshExecutor) publishCatalogItemChanged(ctx context.Context, libraryID int, contentID string) {
-	if e == nil || e.realtimeHub == nil || contentID == "" {
-		return
-	}
-	_ = e.realtimeHub.PublishCatalogItemChanged(ctx, notifications.MetadataUpdateEvent{
-		LibraryID: libraryID,
-		ContentID: contentID,
-		Change:    "metadata_updated",
-	})
-}
-
 func decodeLibraryRefreshRequest(data json.RawMessage) (LibraryRefreshRequest, error) {
 	var req LibraryRefreshRequest
 	if len(data) == 0 {
@@ -24,13 +24,11 @@ const (
 	StatusRunning   = "running"
 	StatusCompleted = "completed"
 	StatusFailed    = "failed"
-	StatusCancelled = "cancelled"
 )

 var (
 	ErrJobNotFound       = errors.New("admin job not found")
 	ErrActiveJobConflict = errors.New("admin job already active for type")
-	ErrJobNotCancellable = errors.New("admin job is not cancellable")
 )

 type ActiveJobConflictError struct {
@@ -473,83 +471,6 @@ func (r *Repository) Fail(ctx context.Context, id string, input FailJobInput) er
 	return nil
 }

-func (r *Repository) Cancel(ctx context.Context, id, message string, expiresAt time.Time) (*models.AdminJob, error) {
-	if message == "" {
-		message = "Admin job cancelled"
-	}
-	job, err := scanAdminJob(r.pool.QueryRow(ctx, `
-		UPDATE admin_jobs
-		SET status = $2,
-			message = $3,
-			error_message = '',
-			completed_at = NOW(),
-			heartbeat_at = NOW(),
-			expires_at = $4,
-			updated_at = NOW()
-		WHERE id = $1
-		  AND status IN ($5, $6)
-		RETURNING `+adminJobColumns,
-		id,
-		StatusCancelled,
-		message,
-		expiresAt,
-		StatusQueued,
-		StatusRunning,
-	))
-	if err == nil {
-		return job, nil
-	}
-	if !errors.Is(err, ErrJobNotFound) {
-		return nil, err
-	}
-	existing, lookupErr := r.GetByID(ctx, id)
-	if lookupErr != nil {
-		return nil, lookupErr
-	}
-	if existing.Status != StatusQueued && existing.Status != StatusRunning {
-		return nil, ErrJobNotCancellable
-	}
-	return nil, ErrJobNotFound
-}
-
-func (r *Repository) CancelQueued(ctx context.Context, id, message string, expiresAt time.Time) (*models.AdminJob, error) {
-	if message == "" {
-		message = "Admin job cancelled"
-	}
-	job, err := scanAdminJob(r.pool.QueryRow(ctx, `
-		UPDATE admin_jobs
-		SET status = $2,
-			message = $3,
-			error_message = '',
-			completed_at = NOW(),
-			heartbeat_at = NOW(),
-			expires_at = $4,
-			updated_at = NOW()
-		WHERE id = $1
-		  AND status = $5
-		RETURNING `+adminJobColumns,
-		id,
-		StatusCancelled,
-		message,
-		expiresAt,
-		StatusQueued,
-	))
-	if err == nil {
-		return job, nil
-	}
-	if !errors.Is(err, ErrJobNotFound) {
-		return nil, err
-	}
-	existing, lookupErr := r.GetByID(ctx, id)
-	if lookupErr != nil {
-		return nil, lookupErr
-	}
-	if existing.Status != StatusQueued {
-		return nil, ErrJobNotCancellable
-	}
-	return nil, ErrJobNotFound
-}
-
 func (r *Repository) RequeueStaleRunning(ctx context.Context, before time.Time) (int, error) {
 	tag, err := r.pool.Exec(ctx, `
 		UPDATE admin_jobs
@@ -57,7 +57,6 @@ type Runner struct {
 	heartbeatInterval   time.Duration
 	staleAfter          time.Duration
 	retention           time.Duration
-	cancelRegistry      *CancelRegistry
 	stop                chan struct{}
 	stopOnce            sync.Once
 }
@@ -100,17 +99,10 @@ func NewRunner(
 		heartbeatInterval:   10 * time.Second,
 		staleAfter:          2 * time.Minute,
 		retention:           7 * 24 * time.Hour,
-		cancelRegistry:      NewCancelRegistry(),
 		stop:                make(chan struct{}),
 	}
 }

-func (r *Runner) SetCancelRegistry(registry *CancelRegistry) {
-	if registry != nil {
-		r.cancelRegistry = registry
-	}
-}
-
 func (r *Runner) Start() {
 	go func() {
 		r.requeueStaleJobs()
@@ -337,8 +329,6 @@ func (r *Runner) executeLibraryRefresh(job *models.AdminJob) {

 	ctx, cancel := context.WithTimeout(context.Background(), libraryRefreshTimeout)
 	defer cancel()
-	unregisterCancel := r.cancelRegistry.Register(job.ID, cancel)
-	defer unregisterCancel()

 	heartbeatStop := make(chan struct{})
 	go r.heartbeatLoop(ctx, job.ID, heartbeatStop)
@@ -367,10 +357,6 @@ func (r *Runner) executeLibraryRefresh(job *models.AdminJob) {
 		r.publishJobByID(ctx, notifications.TypeJobProgress, job.ID)
 	})
 	if err != nil {
-		if errors.Is(ctx.Err(), context.Canceled) {
-			r.cancelJob(job.ID, current, total, "Library metadata refresh cancelled")
-			return
-		}
 		msg := err.Error()
 		if ctx.Err() != nil {
 			msg = fmt.Sprintf("timed out after %s: %s", libraryRefreshTimeout, msg)
@@ -860,21 +846,3 @@ func (r *Runner) failJob(id string, current, total int, message, errorMessage st
 	}
 	r.publishJobByID(ctx, notifications.TypeJobFailed, id)
 }
-
-func (r *Runner) cancelJob(id string, current, total int, message string) {
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-	if err := r.repo.UpdateProgress(ctx, id, current, total, message); err != nil {
-		slog.Warn("admin jobs: failed to update cancellation progress", "job_id", id, "error", err)
-	}
-	job, err := r.repo.Cancel(ctx, id, message, time.Now().UTC().Add(r.retention))
-	if err != nil {
-		slog.Warn("admin jobs: failed to mark job cancelled", "job_id", id, "error", err)
-		return
-	}
-	if r.realtimeHub != nil {
-		if err := r.realtimeHub.PublishJob(ctx, notifications.TypeJobCancelled, job); err != nil {
-			slog.Warn("admin jobs: failed to publish job cancellation", "job_id", id, "error", err)
-		}
-	}
-}
@@ -1,197 +0,0 @@
-// Package jobrunner owns the lifecycle mechanics shared by Silo's AI job
-// services (subtitle translation/ASR, metadata translation): bounded dispatch
-// off a semaphore shared across services, a heartbeat loop that keeps a row
-// alive even while the job is queued, a stale-job reaper for rows orphaned by
-// a crashed worker, and a per-job cancel registry. The services keep their own
-// job tables, validation, and run logic; this package keeps them honest about
-// concurrency and crash recovery without copy-pasting the trickiest code.
-package jobrunner
-
-import (
-	"context"
-	"log/slog"
-	"sync"
-	"time"
-)
-
-const (
-	// A running job refreshes its heartbeat every HeartbeatInterval; one whose
-	// heartbeat has not advanced for StaleJobThreshold is treated as orphaned
-	// by a crashed worker and reaped. The margin over HeartbeatInterval avoids
-	// reaping a job that is merely mid–LLM-call.
-	HeartbeatInterval = 30 * time.Second
-	StaleJobThreshold = 2 * time.Minute
-	// How often the background reaper scans for orphaned jobs.
-	ReaperInterval = time.Minute
-)
-
-// Store is the minimal persistence surface the runner needs. Both AI job
-// repositories satisfy it.
-type Store interface {
-	Heartbeat(ctx context.Context, id int64) error
-	// ResetStaleJobs marks pending/running jobs whose heartbeat predates
-	// `before` as failed with the given message. Returns rows reset.
-	ResetStaleJobs(ctx context.Context, before time.Time, message string) (int64, error)
-}
-
-// NewSemaphore builds the dispatch semaphore shared across runners, so the
-// configured endpoint sees one global bound regardless of job mix. size <= 0
-// falls back to 2.
-func NewSemaphore(size int) chan struct{} {
-	if size <= 0 {
-		size = 2
-	}
-	return make(chan struct{}, size)
-}
-
-// Runner executes jobs with bounded concurrency, heartbeats, cancellation,
-// and crash recovery. One Runner per job table; the semaphore may be shared
-// across Runners.
-type Runner struct {
-	// baseCtx is the application context; dispatched jobs and the reaper
-	// derive from it so they stop when the server shuts down.
-	baseCtx context.Context
-	sem     chan struct{}
-	store   Store
-	// label names the job family in log lines ("subtitle ai", "metadata translation").
-	label  string
-	logger *slog.Logger
-
-	mu      sync.Mutex
-	cancels map[int64]context.CancelFunc
-	wg      sync.WaitGroup
-}
-
-// New wires a runner. A nil appCtx falls back to context.Background(); a nil
-// sem gets a private default-size semaphore (used by tests; production passes
-// the shared one).
-func New(appCtx context.Context, sem chan struct{}, store Store, label string, logger *slog.Logger) *Runner {
-	if appCtx == nil {
-		appCtx = context.Background()
-	}
-	if sem == nil {
-		sem = NewSemaphore(0)
-	}
-	if logger == nil {
-		logger = slog.Default()
-	}
-	return &Runner{
-		baseCtx: appCtx,
-		sem:     sem,
-		store:   store,
-		label:   label,
-		logger:  logger,
-		cancels: make(map[int64]context.CancelFunc),
-	}
-}
-
-// Recover clears jobs orphaned by a crashed worker and starts a background
-// reaper that keeps doing so. Reaping is heartbeat-based (not "every active
-// job"), so it is safe when multiple instances share one database: a job
-// still being heartbeat-updated by a live worker is never reset. Call once at
-// startup; jobs and the reaper derive from the application context, so they
-// stop on shutdown.
-func (r *Runner) Recover() {
-	r.reapStaleJobs()
-	go r.reaperLoop()
-}
-
-func (r *Runner) reaperLoop() {
-	ticker := time.NewTicker(ReaperInterval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-r.baseCtx.Done():
-			return
-		case <-ticker.C:
-			r.reapStaleJobs()
-		}
-	}
-}
-
-func (r *Runner) reapStaleJobs() {
-	before := time.Now().Add(-StaleJobThreshold)
-	n, err := r.store.ResetStaleJobs(context.WithoutCancel(r.baseCtx), before, "interrupted by server restart")
-	if err != nil {
-		r.logger.Warn("failed to reset stale jobs", "jobs", r.label, "error", err)
-		return
-	}
-	if n > 0 {
-		r.logger.Info("reset stale jobs", "jobs", r.label, "count", n)
-	}
-}
-
-// Dispatch launches a bounded background goroutine for job id. run executes
-// once a semaphore slot is acquired; onAbort runs instead if the job is
-// cancelled (user cancel or shutdown) while still waiting for a slot. Both
-// receive a context derived from the application context that is cancelled by
-// Cancel(id) or server shutdown.
-func (r *Runner) Dispatch(id int64, run func(ctx context.Context), onAbort func(ctx context.Context)) {
-	runCtx, cancel := context.WithCancel(r.baseCtx)
-	r.mu.Lock()
-	r.cancels[id] = cancel
-	r.mu.Unlock()
-
-	r.wg.Add(1)
-	go func() {
-		defer r.wg.Done()
-		defer func() {
-			r.mu.Lock()
-			delete(r.cancels, id)
-			r.mu.Unlock()
-			cancel()
-		}()
-
-		// Heartbeat for the whole lifetime — crucially including while queued
-		// behind the semaphore — so the stale-job reaper never reaps a job that
-		// is alive but merely waiting for a slot (which would otherwise mark it
-		// failed and let it resurrect itself on acquire, or admit a duplicate).
-		stopHeartbeat := make(chan struct{})
-		defer close(stopHeartbeat)
-		go r.heartbeatLoop(runCtx, id, stopHeartbeat)
-
-		select {
-		case r.sem <- struct{}{}:
-		case <-runCtx.Done():
-			if onAbort != nil {
-				onAbort(context.WithoutCancel(runCtx))
-			}
-			return
-		}
-		defer func() { <-r.sem }()
-
-		run(runCtx)
-	}()
-}
-
-// Cancel cancels the in-flight goroutine for id, returning false when none is
-// registered (job on another node, or never dispatched) so the caller can
-// fall back to a best-effort terminal transition in the database.
-func (r *Runner) Cancel(id int64) bool {
-	r.mu.Lock()
-	cancel := r.cancels[id]
-	r.mu.Unlock()
-	if cancel == nil {
-		return false
-	}
-	cancel()
-	return true
-}
-
-// heartbeatLoop keeps a job's heartbeat_at fresh until the job ends or the
-// context is cancelled, so the stale-job reaper only ever reaps jobs orphaned
-// by a crashed worker.
-func (r *Runner) heartbeatLoop(ctx context.Context, jobID int64, stop <-chan struct{}) {
-	ticker := time.NewTicker(HeartbeatInterval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-stop:
-			return
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			_ = r.store.Heartbeat(context.WithoutCancel(ctx), jobID)
-		}
-	}
-}
@@ -1,158 +0,0 @@
-package jobrunner
-
-import (
-	"context"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-)
-
-type fakeStore struct {
-	mu         sync.Mutex
-	heartbeats int
-	resets     int
-	lastBefore time.Time
-}
-
-func (s *fakeStore) Heartbeat(context.Context, int64) error {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.heartbeats++
-	return nil
-}
-
-func (s *fakeStore) ResetStaleJobs(_ context.Context, before time.Time, _ string) (int64, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.resets++
-	s.lastBefore = before
-	return 0, nil
-}
-
-func (s *fakeStore) snapshot() (int, time.Time) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return s.resets, s.lastBefore
-}
-
-func TestRecoverReapsImmediatelyWithStaleCutoff(t *testing.T) {
-	store := &fakeStore{}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	approxNow := time.Now()
-	New(ctx, nil, store, "test", nil).Recover()
-
-	resets, before := store.snapshot()
-	if resets < 1 {
-		t.Fatalf("Recover did not reap immediately: resets=%d", resets)
-	}
-	want := approxNow.Add(-StaleJobThreshold)
-	if diff := before.Sub(want); diff > 2*time.Second || diff < -2*time.Second {
-		t.Errorf("stale cutoff = %v, want ~%v", before, want)
-	}
-}
-
-// One shared semaphore bounds jobs across BOTH runners: with size 1, the
-// second runner's job must not start until the first runner's job finishes.
-func TestSharedSemaphoreBoundsAcrossRunners(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	sem := NewSemaphore(1)
-	r1 := New(ctx, sem, &fakeStore{}, "one", nil)
-	r2 := New(ctx, sem, &fakeStore{}, "two", nil)
-
-	release := make(chan struct{})
-	aStarted := make(chan struct{})
-	var bStarted atomic.Bool
-	bDone := make(chan struct{})
-
-	r1.Dispatch(1, func(context.Context) {
-		close(aStarted)
-		<-release
-	}, nil)
-	<-aStarted
-
-	r2.Dispatch(2, func(context.Context) {
-		bStarted.Store(true)
-		close(bDone)
-	}, nil)
-
-	time.Sleep(50 * time.Millisecond)
-	if bStarted.Load() {
-		t.Fatal("job B ran while job A held the only slot")
-	}
-	close(release)
-	select {
-	case <-bDone:
-	case <-time.After(2 * time.Second):
-		t.Fatal("job B never ran after the slot freed")
-	}
-}
-
-// Cancelling a job that is queued behind the semaphore aborts it without
-// running it, via the onAbort callback.
-func TestCancelWhileQueuedCallsOnAbort(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	sem := NewSemaphore(1)
-	r := New(ctx, sem, &fakeStore{}, "test", nil)
-
-	release := make(chan struct{})
-	defer close(release)
-	started := make(chan struct{})
-	r.Dispatch(1, func(context.Context) {
-		close(started)
-		<-release
-	}, nil)
-	<-started
-
-	var ran atomic.Bool
-	aborted := make(chan struct{})
-	r.Dispatch(2, func(context.Context) {
-		ran.Store(true)
-	}, func(context.Context) {
-		close(aborted)
-	})
-
-	if !r.Cancel(2) {
-		t.Fatal("Cancel(2) found no in-flight goroutine")
-	}
-	select {
-	case <-aborted:
-	case <-time.After(2 * time.Second):
-		t.Fatal("onAbort never ran")
-	}
-	if ran.Load() {
-		t.Fatal("cancelled queued job still ran")
-	}
-}
-
-func TestCancelUnknownJobReturnsFalse(t *testing.T) {
-	r := New(context.Background(), nil, &fakeStore{}, "test", nil)
-	if r.Cancel(99) {
-		t.Fatal("Cancel(99) = true for unknown job")
-	}
-}
-
-// The run context is cancelled by Cancel(id) so an in-flight job can stop.
-func TestCancelRunningJobCancelsContext(t *testing.T) {
-	r := New(context.Background(), NewSemaphore(1), &fakeStore{}, "test", nil)
-	started := make(chan struct{})
-	stopped := make(chan struct{})
-	r.Dispatch(7, func(ctx context.Context) {
-		close(started)
-		<-ctx.Done()
-		close(stopped)
-	}, nil)
-	<-started
-	if !r.Cancel(7) {
-		t.Fatal("Cancel(7) found no in-flight goroutine")
-	}
-	select {
-	case <-stopped:
-	case <-time.After(2 * time.Second):
-		t.Fatal("running job did not observe cancellation")
-	}
-}
@@ -1,22 +0,0 @@
-package jobrunner
-
-// Status is the lifecycle state shared by every AI job table.
-type Status string
-
-const (
-	StatusPending   Status = "pending"
-	StatusRunning   Status = "running"
-	StatusCompleted Status = "completed"
-	StatusFailed    Status = "failed"
-	StatusCancelled Status = "cancelled"
-)
-
-// Terminal reports whether a status is final.
-func (s Status) Terminal() bool {
-	switch s {
-	case StatusCompleted, StatusFailed, StatusCancelled:
-		return true
-	default:
-		return false
-	}
-}
@@ -1,314 +0,0 @@
-// Package llm provides the shared OpenAI-compatible API client used by every
-// AI feature in Silo (subtitle translation, metadata translation, Whisper ASR).
-// One endpoint configuration, one retry/backoff implementation; the operator
-// can point it at OpenAI, Groq, a local Ollama/llama.cpp/faster-whisper
-// server, etc.
-package llm
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"log/slog"
-	"net/http"
-	"strconv"
-	"strings"
-	"sync/atomic"
-	"time"
-)
-
-// Config holds the connection settings for the shared OpenAI-compatible
-// endpoints. The ASR fields are optional overrides for operators who run a
-// separate Whisper-compatible server next to their chat endpoint; when empty,
-// transcription uses the chat endpoint's base URL and key.
-type Config struct {
-	BaseURL   string // e.g. "https://api.openai.com" (no trailing /v1)
-	APIKey    string // empty for keyless local servers
-	ChatModel string // chat-completions model used for translation
-
-	ASRBaseURL string // optional; empty = BaseURL
-	ASRAPIKey  string // optional; empty = APIKey
-	ASRModel   string // audio-transcription model, e.g. "whisper-1"
-}
-
-func (c Config) asrBaseURL() string {
-	if c.ASRBaseURL != "" {
-		return c.ASRBaseURL
-	}
-	return c.BaseURL
-}
-
-func (c Config) asrAPIKey() string {
-	if c.ASRAPIKey != "" {
-		return c.ASRAPIKey
-	}
-	return c.APIKey
-}
-
-// ChatConfigured reports whether chat completions are minimally configured.
-func (c Config) ChatConfigured() bool { return c.BaseURL != "" && c.ChatModel != "" }
-
-// ASRConfigured reports whether audio transcription is minimally configured.
-func (c Config) ASRConfigured() bool { return c.asrBaseURL() != "" && c.ASRModel != "" }
-
-// Client is a minimal OpenAI-compatible API client with shared retry/backoff
-// conventions (429 with Retry-After, 5xx, transport errors, and gateway "200
-// with embedded error object" responses are retried; other 4xx fail fast).
-// The config is held behind an atomic pointer so admin settings changes apply
-// to subsequent requests without rebuilding the client; each request snapshots
-// the config once so its URL, key, and model stay consistent.
-type Client struct {
-	cfg atomic.Pointer[Config]
-	// chatHTTP caps a single chat completion at 10 minutes. asrHTTP has no
-	// client-level timeout: a transcription upload's deadline is set per request
-	// (sized to the chunk duration), which a client timeout would silently cap.
-	chatHTTP *http.Client
-	asrHTTP  *http.Client
-}
-
-// NewClient builds a client from the endpoint config.
-func NewClient(cfg Config) *Client {
-	c := &Client{
-		chatHTTP: &http.Client{Timeout: 10 * time.Minute},
-		asrHTTP:  &http.Client{},
-	}
-	c.UpdateConfig(cfg)
-	return c
-}
-
-// UpdateConfig swaps the endpoint config. Safe for concurrent use; in-flight
-// requests finish with the config they started with.
-func (c *Client) UpdateConfig(cfg Config) {
-	c.cfg.Store(&cfg)
-}
-
-// Config returns a snapshot of the current endpoint config.
-func (c *Client) Config() Config {
-	return *c.cfg.Load()
-}
-
-// Message is one chat-completions message.
-type Message struct {
-	Role    string `json:"role"`
-	Content string `json:"content"`
-}
-
-type chatResponseFormat struct {
-	Type string `json:"type"`
-}
-
-type chatCompletionRequest struct {
-	Model          string              `json:"model"`
-	Messages       []Message           `json:"messages"`
-	Temperature    float32             `json:"temperature"`
-	ResponseFormat *chatResponseFormat `json:"response_format,omitempty"`
-}
-
-type chatCompletionResponse struct {
-	Choices []struct {
-		Message Message `json:"message"`
-	} `json:"choices"`
-	// Some OpenAI-compatible gateways (e.g. OpenRouter) return a 200 with an
-	// error object instead of an HTTP error status when an upstream provider
-	// fails. We surface and retry on it.
-	Error *struct {
-		Message string `json:"message"`
-	} `json:"error"`
-}
-
-// Chat performs one chat completion and returns the first choice's content.
-// When jsonObject is true it requests response_format=json_object; providers
-// that ignore the field still work because the prompt itself demands JSON.
-func (c *Client) Chat(ctx context.Context, messages []Message, jsonObject bool) (string, error) {
-	cfg := c.Config()
-	reqBody := chatCompletionRequest{
-		Model:       cfg.ChatModel,
-		Messages:    messages,
-		Temperature: 0.2,
-	}
-	if jsonObject {
-		reqBody.ResponseFormat = &chatResponseFormat{Type: "json_object"}
-	}
-
-	body, err := json.Marshal(reqBody)
-	if err != nil {
-		return "", fmt.Errorf("marshal chat request: %w", err)
-	}
-
-	url := endpointURL(cfg.BaseURL, "chat/completions")
-
-	var content string
-	err = c.doWithRetry(ctx, c.chatHTTP, "chat API",
-		func() (*http.Request, error) {
-			httpReq, reqErr := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
-			if reqErr != nil {
-				return nil, fmt.Errorf("create request: %w", reqErr)
-			}
-			httpReq.Header.Set("Content-Type", "application/json")
-			if cfg.APIKey != "" {
-				httpReq.Header.Set("Authorization", "Bearer "+cfg.APIKey)
-			}
-			return httpReq, nil
-		},
-		func(respBody []byte) error {
-			var parsed chatCompletionResponse
-			if err := json.Unmarshal(respBody, &parsed); err != nil {
-				return fmt.Errorf("decode chat response: %w", err)
-			}
-			if parsed.Error != nil && parsed.Error.Message != "" {
-				// 200 with an upstream error object — transient on gateways.
-				return fmt.Errorf("chat API error: %s", parsed.Error.Message)
-			}
-			if len(parsed.Choices) == 0 || parsed.Choices[0].Message.Content == "" {
-				slog.Warn("AI chat returned no choices, retrying",
-					"model", cfg.ChatModel, "response_bytes", len(respBody))
-				return fmt.Errorf("chat API returned no choices")
-			}
-			content = parsed.Choices[0].Message.Content
-			return nil
-		})
-	if err != nil {
-		return "", err
-	}
-	return content, nil
-}
-
-// SystemUserChat performs one chat completion from a system + user prompt
-// pair, requesting a JSON object response. Its signature matches
-// aitranslate.ChatFn so a client method reference wires straight in.
-func (c *Client) SystemUserChat(ctx context.Context, system, user string) (string, error) {
-	return c.Chat(ctx, []Message{
-		{Role: "system", Content: system},
-		{Role: "user", Content: user},
-	}, true)
-}
-
-// permanentError marks a parse failure that retrying cannot fix (e.g. an
-// endpoint that structurally does not support the requested response format).
-type permanentError struct{ err error }
-
-func (e *permanentError) Error() string { return e.err.Error() }
-func (e *permanentError) Unwrap() error { return e.err }
-
-// doWithRetry runs the shared request/retry loop: build constructs a fresh
-// request per attempt, parse consumes a 200 body. Transport errors, read
-// errors, 429 (honoring Retry-After), 5xx, and retryable parse errors back
-// off and retry; other 4xx and permanentError parse failures return at once.
-func (c *Client) doWithRetry(ctx context.Context, httpClient *http.Client, label string,
-	build func() (*http.Request, error), parse func(body []byte) error) error {
-	const maxAttempts = 6
-	var lastErr error
-	for attempt := 0; attempt < maxAttempts; attempt++ {
-		httpReq, err := build()
-		if err != nil {
-			return err
-		}
-
-		resp, doErr := httpClient.Do(httpReq)
-		if doErr != nil {
-			lastErr = fmt.Errorf("%s request failed: %w", label, doErr)
-			if waitErr := sleepCtx(ctx, time.Duration(attempt+1)*time.Second); waitErr != nil {
-				return waitErr
-			}
-			continue
-		}
-
-		respBody, readErr := io.ReadAll(resp.Body)
-		resp.Body.Close()
-		if readErr != nil {
-			// A truncated/failed read could otherwise be misparsed as a valid
-			// (empty) response; treat it as a retryable transport error.
-			lastErr = fmt.Errorf("read %s response: %w", label, readErr)
-			if waitErr := sleepCtx(ctx, time.Duration(attempt+1)*time.Second); waitErr != nil {
-				return waitErr
-			}
-			continue
-		}
-
-		switch {
-		case resp.StatusCode == http.StatusTooManyRequests:
-			wait := rateLimitBackoff(resp, attempt)
-			slog.Warn("rate limited by AI API, waiting", "api", label, "attempt", attempt+1, "wait", wait)
-			lastErr = fmt.Errorf("%s returned 429: %s", label, Truncate(string(respBody), 300))
-			if waitErr := sleepCtx(ctx, wait); waitErr != nil {
-				return waitErr
-			}
-			continue
-		case resp.StatusCode >= 500:
-			lastErr = fmt.Errorf("%s returned %d: %s", label, resp.StatusCode, Truncate(string(respBody), 300))
-			if waitErr := sleepCtx(ctx, time.Duration(attempt+1)*time.Second); waitErr != nil {
-				return waitErr
-			}
-			continue
-		case resp.StatusCode != http.StatusOK:
-			// 4xx other than 429: not retryable.
-			return fmt.Errorf("%s returned %d: %s", label, resp.StatusCode, Truncate(string(respBody), 300))
-		}
-
-		parseErr := parse(respBody)
-		if parseErr == nil {
-			return nil
-		}
-		var perm *permanentError
-		if errors.As(parseErr, &perm) {
-			return perm.err
-		}
-		lastErr = parseErr
-		if waitErr := sleepCtx(ctx, time.Duration(attempt+1)*time.Second); waitErr != nil {
-			return waitErr
-		}
-	}
-
-	if lastErr == nil {
-		lastErr = fmt.Errorf("%s: retries exhausted", label)
-	}
-	return lastErr
-}
-
-// endpointURL joins a configured base URL with an OpenAI API path,
-// tolerating bases that already include the version segment (e.g.
-// DeepInfra's https://api.deepinfra.com/v1/openai) alongside bare hosts
-// (https://api.openai.com) and prefixed hosts (https://api.groq.com/openai).
-func endpointURL(base, path string) string {
-	base = strings.TrimRight(base, "/")
-	if strings.Contains(base, "/v1") {
-		return base + "/" + path
-	}
-	return base + "/v1/" + path
-}
-
-// Truncate caps a string for inclusion in an error or log line.
-func Truncate(s string, maxLen int) string {
-	if len(s) > maxLen {
-		return s[:maxLen] + "..."
-	}
-	return s
-}
-
-// sleepCtx waits for d or until ctx is cancelled.
-func sleepCtx(ctx context.Context, d time.Duration) error {
-	select {
-	case <-ctx.Done():
-		return ctx.Err()
-	case <-time.After(d):
-		return nil
-	}
-}
-
-// rateLimitBackoff returns how long to wait after a 429, honoring Retry-After
-// and otherwise backing off exponentially (capped at 60s).
-func rateLimitBackoff(resp *http.Response, attempt int) time.Duration {
-	if ra := resp.Header.Get("Retry-After"); ra != "" {
-		if secs, err := strconv.Atoi(ra); err == nil && secs > 0 {
-			return time.Duration(secs) * time.Second
-		}
-	}
-	wait := 10 * time.Second * (1 << attempt)
-	if wait > 60*time.Second {
-		wait = 60 * time.Second
-	}
-	return wait
-}
@@ -1,350 +0,0 @@
-package llm
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync/atomic"
-	"testing"
-	"time"
-)
-
-func chatConfig(baseURL string) Config {
-	return Config{BaseURL: baseURL, APIKey: "test-key", ChatModel: "test-model"}
-}
-
-const chatOK = `{"choices":[{"message":{"role":"assistant","content":"hello"}}]}`
-
-func TestChatSuccessSendsAuthAndModel(t *testing.T) {
-	var gotAuth, gotBody string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotAuth = r.Header.Get("Authorization")
-		buf := make([]byte, 4096)
-		n, _ := r.Body.Read(buf)
-		gotBody = string(buf[:n])
-		w.Write([]byte(chatOK))
-	}))
-	defer srv.Close()
-
-	c := NewClient(chatConfig(srv.URL))
-	out, err := c.Chat(context.Background(), []Message{{Role: "user", Content: "hi"}}, true)
-	if err != nil {
-		t.Fatalf("Chat: %v", err)
-	}
-	if out != "hello" {
-		t.Errorf("content = %q, want hello", out)
-	}
-	if gotAuth != "Bearer test-key" {
-		t.Errorf("auth = %q", gotAuth)
-	}
-	if !strings.Contains(gotBody, `"model":"test-model"`) || !strings.Contains(gotBody, `"json_object"`) {
-		t.Errorf("request body missing model/response_format: %s", gotBody)
-	}
-}
-
-func TestChatRetriesOn429HonoringRetryAfter(t *testing.T) {
-	var calls atomic.Int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if calls.Add(1) == 1 {
-			w.Header().Set("Retry-After", "1")
-			w.WriteHeader(http.StatusTooManyRequests)
-			return
-		}
-		w.Write([]byte(chatOK))
-	}))
-	defer srv.Close()
-
-	start := time.Now()
-	c := NewClient(chatConfig(srv.URL))
-	if _, err := c.Chat(context.Background(), []Message{{Role: "user", Content: "hi"}}, false); err != nil {
-		t.Fatalf("Chat: %v", err)
-	}
-	if calls.Load() != 2 {
-		t.Errorf("calls = %d, want 2", calls.Load())
-	}
-	if elapsed := time.Since(start); elapsed < time.Second {
-		t.Errorf("did not honor Retry-After: elapsed %v", elapsed)
-	}
-}
-
-func TestChatRetriesOn5xxAndEmbeddedErrorAndEmptyChoices(t *testing.T) {
-	responses := []func(w http.ResponseWriter){
-		func(w http.ResponseWriter) { w.WriteHeader(http.StatusBadGateway) },
-		func(w http.ResponseWriter) { w.Write([]byte(`{"error":{"message":"upstream sad"}}`)) },
-		func(w http.ResponseWriter) { w.Write([]byte(`{"choices":[]}`)) },
-		func(w http.ResponseWriter) { w.Write([]byte(chatOK)) },
-	}
-	var calls atomic.Int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		responses[calls.Add(1)-1](w)
-	}))
-	defer srv.Close()
-
-	c := NewClient(chatConfig(srv.URL))
-	out, err := c.Chat(context.Background(), []Message{{Role: "user", Content: "hi"}}, false)
-	if err != nil {
-		t.Fatalf("Chat: %v", err)
-	}
-	if out != "hello" || calls.Load() != 4 {
-		t.Errorf("out=%q calls=%d, want hello/4", out, calls.Load())
-	}
-}
-
-func TestChatFailsFastOnNon429ClientError(t *testing.T) {
-	var calls atomic.Int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		calls.Add(1)
-		w.WriteHeader(http.StatusUnauthorized)
-	}))
-	defer srv.Close()
-
-	c := NewClient(chatConfig(srv.URL))
-	if _, err := c.Chat(context.Background(), []Message{{Role: "user", Content: "hi"}}, false); err == nil {
-		t.Fatal("expected error")
-	}
-	if calls.Load() != 1 {
-		t.Errorf("calls = %d, want 1 (no retry on 401)", calls.Load())
-	}
-}
-
-const verboseJSON = `{"language":"english","text":"hi there","segments":[{"start":0.0,"end":1.5,"text":" hi"},{"start":1.5,"end":3.0,"text":" there"}]}`
-
-func TestTranscribeParsesSegmentsAndMultipart(t *testing.T) {
-	var gotModel, gotFormat, gotLang, gotAuth, gotVAD string
-	var gotGranularities []string
-	var gotFile []byte
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotAuth = r.Header.Get("Authorization")
-		if err := r.ParseMultipartForm(32 << 20); err != nil {
-			t.Errorf("parse multipart: %v", err)
-		}
-		gotModel = r.FormValue("model")
-		gotFormat = r.FormValue("response_format")
-		gotLang = r.FormValue("language")
-		gotVAD = r.FormValue("vad_filter")
-		gotGranularities = r.MultipartForm.Value["timestamp_granularities[]"]
-		f, _, err := r.FormFile("file")
-		if err == nil {
-			buf := make([]byte, 64)
-			n, _ := f.Read(buf)
-			gotFile = buf[:n]
-			f.Close()
-		}
-		w.Write([]byte(verboseJSON))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	c := NewClient(cfg)
-	tr, err := c.Transcribe(context.Background(), TranscribeRequest{
-		Filename: "chunk.wav", Audio: []byte("RIFFfake"), Language: "ja",
-	})
-	if err != nil {
-		t.Fatalf("Transcribe: %v", err)
-	}
-	if gotModel != "whisper-test" || gotFormat != "verbose_json" || gotLang != "ja" {
-		t.Errorf("fields model=%q format=%q lang=%q", gotModel, gotFormat, gotLang)
-	}
-	// Local (non-hosted) endpoint: faster-whisper VAD must be requested or
-	// segment timestamps stretch wall-to-wall across silence.
-	if gotVAD != "true" {
-		t.Errorf("vad_filter = %q, want true for a self-hosted endpoint", gotVAD)
-	}
-	if fmt.Sprint(gotGranularities) != "[segment word]" {
-		t.Errorf("timestamp_granularities[] = %v, want [segment word]", gotGranularities)
-	}
-	if gotAuth != "Bearer test-key" {
-		t.Errorf("auth = %q (should fall back to chat key)", gotAuth)
-	}
-	if string(gotFile) != "RIFFfake" {
-		t.Errorf("file payload = %q", gotFile)
-	}
-	if tr.Language != "english" || len(tr.Segments) != 2 || tr.Segments[1].Text != " there" || tr.Segments[1].End != 3.0 {
-		t.Errorf("unexpected transcription: %+v", tr)
-	}
-}
-
-func TestTranscribeOmitsVADFilterForStrictHostedEndpoints(t *testing.T) {
-	for url, wantVAD := range map[string]bool{
-		"https://api.openai.com":              false,
-		"https://myorg.openai.azure.com":      false,
-		"https://api.groq.com/openai":         false,
-		"http://192.168.1.10:8000":            true,
-		"https://whisper.example.com":         true,
-		"https://api.deepinfra.com/v1/openai": true,
-	} {
-		got := !hostMatchesAny(url, strictHostedASRHosts)
-		if got != wantVAD {
-			t.Errorf("vad_filter for %s = %v, want %v", url, got, wantVAD)
-		}
-	}
-}
-
-func TestTranscribeParsesPerSegmentWords(t *testing.T) {
-	// speaches/faster-whisper shape: words nested inside each segment.
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte(`{"language":"en","text":"hi there","segments":[
-			{"start":0.0,"end":3.0,"text":" hi there","words":[
-				{"start":0.2,"end":0.5,"word":" hi"},{"start":0.6,"end":1.0,"word":" there"}]}]}`))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	tr, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err != nil {
-		t.Fatalf("Transcribe: %v", err)
-	}
-	words := tr.Segments[0].Words
-	if len(words) != 2 || words[1].Text != " there" || words[1].Start != 0.6 || words[1].End != 1.0 {
-		t.Errorf("segment words = %+v", words)
-	}
-}
-
-func TestTranscribeAttachesTopLevelWordsBySegmentTime(t *testing.T) {
-	// OpenAI shape: words in a top-level array, segments without words.
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte(`{"language":"en","text":"hi there friend","segments":[
-			{"start":0.0,"end":1.5,"text":" hi there"},{"start":1.5,"end":3.0,"text":" friend"}],
-			"words":[{"start":0.2,"end":0.5,"word":"hi"},{"start":0.6,"end":1.0,"word":"there"},
-			{"start":1.8,"end":2.2,"word":"friend"}]}`))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	tr, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err != nil {
-		t.Fatalf("Transcribe: %v", err)
-	}
-	if len(tr.Segments[0].Words) != 2 || len(tr.Segments[1].Words) != 1 {
-		t.Errorf("word distribution = %d/%d, want 2/1", len(tr.Segments[0].Words), len(tr.Segments[1].Words))
-	}
-	if tr.Segments[1].Words[0].Text != "friend" {
-		t.Errorf("segment 1 word = %+v", tr.Segments[1].Words[0])
-	}
-}
-
-func TestTranscribeEmptySegmentsIsNotAnError(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte(`{"language":"english","text":"","segments":[]}`))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	tr, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err != nil {
-		t.Fatalf("Transcribe: %v", err)
-	}
-	if len(tr.Segments) != 0 {
-		t.Errorf("segments = %v, want empty", tr.Segments)
-	}
-}
-
-func TestTranscribeMissingSegmentsFieldFailsFast(t *testing.T) {
-	var calls atomic.Int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		calls.Add(1)
-		w.Write([]byte(`{"text":"plain response without segments"}`))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	_, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err == nil || !strings.Contains(err.Error(), "verbose_json") {
-		t.Fatalf("err = %v, want verbose_json complaint", err)
-	}
-	if calls.Load() != 1 {
-		t.Errorf("calls = %d, want 1 (permanent error must not retry)", calls.Load())
-	}
-}
-
-func TestTranscribeUsesASROverrides(t *testing.T) {
-	var gotAuth atomic.Value
-	asrSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotAuth.Store(r.Header.Get("Authorization"))
-		w.Write([]byte(verboseJSON))
-	}))
-	defer asrSrv.Close()
-
-	cfg := Config{
-		BaseURL: "http://chat.invalid", APIKey: "chat-key", ChatModel: "m",
-		ASRBaseURL: asrSrv.URL, ASRAPIKey: "asr-key", ASRModel: "whisper-test",
-	}
-	if _, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")}); err != nil {
-		t.Fatalf("Transcribe: %v", err)
-	}
-	if gotAuth.Load() != "Bearer asr-key" {
-		t.Errorf("auth = %q, want asr-key", gotAuth.Load())
-	}
-}
-
-func TestTranscribeRequiresConfig(t *testing.T) {
-	c := NewClient(Config{BaseURL: "http://x", ChatModel: "m"}) // no ASR model
-	if _, err := c.Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")}); err == nil {
-		t.Fatal("expected not-configured error")
-	}
-}
-
-func TestTranscribeChatOnlyGatewayGetsConfigHint(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusBadRequest)
-		w.Write([]byte(`{"error":{"message":"invalid content-type: multipart/form-data","code":400}}`))
-	}))
-	defer srv.Close()
-
-	cfg := chatConfig(srv.URL)
-	cfg.ASRModel = "whisper-test"
-	_, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err == nil || !strings.Contains(err.Error(), "Whisper-compatible Transcription base URL") {
-		t.Fatalf("err = %v, want configuration hint", err)
-	}
-}
-
-func TestIsChatOnlyGateway(t *testing.T) {
-	cases := map[string]bool{
-		"https://openrouter.ai/api":           true,
-		"https://openrouter.ai":               true,
-		"openrouter.ai/api/v1":                true,
-		"https://gateway.openrouter.ai":       true,
-		"https://api.groq.com/openai":         false,
-		"https://api.openai.com":              false,
-		"http://localhost:8000":               false,
-		"https://my-openrouter.ai.example.io": false,
-		"":                                    false,
-	}
-	for in, want := range cases {
-		if got := IsChatOnlyGateway(in); got != want {
-			t.Errorf("IsChatOnlyGateway(%q) = %v, want %v", in, got, want)
-		}
-	}
-}
-
-func TestTranscribeRefusesChatOnlyGateway(t *testing.T) {
-	cfg := Config{BaseURL: "https://openrouter.ai/api", ChatModel: "m", ASRModel: "whisper-1"}
-	_, err := NewClient(cfg).Transcribe(context.Background(), TranscribeRequest{Filename: "c.wav", Audio: []byte("x")})
-	if err == nil || !strings.Contains(err.Error(), "cannot produce timestamped transcriptions") {
-		t.Fatalf("err = %v, want chat-only refusal", err)
-	}
-}
-
-func TestEndpointURLToleratesVersionedBases(t *testing.T) {
-	cases := map[string]string{
-		"https://api.openai.com":              "https://api.openai.com/v1/chat/completions",
-		"https://api.groq.com/openai":         "https://api.groq.com/openai/v1/chat/completions",
-		"https://api.deepinfra.com/v1/openai": "https://api.deepinfra.com/v1/openai/chat/completions",
-		"http://localhost:8969":               "http://localhost:8969/v1/chat/completions",
-		"http://localhost:8969/v1":            "http://localhost:8969/v1/chat/completions",
-		"https://api.openai.com/":             "https://api.openai.com/v1/chat/completions",
-	}
-	for base, want := range cases {
-		if got := endpointURL(base, "chat/completions"); got != want {
-			t.Errorf("endpointURL(%q) = %q, want %q", base, got, want)
-		}
-	}
-}
@@ -1,287 +0,0 @@
-package llm
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"mime/multipart"
-	"net/http"
-	"net/url"
-	"strings"
-	"time"
-)
-
-// defaultTranscribeTimeout bounds a single transcription request when the
-// caller does not size one to its chunk duration. Generous on purpose: local
-// Whisper servers on modest hardware can run well below realtime.
-const defaultTranscribeTimeout = 20 * time.Minute
-
-// TranscribeRequest is one audio-transcription call. Audio is held in memory
-// so the request can be rebuilt across retries; callers chunk long files
-// (a 10-minute 16 kHz mono WAV is ~19 MB).
-type TranscribeRequest struct {
-	Filename string // e.g. "chunk00001.wav"; the extension hints the container
-	Audio    []byte
-	Language string        // optional ISO-639-1 hint; empty lets the model detect
-	Timeout  time.Duration // per-request deadline; 0 uses defaultTranscribeTimeout
-}
-
-// TranscriptionSegment is one timed segment of recognized speech, in seconds
-// relative to the start of the submitted audio.
-type TranscriptionSegment struct {
-	Start float64
-	End   float64
-	Text  string
-	// Words carries per-word timings when the endpoint honors
-	// timestamp_granularities[]=word; empty otherwise. Word-level times let
-	// cue building split paragraph-length segments and end cues when speech
-	// actually stops instead of when the next segment begins.
-	Words []TranscriptionWord
-}
-
-// TranscriptionWord is one recognized word with timing, in seconds relative
-// to the start of the submitted audio.
-type TranscriptionWord struct {
-	Start float64
-	End   float64
-	Text  string
-}
-
-// Transcription is the parsed verbose_json transcription result.
-type Transcription struct {
-	// Language is the detected (or hinted) language as reported by the
-	// endpoint. OpenAI returns an English language name ("english"); other
-	// servers return ISO codes. Callers must normalize.
-	Language string
-	// Segments may legitimately be empty for speech-free audio (silence,
-	// music-only chunks).
-	Segments []TranscriptionSegment
-}
-
-type transcriptionWordJSON struct {
-	Start float64 `json:"start"`
-	End   float64 `json:"end"`
-	Word  string  `json:"word"`
-}
-
-type transcriptionResponse struct {
-	Language string `json:"language"`
-	Text     string `json:"text"`
-	// Segments distinguishes "verbose_json honored, no speech" (empty array)
-	// from "endpoint ignored verbose_json" (field absent) — the latter cannot
-	// produce timed cues and must fail rather than silently emit nothing.
-	Segments *[]struct {
-		Start float64                 `json:"start"`
-		End   float64                 `json:"end"`
-		Text  string                  `json:"text"`
-		Words []transcriptionWordJSON `json:"words"`
-	} `json:"segments"`
-	// Words is where OpenAI puts word timings; faster-whisper servers
-	// (speaches) nest them inside each segment instead.
-	Words []transcriptionWordJSON `json:"words"`
-	Error *struct {
-		Message string `json:"message"`
-	} `json:"error"`
-}
-
-// chatOnlyGatewayHosts lists OpenAI-compatible gateways that cannot serve
-// Silo's transcription needs: they either lack /v1/audio/transcriptions
-// entirely or (OpenRouter) return plain text with no segment timestamps,
-// which subtitle cues require. Matched by host suffix.
-var chatOnlyGatewayHosts = []string{
-	"openrouter.ai",
-}
-
-// strictHostedASRHosts lists hosted transcription providers that reject
-// multipart fields outside the OpenAI spec, so the faster-whisper-only
-// vad_filter field must be omitted for them. Nothing is lost: hosted Whisper
-// runs voice-activity detection server-side. Self-hosted servers (speaches,
-// faster-whisper) need the explicit field — without it segment timestamps
-// stretch wall-to-wall across silence. Matched by host suffix.
-var strictHostedASRHosts = []string{
-	"api.openai.com",
-	"openai.azure.com",
-	"api.groq.com",
-	"api.mistral.ai",
-}
-
-// IsChatOnlyGateway reports whether baseURL points at a known chat-only
-// gateway that cannot produce timestamped transcriptions. Used to validate
-// the transcription settings and to disable ASR rather than fail jobs at
-// runtime.
-func IsChatOnlyGateway(baseURL string) bool {
-	return hostMatchesAny(baseURL, chatOnlyGatewayHosts)
-}
-
-// hostMatchesAny reports whether baseURL's hostname equals or is a subdomain
-// of any of the given host suffixes.
-func hostMatchesAny(baseURL string, hosts []string) bool {
-	baseURL = strings.TrimSpace(baseURL)
-	if baseURL == "" {
-		return false
-	}
-	if !strings.Contains(baseURL, "://") {
-		baseURL = "https://" + baseURL
-	}
-	u, err := url.Parse(baseURL)
-	if err != nil || u.Host == "" {
-		return false
-	}
-	host := strings.ToLower(u.Hostname())
-	for _, h := range hosts {
-		if host == h || strings.HasSuffix(host, "."+h) {
-			return true
-		}
-	}
-	return false
-}
-
-// Transcribe performs one audio transcription against the ASR endpoint
-// (falling back to the chat endpoint's base URL/key when no ASR override is
-// configured), using the OpenAI-compatible /v1/audio/transcriptions API with
-// response_format=verbose_json for segment timestamps.
-func (c *Client) Transcribe(ctx context.Context, req TranscribeRequest) (*Transcription, error) {
-	cfg := c.Config()
-	if !cfg.ASRConfigured() {
-		return nil, fmt.Errorf("transcription endpoint is not configured")
-	}
-	if IsChatOnlyGateway(cfg.asrBaseURL()) {
-		return nil, fmt.Errorf("the configured transcription endpoint (%s) cannot produce timestamped transcriptions; "+
-			"set a Whisper-compatible Transcription base URL under Admin Settings → AI Services", cfg.asrBaseURL())
-	}
-	if len(req.Audio) == 0 {
-		return nil, fmt.Errorf("no audio data to transcribe")
-	}
-
-	timeout := req.Timeout
-	if timeout <= 0 {
-		timeout = defaultTranscribeTimeout
-	}
-	ctx, cancel := context.WithTimeout(ctx, timeout)
-	defer cancel()
-
-	url := endpointURL(cfg.asrBaseURL(), "audio/transcriptions")
-
-	var result *Transcription
-	doErr := c.doWithRetry(ctx, c.asrHTTP, "transcription API",
-		func() (*http.Request, error) {
-			var buf bytes.Buffer
-			w := multipart.NewWriter(&buf)
-			fw, err := w.CreateFormFile("file", req.Filename)
-			if err != nil {
-				return nil, fmt.Errorf("create multipart file: %w", err)
-			}
-			if _, err := fw.Write(req.Audio); err != nil {
-				return nil, fmt.Errorf("write multipart audio: %w", err)
-			}
-			fields := [][2]string{
-				{"model", cfg.ASRModel},
-				{"response_format", "verbose_json"},
-				{"temperature", "0"},
-				// Word timings let cue building split paragraph-length
-				// segments and end cues when speech actually stops; segment
-				// granularity must be requested alongside or OpenAI omits it.
-				{"timestamp_granularities[]", "segment"},
-				{"timestamp_granularities[]", "word"},
-			}
-			if req.Language != "" {
-				fields = append(fields, [2]string{"language", req.Language})
-			}
-			if !hostMatchesAny(cfg.asrBaseURL(), strictHostedASRHosts) {
-				fields = append(fields, [2]string{"vad_filter", "true"})
-			}
-			for _, f := range fields {
-				if err := w.WriteField(f[0], f[1]); err != nil {
-					return nil, fmt.Errorf("write multipart field %s: %w", f[0], err)
-				}
-			}
-			if err := w.Close(); err != nil {
-				return nil, fmt.Errorf("finalize multipart body: %w", err)
-			}
-
-			httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(buf.Bytes()))
-			if err != nil {
-				return nil, fmt.Errorf("create request: %w", err)
-			}
-			httpReq.Header.Set("Content-Type", w.FormDataContentType())
-			if key := cfg.asrAPIKey(); key != "" {
-				httpReq.Header.Set("Authorization", "Bearer "+key)
-			}
-			return httpReq, nil
-		},
-		func(respBody []byte) error {
-			var parsed transcriptionResponse
-			if err := json.Unmarshal(respBody, &parsed); err != nil {
-				return fmt.Errorf("decode transcription response: %w", err)
-			}
-			if parsed.Error != nil && parsed.Error.Message != "" {
-				return fmt.Errorf("transcription API error: %s", parsed.Error.Message)
-			}
-			if parsed.Segments == nil {
-				return &permanentError{err: fmt.Errorf(
-					"transcription endpoint did not return verbose_json segments (model %q); a verbose_json-capable Whisper endpoint is required", cfg.ASRModel)}
-			}
-			out := &Transcription{Language: parsed.Language}
-			for _, s := range *parsed.Segments {
-				out.Segments = append(out.Segments, TranscriptionSegment{
-					Start: s.Start, End: s.End, Text: s.Text, Words: wordsFromJSON(s.Words),
-				})
-			}
-			attachTopLevelWords(out.Segments, wordsFromJSON(parsed.Words))
-			result = out
-			return nil
-		})
-	if doErr != nil {
-		return nil, decorateTranscribeError(doErr)
-	}
-	return result, nil
-}
-
-func wordsFromJSON(words []transcriptionWordJSON) []TranscriptionWord {
-	out := make([]TranscriptionWord, 0, len(words))
-	for _, w := range words {
-		out = append(out, TranscriptionWord{Start: w.Start, End: w.End, Text: w.Word})
-	}
-	return out
-}
-
-// attachTopLevelWords distributes an OpenAI-style top-level word list onto
-// segments by word midpoint, for endpoints that report words separately from
-// segments. Segments that already carry their own words are left untouched.
-func attachTopLevelWords(segments []TranscriptionSegment, words []TranscriptionWord) {
-	if len(segments) == 0 || len(words) == 0 {
-		return
-	}
-	for _, s := range segments {
-		if len(s.Words) > 0 {
-			return
-		}
-	}
-	si := 0
-	for _, w := range words {
-		mid := (w.Start + w.End) / 2
-		for si < len(segments)-1 && mid >= segments[si].End {
-			si++
-		}
-		segments[si].Words = append(segments[si].Words, w)
-	}
-}
-
-// decorateTranscribeError appends a configuration hint to the errors a
-// chat-only gateway produces when it receives a transcription upload (no
-// /v1/audio/transcriptions route, or multipart rejected). Operators routinely
-// point the shared base URL at a chat-only provider; without the hint the raw
-// 400/404 reads like a pipeline bug instead of "set a Whisper endpoint".
-func decorateTranscribeError(err error) error {
-	msg := err.Error()
-	likelyUnsupported := strings.Contains(msg, "returned 400") ||
-		strings.Contains(msg, "returned 404") ||
-		strings.Contains(msg, "returned 405")
-	if !likelyUnsupported {
-		return err
-	}
-	return fmt.Errorf("%w — the configured endpoint likely does not support audio transcription; "+
-		"set a Whisper-compatible Transcription base URL (and model) under Admin Settings → AI Services "+
-		"(e.g. a self-hosted faster-whisper/speaches server, api.groq.com/openai with whisper-large-v3-turbo, or api.openai.com with whisper-1)", err)
-}
@@ -1,52 +0,0 @@
-package aitranslate
-
-import "strings"
-
-// languageNames maps common ISO 639-1 codes to English names. The model handles
-// bare codes acceptably, but full names noticeably improve translation quality,
-// so we resolve the common cases and fall back to the raw code otherwise.
-var languageNames = map[string]string{
-	"ar": "Arabic", "bg": "Bulgarian", "bn": "Bengali", "cs": "Czech",
-	"da": "Danish", "de": "German", "el": "Greek", "en": "English",
-	"es": "Spanish", "et": "Estonian", "fa": "Persian", "fi": "Finnish",
-	"fr": "French", "he": "Hebrew", "hi": "Hindi", "hr": "Croatian",
-	"hu": "Hungarian", "id": "Indonesian", "it": "Italian", "ja": "Japanese",
-	"ko": "Korean", "lt": "Lithuanian", "lv": "Latvian", "ms": "Malay",
-	"nl": "Dutch", "no": "Norwegian", "pl": "Polish", "pt": "Portuguese",
-	"ro": "Romanian", "ru": "Russian", "sk": "Slovak", "sl": "Slovenian",
-	"sr": "Serbian", "sv": "Swedish", "ta": "Tamil", "th": "Thai",
-	"tr": "Turkish", "uk": "Ukrainian", "vi": "Vietnamese", "zh": "Chinese",
-}
-
-// LanguageCodeFromName maps an English language name back to its ISO 639-1
-// code — Whisper endpoints report detected languages as names ("english")
-// while local servers report codes. Returns "" when unknown.
-func LanguageCodeFromName(name string) string {
-	name = strings.ToLower(strings.TrimSpace(name))
-	if name == "" {
-		return ""
-	}
-	for code, display := range languageNames {
-		if strings.ToLower(display) == name {
-			return code
-		}
-	}
-	return ""
-}
-
-// LanguageDisplayName returns a human-readable language name for a code, or
-// the trimmed code itself when unknown. An empty code yields an empty string.
-func LanguageDisplayName(code string) string {
-	code = strings.TrimSpace(code)
-	if code == "" {
-		return ""
-	}
-	base := strings.ToLower(code)
-	if i := strings.IndexAny(base, "-_"); i >= 0 {
-		base = base[:i]
-	}
-	if name, ok := languageNames[base]; ok {
-		return name
-	}
-	return code
-}
@@ -1,212 +0,0 @@
-// Package aitranslate implements generic batched text translation over an
-// OpenAI-compatible chat model. Callers hand it ordered text segments and a
-// domain-specific system prompt; it owns the wire protocol (indexed-JSON
-// batches the model must echo back key-for-key), context carryover between
-// batches, and retries on malformed model output. Subtitle cues and metadata
-// descriptions both translate through this one implementation.
-package aitranslate
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"strconv"
-	"strings"
-)
-
-// Segment is one unit of translatable text. ID is the caller's identifier and
-// is never sent to the model (batches are keyed by position), so any stable
-// string works.
-type Segment struct {
-	ID   string
-	Text string
-}
-
-// ChatFn performs one chat completion. Wiring this as a function keeps the
-// package independent of the client and trivially testable.
-type ChatFn func(ctx context.Context, system, user string) (string, error)
-
-// Request describes one translation run.
-type Request struct {
-	Segments     []Segment
-	SystemPrompt string // domain-specific; must demand same-keys JSON output
-	// TargetName is the human-readable target language name used in the
-	// per-batch user message.
-	TargetName string
-	// EntryNoun names the units in the user message ("cues", "descriptions");
-	// empty defaults to "entries".
-	EntryNoun string
-	// BatchSize is the number of segments per chat request (required, > 0).
-	BatchSize int
-	// ContextNeighbors is how many preceding source segments are included,
-	// untranslated, for continuity across batch boundaries.
-	ContextNeighbors int
-}
-
-// maxFormatRetries is how many times a batch is re-asked after the model
-// returns unparsable or incomplete JSON. Transport/API errors are retried
-// inside the chat client and are not part of this count.
-const maxFormatRetries = 2
-
-// Translate translates req.Segments in order, preserving count and IDs and
-// only rewriting Text. onBatch, when non-nil, is called after each batch with
-// that batch's translated segments and overall progress (done/total
-// segments). Implementations must honor ctx cancellation between batches.
-func Translate(ctx context.Context, chat ChatFn, req Request, onBatch func(batch []Segment, done, total int)) ([]Segment, error) {
-	if chat == nil {
-		return nil, fmt.Errorf("chat function is nil")
-	}
-	if req.BatchSize <= 0 {
-		return nil, fmt.Errorf("invalid batch size: %d", req.BatchSize)
-	}
-	total := len(req.Segments)
-	if total == 0 {
-		return nil, fmt.Errorf("no segments to translate")
-	}
-	noun := req.EntryNoun
-	if noun == "" {
-		noun = "entries"
-	}
-
-	// Preserve IDs by copying input segments and only replacing Text.
-	out := make([]Segment, total)
-	copy(out, req.Segments)
-
-	for start := 0; start < total; start += req.BatchSize {
-		if err := ctx.Err(); err != nil {
-			return nil, err
-		}
-		end := min(start+req.BatchSize, total)
-
-		contextStart := max(0, start-req.ContextNeighbors)
-		translated, err := translateBatch(ctx, chat, req, noun, req.Segments[contextStart:start], req.Segments[start:end])
-		if err != nil {
-			return nil, fmt.Errorf("translate %s %d-%d: %w", noun, start+1, end, err)
-		}
-		for i, text := range translated {
-			out[start+i].Text = text
-		}
-		if onBatch != nil {
-			onBatch(out[start:end], end, total)
-		}
-	}
-
-	return out, nil
-}
-
-func translateBatch(ctx context.Context, chat ChatFn, req Request, noun string, contextSegs, batch []Segment) ([]string, error) {
-	texts := make([]string, len(batch))
-	for i, s := range batch {
-		texts[i] = s.Text
-	}
-	payload, err := buildIndexedJSON(texts)
-	if err != nil {
-		return nil, err
-	}
-
-	var user strings.Builder
-	if len(contextSegs) > 0 {
-		user.WriteString("Preceding lines for context only — do not translate or include them in your output:\n")
-		for _, s := range contextSegs {
-			user.WriteString(strings.ReplaceAll(s.Text, "\n", " "))
-			user.WriteByte('\n')
-		}
-		user.WriteByte('\n')
-	}
-	target := req.TargetName
-	if target == "" {
-		target = "the target language"
-	}
-	fmt.Fprintf(&user, "Translate these %d %s into %s. Respond with only the JSON object:\n%s", len(batch), noun, target, payload)
-
-	var lastErr error
-	for attempt := 0; attempt <= maxFormatRetries; attempt++ {
-		if err := ctx.Err(); err != nil {
-			return nil, err
-		}
-		content, err := chat(ctx, req.SystemPrompt, user.String())
-		if err != nil {
-			return nil, err // transport/API errors are already retried inside the client
-		}
-
-		obj, err := extractJSONObject(content)
-		if err != nil {
-			lastErr = err
-			continue
-		}
-		var m map[string]string
-		if err := json.Unmarshal([]byte(obj), &m); err != nil {
-			lastErr = fmt.Errorf("decode translation JSON: %w", err)
-			continue
-		}
-
-		out := make([]string, len(batch))
-		complete := true
-		for i := range batch {
-			v, ok := m[strconv.Itoa(i+1)]
-			if !ok {
-				complete = false
-				break
-			}
-			out[i] = v
-		}
-		if !complete {
-			lastErr = fmt.Errorf("model omitted one or more %s", noun)
-			continue
-		}
-		return out, nil
-	}
-
-	return nil, fmt.Errorf("invalid model response after %d attempts: %w", maxFormatRetries+1, lastErr)
-}
-
-// buildIndexedJSON renders texts as a JSON object {"1":..., "2":...} keyed by
-// 1-based position, escaping each value safely. It is built by hand rather
-// than json.Marshal'ing a map so the keys stay in numeric order — that reads
-// more naturally for the model than the lexicographic order Go emits for maps
-// ("1","10","11",...,"2"). Correctness doesn't depend on order (results are
-// mapped back by key), but ordered input gives the model better context.
-func buildIndexedJSON(texts []string) (string, error) {
-	var b strings.Builder
-	b.WriteByte('{')
-	for i, text := range texts {
-		if i > 0 {
-			b.WriteByte(',')
-		}
-		key, err := json.Marshal(strconv.Itoa(i + 1))
-		if err != nil {
-			return "", err
-		}
-		val, err := json.Marshal(text)
-		if err != nil {
-			return "", err
-		}
-		b.Write(key)
-		b.WriteByte(':')
-		b.Write(val)
-	}
-	b.WriteByte('}')
-	return b.String(), nil
-}
-
-// extractJSONObject pulls the first balanced-looking JSON object out of a
-// model reply, tolerating ``` code fences and surrounding prose.
-func extractJSONObject(s string) (string, error) {
-	s = strings.TrimSpace(s)
-	if strings.HasPrefix(s, "```") {
-		s = strings.TrimPrefix(s, "```")
-		if nl := strings.IndexByte(s, '\n'); nl >= 0 {
-			s = s[nl+1:]
-		}
-		if idx := strings.LastIndex(s, "```"); idx >= 0 {
-			s = s[:idx]
-		}
-		s = strings.TrimSpace(s)
-	}
-	start := strings.IndexByte(s, '{')
-	end := strings.LastIndexByte(s, '}')
-	if start < 0 || end < 0 || end < start {
-		return "", fmt.Errorf("no JSON object found in model response")
-	}
-	return s[start : end+1], nil
-}
@@ -1,153 +0,0 @@
-package aitranslate
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"strconv"
-	"strings"
-	"testing"
-)
-
-// echoChat translates by upper-casing every value of the indexed JSON payload
-// in the user message, mimicking a well-behaved model.
-func echoChat(t *testing.T) ChatFn {
-	t.Helper()
-	return func(_ context.Context, _ string, user string) (string, error) {
-		obj, err := extractJSONObject(user)
-		if err != nil {
-			return "", fmt.Errorf("test chat: %w", err)
-		}
-		var m map[string]string
-		if err := json.Unmarshal([]byte(obj), &m); err != nil {
-			return "", fmt.Errorf("test chat decode: %w", err)
-		}
-		out := make(map[string]string, len(m))
-		for k, v := range m {
-			out[k] = strings.ToUpper(v)
-		}
-		b, _ := json.Marshal(out)
-		return string(b), nil
-	}
-}
-
-func segments(n int) []Segment {
-	out := make([]Segment, n)
-	for i := range out {
-		out[i] = Segment{ID: strconv.Itoa(i + 1), Text: fmt.Sprintf("line %d", i+1)}
-	}
-	return out
-}
-
-func TestTranslateBatchesAndPreservesIDs(t *testing.T) {
-	var batches []int
-	out, err := Translate(context.Background(), echoChat(t), Request{
-		Segments:  segments(7),
-		BatchSize: 3,
-	}, func(batch []Segment, done, total int) {
-		batches = append(batches, len(batch))
-		if total != 7 {
-			t.Errorf("total = %d, want 7", total)
-		}
-	})
-	if err != nil {
-		t.Fatalf("Translate: %v", err)
-	}
-	if len(out) != 7 {
-		t.Fatalf("len(out) = %d", len(out))
-	}
-	for i, s := range out {
-		if s.ID != strconv.Itoa(i+1) {
-			t.Errorf("ID[%d] = %q, want %d", i, s.ID, i+1)
-		}
-		if want := strings.ToUpper(fmt.Sprintf("line %d", i+1)); s.Text != want {
-			t.Errorf("Text[%d] = %q, want %q", i, s.Text, want)
-		}
-	}
-	if fmt.Sprint(batches) != "[3 3 1]" {
-		t.Errorf("batch sizes = %v, want [3 3 1]", batches)
-	}
-}
-
-func TestTranslateSendsContextNeighborsUntranslated(t *testing.T) {
-	var secondBatchMsg string
-	call := 0
-	chat := func(ctx context.Context, system, user string) (string, error) {
-		call++
-		if call == 2 {
-			secondBatchMsg = user
-		}
-		return echoChat(t)(ctx, system, user)
-	}
-	_, err := Translate(context.Background(), chat, Request{
-		Segments:         segments(4),
-		BatchSize:        2,
-		ContextNeighbors: 2,
-		TargetName:       "French",
-		EntryNoun:        "cues",
-	}, nil)
-	if err != nil {
-		t.Fatalf("Translate: %v", err)
-	}
-	if !strings.Contains(secondBatchMsg, "context only") ||
-		!strings.Contains(secondBatchMsg, "line 1\nline 2") {
-		t.Errorf("second batch missing context block:\n%s", secondBatchMsg)
-	}
-	if !strings.Contains(secondBatchMsg, "Translate these 2 cues into French.") {
-		t.Errorf("second batch missing instruction:\n%s", secondBatchMsg)
-	}
-}
-
-func TestTranslateToleratesCodeFences(t *testing.T) {
-	chat := func(_ context.Context, _, _ string) (string, error) {
-		return "Sure! Here you go:\n```json\n{\"1\":\"ok\"}\n```", nil
-	}
-	out, err := Translate(context.Background(), chat, Request{
-		Segments:  segments(1),
-		BatchSize: 5,
-	}, nil)
-	if err != nil {
-		t.Fatalf("Translate: %v", err)
-	}
-	if out[0].Text != "ok" {
-		t.Errorf("Text = %q", out[0].Text)
-	}
-}
-
-func TestTranslateRetriesOmittedKeysThenFails(t *testing.T) {
-	calls := 0
-	chat := func(_ context.Context, _, _ string) (string, error) {
-		calls++
-		return `{"1":"only one"}`, nil // always omits key "2"
-	}
-	_, err := Translate(context.Background(), chat, Request{
-		Segments:  segments(2),
-		BatchSize: 5,
-	}, nil)
-	if err == nil || !strings.Contains(err.Error(), "omitted") {
-		t.Fatalf("err = %v, want omission failure", err)
-	}
-	if calls != maxFormatRetries+1 {
-		t.Errorf("calls = %d, want %d", calls, maxFormatRetries+1)
-	}
-}
-
-func TestTranslateStopsOnCancelledContext(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	calls := 0
-	chat := func(_ context.Context, _, _ string) (string, error) {
-		calls++
-		cancel() // cancel after the first batch completes
-		return `{"1":"a"}`, nil
-	}
-	_, err := Translate(ctx, chat, Request{
-		Segments:  segments(3),
-		BatchSize: 1,
-	}, nil)
-	if err == nil || !strings.Contains(err.Error(), "context canceled") {
-		t.Fatalf("err = %v, want context cancellation", err)
-	}
-	if calls != 1 {
-		t.Errorf("calls = %d, want 1", calls)
-	}
-}
@@ -1,161 +0,0 @@
-package api
-
-import (
-	"context"
-	"fmt"
-	"strings"
-
-	"github.com/redis/go-redis/v9"
-
-	"github.com/Silo-Server/silo-server/internal/autoscan"
-	"github.com/Silo-Server/silo-server/internal/catalog"
-	"github.com/Silo-Server/silo-server/internal/plugins"
-	mediarequests "github.com/Silo-Server/silo-server/internal/requests"
-	"github.com/Silo-Server/silo-server/internal/scantrigger"
-)
-
-// autoscanQueuer is the scan-enqueue surface BuildAutoscanService needs; it is
-// satisfied by *scanqueue.Service (autoscan.Queuer's concrete production impl).
-type autoscanQueuer = autoscan.Queuer
-
-// RequestIntegrationLookup adapts the Requests repository to the autoscan
-// connection resolver's RequestIntegrationLookup: it resolves a soft-linked
-// Requests integration to its base URL and api key (the repo decrypts the key
-// on read, so this returns plaintext).
-type RequestIntegrationLookup struct {
-	Repo *mediarequests.Repository
-}
-
-func (l RequestIntegrationLookup) Get(ctx context.Context, integrationID string) (baseURL, apiKey string, err error) {
-	integration, err := l.Repo.GetIntegration(ctx, integrationID)
-	if err != nil {
-		return "", "", err
-	}
-	// A reused Requests connection must honor the integration's live state. The
-	// v1 poll gated on `WHERE ri.enabled = true`; here we surface a disabled or
-	// unconfigured (blank base_url) integration as an error so the engine turns
-	// it into a logged skip / RecordError rather than polling an unusable target.
-	if err := checkRequestIntegrationUsable(integrationID, integration.Enabled, integration.BaseURL); err != nil {
-		return "", "", err
-	}
-	return integration.BaseURL, integration.APIKeyRef, nil
-}
-
-// checkRequestIntegrationUsable returns a non-nil error when a linked Requests
-// integration cannot be polled: it is disabled, or it has no base_url. Extracted
-// as a pure function so the gating is unit-testable without a DB-backed repo.
-func checkRequestIntegrationUsable(integrationID string, enabled bool, baseURL string) error {
-	if !enabled {
-		return fmt.Errorf("linked requests integration %q is disabled", integrationID)
-	}
-	if strings.TrimSpace(baseURL) == "" {
-		return fmt.Errorf("linked requests integration %q has no base_url configured", integrationID)
-	}
-	return nil
-}
-
-// PluginScanSourceAdapter adapts plugins.Service to autoscan.ScanSourceResolver.
-// plugins.Service.ScanSourceClient returns the concrete
-// *pluginhost.ScanSourceClient; that concrete type satisfies
-// autoscan.PollChangesClient (it has the matching PollChanges method), so the
-// adapter declares the exported interface as its return type and returns the
-// concrete value (Go has no return-type covariance, so the method signature must
-// name the interface exactly to satisfy ScanSourceResolver).
-type PluginScanSourceAdapter struct {
-	Svc *plugins.Service
-}
-
-func (a PluginScanSourceAdapter) ScanSourceClient(ctx context.Context, pluginID, capabilityID string) (autoscan.PollChangesClient, error) {
-	return a.Svc.ScanSourceClientByPluginID(ctx, pluginID, capabilityID)
-}
-
-// scanSourceCapabilityType is the plugin capability type autoscan discovery
-// enumerates.
-const scanSourceCapabilityType = "scan_source.v1"
-
-// PluginScanSourceLister adapts the plugin installation store to
-// autoscan.ScanSourceLister: it enumerates every installed scan_source.v1
-// capability across ALL installed plugins, regardless of enabled state.
-type PluginScanSourceLister struct {
-	Store *plugins.InstallationStore
-}
-
-func (l PluginScanSourceLister) ListScanSources(ctx context.Context) ([]autoscan.DiscoveredSource, error) {
-	installations, err := l.Store.List(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var out []autoscan.DiscoveredSource
-	for _, inst := range installations {
-		caps, err := l.Store.ListCapabilities(ctx, inst.ID)
-		if err != nil {
-			return nil, err
-		}
-		for _, c := range caps {
-			if c == nil || c.Type != scanSourceCapabilityType {
-				continue
-			}
-			out = append(out, autoscan.DiscoveredSource{
-				PluginID:     inst.PluginID,
-				CapabilityID: c.ID,
-				DisplayName:  scanSourceDisplayName(inst.PluginID, c),
-			})
-		}
-	}
-	return out, nil
-}
-
-// scanSourceDisplayName derives a human-friendly label for a scan_source
-// capability: the capability manifest's display_name when present, else the
-// plugin id (with the capability id appended when it adds information).
-func scanSourceDisplayName(pluginID string, c *plugins.Capability) string {
-	if c != nil && c.Metadata != nil {
-		if name, ok := c.Metadata["display_name"].(string); ok && strings.TrimSpace(name) != "" {
-			return strings.TrimSpace(name)
-		}
-	}
-	switch {
-	case pluginID != "" && c != nil && c.ID != "":
-		return pluginID + " / " + c.ID
-	case pluginID != "":
-		return pluginID
-	case c != nil:
-		return c.ID
-	default:
-		return ""
-	}
-}
-
-// BuildAutoscanService wires the v2 autoscan engine from its concrete
-// dependencies. Both the HTTP router (manual trigger) and the background poll
-// task share this constructor so the adapter wiring lives in exactly one place.
-// Credentials are now decrypted inline by the autoscan/requests repos, so there
-// is no separate secret resolver to thread.
-func BuildAutoscanService(
-	repo *autoscan.Repository,
-	pluginService *plugins.Service,
-	installationStore *plugins.InstallationStore,
-	requestsRepo *mediarequests.Repository,
-	folderRepo *catalog.FolderRepository,
-	queue autoscanQueuer,
-	redisClient *redis.Client,
-) *autoscan.Service {
-	provider := autoscan.NewPluginProvider(PluginScanSourceAdapter{pluginService})
-	connRes := autoscan.NewConnectionResolver(RequestIntegrationLookup{requestsRepo})
-	svc := autoscan.NewService(
-		repo,
-		provider,
-		connRes,
-		scantrigger.NewResolver(folderRepo),
-		queue,
-		autoscan.NewRedisSuppressor(redisClient),
-		PluginScanSourceLister{installationStore},
-	)
-	// Wire the connection-test + rewrite-suggester deps: a (long-timeout)
-	// arr root-folder/status client and a Silo media-folder lister.
-	svc.SetSuggesterDeps(
-		autoscan.NewArrRootFolderClient(nil),
-		autoscan.NewCatalogFolderLister(folderRepo),
-	)
-	return svc
-}
@@ -1,56 +0,0 @@
-package api
-
-import (
-	"testing"
-
-	mediarequests "github.com/Silo-Server/silo-server/internal/requests"
-)
-
-// TestCheckRequestIntegrationUsable verifies the Fix 4 gate: a reused Requests
-// connection is rejected when the integration is disabled or has no base_url, so
-// the autoscan engine skips it instead of polling an unusable target.
-func TestCheckRequestIntegrationUsable(t *testing.T) {
-	t.Run("enabled with base_url is usable", func(t *testing.T) {
-		if err := checkRequestIntegrationUsable("req-1", true, "http://radarr:7878"); err != nil {
-			t.Fatalf("expected usable, got %v", err)
-		}
-	})
-	t.Run("disabled is rejected", func(t *testing.T) {
-		if err := checkRequestIntegrationUsable("req-1", false, "http://radarr:7878"); err == nil {
-			t.Fatal("expected error for disabled integration")
-		}
-	})
-	t.Run("blank base_url is rejected", func(t *testing.T) {
-		if err := checkRequestIntegrationUsable("req-1", true, "   "); err == nil {
-			t.Fatal("expected error for blank base_url")
-		}
-	})
-}
-
-// TestCheckRequestIntegrationUsableGatesReuse is the Task 17 regression test. It
-// locks the autoscan→requests credential-reuse behavior after the
-// request_integrations table was generalized into the two-tier connection
-// registry (Task 9/10): autoscan must keep reusing the Sonarr/Radarr connection
-// rows via the same enabled + base_url gate, regardless of the added
-// capability/installation columns.
-func TestCheckRequestIntegrationUsableGatesReuse(t *testing.T) {
-	// Enabled + non-blank base_url -> usable (autoscan can reuse the connection).
-	if err := checkRequestIntegrationUsable("int-1", true, "http://sonarr:8989"); err != nil {
-		t.Fatalf("enabled integration with base_url should be usable, got: %v", err)
-	}
-	// Disabled -> error (autoscan must not poll a disabled connection).
-	if err := checkRequestIntegrationUsable("int-1", false, "http://sonarr:8989"); err == nil {
-		t.Fatal("disabled integration must be rejected")
-	}
-	// Blank base_url -> error.
-	if err := checkRequestIntegrationUsable("int-1", true, "   "); err == nil {
-		t.Fatal("blank base_url must be rejected")
-	}
-}
-
-// Compile-time guard: autoscan's RequestIntegrationLookup reads these fields off
-// mediarequests.Integration. If any is renamed/removed, autoscan reuse breaks —
-// fail the build here rather than silently at runtime.
-var _ = func(in mediarequests.Integration) (string, string, bool) {
-	return in.BaseURL, in.APIKeyRef, in.Enabled
-}
@@ -9,7 +9,6 @@ import (
 	"io"
 	"log/slog"
 	"net/http"
-	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -21,18 +20,14 @@ import (

 	"github.com/Silo-Server/silo-server/internal/access"
 	"github.com/Silo-Server/silo-server/internal/adminjob"
-	"github.com/Silo-Server/silo-server/internal/ai/llm"
 	apimw "github.com/Silo-Server/silo-server/internal/api/middleware"
 	"github.com/Silo-Server/silo-server/internal/auth"
 	"github.com/Silo-Server/silo-server/internal/cache"
 	"github.com/Silo-Server/silo-server/internal/catalog"
 	"github.com/Silo-Server/silo-server/internal/clientip"
-	"github.com/Silo-Server/silo-server/internal/config"
-	evt "github.com/Silo-Server/silo-server/internal/events"
 	"github.com/Silo-Server/silo-server/internal/markers"
 	"github.com/Silo-Server/silo-server/internal/models"
 	"github.com/Silo-Server/silo-server/internal/notifications"
-	subtitleai "github.com/Silo-Server/silo-server/internal/subtitles/ai"
 	"github.com/Silo-Server/silo-server/internal/userstore"
 )

@@ -86,9 +81,7 @@ type AdminHandler struct {
 	accountProvisioner           *auth.AccountProvisioner
 	DetailSvc                    *catalog.DetailService
 	StatsSource                  AdminStatsSource
-	Config                       *config.Config
 	EventBus                     cache.EventBus
-	EventsHub                    *evt.Hub
 	SettingsRepo                 ServerSettingsStore
 	JobRepo                      AdminJobCreator
 	ItemRefreshResolver          ItemRefreshScopeResolver
@@ -98,7 +91,6 @@ type AdminHandler struct {
 	BootstrapSensitiveValues     map[string]string
 	OnUserSessionsRevoked        func(ctx context.Context, userID int)
 	OnServerSettingUpdated       func(ctx context.Context, key, value string)
-	RestartStatus                *ServerRestartStatusTracker
 }

 // NewAdminHandler creates a new AdminHandler backed by the given
@@ -120,34 +112,20 @@ func NewAdminHandler(

 // createUserRequest represents the JSON body for POST /admin/users.
 type createUserRequest struct {
-	Username                 string                 `json:"username"`
-	Email                    string                 `json:"email"`
-	Password                 string                 `json:"password"`
-	Role                     string                 `json:"role"`
-	Permissions              createStringSliceField `json:"permissions"`
-	CreateDefaultProfile     bool                   `json:"create_default_profile"`
-	DefaultProfileName       string                 `json:"default_profile_name,omitempty"`
-	LibraryIDs               []int                  `json:"library_ids"`
-	MaxPlaybackQuality       string                 `json:"max_playback_quality"`
-	MaxStreams               *int                   `json:"max_streams,omitempty"`
-	MaxTranscodes            *int                   `json:"max_transcodes,omitempty"`
-	MaxProfiles              *int                   `json:"max_profiles,omitempty"`
-	DownloadAllowed          *bool                  `json:"download_allowed,omitempty"`
-	DownloadTranscodeAllowed *bool                  `json:"download_transcode_allowed,omitempty"`
-}
-
-type createStringSliceField struct {
-	Set   bool
-	Value []string
-}
-
-func (f *createStringSliceField) UnmarshalJSON(data []byte) error {
-	f.Set = true
-	if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
-		f.Value = []string{}
-		return nil
-	}
-	return json.Unmarshal(data, &f.Value)
+	Username                 string   `json:"username"`
+	Email                    string   `json:"email"`
+	Password                 string   `json:"password"`
+	Role                     string   `json:"role"`
+	Permissions              []string `json:"permissions"`
+	CreateDefaultProfile     bool     `json:"create_default_profile"`
+	DefaultProfileName       string   `json:"default_profile_name,omitempty"`
+	LibraryIDs               []int    `json:"library_ids"`
+	MaxPlaybackQuality       string   `json:"max_playback_quality"`
+	MaxStreams               *int     `json:"max_streams,omitempty"`
+	MaxTranscodes            *int     `json:"max_transcodes,omitempty"`
+	MaxProfiles              *int     `json:"max_profiles,omitempty"`
+	DownloadAllowed          *bool    `json:"download_allowed,omitempty"`
+	DownloadTranscodeAllowed *bool    `json:"download_transcode_allowed,omitempty"`
 }

 type updateLibraryIDsField struct {
@@ -395,9 +373,6 @@ func (h *AdminHandler) HandleCreateUser(w http.ResponseWriter, r *http.Request)
 		return
 	}

-	req.Username = auth.NormalizeUsername(req.Username)
-	req.Email = auth.NormalizeEmail(req.Email)
-
 	if req.Username == "" || req.Email == "" || req.Password == "" || req.Role == "" {
 		writeError(w, http.StatusBadRequest, "bad_request", "Username, email, password, and role are required")
 		return
@@ -412,11 +387,7 @@ func (h *AdminHandler) HandleCreateUser(w http.ResponseWriter, r *http.Request)
 		writeError(w, http.StatusBadRequest, "bad_request", "max_profiles must be at least 1")
 		return
 	}
-	permissions := auth.DefaultUserPermissions()
-	if req.Permissions.Set {
-		permissions = req.Permissions.Value
-	}
-	permissions, err := auth.NormalizePermissions(permissions)
+	permissions, err := auth.NormalizePermissions(req.Permissions)
 	if err != nil {
 		writeError(w, http.StatusBadRequest, "bad_request", err.Error())
 		return
@@ -489,7 +460,7 @@ func (h *AdminHandler) HandleUpdateUser(w http.ResponseWriter, r *http.Request)
 		permissions = &normalized
 	}

-	updateInput := models.UpdateUserInput{
+	err = h.userRepo.Update(r.Context(), id, models.UpdateUserInput{
 		Username:                 req.Username,
 		Email:                    req.Email,
 		Password:                 req.Password,
@@ -503,31 +474,12 @@ func (h *AdminHandler) HandleUpdateUser(w http.ResponseWriter, r *http.Request)
 		MaxProfiles:              req.MaxProfiles,
 		DownloadAllowed:          req.DownloadAllowed,
 		DownloadTranscodeAllowed: req.DownloadTranscodeAllowed,
-	}
-
-	var currentUser *models.User
-	if updateMayRequireSessionRevocation(updateInput) {
-		currentUser, err = h.userRepo.GetByID(r.Context(), id)
-		if err != nil {
-			if auth.IsNotFound(err) {
-				writeError(w, http.StatusNotFound, "not_found", "User not found")
-				return
-			}
-			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to fetch user")
-			return
-		}
-	}
-
-	err = h.userRepo.Update(r.Context(), id, updateInput)
+	})
 	if err != nil {
-		if auth.IsNotFound(err) {
-			writeError(w, http.StatusNotFound, "not_found", "User not found")
-			return
-		}
 		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to update user")
 		return
 	}
-	if updateRequiresSessionRevocation(currentUser, updateInput) {
+	if updateRequiresSessionRevocation(req) {
 		if err := h.revokeUserSessions(r.Context(), id); err != nil {
 			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to revoke updated user sessions")
 			return
@@ -795,35 +747,13 @@ func (h *AdminHandler) HandleListUserProfiles(w http.ResponseWriter, r *http.Req
 	writeJSON(w, http.StatusOK, resp)
 }

-func updateMayRequireSessionRevocation(input models.UpdateUserInput) bool {
-	return input.Password != nil ||
-		input.Role != nil ||
-		input.Enabled != nil ||
-		input.Permissions != nil ||
-		input.MaxPlaybackQuality != nil
-}
-
-func updateRequiresSessionRevocation(current *models.User, input models.UpdateUserInput) bool {
-	if input.Password != nil {
-		return true
-	}
-	if current == nil {
-		return updateMayRequireSessionRevocation(input)
-	}
-	if input.Role != nil && *input.Role != current.Role {
-		return true
-	}
-	if input.Enabled != nil && *input.Enabled != current.Enabled {
-		return true
-	}
-	if input.Permissions != nil && !slices.Equal(*input.Permissions, current.Permissions) {
-		return true
-	}
-	if input.MaxPlaybackQuality != nil &&
-		access.NormalizePlaybackQuality(*input.MaxPlaybackQuality) != access.NormalizePlaybackQuality(current.MaxPlaybackQuality) {
-		return true
-	}
-	return false
+func updateRequiresSessionRevocation(req updateUserRequest) bool {
+	return req.Password != nil ||
+		req.Role != nil ||
+		req.Enabled != nil ||
+		req.LibraryIDs.Set ||
+		req.Permissions.Set ||
+		req.MaxPlaybackQuality != nil
 }

 func (h *AdminHandler) revokeUserSessions(ctx context.Context, userID int) error {
@@ -900,9 +830,6 @@ func (h *AdminHandler) HandleGetStats(w http.ResponseWriter, r *http.Request) {
 	var resp AdminStats

 	if h.StatsSource != nil {
-		if isTruthyQuery(r.URL.Query().Get("refresh")) {
-			h.StatsSource.Invalidate()
-		}
 		stats, err := h.StatsSource.Get(r.Context())
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to get stats")
@@ -929,15 +856,6 @@ func (h *AdminHandler) HandleGetStats(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, resp)
 }

-func isTruthyQuery(value string) bool {
-	switch strings.ToLower(strings.TrimSpace(value)) {
-	case "1", "true", "yes", "on":
-		return true
-	default:
-		return false
-	}
-}
-
 func (h *AdminHandler) invalidateStats(ctx context.Context, channel, eventType, payload string) {
 	if h.StatsSource != nil {
 		h.StatsSource.Invalidate()
@@ -1048,7 +966,6 @@ type UpdateItemMetadataRequest struct {
 	FirstAirDate     *string   `json:"first_air_date"`
 	LastAirDate      *string   `json:"last_air_date"`
 	AirTime          *string   `json:"air_time"`
-	AirTimezone      *string   `json:"air_timezone"`
 	AirDate          *string   `json:"air_date"`
 	Status           *string   `json:"status"`
 	RatingIMDB       *float64  `json:"rating_imdb"`
@@ -1076,14 +993,6 @@ func (h *AdminHandler) HandleUpdateItemMetadata(w http.ResponseWriter, r *http.R
 		writeError(w, http.StatusBadRequest, "bad_request", "Invalid request body")
 		return
 	}
-	if req.AirTimezone != nil {
-		trimmed := strings.TrimSpace(*req.AirTimezone)
-		req.AirTimezone = &trimmed
-		if !catalog.ValidateAirTimezone(trimmed) {
-			writeError(w, http.StatusBadRequest, "bad_request", "air_timezone must be a valid IANA timezone")
-			return
-		}
-	}

 	upd := catalog.MetadataUpdate{
 		Title: req.Title, SortTitle: req.SortTitle, OriginalTitle: req.OriginalTitle,
@@ -1091,7 +1000,7 @@ func (h *AdminHandler) HandleUpdateItemMetadata(w http.ResponseWriter, r *http.R
 		Year: req.Year, Runtime: req.Runtime,
 		Genres: req.Genres, Studios: req.Studios, Networks: req.Networks, Countries: req.Countries,
 		ReleaseDate: req.ReleaseDate, FirstAirDate: req.FirstAirDate, LastAirDate: req.LastAirDate,
-		AirTime: req.AirTime, AirTimezone: req.AirTimezone,
+		AirTime: req.AirTime,
 		AirDate: req.AirDate, Status: req.Status,
 		RatingIMDB: req.RatingIMDB, RatingTMDB: req.RatingTMDB,
 		RatingRTCritic: req.RatingRTCritic, RatingRTAudience: req.RatingRTAudience,
@@ -1144,10 +1053,28 @@ func (h *AdminHandler) HandleUpdateItemMetadata(w http.ResponseWriter, r *http.R

 // --- Server Settings endpoints ---

-// sensitiveSettingKeys is the audited allowlist of secret-bearing settings
-// keys, shared with the at-rest encryption decorator so redaction and
-// encryption can never drift apart. See catalog.SensitiveSettingKeys.
-var sensitiveSettingKeys = catalog.SensitiveSettingKeys
+var sensitiveSettingKeys = map[string]bool{
+	"auth.jwt_secret":                      true,
+	"s3.public_access_key":                 true,
+	"s3.public_secret_key":                 true,
+	"s3.public_token_secret":               true,
+	"s3.private_access_key":                true,
+	"s3.private_secret_key":                true,
+	"s3.user_db_access_key":                true,
+	"s3.user_db_secret_key":                true,
+	"redis.url":                            true,
+	"recommendations.openai_api_key":       true,
+	"recommendations.embedding_auth_token": true,
+	"tmdb.api_key":                         true,
+	"introdb.api_key":                      true,
+	"mdblist.api_key":                      true,
+	"requests.radarr.api_key":              true,
+	"requests.sonarr.api_key":              true,
+	"watchsync.trakt.client_id":            true,
+	"watchsync.trakt.client_secret":        true,
+	"watchsync.simkl.client_id":            true,
+	"watchsync.simkl.client_secret":        true,
+}

 // HandleGetSettings handles GET /admin/settings.
 func (h *AdminHandler) HandleGetSettings(w http.ResponseWriter, r *http.Request) {
@@ -1222,9 +1149,6 @@ func (h *AdminHandler) HandleGetSensitiveStatus(w http.ResponseWriter, r *http.R
 type adminSettingResponse struct {
 	Key   string `json:"key"`
 	Value string `json:"value"`
-	// RestartRequired reports whether the saved value only takes effect
-	// after a server restart (set on update responses only).
-	RestartRequired bool `json:"restart_required,omitempty"`
 }

 type adminSettingsListResponse struct {
@@ -1278,9 +1202,6 @@ type adminDeviceDetailResponse struct {
 	DeviceID       string                       `json:"device_id"`
 	DeviceName     string                       `json:"device_name"`
 	DevicePlatform string                       `json:"device_platform"`
-	OverrideCount  int                          `json:"override_count"`
-	ProfileCount   int                          `json:"profile_count"`
-	Profiles       []adminDeviceProfileSummary  `json:"profiles"`
 	LastUpdated    string                       `json:"last_updated"`
 	Settings       []adminDeviceSettingResponse `json:"settings"`
 }
@@ -1523,12 +1444,6 @@ func (h *AdminHandler) HandleUpdateUserDeviceSetting(w http.ResponseWriter, r *h
 	if existing != nil {
 		entry.DeviceName = existing.DeviceName
 		entry.DevicePlatform = existing.DevicePlatform
-	} else if registered, err := registeredDeviceForProfile(r.Context(), store, profileID, deviceID); err != nil {
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load device")
-		return
-	} else if registered != nil {
-		entry.DeviceName = registered.DeviceName
-		entry.DevicePlatform = registered.DevicePlatform
 	}
 	if err := store.SetDeviceSetting(r.Context(), entry); err != nil {
 		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to update device setting")
@@ -1651,10 +1566,6 @@ func (h *AdminHandler) HandleListDevices(w http.ResponseWriter, r *http.Request)
 			if err != nil {
 				return fmt.Errorf("list device settings: %w", err)
 			}
-			devices, err := listRegisteredDevices(gctx, store)
-			if err != nil {
-				return fmt.Errorf("list devices: %w", err)
-			}
 			profileNames, err := listProfileNamesByID(gctx, store)
 			if err != nil {
 				slog.Warn("admin list devices profile lookup failed",
@@ -1663,14 +1574,7 @@ func (h *AdminHandler) HandleListDevices(w http.ResponseWriter, r *http.Request)
 				)
 				profileNames = map[string]string{}
 			}
-			perUser[i] = buildAdminDeviceSummaries(
-				user.ID,
-				user.Username,
-				user.Email,
-				entries,
-				devices,
-				profileNames,
-			)
+			perUser[i] = buildAdminDeviceSummaries(user.ID, user.Username, user.Email, entries, profileNames)
 			return nil
 		})
 	}
@@ -1734,11 +1638,6 @@ func (h *AdminHandler) HandleGetDevice(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load device")
 		return
 	}
-	registeredDevices, err := listRegisteredDevices(r.Context(), store)
-	if err != nil {
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load device")
-		return
-	}
 	profileNames, err := listProfileNamesByID(r.Context(), store)
 	if err != nil {
 		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to list profiles")
@@ -1751,26 +1650,12 @@ func (h *AdminHandler) HandleGetDevice(w http.ResponseWriter, r *http.Request) {
 			deviceEntries = append(deviceEntries, entry)
 		}
 	}
-	deviceRegistrations := make([]userstore.DeviceEntry, 0)
-	for _, entry := range registeredDevices {
-		if entry.DeviceID == deviceID {
-			deviceRegistrations = append(deviceRegistrations, entry)
-		}
-	}
-	summaries := buildAdminDeviceSummaries(
-		user.ID,
-		user.Username,
-		user.Email,
-		deviceEntries,
-		deviceRegistrations,
-		profileNames,
-	)
-	if len(summaries) == 0 {
+	if len(deviceEntries) == 0 {
 		writeError(w, http.StatusNotFound, "not_found", "Device not found")
 		return
 	}

-	summary := summaries[0]
+	summary := buildAdminDeviceSummaries(user.ID, user.Username, user.Email, deviceEntries, profileNames)[0]
 	writeJSON(w, http.StatusOK, adminDeviceDetailResponse{
 		UserID:         user.ID,
 		Username:       user.Username,
@@ -1778,41 +1663,11 @@ func (h *AdminHandler) HandleGetDevice(w http.ResponseWriter, r *http.Request) {
 		DeviceID:       summary.DeviceID,
 		DeviceName:     summary.DeviceName,
 		DevicePlatform: summary.DevicePlatform,
-		OverrideCount:  summary.OverrideCount,
-		ProfileCount:   summary.ProfileCount,
-		Profiles:       summary.Profiles,
 		LastUpdated:    summary.LastUpdated,
 		Settings:       buildAdminDeviceSettingsResponse(user.ID, profileNames, deviceEntries).Settings,
 	})
 }

-func listRegisteredDevices(ctx context.Context, store userstore.UserStore) ([]userstore.DeviceEntry, error) {
-	registry, ok := store.(userstore.DeviceRegistry)
-	if !ok {
-		return nil, nil
-	}
-	return registry.ListDevices(ctx)
-}
-
-func registeredDeviceForProfile(
-	ctx context.Context,
-	store userstore.UserStore,
-	profileID string,
-	deviceID string,
-) (*userstore.DeviceEntry, error) {
-	devices, err := listRegisteredDevices(ctx, store)
-	if err != nil {
-		return nil, err
-	}
-	for _, device := range devices {
-		if device.ProfileID == profileID && device.DeviceID == deviceID {
-			matched := device
-			return &matched, nil
-		}
-	}
-	return nil, nil
-}
-
 func buildAdminDeviceSettingsResponse(userID int, profileNames map[string]string, entries []userstore.DeviceSettingEntry) adminDeviceSettingsListResponse {
 	resp := adminDeviceSettingsListResponse{
 		Settings: make([]adminDeviceSettingResponse, 0, len(entries)),
@@ -1838,7 +1693,6 @@ func buildAdminDeviceSummaries(
 	username string,
 	email string,
 	entries []userstore.DeviceSettingEntry,
-	registeredDevices []userstore.DeviceEntry,
 	profileNames map[string]string,
 ) []adminDeviceSummaryResponse {
 	type profileAccumulator struct {
@@ -1852,10 +1706,10 @@ func buildAdminDeviceSummaries(
 	}

 	byDevice := make(map[string]*summary)
-
-	ensureDevice := func(deviceID, deviceName, devicePlatform, lastUpdated string) *summary {
+	for _, entry := range entries {
+		deviceID := strings.TrimSpace(entry.DeviceID)
 		if deviceID == "" {
-			return nil
+			continue
 		}
 		current, ok := byDevice[deviceID]
 		if !ok {
@@ -1865,86 +1719,49 @@ func buildAdminDeviceSummaries(
 					Username:       username,
 					Email:          email,
 					DeviceID:       deviceID,
-					DeviceName:     deviceName,
-					DevicePlatform: devicePlatform,
-					LastUpdated:    lastUpdated,
+					DeviceName:     entry.DeviceName,
+					DevicePlatform: entry.DevicePlatform,
+					LastUpdated:    entry.UpdatedAt,
 				},
 				keys:     make(map[string]struct{}),
 				profiles: make(map[string]*profileAccumulator),
 			}
 			byDevice[deviceID] = current
 		}
-		if current.device.DeviceName == "" && deviceName != "" {
-			current.device.DeviceName = deviceName
-		}
-		if current.device.DevicePlatform == "" && devicePlatform != "" {
-			current.device.DevicePlatform = devicePlatform
-		}
-		if lastUpdated > current.device.LastUpdated {
-			current.device.LastUpdated = lastUpdated
-			if deviceName != "" {
-				current.device.DeviceName = deviceName
-			}
-			if devicePlatform != "" {
-				current.device.DevicePlatform = devicePlatform
-			}
-		}
-		return current
-	}
-
-	ensureProfile := func(current *summary, profileID, lastUpdated string) *profileAccumulator {
-		if current == nil || profileID == "" {
-			return nil
-		}
-		profile, exists := current.profiles[profileID]
-		if !exists {
-			profile = &profileAccumulator{
-				summary: adminDeviceProfileSummary{
-					ProfileID:   profileID,
-					ProfileName: profileNames[profileID],
-					LastUpdated: lastUpdated,
-				},
-				keys: make(map[string]struct{}),
-			}
-			current.profiles[profileID] = profile
-			return profile
-		}
-		if lastUpdated > profile.summary.LastUpdated {
-			profile.summary.LastUpdated = lastUpdated
-		}
-		return profile
-	}
-
-	for _, device := range registeredDevices {
-		deviceID := strings.TrimSpace(device.DeviceID)
-		profileID := strings.TrimSpace(device.ProfileID)
-		current := ensureDevice(
-			deviceID,
-			device.DeviceName,
-			device.DevicePlatform,
-			device.LastSeenAt,
-		)
-		ensureProfile(current, profileID, device.LastSeenAt)
-	}
-
-	for _, entry := range entries {
-		deviceID := strings.TrimSpace(entry.DeviceID)
+		current.keys[entry.ProfileID+":"+entry.Key] = struct{}{}
 		profileID := strings.TrimSpace(entry.ProfileID)
-		current := ensureDevice(
-			deviceID,
-			entry.DeviceName,
-			entry.DevicePlatform,
-			entry.UpdatedAt,
-		)
-		if current == nil {
-			continue
-		}
-		if profileID != "" && entry.Key != "" {
-			current.keys[profileID+":"+entry.Key] = struct{}{}
-		}
-		profile := ensureProfile(current, profileID, entry.UpdatedAt)
-		if profile != nil && entry.Key != "" {
+		if profileID != "" {
+			profile, exists := current.profiles[profileID]
+			if !exists {
+				profile = &profileAccumulator{
+					summary: adminDeviceProfileSummary{
+						ProfileID:   profileID,
+						ProfileName: profileNames[profileID],
+						LastUpdated: entry.UpdatedAt,
+					},
+					keys: make(map[string]struct{}),
+				}
+				current.profiles[profileID] = profile
+			}
 			profile.keys[entry.Key] = struct{}{}
+			if entry.UpdatedAt > profile.summary.LastUpdated {
+				profile.summary.LastUpdated = entry.UpdatedAt
+			}
+		}
+		if current.device.DeviceName == "" && entry.DeviceName != "" {
+			current.device.DeviceName = entry.DeviceName
+		}
+		if current.device.DevicePlatform == "" && entry.DevicePlatform != "" {
+			current.device.DevicePlatform = entry.DevicePlatform
+		}
+		if entry.UpdatedAt > current.device.LastUpdated {
+			current.device.LastUpdated = entry.UpdatedAt
+			if entry.DeviceName != "" {
+				current.device.DeviceName = entry.DeviceName
+			}
+			if entry.DevicePlatform != "" {
+				current.device.DevicePlatform = entry.DevicePlatform
+			}
 		}
 	}

@@ -2111,33 +1928,6 @@ func (h *AdminHandler) HandleUpdateSetting(w http.ResponseWriter, r *http.Reques
 		} else {
 			req.Value = normalized
 		}
-	case "ai.asr_base_url":
-		if llm.IsChatOnlyGateway(req.Value) {
-			writeError(w, http.StatusBadRequest, "bad_request",
-				"This endpoint cannot produce timestamped transcriptions (chat-only gateway). "+
-					"Use a self-hosted Whisper server (faster-whisper/speaches), api.groq.com/openai, or api.openai.com.")
-			return
-		}
-	case "metadata_ai.on_view":
-		switch req.Value {
-		case "off", "button", "auto":
-		default:
-			writeError(w, http.StatusBadRequest, "bad_request",
-				"metadata_ai.on_view must be off, button, or auto")
-			return
-		}
-	case "subtitle_ai.transcribe_quota_jobs":
-		if n, err := strconv.Atoi(req.Value); err != nil || n < 0 {
-			writeError(w, http.StatusBadRequest, "bad_request",
-				"subtitle_ai.transcribe_quota_jobs must be an integer >= 0 (0 = unlimited)")
-			return
-		}
-	case "subtitle_ai.transcribe_quota_period":
-		if !subtitleai.ValidQuotaPeriod(req.Value) {
-			writeError(w, http.StatusBadRequest, "bad_request",
-				"subtitle_ai.transcribe_quota_period must be day, week, or month")
-			return
-		}
 	}

 	if err := h.SettingsRepo.Set(r.Context(), key, req.Value); err != nil {
@@ -2152,13 +1942,10 @@ func (h *AdminHandler) HandleUpdateSetting(w http.ResponseWriter, r *http.Reques
 	if h.OnServerSettingUpdated != nil {
 		h.OnServerSettingUpdated(r.Context(), key, req.Value)
 	}
-	restartRequired := config.RestartRequired(key)
-	if restartRequired {
-		h.markServerRestartRequired("server_settings")
-	}
+
 	if sensitiveSettingKeys[key] {
-		writeJSON(w, http.StatusOK, adminSettingResponse{Key: key, RestartRequired: restartRequired})
+		writeJSON(w, http.StatusOK, adminSettingResponse{Key: key})
 		return
 	}
-	writeJSON(w, http.StatusOK, adminSettingResponse{Key: key, Value: req.Value, RestartRequired: restartRequired})
+	writeJSON(w, http.StatusOK, adminSettingResponse{Key: key, Value: req.Value})
 }
@@ -14,7 +14,6 @@ import (
 	apimw "github.com/Silo-Server/silo-server/internal/api/middleware"
 	"github.com/Silo-Server/silo-server/internal/auth"
 	"github.com/Silo-Server/silo-server/internal/models"
-	"github.com/Silo-Server/silo-server/internal/notifications"
 )

 const adminJobDownloadExpiry = 15 * time.Minute
@@ -24,22 +23,12 @@ type AdminJobArtifactStore interface {
 	PresignGetURL(ctx context.Context, bucket, key string, expiry time.Duration) (string, error)
 }

-type adminJobRepository interface {
-	List(ctx context.Context, opts adminjob.ListJobsOptions) ([]*models.AdminJob, error)
-	GetByID(ctx context.Context, id string) (*models.AdminJob, error)
-	Cancel(ctx context.Context, id, message string, expiresAt time.Time) (*models.AdminJob, error)
-	CancelQueued(ctx context.Context, id, message string, expiresAt time.Time) (*models.AdminJob, error)
-	UpdateProgress(ctx context.Context, id string, current, total int, message string) error
-}
-
 type AdminJobsHandler struct {
-	repo           adminJobRepository
-	store          AdminJobArtifactStore
-	CancelRegistry *adminjob.CancelRegistry
-	RealtimeHub    *notifications.Hub
+	repo  *adminjob.Repository
+	store AdminJobArtifactStore
 }

-func NewAdminJobsHandler(repo adminJobRepository, store AdminJobArtifactStore) *AdminJobsHandler {
+func NewAdminJobsHandler(repo *adminjob.Repository, store AdminJobArtifactStore) *AdminJobsHandler {
 	return &AdminJobsHandler{repo: repo, store: store}
 }

@@ -131,105 +120,6 @@ func (h *AdminJobsHandler) HandleGet(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, adminJobToResponseForClaims(r, job, h.store, claims))
 }

-func (h *AdminJobsHandler) HandleCancel(w http.ResponseWriter, r *http.Request) {
-	if h == nil || h.repo == nil {
-		writeError(w, http.StatusServiceUnavailable, "not_configured", "Admin jobs are not configured")
-		return
-	}
-
-	id := chi.URLParam(r, "id")
-	if id == "" {
-		writeError(w, http.StatusBadRequest, "bad_request", "Job ID is required")
-		return
-	}
-
-	job, err := h.repo.GetByID(r.Context(), id)
-	if err != nil {
-		if errors.Is(err, adminjob.ErrJobNotFound) {
-			writeError(w, http.StatusNotFound, "not_found", "Job not found")
-			return
-		}
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load admin job")
-		return
-	}
-
-	if job.JobType != adminjob.JobTypeLibraryRefresh {
-		writeError(w, http.StatusConflict, "not_cancellable", "Only library metadata refresh jobs can be cancelled")
-		return
-	}
-
-	switch job.Status {
-	case adminjob.StatusQueued:
-		cancelled, cancelErr := h.repo.CancelQueued(
-			r.Context(),
-			id,
-			"Library metadata refresh cancelled",
-			time.Now().UTC().Add(7*24*time.Hour),
-		)
-		if cancelErr != nil {
-			if errors.Is(cancelErr, adminjob.ErrJobNotFound) {
-				writeError(w, http.StatusNotFound, "not_found", "Job not found")
-				return
-			}
-			if errors.Is(cancelErr, adminjob.ErrJobNotCancellable) {
-				advanced, loadErr := h.repo.GetByID(r.Context(), id)
-				if loadErr != nil {
-					if errors.Is(loadErr, adminjob.ErrJobNotFound) {
-						writeError(w, http.StatusNotFound, "not_found", "Job not found")
-						return
-					}
-					writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load admin job")
-					return
-				}
-				if advanced.Status == adminjob.StatusRunning {
-					h.requestRunningCancellation(w, r, advanced)
-					return
-				}
-				writeError(w, http.StatusConflict, "not_cancellable", "Job is no longer cancellable")
-				return
-			}
-			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to cancel job")
-			return
-		}
-		if h.RealtimeHub != nil {
-			publishEventJob(
-				r.Context(),
-				h.RealtimeHub.EventsHub(),
-				string(notifications.TypeJobCancelled),
-				cancelled,
-			)
-		}
-		writeJSON(w, http.StatusOK, adminJobToResponse(r, cancelled, h.store))
-	case adminjob.StatusRunning:
-		h.requestRunningCancellation(w, r, job)
-	default:
-		writeError(w, http.StatusConflict, "not_cancellable", "Job is no longer cancellable")
-	}
-}
-
-func (h *AdminJobsHandler) requestRunningCancellation(w http.ResponseWriter, r *http.Request, job *models.AdminJob) {
-	if h.CancelRegistry == nil || !h.CancelRegistry.Cancel(job.ID) {
-		writeError(w, http.StatusConflict, "not_cancellable", "Running job is not cancellable on this node")
-		return
-	}
-	if err := h.repo.UpdateProgress(
-		r.Context(),
-		job.ID,
-		job.ProgressCurrent,
-		job.ProgressTotal,
-		"Cancellation requested",
-	); err != nil {
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to request cancellation")
-		return
-	}
-	updated, err := h.repo.GetByID(r.Context(), job.ID)
-	if err != nil {
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to load admin job")
-		return
-	}
-	writeJSON(w, http.StatusAccepted, adminJobToResponse(r, updated, h.store))
-}
-
 func adminJobToResponse(r *http.Request, job *models.AdminJob, store AdminJobArtifactStore) adminJobResponse {
 	resp := adminJobResponse{
 		ID:                job.ID,
@@ -2,21 +2,12 @@ package handlers

 import (
 	"bytes"
-	"context"
 	"encoding/json"
-	"errors"
-	"net/http"
-	"net/http/httptest"
 	"testing"
-	"time"
-
-	"github.com/go-chi/chi/v5"

 	"github.com/Silo-Server/silo-server/internal/adminjob"
 	"github.com/Silo-Server/silo-server/internal/auth"
-	"github.com/Silo-Server/silo-server/internal/cache"
 	"github.com/Silo-Server/silo-server/internal/models"
-	"github.com/Silo-Server/silo-server/internal/notifications"
 )

 func TestCanReadAdminJob_AdminCanReadAnyJob(t *testing.T) {
@@ -88,195 +79,3 @@ func TestAdminJobToResponseForClaims_NonAdminSanitizesItemRefreshPayloads(t *tes
 		t.Fatalf("ErrorMessage = %q, want stripped for non-admin", resp.ErrorMessage)
 	}
 }
-
-func TestAdminJobsHandleCancel_RunningRegistryMissDoesNotUpdateProgress(t *testing.T) {
-	repo := &fakeAdminJobRepository{
-		job: &models.AdminJob{
-			ID:              "job-1",
-			JobType:         adminjob.JobTypeLibraryRefresh,
-			Status:          adminjob.StatusRunning,
-			CreatedByUserID: 1,
-			Message:         "Running",
-			RequestedAt:     time.Now().UTC(),
-		},
-	}
-	handler := NewAdminJobsHandler(repo, nil)
-
-	rec := httptest.NewRecorder()
-	handler.HandleCancel(rec, adminJobCancelRequest("job-1"))
-
-	if rec.Code != http.StatusConflict {
-		t.Fatalf("status = %d, want %d", rec.Code, http.StatusConflict)
-	}
-	if repo.updateProgressCalls != 0 {
-		t.Fatalf("UpdateProgress called %d times, want 0", repo.updateProgressCalls)
-	}
-}
-
-func TestAdminJobsHandleCancel_QueuedPublishesCancelledEvent(t *testing.T) {
-	repo := &fakeAdminJobRepository{
-		job: &models.AdminJob{
-			ID:              "job-1",
-			JobType:         adminjob.JobTypeLibraryRefresh,
-			Status:          adminjob.StatusQueued,
-			CreatedByUserID: 1,
-			Message:         "Queued",
-			RequestedAt:     time.Now().UTC(),
-		},
-	}
-	hub := notifications.NewHub("test", &cache.NoopEventBus{})
-	events, unsubscribe := hub.Subscribe()
-	defer unsubscribe()
-
-	handler := NewAdminJobsHandler(repo, nil)
-	handler.RealtimeHub = hub
-
-	rec := httptest.NewRecorder()
-	handler.HandleCancel(rec, adminJobCancelRequest("job-1"))
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want %d: %s", rec.Code, http.StatusOK, rec.Body.String())
-	}
-
-	select {
-	case event := <-events:
-		if event.Type != notifications.TypeJobCancelled {
-			t.Fatalf("event.Type = %q, want %q", event.Type, notifications.TypeJobCancelled)
-		}
-		if event.Job == nil || event.Job.ID != "job-1" {
-			t.Fatalf("event.Job = %#v, want job-1", event.Job)
-		}
-	case <-time.After(time.Second):
-		t.Fatal("timed out waiting for job.cancelled event")
-	}
-}
-
-func TestAdminJobsHandleCancel_QueuedSnapshotFallsBackToRunningCancellation(t *testing.T) {
-	repo := &fakeAdminJobRepository{
-		job: &models.AdminJob{
-			ID:              "job-1",
-			JobType:         adminjob.JobTypeLibraryRefresh,
-			Status:          adminjob.StatusQueued,
-			CreatedByUserID: 1,
-			Message:         "Queued",
-			RequestedAt:     time.Now().UTC(),
-			ProgressCurrent: 3,
-			ProgressTotal:   10,
-		},
-		promoteToRunningOnCancelQueued: true,
-	}
-	cancelled := false
-	registry := adminjob.NewCancelRegistry()
-	unregister := registry.Register("job-1", func() {
-		cancelled = true
-	})
-	defer unregister()
-
-	handler := NewAdminJobsHandler(repo, nil)
-	handler.CancelRegistry = registry
-
-	rec := httptest.NewRecorder()
-	handler.HandleCancel(rec, adminJobCancelRequest("job-1"))
-
-	if rec.Code != http.StatusAccepted {
-		t.Fatalf("status = %d, want %d: %s", rec.Code, http.StatusAccepted, rec.Body.String())
-	}
-	if !cancelled {
-		t.Fatal("expected running job cancel registry to be invoked")
-	}
-	if repo.cancelQueuedCalls != 1 {
-		t.Fatalf("CancelQueued called %d times, want 1", repo.cancelQueuedCalls)
-	}
-	if repo.cancelCalls != 0 {
-		t.Fatalf("Cancel called %d times, want 0", repo.cancelCalls)
-	}
-	if repo.updateProgressCalls != 1 {
-		t.Fatalf("UpdateProgress called %d times, want 1", repo.updateProgressCalls)
-	}
-	if repo.job.Status != adminjob.StatusRunning {
-		t.Fatalf("job status = %q, want %q", repo.job.Status, adminjob.StatusRunning)
-	}
-	if repo.job.Message != "Cancellation requested" {
-		t.Fatalf("job message = %q, want cancellation request", repo.job.Message)
-	}
-}
-
-func adminJobCancelRequest(id string) *http.Request {
-	req := httptest.NewRequest(http.MethodPost, "/admin/jobs/"+id+"/cancel", nil)
-	routeCtx := chi.NewRouteContext()
-	routeCtx.URLParams.Add("id", id)
-	return req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, routeCtx))
-}
-
-type fakeAdminJobRepository struct {
-	job                            *models.AdminJob
-	updateProgressCalls            int
-	cancelCalls                    int
-	cancelQueuedCalls              int
-	promoteToRunningOnCancelQueued bool
-}
-
-func (r *fakeAdminJobRepository) List(context.Context, adminjob.ListJobsOptions) ([]*models.AdminJob, error) {
-	if r.job == nil {
-		return nil, nil
-	}
-	return []*models.AdminJob{r.job}, nil
-}
-
-func (r *fakeAdminJobRepository) GetByID(_ context.Context, id string) (*models.AdminJob, error) {
-	if r.job == nil || r.job.ID != id {
-		return nil, adminjob.ErrJobNotFound
-	}
-	cp := *r.job
-	return &cp, nil
-}
-
-func (r *fakeAdminJobRepository) Cancel(_ context.Context, id, message string, _ time.Time) (*models.AdminJob, error) {
-	r.cancelCalls++
-	if r.job == nil || r.job.ID != id {
-		return nil, adminjob.ErrJobNotFound
-	}
-	if r.job.Status != adminjob.StatusQueued && r.job.Status != adminjob.StatusRunning {
-		return nil, adminjob.ErrJobNotCancellable
-	}
-	cp := *r.job
-	cp.Status = adminjob.StatusCancelled
-	cp.Message = message
-	r.job = &cp
-	return &cp, nil
-}
-
-func (r *fakeAdminJobRepository) CancelQueued(_ context.Context, id, message string, _ time.Time) (*models.AdminJob, error) {
-	r.cancelQueuedCalls++
-	if r.job == nil || r.job.ID != id {
-		return nil, adminjob.ErrJobNotFound
-	}
-	if r.promoteToRunningOnCancelQueued {
-		cp := *r.job
-		cp.Status = adminjob.StatusRunning
-		r.job = &cp
-		return nil, adminjob.ErrJobNotCancellable
-	}
-	if r.job.Status != adminjob.StatusQueued {
-		return nil, adminjob.ErrJobNotCancellable
-	}
-	cp := *r.job
-	cp.Status = adminjob.StatusCancelled
-	cp.Message = message
-	r.job = &cp
-	return &cp, nil
-}
-
-func (r *fakeAdminJobRepository) UpdateProgress(_ context.Context, id string, current, total int, message string) error {
-	r.updateProgressCalls++
-	if r.job == nil || r.job.ID != id {
-		return adminjob.ErrJobNotFound
-	}
-	if message == "" {
-		return errors.New("message is required")
-	}
-	r.job.ProgressCurrent = current
-	r.job.ProgressTotal = total
-	r.job.Message = message
-	return nil
-}
@@ -1,236 +0,0 @@
-package handlers
-
-import (
-	"encoding/json"
-	"log/slog"
-	"net/http"
-	"sort"
-
-	"github.com/Silo-Server/silo-server/internal/cache"
-	"github.com/Silo-Server/silo-server/internal/markers"
-)
-
-// AdminMarkerProvidersHandler serves the per-provider marker config + key
-// validation API under the RequireAdmin group.
-type AdminMarkerProvidersHandler struct {
-	Registry *markers.Registry
-	Config   *markers.ProviderConfigStore
-	EventBus cache.EventBus
-	logger   *slog.Logger
-}
-
-// NewAdminMarkerProvidersHandler constructs the handler.
-func NewAdminMarkerProvidersHandler(registry *markers.Registry, config *markers.ProviderConfigStore, eventBus cache.EventBus, logger *slog.Logger) *AdminMarkerProvidersHandler {
-	if logger == nil {
-		logger = slog.Default()
-	}
-	return &AdminMarkerProvidersHandler{Registry: registry, Config: config, EventBus: eventBus, logger: logger}
-}
-
-type providerConfigResponse struct {
-	Provider                string  `json:"provider"`
-	DisplayName             string  `json:"display_name,omitempty"`
-	SourceType              string  `json:"source_type,omitempty"`
-	PluginID                string  `json:"plugin_id,omitempty"`
-	PluginInstallationID    int     `json:"plugin_installation_id,omitempty"`
-	CapabilityID            string  `json:"capability_id,omitempty"`
-	IsSubmitter             bool    `json:"is_submitter"`
-	FetchEnabled            bool    `json:"fetch_enabled"`
-	FetchPriority           int     `json:"fetch_priority"`
-	ContributeEnabled       bool    `json:"contribute_enabled"`
-	ContributeAutoLocal     bool    `json:"contribute_auto_local"`
-	ContributeMinConfidence float64 `json:"contribute_min_confidence"`
-}
-
-type markerUserStatsResponse struct {
-	Total          int     `json:"total"`
-	Accepted       int     `json:"accepted"`
-	Pending        int     `json:"pending"`
-	Rejected       int     `json:"rejected"`
-	AcceptanceRate float64 `json:"acceptance_rate"`
-	CurrentStreak  int     `json:"current_streak"`
-	BestStreak     int     `json:"best_streak"`
-}
-
-func (h *AdminMarkerProvidersHandler) submitterIDs() map[string]bool {
-	out := map[string]bool{}
-	if h.Registry == nil {
-		return out
-	}
-	for _, p := range h.Registry.Providers() {
-		if _, ok := p.(markers.Submitter); ok {
-			out[p.ID()] = true
-		}
-	}
-	return out
-}
-
-func (h *AdminMarkerProvidersHandler) providerDescriptions() map[string]markers.ProviderDescriptor {
-	out := map[string]markers.ProviderDescriptor{}
-	if h.Registry == nil {
-		return out
-	}
-	for _, p := range h.Registry.Providers() {
-		desc := markers.ProviderDescriptor{ID: p.ID()}
-		if described, ok := p.(markers.DescribedProvider); ok {
-			desc = described.ProviderDescription()
-		}
-		if desc.ID == "" {
-			desc.ID = p.ID()
-		}
-		out[p.ID()] = desc
-	}
-	return out
-}
-
-// HandleListProviders lists registered providers with their config + capability.
-func (h *AdminMarkerProvidersHandler) HandleListProviders(w http.ResponseWriter, r *http.Request) {
-	if h == nil || h.Config == nil {
-		writeError(w, http.StatusServiceUnavailable, "unavailable", "Marker providers are not configured")
-		return
-	}
-	submitters := h.submitterIDs()
-	descriptions := h.providerDescriptions()
-	out := []providerConfigResponse{}
-	if h.Registry != nil {
-		for _, provider := range h.Registry.Providers() {
-			c, ok := h.Config.Get(provider.ID())
-			if !ok {
-				continue
-			}
-			out = append(out, toProviderConfigResponse(c, submitters[c.Provider], descriptions[c.Provider]))
-		}
-	} else {
-		for _, c := range h.Config.List() {
-			out = append(out, toProviderConfigResponse(c, submitters[c.Provider], descriptions[c.Provider]))
-		}
-	}
-	sort.Slice(out, func(i, j int) bool {
-		if out[i].FetchPriority != out[j].FetchPriority {
-			return out[i].FetchPriority < out[j].FetchPriority
-		}
-		return out[i].Provider < out[j].Provider
-	})
-	writeJSON(w, http.StatusOK, map[string]any{"providers": out})
-}
-
-// HandleUpdateProvider updates a provider's config row.
-func (h *AdminMarkerProvidersHandler) HandleUpdateProvider(w http.ResponseWriter, r *http.Request) {
-	if h == nil || h.Config == nil {
-		writeError(w, http.StatusServiceUnavailable, "unavailable", "Marker providers are not configured")
-		return
-	}
-	provider, err := decodedURLParam(r, "provider")
-	if err != nil {
-		writeError(w, http.StatusBadRequest, "bad_request", "Invalid provider ID")
-		return
-	}
-	existing, ok := h.Config.Get(provider)
-	if !ok {
-		writeError(w, http.StatusNotFound, "not_found", "Unknown marker provider")
-		return
-	}
-	var body struct {
-		FetchEnabled            *bool    `json:"fetch_enabled"`
-		FetchPriority           *int     `json:"fetch_priority"`
-		ContributeEnabled       *bool    `json:"contribute_enabled"`
-		ContributeAutoLocal     *bool    `json:"contribute_auto_local"`
-		ContributeMinConfidence *float64 `json:"contribute_min_confidence"`
-	}
-	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
-		writeError(w, http.StatusBadRequest, "bad_request", "Invalid request body")
-		return
-	}
-	if body.FetchEnabled != nil {
-		existing.FetchEnabled = *body.FetchEnabled
-	}
-	if body.FetchPriority != nil {
-		existing.FetchPriority = *body.FetchPriority
-	}
-	if body.ContributeEnabled != nil {
-		existing.ContributeEnabled = *body.ContributeEnabled
-	}
-	if body.ContributeAutoLocal != nil {
-		existing.ContributeAutoLocal = *body.ContributeAutoLocal
-	}
-	if body.ContributeMinConfidence != nil {
-		v := *body.ContributeMinConfidence
-		if v < 0 || v > 1 {
-			writeError(w, http.StatusBadRequest, "bad_request", "contribute_min_confidence must be between 0 and 1")
-			return
-		}
-		existing.ContributeMinConfidence = v
-	}
-	if err := h.Config.Update(r.Context(), existing); err != nil {
-		h.logger.Error("admin markers: update provider config failed", "provider", provider, "error", err)
-		writeError(w, http.StatusInternalServerError, "internal_error", "Failed to update provider")
-		return
-	}
-	if h.EventBus != nil {
-		_ = h.EventBus.Publish(r.Context(), cache.ChannelAdmin, cache.Event{
-			Type:    cache.EventMarkerProviderConfigChanged,
-			Payload: provider,
-		})
-	}
-	writeJSON(w, http.StatusOK, toProviderConfigResponse(existing, h.submitterIDs()[provider], h.providerDescriptions()[provider]))
-}
-
-// HandleValidateProvider validates the provider's configured key and returns stats.
-func (h *AdminMarkerProvidersHandler) HandleValidateProvider(w http.ResponseWriter, r *http.Request) {
-	if h == nil || h.Registry == nil {
-		writeError(w, http.StatusServiceUnavailable, "unavailable", "Marker providers are not configured")
-		return
-	}
-	provider, err := decodedURLParam(r, "provider")
-	if err != nil {
-		writeError(w, http.StatusBadRequest, "bad_request", "Invalid provider ID")
-		return
-	}
-	var submitter markers.Submitter
-	for _, p := range h.Registry.Providers() {
-		if p.ID() == provider {
-			if s, ok := p.(markers.Submitter); ok {
-				submitter = s
-			}
-		}
-	}
-	if submitter == nil {
-		writeError(w, http.StatusBadRequest, "bad_request", "Provider does not support contribution")
-		return
-	}
-	stats, err := submitter.FetchUserStats(r.Context())
-	if err != nil {
-		writeJSON(w, http.StatusOK, map[string]any{"valid": false, "error": err.Error()})
-		return
-	}
-	writeJSON(w, http.StatusOK, map[string]any{"valid": true, "stats": toMarkerUserStatsResponse(stats)})
-}
-
-func toProviderConfigResponse(c markers.ProviderConfig, isSubmitter bool, desc markers.ProviderDescriptor) providerConfigResponse {
-	return providerConfigResponse{
-		Provider:                c.Provider,
-		DisplayName:             desc.DisplayName,
-		SourceType:              desc.SourceType,
-		PluginID:                desc.PluginID,
-		PluginInstallationID:    desc.PluginInstallationID,
-		CapabilityID:            desc.CapabilityID,
-		IsSubmitter:             isSubmitter,
-		FetchEnabled:            c.FetchEnabled,
-		FetchPriority:           c.FetchPriority,
-		ContributeEnabled:       c.ContributeEnabled,
-		ContributeAutoLocal:     c.ContributeAutoLocal,
-		ContributeMinConfidence: c.ContributeMinConfidence,
-	}
-}
-
-func toMarkerUserStatsResponse(s markers.UserStats) markerUserStatsResponse {
-	return markerUserStatsResponse{
-		Total:          s.Total,
-		Accepted:       s.Accepted,
-		Pending:        s.Pending,
-		Rejected:       s.Rejected,
-		AcceptanceRate: s.AcceptanceRate,
-		CurrentStreak:  s.CurrentStreak,
-		BestStreak:     s.BestStreak,
-	}
-}
@@ -1,101 +0,0 @@
-package handlers
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-
-	"github.com/go-chi/chi/v5"
-
-	"github.com/Silo-Server/silo-server/internal/markers"
-)
-
-type fakeMarkerStatsSubmitter struct{}
-
-func (fakeMarkerStatsSubmitter) ID() string { return "introdb" }
-func (fakeMarkerStatsSubmitter) FetchMarkers(context.Context, markers.Request) (markers.Result, error) {
-	return markers.Result{}, nil
-}
-func (fakeMarkerStatsSubmitter) SubmitMarker(context.Context, markers.SubmissionRequest) (markers.SubmissionResult, error) {
-	return markers.SubmissionResult{}, nil
-}
-func (fakeMarkerStatsSubmitter) FetchUserStats(context.Context) (markers.UserStats, error) {
-	return markers.UserStats{Total: 10, Accepted: 7, Pending: 2, Rejected: 1, AcceptanceRate: 0.7, CurrentStreak: 3, BestStreak: 5}, nil
-}
-
-func TestValidateMarkerProviderUsesSnakeCaseStats(t *testing.T) {
-	reg := markers.NewRegistry(nil)
-	if err := reg.Register(fakeMarkerStatsSubmitter{}); err != nil {
-		t.Fatalf("register provider: %v", err)
-	}
-	h := NewAdminMarkerProvidersHandler(reg, nil, nil, nil)
-
-	req := httptest.NewRequest(http.MethodPost, "/admin/markers/providers/introdb/validate", nil)
-	rctx := chi.NewRouteContext()
-	rctx.URLParams.Add("provider", "introdb")
-	req = req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, rctx))
-
-	rec := httptest.NewRecorder()
-	h.HandleValidateProvider(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
-	}
-	body := rec.Body.String()
-	if !strings.Contains(body, `"acceptance_rate":0.7`) || strings.Contains(body, "AcceptanceRate") {
-		t.Fatalf("unexpected stats response shape: %s", body)
-	}
-}
-
-type fakePluginMarkerSubmitter struct{ fakeMarkerStatsSubmitter }
-
-func (fakePluginMarkerSubmitter) ID() string { return "plugin:6:introdb" }
-
-// Browsers send encodeURIComponent-escaped provider IDs (plugin%3A6%3Aintrodb),
-// and chi matches the raw path, so the handler must decode the route param.
-func TestValidateMarkerProviderDecodesEncodedID(t *testing.T) {
-	reg := markers.NewRegistry(nil)
-	if err := reg.Register(fakePluginMarkerSubmitter{}); err != nil {
-		t.Fatalf("register provider: %v", err)
-	}
-	h := NewAdminMarkerProvidersHandler(reg, nil, nil, nil)
-
-	router := chi.NewRouter()
-	router.Post("/admin/markers/providers/{provider}/validate", h.HandleValidateProvider)
-
-	req := httptest.NewRequest(http.MethodPost, "/admin/markers/providers/plugin%3A6%3Aintrodb/validate", nil)
-	rec := httptest.NewRecorder()
-	router.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
-	}
-	if !strings.Contains(rec.Body.String(), `"valid":true`) {
-		t.Fatalf("unexpected response: %s", rec.Body.String())
-	}
-}
-
-func TestMarkerProviderResponseIncludesPluginMetadata(t *testing.T) {
-	resp := toProviderConfigResponse(
-		markers.ProviderConfig{Provider: "plugin:4:markers", FetchEnabled: true, FetchPriority: 25},
-		true,
-		markers.ProviderDescriptor{
-			DisplayName:          "Plugin Markers",
-			SourceType:           markers.ProviderSourcePlugin,
-			PluginID:             "silo.plugin.markers",
-			PluginInstallationID: 4,
-			CapabilityID:         "markers",
-		},
-	)
-	if resp.DisplayName != "Plugin Markers" || resp.SourceType != markers.ProviderSourcePlugin {
-		t.Fatalf("plugin metadata fields missing: %+v", resp)
-	}
-	if resp.PluginID != "silo.plugin.markers" ||
-		resp.PluginInstallationID != 4 ||
-		resp.CapabilityID != "markers" ||
-		!resp.IsSubmitter {
-		t.Fatalf("plugin identity fields missing: %+v", resp)
-	}
-}
--- a/Show More
+++ b/Show More