Merge pull request 'Placement reconciler: put every image in its own artist's folder, one artist at a time' (#256) from dev into main

The UI half of the reconciler, in Maintenance. Survey shows how many images
sit in the wrong artist's folder and which folders they are in; each artist
gets its own Plan button; each run can be reviewed, applied, and put back.

Deliberately NOT using useMaintenanceTask. That composable stashes a task id
in localStorage so a result survives navigate-away, which is the right answer
when the only record is a Celery result. Here the runs are database rows — so
a reload, another machine, or coming back tomorrow simply shows the same
state, because the state IS the row. The card polls the runs endpoint instead.

Copy avoids the vocabulary this work has been tripping over: "folder", "put
back", "in the wrong folder" rather than artist_id, revert and canonical. The
one thing the operator most needs to know — nothing here changes who an image
belongs to — is what the blurb says first.

Three things I had assumed and checked instead: MaintenanceTile lives in
common/ not settings/; there is no generic ConfirmDialog (BackupCard uses a
purpose-built modal), so this uses a plain v-dialog; and `loadArtistNames`
did not exist — it does now, mapping id to name so a run row reads "Conto"
rather than "#47". The name deliberately is not denormalised into the run: it
belongs to the artist and would go stale on a rename.

Also extracted `stubFetch` to frontend/test/stubFetch.js. The shape ledger
flagged it as a byte-identical duplicate across five specs and this would
have been the sixth; the others keep their copies until each is next touched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LVjrnpQjRgHdvq95rASoiR

alembic/versions/0098_phash_256_bit_rehash.py

@@ -0,0 +1,90 @@
+"""Widen image_record.phash to 256-bit and re-hash the library (issue #4223).
+
+The operator reported a 15-image variant pack landing as 3 records, and then
+that variants were STILL being dropped with `phash_threshold` at 0. Zero was
+already the floor of the dial, so no setting could have fixed it: at
+`hash_size=8` a pHash is 64 bits of coarse light/dark layout, and variant
+artwork sharing a composition produces the SAME 64 bits. Distance 0 meant
+"identical hash", never "identical image".
+
+`utils/phash.py` moves to `hash_size=16` (256 bits, what ImageRepo always
+used) and adds an aspect-ratio gate plus a pixel-level confirm, so a merge is
+accepted on the files rather than on the hash.
+
+## Why this NULLs every phash
+
+Widening the column does not correct the values already in it. Every stored
+hash is a 64-bit hash of an image the app will now hash at 256 bits, and the
+two cannot be compared — `find_similar` skips a mismatched-length candidate
+rather than guessing, so leaving them would silently mean "no dedup, forever,
+for everything imported before today". NULL is the state `backfill_phash`
+already knows how to repair: it is NULL-only, keyset-paginated and
+restart-safe, and the beat schedule runs it daily.
+
+Until that backfill finishes, image dedup degrades to sha256 only —
+duplicates may be kept. That is the safe direction, and the only one
+available: the alternative is comparing hashes of different widths, which
+would drop artwork. NOTHING here deletes or supersedes a file.
+
+## Why the threshold is reset rather than carried over
+
+`phash_threshold` counts bits, and the denominator went from 64 to 256. The
+stored number would keep its value while meaning something four times
+tighter. There is no honest carry-over, so every row goes to the new default
+of 24 — including the operator's 0, which was a workaround for the bug this
+revision fixes.
+
+Revision ID: 0098
+Revises: 0097
+Create Date: 2026-09-21
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0098"
+down_revision: Union[str, None] = "0097"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # varchar(32) -> varchar(64): widening a length limit is a catalog-only
+    # change in Postgres, so this does not rewrite the table or its index.
+    op.alter_column(
+        "image_record", "phash",
+        existing_type=sa.String(32),
+        type_=sa.String(64),
+        existing_nullable=True,
+    )
+    op.execute("UPDATE image_record SET phash = NULL WHERE phash IS NOT NULL")
+    op.alter_column(
+        "import_settings", "phash_threshold",
+        existing_type=sa.Integer(),
+        server_default="24",
+        existing_nullable=False,
+    )
+    op.execute("UPDATE import_settings SET phash_threshold = 24")
+
+
+def downgrade() -> None:
+    # The 64-bit hashes this replaced are gone, and a 64-char value does not
+    # fit back into varchar(32) — so the column is cleared again on the way
+    # down and left for backfill_phash to refill at whatever HASH_SIZE the
+    # code is running. Rule #22: no legacy to preserve.
+    op.execute("UPDATE image_record SET phash = NULL WHERE phash IS NOT NULL")
+    op.alter_column(
+        "image_record", "phash",
+        existing_type=sa.String(64),
+        type_=sa.String(32),
+        existing_nullable=True,
+    )
+    op.alter_column(
+        "import_settings", "phash_threshold",
+        existing_type=sa.Integer(),
+        server_default="10",
+        existing_nullable=False,
+    )
+    op.execute("UPDATE import_settings SET phash_threshold = 10")

alembic/versions/0099_library_placement_run.py

@@ -0,0 +1,99 @@
+"""library_placement_run — the placement reconciler's plan/apply/undo ledger.
+
+Milestone #421 step 3. The survey (#4245) measured 33,789 ImageRecord rows
+sitting outside their artist's canonical directory, across 56 artists. This
+table holds one run of the sweep that trues them up: the plan, what it did,
+and where every file came from.
+
+## Why the moves live in a table rather than a log line
+
+`ImageRecord.path` is the only pointer at the bytes, so a move rewrites the
+row. Once that write lands, the previous location exists nowhere — unless it
+was recorded first. `moves` is that record, which is what makes a 33,789-file
+operation something the operator can undo per artist after looking at the
+result, rather than a one-way door.
+
+An `applied` row is therefore HISTORY, not state (lesson #4226). Any future
+retention on this table may prune `ready`, `cancelled` and `error` runs; an
+`applied` one is only disposable once someone decides undo is no longer
+wanted. That is deliberately not a timer's decision, and no pruning is added
+here.
+
+Revision ID: 0099
+Revises: 0098
+Create Date: 2026-09-21
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0099"
+down_revision: Union[str, None] = "0098"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "library_placement_run",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column(
+            "status", sa.String(length=16), server_default="running",
+            nullable=False,
+        ),
+        # SET NULL, not CASCADE: deleting an artist must not destroy the
+        # record of where their files were moved.
+        sa.Column("artist_id", sa.Integer(), nullable=True),
+        sa.Column(
+            "started_at", sa.DateTime(timezone=True),
+            server_default=sa.text("now()"), nullable=False,
+        ),
+        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "planned_count", sa.Integer(), server_default="0", nullable=False,
+        ),
+        sa.Column(
+            "moved_count", sa.Integer(), server_default="0", nullable=False,
+        ),
+        sa.Column(
+            "refused_count", sa.Integer(), server_default="0", nullable=False,
+        ),
+        sa.Column(
+            "moves", postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'::jsonb"), nullable=False,
+        ),
+        sa.Column(
+            "refusals", postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'::jsonb"), nullable=False,
+        ),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["artist_id"], ["artist.id"],
+            name="fk_library_placement_run_artist_id", ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_library_placement_run_status", "library_placement_run", ["status"],
+    )
+    op.create_index(
+        "ix_library_placement_run_artist_id", "library_placement_run",
+        ["artist_id"],
+    )
+
+
+def downgrade() -> None:
+    # Dropping this table destroys the only record of where moved files came
+    # from. That is correct for a downgrade — the code that reads it is going
+    # away too — but it is worth saying out loud rather than discovering.
+    op.drop_index(
+        "ix_library_placement_run_artist_id",
+        table_name="library_placement_run",
+    )
+    op.drop_index(
+        "ix_library_placement_run_status", table_name="library_placement_run",
+    )
+    op.drop_table("library_placement_run")

backend/app/api/admin.py

@@ -475,6 +475,20 @@ async def trigger_reclaim_attachments():
     return _queued(async_result)
 
 
+@admin_bp.route("/maintenance/repair-discord-downloads", methods=["POST"])
+async def trigger_repair_discord_downloads():
+    """Clean re-download of the Discord files broken by the `None` naming
+    (#3999). Body {"dry_run": bool}; dry_run is the DEFAULT, because the apply
+    deletes files and makes gallery-dl forget every Discord download. Returns the
+    Celery task id — poll /maintenance/task-result/<id> for the summary."""
+    from ..tasks.admin import repair_discord_downloads_task
+
+    body = await request.get_json(silent=True) or {}
+    dry_run = bool(body.get("dry_run", True))
+    async_result = repair_discord_downloads_task.delay(dry_run=dry_run)
+    return _queued(async_result)
+
+
 @admin_bp.route("/maintenance/dedup-videos", methods=["POST"])
 async def trigger_dedup_videos():
     """Tier-1 video dedup (#871). Body {"dry_run": bool}: dry_run=true previews

backend/app/api/artists.py

@@ -65,6 +65,16 @@ async def autocomplete():
     ])
 
 
+@artists_bp.route("/names", methods=["GET"])
+async def names():
+    """Every artist, id + name + slug, alphabetical. For filter pickers that
+    list artists before anything is typed; `autocomplete` deliberately returns
+    nothing for an empty query."""
+    async with get_session() as session:
+        rows = await ArtistService(session).all_names()
+    return jsonify([{"id": i, "name": n, "slug": s} for i, n, s in rows])
+
+
 @artists_bp.route("/directory", methods=["GET"])
 async def directory():
     """FC-3f: cursor-paginated artists directory.

backend/app/api/cleanup.py

@@ -29,8 +29,8 @@ from quart import Blueprint, jsonify, request
 from sqlalchemy import select
 
 from ..extensions import get_session
-from ..models import LibraryAuditRun
-from ..services import cleanup_service
+from ..models import LibraryAuditRun, LibraryPlacementRun
+from ..services import cleanup_service, library_layout
 from ._responses import error_response as _bad
 
 cleanup_bp = Blueprint("cleanup", __name__, url_prefix="/api/cleanup")
@@ -196,3 +196,113 @@ async def audit_cancel(audit_id: int):
         )
         await session.commit()
     return jsonify({"cancelled": True})
+
+
+@cleanup_bp.route("/layout", methods=["GET"])
+async def layout_survey():
+    """Milestone #421 blast radius: which ImageRecord rows sit outside their
+    artist's canonical slug directory, per artist.
+
+    Read-only. `?check_disk=1` additionally stats every destination to find
+    collisions with a file already there and sources that have gone missing —
+    the numbers the apply refuses on, at the cost of one stat per misplaced
+    row over NFS. It is OFF by default because a count-only pass answers "how
+    big is this" in seconds where the disk pass can run for minutes and time
+    the request out.
+    """
+    check_disk = request.args.get("check_disk", "").lower() in ("1", "true", "yes")
+    async with get_session() as session:
+        report = await session.run_sync(
+            lambda s: library_layout.survey_layout(
+                s, IMAGES_ROOT, check_disk=check_disk,
+            )
+        )
+    return jsonify({**report.as_dict(), "checked_disk": check_disk})
+
+
+def _serialize_placement_run(run: LibraryPlacementRun, *, moves: bool = False) -> dict:
+    """`moves` is opt-in: an applied whole-library run carries tens of
+    thousands of entries, which is a fine thing to hold in Postgres and a
+    poor thing to put in every list response."""
+    out = {
+        "id": run.id,
+        "status": run.status,
+        "artist_id": run.artist_id,
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "finished_at": run.finished_at.isoformat() if run.finished_at else None,
+        "planned_count": run.planned_count,
+        "moved_count": run.moved_count,
+        "refused_count": run.refused_count,
+        "refusals": run.refusals or [],
+        "error": run.error,
+    }
+    if moves:
+        out["moves"] = run.moves or []
+    return out
+
+
+@cleanup_bp.route("/placement/runs", methods=["GET"])
+async def placement_runs():
+    """Newest first. Without `moves`, so the list stays small."""
+    try:
+        limit = min(int(request.args.get("limit", "25")), 100)
+    except ValueError:
+        return _bad("invalid_limit")
+    async with get_session() as session:
+        rows = (await session.execute(
+            select(LibraryPlacementRun)
+            .order_by(LibraryPlacementRun.id.desc()).limit(limit)
+        )).scalars().all()
+    return jsonify({"runs": [_serialize_placement_run(r) for r in rows]})
+
+
+@cleanup_bp.route("/placement/runs/<int:run_id>", methods=["GET"])
+async def placement_run(run_id: int):
+    """One run WITH its moves — this is the preview the operator reads before
+    agreeing, and the record of what happened afterwards."""
+    async with get_session() as session:
+        run = await session.get(LibraryPlacementRun, run_id)
+        if run is None:
+            return _bad("not_found", status=404)
+        return jsonify(_serialize_placement_run(run, moves=True))
+
+
+@cleanup_bp.route("/placement/plan", methods=["POST"])
+async def placement_plan():
+    """Queue a planning run. `artist_id` scopes it to one artist, which is the
+    intended use: do one, look at the gallery, then continue or revert."""
+    body = await request.get_json(silent=True) or {}
+    artist_id = body.get("artist_id")
+    if artist_id is not None and not isinstance(artist_id, int):
+        return _bad("invalid_artist_id")
+    from ..tasks.library_placement import plan_placement
+    plan_placement.delay(artist_id)
+    return jsonify({"status": "dispatched"}), 202
+
+
+@cleanup_bp.route("/placement/runs/<int:run_id>/apply", methods=["POST"])
+async def placement_apply(run_id: int):
+    """Execute a ready run. This renames files and rewrites rows."""
+    async with get_session() as session:
+        run = await session.get(LibraryPlacementRun, run_id)
+        if run is None:
+            return _bad("not_found", status=404)
+        if run.status != "ready":
+            return _bad("not_ready", detail=f"run is {run.status}")
+    from ..tasks.library_placement import apply_placement
+    apply_placement.delay(run_id)
+    return jsonify({"status": "dispatched"}), 202
+
+
+@cleanup_bp.route("/placement/runs/<int:run_id>/revert", methods=["POST"])
+async def placement_revert(run_id: int):
+    """Put an applied run's files back. The reason the ledger is kept."""
+    async with get_session() as session:
+        run = await session.get(LibraryPlacementRun, run_id)
+        if run is None:
+            return _bad("not_found", status=404)
+        if run.status != "applied":
+            return _bad("not_applied", detail=f"run is {run.status}")
+    from ..tasks.library_placement import revert_placement
+    revert_placement.delay(run_id)
+    return jsonify({"status": "dispatched"}), 202

backend/app/celery_app.py

@@ -35,6 +35,7 @@ def make_celery() -> Celery:
             "backend.app.tasks.backup",
             "backend.app.tasks.admin",
             "backend.app.tasks.library_audit",
+            "backend.app.tasks.library_placement",
             "backend.app.tasks.translation",
         ],
     )
@@ -62,6 +63,8 @@ def make_celery() -> Celery:
             # 2026-06-07: a 2h audit blocked vacuum/backup/normalize for hours).
             "backend.app.tasks.maintenance.*": {"queue": "maintenance"},
             "backend.app.tasks.backup.*": {"queue": "maintenance_long"},
+            # 33k renames on NFS: long lane, same as backups.
+            "backend.app.tasks.library_placement.*": {"queue": "maintenance_long"},
             "backend.app.tasks.admin.*": {"queue": "maintenance_long"},
             "backend.app.tasks.library_audit.*": {"queue": "maintenance_long"},
             # Translation backfill hits the LLM (~1–6s/item) → the long lane so it
@@ -120,6 +123,14 @@ def make_celery() -> Celery:
                 "schedule": 86400.0,  # daily — sweep .part/.partial left by a
                 # download/import killed mid-write (graceful-shutdown fallout)
             },
+            "backfill-phash-daily": {
+                "task": "backend.app.tasks.maintenance.backfill_phash",
+                "schedule": 86400.0,  # daily — NULL-only, so a no-op once the
+                # library is hashed. This is what makes migration 0098's
+                # re-hash happen on its own: 0098 NULLs every phash, and
+                # without a scheduled refill the library would sit
+                # dedup-disabled until someone ran a deep scan (#4223).
+            },
             "train-heads-nightly": {
                 "task": "backend.app.tasks.ml.scheduled_train_heads",
                 "schedule": 86400.0,  # passive cadence; manual retrain stays available

backend/app/models/__init__.py

@@ -22,6 +22,7 @@ from .import_batch import ImportBatch
 from .import_settings import ImportSettings
 from .import_task import ImportTask
 from .library_audit_run import LibraryAuditRun
+from .library_placement_run import LibraryPlacementRun
 from .membership_sync import MembershipSync
 from .ml_settings import MLSettings
 from .patreon_failed_media import PatreonFailedMedia
@@ -85,6 +86,7 @@ __all__ = [
     "ImportTask",
     "ImportSettings",
     "LibraryAuditRun",
+    "LibraryPlacementRun",
     "MembershipSync",
     "MLSettings",
     "HeadAutoApplyRun",

backend/app/models/image_record.py

@@ -64,7 +64,11 @@ class ImageRecord(Base):
     # that 0001 also built was an exact duplicate of it — dropped in 0089
     # (#3301). Lookups by sha256 use the constraint's index.
     sha256: Mapped[str] = mapped_column(String(64), nullable=False)
-    phash: Mapped[str | None] = mapped_column(String(32), nullable=True, index=True)
+    # 64 hex chars = the 256-bit hash utils.phash emits at hash_size=16. Was
+    # String(32) (64-bit) until migration 0098; the narrow column was the
+    # reason for the undersized hash, and the undersized hash was collapsing
+    # variant artwork into one record (#4223).
+    phash: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
     size_bytes: Mapped[int] = mapped_column(BigInteger, nullable=False)
     mime: Mapped[str] = mapped_column(String(64), nullable=False)
     width: Mapped[int | None] = mapped_column(Integer, nullable=True)

backend/app/models/import_settings.py

@@ -42,7 +42,12 @@ class ImportSettings(Base):
     single_color_threshold: Mapped[float] = mapped_column(Float, nullable=False, default=0.95, server_default="0.95")
     single_color_tolerance: Mapped[int] = mapped_column(Integer, nullable=False, default=30, server_default="30")
 
-    phash_threshold: Mapped[int] = mapped_column(Integer, nullable=False, default=10, server_default="10")
+    # Hamming distance over a 256-bit pHash (utils.phash, hash_size=16). The
+    # unit CHANGED in migration 0098 — it used to be bits out of 64 — so the
+    # old default of 10 is not this scale's 10, and 0098 resets every row.
+    # This is now the cheap PRE-FILTER: the aspect + pixel gates decide, which
+    # is what lets it be generous enough to catch a re-encoded rescale.
+    phash_threshold: Mapped[int] = mapped_column(Integer, nullable=False, default=24, server_default="24")
 
     # FC-3c downloader knobs
     download_rate_limit_seconds: Mapped[float] = mapped_column(

backend/app/models/library_placement_run.py

@@ -0,0 +1,99 @@
+"""LibraryPlacementRun — one run of the placement reconciler (milestone #421).
+
+The library is keyed on the Artist row's `slug`, one directory per artist.
+Every writer agrees on that now (`utils.paths.canonical_subdir`, task #4244),
+but ~33,789 rows were written under older rules and sit in some other
+artist's directory. This row is a run of the sweep that trues them up.
+
+State machine, mirroring LibraryAuditRun:
+
+    running -> ready -> applied -> reverted
+                     \\-> cancelled
+    (any)   -> error
+
+## The `moves` column does three jobs
+
+`moves` is the plan: `[{"image_id": 1, "from": "...", "to": "..."}, ...]`.
+
+  1. **Preview.** It is what the operator reads before agreeing.
+  2. **Apply.** The apply executes THIS list rather than re-deriving the set,
+     so the preview cannot describe a different set from the apply. That is
+     rule 93's guarantee reached the way LibraryAuditRun reaches it — the
+     plan is materialised, not recomputed.
+  3. **Revert.** `from` is retained, so a batch that looks wrong in the
+     gallery goes back where it came from.
+
+## An applied run IS the undo ledger — it must never be pruned
+
+This is the trap lesson #4226 names: a record that answers both "what is the
+current plan" and "what happened" gets deleted by whatever forgets the first.
+A `ready` run is disposable state. An `applied` run is HISTORY, and it is the
+only record of where 33,789 files used to be — delete it and the moves become
+irreversible.
+
+No pruning exists for this table today, and that is deliberate. If retention
+is ever added here, it may prune `ready`, `cancelled` and `error` runs; an
+`applied` run is only safe to drop once someone decides the moves are settled
+and undo is no longer wanted, which is an operator decision and not a
+timer's.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, func, text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class LibraryPlacementRun(Base):
+    __tablename__ = "library_placement_run"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    status: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="running", index=True,
+        server_default="running",
+    )
+    # running | ready | applied | reverted | cancelled | error
+
+    # Scope. NULL = the whole library; set = one artist, which is how this is
+    # meant to be used — do one artist, look at it in the gallery, continue or
+    # revert. ondelete SET NULL rather than CASCADE: deleting an artist must
+    # not destroy the record of where their files were moved.
+    artist_id: Mapped[int | None] = mapped_column(
+        ForeignKey("artist.id", ondelete="SET NULL"), nullable=True, index=True,
+    )
+
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(),
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True,
+    )
+
+    planned_count: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0",
+    )
+    moved_count: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0",
+    )
+    refused_count: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0",
+    )
+
+    # [{"image_id": int, "from": str, "to": str}, ...] — see the module
+    # docstring. This is the plan, the audit trail and the undo, in that order
+    # of appearance and in one place.
+    moves: Mapped[list[dict[str, Any]]] = mapped_column(
+        JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb"),
+    )
+    # [{"image_id": int, "reason": str}, ...] — rows the apply declined to
+    # touch, with why. A refusal is an expected outcome, not an error: the
+    # world moves between plan and apply, and every gate fails closed.
+    refusals: Mapped[list[dict[str, Any]]] = mapped_column(
+        JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb"),
+    )
+
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/app/services/artist_service.py

@@ -300,6 +300,18 @@ class ArtistService:
         await self.session.commit()
         return artist
 
+    async def all_names(self) -> list[tuple[int, str, str]]:
+        """Every artist as (id, name, slug), alphabetical.
+
+        For pickers that should show a full list before anything is typed (the
+        Latest feed's artist filter). Three columns and no joins, so it stays
+        cheap on a library of thousands of artists.
+        """
+        rows = (await self.session.execute(
+            select(Artist.id, Artist.name, Artist.slug).order_by(func.lower(Artist.name))
+        )).all()
+        return [(r.id, r.name, r.slug) for r in rows]
+
     async def autocomplete(self, prefix: str, limit: int = 20) -> list[Artist]:
         cleaned = (prefix or "").strip()
         if not cleaned:

backend/app/services/backup_service.py

@@ -24,6 +24,25 @@ from pathlib import Path
 
 _BACKUPS_DIRNAME = "_backups"
 
+# Excluded from the images tarball, and each for its own reason (#4233, #4234):
+#
+#   _backups    — the archive would otherwise contain every previous archive.
+#                 This is not hypothetical: the 2026-05-23/24 runs, taken before
+#                 this exclude existed, grew 43G -> 107G -> ... -> 2123G as each
+#                 swallowed its predecessors, and cost 4.3T of the images
+#                 filesystem until they were reclaimed on 2026-09-21.
+#   _quarantine — holds files deliberately pulled OUT of the library.
+#   secrets     — `credential_key.b64`, the key that decrypts the stored
+#                 Patreon/SubscribeStar session credentials.
+#   cookies     — those session cookies themselves.
+#
+# The last two are the ones worth stating plainly: an images tarball is a media
+# archive, and a media archive that carries the key to the operator's accounts
+# is a credential leak wearing a backup's name. Encryption at rest buys nothing
+# when the key rides along in the same file. A restore therefore does NOT
+# re-establish credentials — you sign in again, which is the correct outcome.
+_IMAGES_EXCLUDED_DIRNAMES = ("_backups", "_quarantine", "secrets", "cookies")
+
 # Subprocess-level guardrails BEYOND the Celery soft_time_limit. The Celery
 # soft limit signals the Python process; subprocess.Popen in a blocking syscall
 # ignores that signal, so these bound the worst case directly. Each sits just
@@ -173,8 +192,10 @@ def backup_images(
         [
             "tar", "--zstd", "-cf", str(tar_path),
             "-C", str(images_root.parent), images_root.name,
-            f"--exclude={images_root.name}/_backups",
-            f"--exclude={images_root.name}/_quarantine",
+            *(
+                f"--exclude={images_root.name}/{name}"
+                for name in _IMAGES_EXCLUDED_DIRNAMES
+            ),
         ],
         _IMAGES_SUBPROCESS_TIMEOUT_S,
     )

backend/app/services/discord_repair.py

@@ -0,0 +1,183 @@
+"""Repair the Discord downloads made before the naming fix (issue #3999).
+
+Until dc840fe, gallery-dl's Discord patterns asked for keys the extractor never
+emits, so every Discord download landed as
+`<artist>/discord/None/<date>_None_<original name>`, next to a sidecar named
+after the attachment's ORIGINAL name. That broke two things:
+
+* **No Post, no date.** `find_sidecar` can never pair those names, so these
+  files were imported as loose images with no Post, and a card shows the
+  download time.
+* **No trustworthy metadata to relink from.** Every `image.png` in a channel
+  wrote the same `image.json`, so the surviving sidecar describes whichever
+  message was written last. The message id is gone from the filename too.
+
+The operator chose a clean re-download (2026-09-13) over relinking in place:
+delete the broken files and their records, make gallery-dl forget it fetched
+them, and backfill every Discord source again under the fixed naming.
+
+## Why the archive is cleared for ALL of Discord
+
+gallery-dl records a download as `discord{message_id}_{num}` (upstream
+`DiscordExtractor.archive_fmt`, prefixed with the category). The broken files
+lost their message ids, so there is no way to forget one source's entries and
+not another's. Every Discord download made before the fix is broken, so
+forgetting all of them is exactly right. Anything downloaded AFTER the fix still
+exists on disk under its correct name, and gallery-dl's `skip` sees the file and
+does not fetch it again.
+
+## What it does not touch
+
+Discord posts FC grouped itself (#388 E2) are built from Posts, and these files
+never had one, so there is nothing grouped to unwind. Images outside a
+`discord/None/` directory are never selected: the path filter requires both the
+`None` directory and the `_None_` filename, the pair only the bug produced.
+
+Operator-triggered only (Settings, preview first). Never on a beat.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from ..models import ImageRecord, Source
+from .cleanup_service import delete_images
+from .gallery_dl import archive_path
+from .source_service import arm_backfill
+
+log = logging.getLogger(__name__)
+
+# `%` and `_` are LIKE wildcards, so the literal underscores around None are
+# escaped. `________` is the eight-digit date prefix the old pattern wrote.
+_BROKEN_PATH_LIKE = r"%/discord/None/________\_None\_%"
+
+# Upstream keys asset downloads as `asset_{server_id}_{id}`. FC never fetches
+# server assets, but excluding them keeps this to exactly the message
+# attachments the bug mangled.
+_ARCHIVE_SQL_MATCH = r"entry LIKE 'discord%' AND entry NOT LIKE 'discordasset\_%' ESCAPE '\'"
+_COUNT_SQL = "SELECT COUNT(*) FROM archive WHERE " + _ARCHIVE_SQL_MATCH
+_DELETE_SQL = "DELETE FROM archive WHERE " + _ARCHIVE_SQL_MATCH
+
+
+def broken_directories(images_root: Path) -> list[Path]:
+    """Every `<artist>/discord/None` directory. Artist folders that differ only by
+    case (`Conto` and `conto`) are separate directories and both are found."""
+    return sorted(d for d in Path(images_root).glob("*/discord/None") if d.is_dir())
+
+
+def count_archive_entries(archive: Path) -> int:
+    return _archive(archive, delete=False)
+
+
+def forget_archive_entries(archive: Path) -> int:
+    return _archive(archive, delete=True)
+
+
+def _archive(archive: Path, *, delete: bool) -> int:
+    if not archive.is_file():
+        return 0
+    # A download running at the same moment holds this file briefly. Waiting
+    # 30s for its lock beats failing the repair over a transient contention.
+    conn = sqlite3.connect(str(archive), timeout=30)
+    try:
+        has_table = conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='archive'"
+        ).fetchone()
+        if not has_table:
+            return 0
+        if not delete:
+            return conn.execute(_COUNT_SQL).fetchone()[0]
+        cur = conn.execute(_DELETE_SQL)
+        conn.commit()
+        return cur.rowcount
+    finally:
+        conn.close()
+
+
+def _sweep_directory(directory: Path) -> tuple[int, bool]:
+    """Remove what the record deletes left behind: the collided sidecars, plus any
+    file that never became a record (a quarantined or rejected download). Then
+    the directory itself, if it is empty. Returns (files removed, dir removed)."""
+    removed = 0
+    for f in directory.iterdir():
+        if f.is_file():
+            try:
+                f.unlink()
+                removed += 1
+            except OSError as exc:
+                log.warning("discord repair: could not remove %s: %s", f, exc)
+    try:
+        directory.rmdir()
+        return removed, True
+    except OSError:
+        return removed, False
+
+
+def repair_discord_downloads(
+    session: Session, *, images_root: Path, dry_run: bool,
+) -> dict:
+    images_root = Path(images_root)
+    archive = archive_path(images_root)
+
+    broken = select(ImageRecord.id, ImageRecord.size_bytes).where(
+        ImageRecord.path.like(_BROKEN_PATH_LIKE, escape="\\")
+    )
+    rows = session.execute(broken).all()
+    image_ids = [r.id for r in rows]
+    directories = broken_directories(images_root)
+    sources = session.execute(
+        select(Source).where(Source.platform == "discord")
+    ).scalars().all()
+
+    summary = {
+        "images": len(image_ids),
+        "bytes": sum(r.size_bytes or 0 for r in rows),
+        "directories": len(directories),
+        "sources": len(sources),
+        "enabled_sources": sum(1 for s in sources if s.enabled),
+    }
+
+    if dry_run:
+        summary["archive_entries"] = count_archive_entries(archive)
+        return summary
+
+    deleted = delete_images(session, image_ids=image_ids, images_root=images_root)
+
+    swept = 0
+    directories_removed = 0
+    for d in directories:
+        n, gone = _sweep_directory(d)
+        swept += n
+        directories_removed += int(gone)
+
+    # Only after the files are gone. Forgetting first and failing half way would
+    # leave gallery-dl free to re-fetch into a directory still full of the old
+    # copies.
+    forgotten = forget_archive_entries(archive)
+
+    for source in sources:
+        arm_backfill(source)
+    session.commit()
+
+    remaining = session.execute(
+        select(func.count(ImageRecord.id)).where(
+            ImageRecord.path.like(_BROKEN_PATH_LIKE, escape="\\")
+        )
+    ).scalar_one()
+
+    summary.update(
+        images_deleted=deleted["images_deleted"],
+        files_failed=deleted["files_failed"],
+        leftover_files_removed=swept,
+        directories_removed=directories_removed,
+        archive_entries=forgotten,
+        backfills_started=len(sources),
+        remaining=remaining,
+    )
+    log.info("discord repair applied: %s", summary)
+    return summary

backend/app/services/gallery_dl.py

@@ -94,6 +94,58 @@ BACKFILL_CHUNK_SECONDS = 600
 _DEFAULT_GDL_TIMEOUT_SECONDS = 870
 
 
+# --- Discord naming ---------------------------------------------------------
+#
+# Derived from a REAL sidecar (operator's instance, 2026-09-13), not from memory
+# of gallery-dl's extractor. What gallery-dl's discord extractor actually emits
+# for an attachment: `channel` is a plain STRING (the channel's name), the
+# message is `message_id`, the attachment's position in it is `num`, and there
+# is NO `id` key at all.
+#
+# The previous patterns asked for `{channel[name]}` and `{id}`. Both render as
+# "None", so every Discord download since the platform was added landed in a
+# directory called `None` as `<date>_None_<original name>`. Worse, the sidecar was
+# named `{filename}.json` — the attachment's ORIGINAL name — which (a) `find_
+# sidecar` can never pair with `<date>_None_<name>.png`, so no Discord file ever
+# got a Post or a post date, and (b) collides: every `image.png` in a channel
+# overwrote the same `image.json`, so the one sidecar that survived described
+# whichever message happened to be written last.
+#
+# The fix names the sidecar EXACTLY like the media minus its extension, so
+# `find_sidecar`'s first candidate (`media.with_suffix(".json")`) is the match
+# and the name is unique per attachment. tests/test_gallery_dl_naming.py renders
+# these patterns against a sanitized copy of the real sidecar, so a key that
+# does not exist fails CI instead of silently becoming "None".
+DISCORD_FILENAME = "{date:%Y%m%d}_{message_id}_{num:>02}_{filename}.{extension}"
+DISCORD_DIRECTORY = ["{channel}"]
+
+
+def sidecar_name_for(media_pattern: str) -> str | None:
+    """The metadata filename pattern that names a sidecar exactly like its media.
+
+    Returns None for a pattern that does not end in `.{extension}`, since then
+    there is no media stem to mirror and the caller must fall back.
+    """
+    suffix = ".{extension}"
+    if not media_pattern.endswith(suffix):
+        return None
+    return media_pattern[: -len(suffix)] + ".json"
+
+
+def metadata_postprocessor(filename: str) -> dict:
+    return {"name": "metadata", "mode": "json", "directory": ".", "filename": filename}
+
+
+def archive_path(images_root: Path) -> Path:
+    """gallery-dl's download archive: the record of what it has already fetched.
+
+    One definition, because the Discord repair (services/discord_repair.py) has
+    to find the same file the downloader writes, without constructing a service
+    whose __init__ creates directories.
+    """
+    return Path(images_root) / ".gallery-dl" / "archive.sqlite3"
+
+
 @dataclass
 class SourceConfig:
     """Per-source overrides loaded from Source.config_overrides JSON.
@@ -376,8 +428,11 @@ class GalleryDLService:
         },
         "discord": {
             "content_types": ["all"],
-            "directory": ["{channel[name]}"],
-            "filename": "{date:%Y%m%d}_{id}_{filename}.{extension}",
+            "directory": DISCORD_DIRECTORY,
+            "filename": DISCORD_FILENAME,
+            # Overrides the global `{filename}.json` sidecar for this extractor
+            # only — see the Discord naming note above.
+            "postprocessors": [metadata_postprocessor(sidecar_name_for(DISCORD_FILENAME))],
             "embeds": "all",
             "stickers": True,
             "reactions": False,
@@ -402,7 +457,7 @@ class GalleryDLService:
         config = {
             "extractor": {
                 "base-directory": str(self.images_root),
-                "archive": str(self._config_dir / "archive.sqlite3"),
+                "archive": str(archive_path(self.images_root)),
                 "skip": True,
                 "sleep": self._rate_limit,
                 "sleep-request": max(0.5, self._rate_limit / 4),
@@ -497,6 +552,17 @@ class GalleryDLService:
         if source_config.filename_pattern:
             platform_section["filename"] = source_config.filename_pattern
 
+        # A platform that names its sidecar after its media must keep doing so
+        # under a per-source filename override, or the pairing breaks exactly the
+        # way Discord's did. No metadata wanted means no platform postprocessor
+        # either — the global list was already dropped above.
+        if "postprocessors" in platform_section:
+            mirrored = sidecar_name_for(platform_section.get("filename") or "")
+            if not source_config.save_metadata or mirrored is None:
+                platform_section.pop("postprocessors")
+            else:
+                platform_section["postprocessors"] = [metadata_postprocessor(mirrored)]
+
         platform_section["metadata"] = source_config.save_metadata
 
         return config

backend/app/services/gallery_service.py

@@ -322,7 +322,7 @@ def _gallery_images(rows, artists: dict[int, dict]) -> list[GalleryImage]:
     ]
 
 
-def _diversify_similar(src, rows, limit, *, dup_threshold=8, lam=0.40):
+def _diversify_similar(src, rows, limit, *, dup_threshold=32, lam=0.40):
     """Trim a nearest-cosine candidate pool down to `limit` diverse picks.
 
     1. pHash collapse: drop any candidate whose perceptual hash is within
@@ -338,6 +338,11 @@ def _diversify_similar(src, rows, limit, *, dup_threshold=8, lam=0.40):
     2026-07-01 — dropped 0.55→0.40, dup 6→8, paired with a wider pool in
     `similar()`).
 
+    `dup_threshold` counts Hamming bits, so it moved 8→32 when the pHash went
+    from 64 to 256 bits (#4223, migration 0098) — the same fraction of the
+    hash, i.e. the tuning the operator chose, unchanged. This collapse is
+    DISPLAY-only: it hides a near-dup from one rail, it never drops a record.
+
     Falls back to nearest-order (`rows[:limit]`) on any failure or a small pool.
     """
     if len(rows) <= 1:

backend/app/services/importer.py

@@ -33,13 +33,14 @@ from ..models import (
 )
 from ..utils import safe_probe
 from ..utils.paths import (
+    canonical_subdir,
     derive_subdir,
     derive_top_level_artist,
     filehash_from_url,
     hash_suffixed_name,
     safe_ext,
 )
-from ..utils.phash import compute_phash, find_similar
+from ..utils.phash import compute_phash, find_similar, fingerprint_path, fingerprints_match
 from ..utils.sidecar import find_sidecar, parse_sidecar
 from ..utils.slug import slugify
 from .archive_extractor import extract_archive, is_archive
@@ -234,6 +235,38 @@ class Importer:
                 (phash, width or 0, height or 0, image_id)
             )
 
+    def _pixel_confirmer(self, source: Path):
+        """Build `find_similar`'s gate-3 callback for an incoming file.
+
+        pHash proposes; this accepts. A candidate is a duplicate only if its
+        file really is the same picture as `source` at a different size —
+        which is the only merge the operator asked for (#4223). Everything
+        else (a missing file, an unreadable one, a deleted row) returns
+        False: the destructive outcomes here are dropping a download and
+        overwriting a kept file, so an unanswerable question must not read
+        as "yes".
+
+        Both sides' fingerprints are computed lazily and cached, so an
+        import that matches nothing costs no I/O at all and an archive
+        member that keeps hitting the same candidate pays for it once.
+        """
+        new_fp: list = []
+        cand_fps: dict[int, object] = {}
+
+        def confirm(candidate_id: int) -> bool:
+            if not new_fp:
+                new_fp.append(fingerprint_path(source))
+            if new_fp[0] is None:
+                return False
+            if candidate_id not in cand_fps:
+                rec = self.session.get(ImageRecord, candidate_id)
+                cand_fps[candidate_id] = (
+                    fingerprint_path(Path(rec.path)) if rec and rec.path else None
+                )
+            return fingerprints_match(new_fp[0], cand_fps[candidate_id])
+
+        return confirm
+
     def _get_or_create(self, stmt, factory):
         """Race-safe find-or-create. Run `stmt` (scalar_one_or_none); if a
         row exists, return it. Otherwise open a savepoint and INSERT
@@ -862,6 +895,7 @@ class Importer:
                 rel, match_id = find_similar(
                     phash, width or 0, height or 0,
                     candidates, self.settings.phash_threshold,
+                    confirm=self._pixel_confirmer(source),
                 )
                 if rel == "larger_exists":
                     # Enrich-on-duplicate (parity with attach_in_place).
@@ -911,7 +945,7 @@ class Importer:
                 )
                 return ImportResult(status="superseded", image_id=match_id)
 
-        dest = self._copy_to_library(source, sha, attribution_path)
+        dest = self._copy_to_library(source, sha, attribution_path, path_artist)
 
         record = ImageRecord(
             path=str(dest),
@@ -1241,6 +1275,7 @@ class Importer:
                 rel, match_id = find_similar(
                     phash, width or 0, height or 0,
                     candidates, self.settings.phash_threshold,
+                    confirm=self._pixel_confirmer(path),
                 )
                 if rel == "larger_exists":
                     # Enrich-on-duplicate: link the near-dup's post to the
@@ -1566,7 +1601,8 @@ class Importer:
         )
 
     def _copy_to_library(
-        self, source: Path, sha: str, attribution_path: Path
+        self, source: Path, sha: str, attribution_path: Path,
+        artist: Artist | None = None,
     ) -> Path:
         """Copy `source` to its final library path. Returns the destination.
 
@@ -1574,8 +1610,18 @@ class Importer:
         _import_media (filesystem scan) and _supersede (when new_path is
         not passed). FC-3c's attach_in_place skips this helper entirely
         — the file is already at its final home.
+
+        `artist`, when resolved, decides the top-level directory: the
+        library is keyed on the Artist row's slug, NOT on however the
+        import folder happened to be capitalised. Without that, an import
+        from `/import/Conto/` and a download for the same artist write to
+        `Conto/` and `conto/` respectively and the library grows a second
+        home for one artist (milestone #421).
         """
-        subdir = derive_subdir(attribution_path, self.import_root)
+        subdir = canonical_subdir(
+            derive_subdir(attribution_path, self.import_root),
+            artist.slug if artist else None,
+        )
         dest_dir = self.images_root / subdir if subdir else self.images_root
         dest_dir.mkdir(parents=True, exist_ok=True)
         dest_name = hash_suffixed_name(source.stem, sha, source.suffix)
@@ -1610,7 +1656,16 @@ class Importer:
         that path (FC-3c attach_in_place case) — skip the copy step.
         Otherwise the file is copied via _copy_to_library."""
         if new_path is None:
-            dest = self._copy_to_library(source, sha, source)
+            # The KEPT row's artist decides the destination, not the incoming
+            # file's folder — a supersede rewrites `existing.path`, so writing
+            # it anywhere but that artist's canonical directory would move a
+            # row OUT of the tree milestone #421 is consolidating. ImageRecord
+            # carries `artist_id` with no relationship attribute, so this is a
+            # lookup rather than `existing.artist`.
+            kept_artist = artist
+            if kept_artist is None and existing.artist_id is not None:
+                kept_artist = self.session.get(Artist, existing.artist_id)
+            dest = self._copy_to_library(source, sha, source, kept_artist)
         else:
             dest = new_path
 

backend/app/services/library_layout.py

@@ -0,0 +1,434 @@
+"""Milestone #421: where an image file BELONGS, and which rows are not there.
+
+The library is keyed on the Artist row's `slug` — one directory per artist.
+It grew a second (and third, and fourth) home for many of them because
+`Importer._copy_to_library` used to name the destination after the IMPORT
+folder while the downloader wrote under the slug. That writer is fixed
+(`utils.paths.canonical_subdir`, task #4244); this module is the other half —
+finding the rows whose files are still in the old places, and saying where
+each one goes.
+
+## Preview and apply share these predicates, they do not re-derive them
+
+`_misplaced_conditions` and `destination_for` are the whole decision. The
+report (task #4245) and the move (task #4246) both spread them rather than
+writing their own — the house shape for rule 93, snippet #3087. A preview
+that computes its set differently from the apply is a preview that can lie,
+and here the apply RENAMES the operator's art.
+
+## What writes and what does not
+
+`survey_layout` and `plan_placement` are read-only — they report and they
+record a plan. `apply_run` and `revert_run` are the only functions here that
+rename a file or rewrite a row, and each does both for one row at a time,
+updating the row only after its rename lands.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from ..models import Artist, ImageRecord, LibraryPlacementRun
+from ..utils.paths import canonical_subdir
+
+# Top-level directories under the images root that are STORES, not artists.
+# A sweep that treats these as misplaced artwork would relocate the
+# thumbnail cache, the attachment blobs, or the credential key.
+#   thumbs/      sha-addressed thumbnail cache (NOT path-keyed — see below)
+#   attachments/ sha-addressed non-media blobs
+#   cookies/, secrets/   credential material
+#   _backups/, _quarantine/  backup artifacts; files pulled out of the library
+RESERVED_TOP_LEVEL = frozenset({
+    "thumbs", "attachments", "cookies", "secrets", "_backups", "_quarantine",
+})
+
+
+def canonical_dir(images_root: Path, slug: str) -> Path:
+    """The one directory an artist's files belong under."""
+    return images_root / slug
+
+
+def _misplaced_conditions(images_root: Path, artist_id: int, slug: str) -> list:
+    """Rows of `artist_id` whose file is NOT under that artist's canonical
+    directory. Spread into both halves — never restated.
+
+    The prefix carries a trailing separator on purpose: without it, artist
+    `ara` would match every path under `arbuzbudesh/`, and the sweep would
+    report one artist's whole library as correctly placed while quietly
+    skipping another's.
+
+    `startswith` compiles to LIKE, where `_` and `%` are wildcards, and this
+    does not escape them. That is safe ONLY because `utils.slug.slugify`
+    reduces a slug to `[a-z0-9-]` — neither character can reach the pattern.
+    Widen that charset and this needs `autoescape=True`, or `poch4n_art`
+    starts matching `poch4nXart` too.
+    """
+    prefix = f"{canonical_dir(images_root, slug)}/"
+    return [
+        ImageRecord.artist_id == artist_id,
+        ImageRecord.path.is_not(None),
+        ~ImageRecord.path.startswith(prefix),
+    ]
+
+
+def destination_for(path: str, images_root: Path, slug: str) -> Path | None:
+    """Where `path`'s file belongs, or None when this row must not be moved.
+
+    None means: the path is outside the images root, or its top-level segment
+    is a reserved store. Both are refusals rather than errors — a row pointing
+    somewhere unexpected is exactly what should NOT be relocated automatically.
+
+    ## The one place this diverges from `canonical_subdir`
+
+    A file sitting at the images ROOT with a known artist moves under that
+    artist's directory here, where `canonical_subdir` would leave it alone.
+    The two answer different questions. At import time an empty subdir means
+    no artist was resolved, so there is nothing to canonicalise against. Here
+    the row already CARRIES an artist_id, so a file at the root is an anomaly
+    with a known correct home — which is the whole point of the sweep.
+
+    (The 660 unattributed files at the root have no artist_id at all and are
+    not reachable from these predicates; task #4247 decides those.)
+    """
+    p = Path(path)
+    try:
+        rel_dir = p.parent.relative_to(images_root)
+    except ValueError:
+        return None
+    parts = rel_dir.parts
+    if parts and parts[0] in RESERVED_TOP_LEVEL:
+        return None
+    sub = canonical_subdir(str(rel_dir) if str(rel_dir) != "." else "", slug)
+    if not sub:
+        # At the root, with an artist — see the docstring above.
+        return canonical_dir(images_root, slug) / p.name
+    return images_root / sub / p.name
+
+
+@dataclass
+class ArtistLayout:
+    """One artist's verdict."""
+
+    artist_id: int
+    name: str
+    slug: str
+    canonical_rows: int = 0
+    misplaced_rows: int = 0
+    # The non-canonical top-level directories this artist's files sit in —
+    # "Conto", "StickySpoodge", … This is what makes the report readable as
+    # the family list the disk survey found.
+    stray_dirs: list[str] = field(default_factory=list)
+    collisions: list[str] = field(default_factory=list)
+    missing_files: int = 0
+    unmovable: int = 0
+
+
+@dataclass
+class LayoutReport:
+    artists: list[ArtistLayout] = field(default_factory=list)
+    total_rows: int = 0
+    canonical_rows: int = 0
+    misplaced_rows: int = 0
+    collision_count: int = 0
+    missing_files: int = 0
+    unmovable: int = 0
+    unattributed_rows: int = 0
+
+    def as_dict(self) -> dict:
+        return {
+            "total_rows": self.total_rows,
+            "canonical_rows": self.canonical_rows,
+            "misplaced_rows": self.misplaced_rows,
+            "collision_count": self.collision_count,
+            "missing_files": self.missing_files,
+            "unmovable": self.unmovable,
+            "unattributed_rows": self.unattributed_rows,
+            "artists": [
+                {
+                    "artist_id": a.artist_id,
+                    "name": a.name,
+                    "slug": a.slug,
+                    "canonical_rows": a.canonical_rows,
+                    "misplaced_rows": a.misplaced_rows,
+                    "stray_dirs": a.stray_dirs,
+                    "collisions": a.collisions,
+                    "missing_files": a.missing_files,
+                    "unmovable": a.unmovable,
+                }
+                for a in self.artists
+                if a.misplaced_rows or a.collisions
+            ],
+        }
+
+
+def survey_layout(
+    session: Session, images_root: Path, *, check_disk: bool = True,
+) -> LayoutReport:
+    """Read-only blast radius for the consolidation.
+
+    `check_disk` stats every destination to find rows that would collide with
+    a file already there, and sources that have already gone missing. It is
+    the honest number and it is what the apply will refuse on, but it costs
+    one stat per misplaced row over NFS — turn it off when you only want
+    counts.
+    """
+    report = LayoutReport()
+    report.total_rows = session.execute(
+        select(func.count(ImageRecord.id))
+    ).scalar_one()
+    report.unattributed_rows = session.execute(
+        select(func.count(ImageRecord.id)).where(ImageRecord.artist_id.is_(None))
+    ).scalar_one()
+
+    artists = session.execute(
+        select(Artist).order_by(Artist.slug)
+    ).scalars().all()
+
+    for artist in artists:
+        layout = ArtistLayout(
+            artist_id=artist.id, name=artist.name, slug=artist.slug,
+        )
+        conds = _misplaced_conditions(images_root, artist.id, artist.slug)
+        owned = session.execute(
+            select(func.count(ImageRecord.id))
+            .where(ImageRecord.artist_id == artist.id)
+        ).scalar_one()
+        rows = session.execute(
+            select(ImageRecord.id, ImageRecord.path).where(*conds)
+        ).all()
+        layout.misplaced_rows = len(rows)
+        layout.canonical_rows = owned - len(rows)
+
+        strays: set[str] = set()
+        destinations: dict[str, int] = {}
+        for row_id, path in rows:
+            dest = destination_for(path, images_root, artist.slug)
+            if dest is None:
+                layout.unmovable += 1
+                continue
+            try:
+                top = Path(path).parent.relative_to(images_root).parts
+                strays.add(top[0] if top else "<root>")
+            except ValueError:
+                strays.add("<outside>")
+            key = str(dest)
+            if key in destinations:
+                layout.collisions.append(key)
+            else:
+                destinations[key] = row_id
+            if check_disk:
+                if not Path(path).exists():
+                    layout.missing_files += 1
+                elif dest.exists():
+                    layout.collisions.append(key)
+
+        layout.stray_dirs = sorted(strays)
+        report.artists.append(layout)
+        report.canonical_rows += layout.canonical_rows
+        report.misplaced_rows += layout.misplaced_rows
+        report.collision_count += len(layout.collisions)
+        report.missing_files += layout.missing_files
+        report.unmovable += layout.unmovable
+
+    return report
+
+
+# --- the reconciler: plan -> apply -> revert (#4246) -------------------------
+#
+# The three verbs share one materialised plan rather than each deriving its
+# own set. `plan_placement` writes `LibraryPlacementRun.moves`; `apply_run`
+# executes THAT list; `revert_run` walks it backwards. A preview that can
+# disagree with its apply is the failure this shape exists to prevent, and
+# here the apply renames the operator's art.
+#
+# Every step fails CLOSED. The world moves between planning and applying —
+# a download lands, a supersede rewrites a path, a file is deleted — so the
+# apply re-checks each row against what the plan recorded and declines the
+# ones that moved on, instead of trusting a plan that may be minutes old.
+
+
+def plan_placement(
+    session: Session, images_root: Path, *, artist_id: int | None = None,
+) -> LibraryPlacementRun:
+    """Build (and persist) the move plan. Touches no files.
+
+    `artist_id` scopes the run to one artist, which is how this is meant to be
+    used: do one, look at the gallery, then continue or revert. None plans the
+    whole library.
+    """
+    stmt = select(Artist).order_by(Artist.slug)
+    if artist_id is not None:
+        stmt = stmt.where(Artist.id == artist_id)
+    artists = session.execute(stmt).scalars().all()
+
+    candidates: list[dict] = []
+    wanted: dict[str, int] = {}
+    for artist in artists:
+        rows = session.execute(
+            select(ImageRecord.id, ImageRecord.path)
+            .where(*_misplaced_conditions(images_root, artist.id, artist.slug))
+        ).all()
+        for row_id, path in rows:
+            dest = destination_for(path, images_root, artist.slug)
+            if dest is None or dest.exists():
+                continue
+            key = str(dest)
+            candidates.append({"image_id": row_id, "from": path, "to": key})
+            wanted[key] = wanted.get(key, 0) + 1
+
+    # Two rows wanting one destination: plan NEITHER. Which of them "wins" is
+    # not this sweep's call, and planning one of them would silently pick a
+    # winner by iteration order. Counting first and filtering after is what
+    # makes that true — claiming as we go would quietly keep whichever came
+    # first.
+    moves = [m for m in candidates if wanted[m["to"]] == 1]
+
+    run = LibraryPlacementRun(
+        status="ready", artist_id=artist_id, moves=moves,
+        planned_count=len(moves),
+    )
+    session.add(run)
+    session.flush()
+    return run
+
+
+def _move_one(src: Path, dest: Path) -> str | None:
+    """Rename `src` to `dest`. Returns a refusal reason, or None on success.
+
+    A rename within one filesystem, so no copy and no free space needed. The
+    destination check is not a race-free guarantee — nothing here is — but it
+    turns the common case of "something already landed there" into a refusal
+    instead of a silent overwrite.
+    """
+    if not src.exists():
+        return "source missing"
+    if dest.exists():
+        return "destination occupied"
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        src.rename(dest)
+    except OSError as exc:
+        return f"rename failed: {exc}"
+    return None
+
+
+def apply_run(
+    session: Session, run: LibraryPlacementRun, *, chunk: int = 0,
+) -> LibraryPlacementRun:
+    """Execute a `ready` run's stored plan: file and row together, per row.
+
+    The row is updated ONLY after its rename lands, so a refused or failed
+    move can never leave `ImageRecord.path` pointing at a file that is not
+    there. Refusals are recorded and the run continues — one row that moved
+    on since planning is not a reason to abandon the other 33,788.
+
+    `chunk` commits progress every N moves. Set it for any real run: the
+    ledger is the ONLY record of where a file came from, so a worker that
+    dies at row 30,000 of 33,789 must not take the undo information for the
+    first 29,999 with it. Left at 0 (tests, small runs) everything persists
+    in one go at the end.
+
+    Re-running a partially-applied plan is safe rather than clever: the rows
+    already moved no longer match their `from`, so they refuse as "row moved
+    since planning" instead of being moved twice.
+    """
+    if run.status != "ready":
+        raise ValueError(f"run {run.id} is {run.status}, not ready")
+
+    refusals: list[dict] = []
+    moved: list[dict] = []
+
+    def _persist() -> None:
+        # Reassign rather than mutate: SQLAlchemy does not track in-place
+        # changes to a JSONB list, so an .append() alone would never reach
+        # the database and the ledger would silently stay empty.
+        run.moves = list(moved)
+        run.refusals = list(refusals)
+        run.moved_count = len(moved)
+        run.refused_count = len(refusals)
+        session.commit()
+
+    # Snapshot the plan before iterating: `_persist` reassigns `run.moves`,
+    # and iterating the attribute while rewriting it would walk a list that
+    # changes underneath the loop.
+    plan = list(run.moves)
+    for done, move in enumerate(plan, start=1):
+        record = session.get(ImageRecord, move["image_id"])
+        if record is None:
+            refusals.append({"image_id": move["image_id"], "reason": "row gone"})
+            continue
+        if record.path != move["from"]:
+            # Something rewrote this row since the plan was built — a
+            # supersede, or an earlier run. The plan is stale for it.
+            refusals.append({
+                "image_id": move["image_id"], "reason": "row moved since planning",
+            })
+            continue
+        reason = _move_one(Path(move["from"]), Path(move["to"]))
+        if reason is not None:
+            refusals.append({"image_id": move["image_id"], "reason": reason})
+            continue
+        record.path = move["to"]
+        moved.append(move)
+        if chunk and done % chunk == 0:
+            _persist()
+
+    run.moves = moved
+    run.refusals = refusals
+    run.moved_count = len(moved)
+    run.refused_count = len(refusals)
+    run.status = "applied"
+    run.finished_at = datetime.now(UTC)
+    session.flush()
+    return run
+
+
+def revert_run(
+    session: Session, run: LibraryPlacementRun,
+) -> LibraryPlacementRun:
+    """Put an applied run's files back where they came from.
+
+    This is why `from` is retained. It is the answer to "do one artist, look
+    at it, and undo if it reads wrong" — which is a cheaper way to settle
+    whether artist_id or the folder held the truth (#4257) than arguing it
+    from a sample.
+
+    Refuses the same way the apply does: a file someone has since moved or
+    replaced stays where it is, and its row is left alone.
+
+    A revert interrupted half way is resumable by re-running it: the rows
+    already put back no longer sit at `to`, so they refuse rather than move
+    twice. Unlike the apply this needs no chunked persistence — it consumes
+    the ledger rather than producing it, so a crash costs progress, not
+    information.
+    """
+    if run.status != "applied":
+        raise ValueError(f"run {run.id} is {run.status}, not applied")
+
+    refusals: list[dict] = []
+    reverted = 0
+    for move in run.moves:
+        record = session.get(ImageRecord, move["image_id"])
+        if record is None or record.path != move["to"]:
+            refusals.append({
+                "image_id": move["image_id"], "reason": "row changed since apply",
+            })
+            continue
+        reason = _move_one(Path(move["to"]), Path(move["from"]))
+        if reason is not None:
+            refusals.append({"image_id": move["image_id"], "reason": reason})
+            continue
+        record.path = move["from"]
+        reverted += 1
+
+    run.refusals = refusals
+    run.refused_count = len(refusals)
+    run.moved_count = run.moved_count - reverted
+    run.status = "reverted"
+    run.finished_at = datetime.now(UTC)
+    session.flush()
+    return run

backend/app/services/membership_reconcile.py

@@ -8,9 +8,10 @@ trustworthy enough to act on.
 1. `subscribed_not_tracked` — you pay for this and FC does not follow it. The
    adoption win, and the only bucket carrying an action.
 2. `tracked_not_subscribed` — FC follows this and the roster does not show you
-   paying for it. REPORT ONLY, by the operator's decision (2026-09-11): it says
-   what it sees and links to the existing Subscriptions row, and offers no
-   one-click disable.
+   paying for it. No longer shown on the card: the operator reversed the
+   2026-09-11 "report only" call on 2026-09-13. The lapsed half of it now ACTS,
+   in `apply_membership_lapses` below (#3995). The absent half still only
+   reports, because absence proves nothing.
 3. `matched` — the healthy set. Counted, not listed loudly.
 4. `unidentified` — sources this join cannot speak to at all. Reported as
    exactly that, because the alternative is filing them under a verdict.
@@ -39,7 +40,7 @@ rendered as lapsed. That is the whole reason it returns a tri-state.
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import UTC, datetime
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -47,12 +48,12 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from ..models import Artist, MembershipSync, PlatformMembership, Source
 from .membership_roster import (
     get_sync_state,
-    has_paid_access,
     identity_keys_for_source,
     pair_sources_with_memberships,
     roster_is_fresh,
     url_tail,
 )
+from .native_ingest_common import has_paid_access
 
 # Why a source appears in `tracked_not_subscribed`. Ordered strongest first —
 # the UI renders a different sentence per basis, because collapsing them into
@@ -233,3 +234,126 @@ async def reconcile_all(session: AsyncSession, now: datetime | None = None) -> d
             await reconcile(session, platform=p, now=now) for p in sorted(platforms)
         ]
     }
+
+
+# ---------------------------------------------------------------------------
+# Stop pulling what the account no longer pays for (#3995)
+# ---------------------------------------------------------------------------
+#
+# Operator decision, 2026-09-13, reversing the 2026-09-11 "report only" call
+# for this direction: "if I kill a subscription on patreon I would like the
+# pulling to stop on curator as well", with automatic resume on resubscribing.
+#
+# This is a SOURCE-level action taken by the daily sweep, visible on the source
+# row and reversible there. It is not a fetch-path decision. The line C5 draws,
+# that the roster never decides a POST is inaccessible, still holds: nothing
+# here reads per-post access, and no download path reads the roster
+# (`test_no_fetch_path_can_read_the_roster`). The scheduler keeps selecting on
+# `enabled` alone.
+#
+# Acts ONLY on positive evidence. A source whose matched membership says access
+# has ended is stopped. A source with NO matched membership is left alone,
+# because absence has innocent causes: a creator rename, a source never walked
+# so no id is cached, a membership the platform stopped listing. Stopping on
+# absence would switch off things the operator still pays for.
+#
+# Two app-managed config_overrides keys carry the state. The `_` prefix is
+# already the "FC writes this, an operator edit preserves it" family.
+#   _membership_stopped  set when the sweep stops a source; the sweep resumes
+#                        ONLY sources carrying it, so a source the operator
+#                        switched off by hand is never switched back on
+#   _membership_kept     set by SourceService.update when the operator turns a
+#                        stopped source back ON: a deliberate choice to keep
+#                        pulling a lapsed creator, which the next sweep must
+#                        not undo. Cleared when the membership is paid again.
+STOPPED_KEY = "_membership_stopped"
+KEPT_KEY = "_membership_kept"
+
+
+def _access_expires_at(m: PlatformMembership) -> datetime | None:
+    """When paid access actually ends, if the platform says.
+
+    Patreon keeps a cancelled membership's access until the end of the billing
+    period and reports that date (`member.access_expires_at`, note #3992).
+    SubscribeStar's page gives no such date, so a cancelled SubscribeStar
+    membership stops at once. Returns None when there is no usable date.
+    """
+    details = m.details or {}
+    raw = details.get("access_expires_at") or (details.get("member") or {}).get("access_expires_at")
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+
+
+async def apply_membership_lapses(
+    session: AsyncSession, *, platform: str, now: datetime | None = None,
+) -> dict:
+    """Stop sources whose paid access has ended; resume the ones this stopped.
+
+    Refuses to act on a roster that isn't fresh, for the same reason C4 refuses
+    to draw conclusions from one.
+    """
+    now = now or datetime.now(UTC)
+    state = await get_sync_state(session, platform)
+    if not roster_is_fresh(state, now=now):
+        return {"platform": platform, "skipped": "roster not fresh", "stopped": 0, "resumed": 0}
+
+    memberships = (await session.execute(
+        select(PlatformMembership).where(PlatformMembership.platform == platform)
+    )).scalars().all()
+    sources = (await session.execute(
+        select(Source).where(Source.platform == platform)
+    )).scalars().all()
+    pairs = pair_sources_with_memberships(list(sources), list(memberships))
+
+    stopped: list[int] = []
+    resumed: list[int] = []
+    for source in sources:
+        pair = pairs.get(source.id)
+        if pair is None:
+            continue  # absence is never acted on, see above
+        m, _kind = pair
+        paid = has_paid_access(
+            m.platform, m.status,
+            is_free_member=bool((m.details or {}).get("is_free_member")),
+        )
+        co = dict(source.config_overrides or {})
+
+        if paid is True:
+            changed = co.pop(KEPT_KEY, None) is not None
+            if STOPPED_KEY in co:
+                co.pop(STOPPED_KEY)
+                source.enabled = True
+                resumed.append(source.id)
+                changed = True
+            if changed:
+                source.config_overrides = co
+            continue
+
+        # Unknown status: never a reason to stop something (has_paid_access's
+        # tri-state exists for exactly this).
+        if paid is None:
+            continue
+        if not source.enabled or co.get(KEPT_KEY):
+            continue
+        expires = _access_expires_at(m)
+        if expires is not None and expires > now:
+            continue  # still inside the paid-through period
+
+        co[STOPPED_KEY] = {"at": now.isoformat(), "status": m.status}
+        source.config_overrides = co
+        source.enabled = False
+        # The same clean slate a manual disable gives (SourceService.update,
+        # #1285), so a stopped source doesn't linger as failing or gated.
+        source.last_error = None
+        source.error_type = None
+        source.consecutive_failures = 0
+        stopped.append(source.id)
+
+    await session.commit()
+    return {"platform": platform, "stopped": len(stopped), "resumed": len(resumed)}
+

backend/app/services/membership_roster.py

@@ -20,8 +20,10 @@ own word — `active_patron`, not some normalised FC value. The mapping from
 those words to FC's meaning is a read-site concern and belongs in code that can
 be corrected without a migration, because the vocabulary comes from whatever
 each platform says and will be discovered per platform rather than designed up
-front. `MEMBERSHIP_STATUS` below is a place for that knowledge to accumulate as
-platforms are characterised; it is deliberately empty of guesses today.
+front. `native_ingest_common.MEMBERSHIP_STATUS` is where that knowledge
+accumulates as platforms are characterised, and it holds no guesses. It lives
+there rather than here because platform clients need it, and a client may not
+import this module (test_gated_reason.py).
 """
 
 from __future__ import annotations
@@ -35,78 +37,10 @@ from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..models import MembershipSync, PlatformMembership, Source
+from .native_ingest_common import has_paid_access
 
 log = logging.getLogger(__name__)
 
-# Platform word -> whether the account currently has paid access.
-#
-# Every entry here must come from a CHARACTERISED response, never from API docs
-# or a plausible guess — project rule 130, and inventing a status before seeing
-# it in a real payload is exactly the failure it names.
-#
-# patreon: from a live capture of the operator's own session, 2026-09-10
-# (Scribe note #3886). Only two values were OBSERVED in `patron_status` and
-# only those two are here.
-#
-# `declined_patron` is deliberately ABSENT even though it looks obviously
-# right. It appears in the request's `filter[membership_type]`, and the capture
-# proved that filter is NOT the same vocabulary as the attribute — a row
-# selected by the filter as `free_member` came back with
-# `patron_status: former_patron`, a word the filter does not contain. Reading
-# the filter as an enum is the specific mistake the capture caught; adding
-# `declined_patron` on the strength of it would be repeating that mistake one
-# step later.
-#
-# Unknown words are NOT an error: an unrecognised status means the roster
-# records evidence it cannot yet interpret, which is a better state than
-# dropping the row or asserting a meaning for it.
-#
-# subscribestar: from a live capture of the account's /subscriptions page,
-# 2026-09-13 (Scribe note #3989). SubscribeStar gives NO per-row status word —
-# a membership's state is which of two tables it sits in — so the "word" stored
-# is the table card's own `data-identifier`, verbatim. Those two identifiers are
-# the whole vocabulary; there is nothing further to characterise later.
-MEMBERSHIP_STATUS: dict[str, dict[str, bool]] = {
-    "patreon": {
-        "active_patron": True,
-        "former_patron": False,
-    },
-    "subscribestar": {
-        "active_subscriptions": True,
-        "cancelled_subscriptions": False,
-    },
-}
-
-
-def has_paid_access(
-    platform: str, status: str | None, *, is_free_member: bool = False,
-) -> bool | None:
-    """Does this membership mean the account currently PAYS for access?
-
-    Returns None for a status this code has not been taught, which callers must
-    treat as "unknown" rather than as False. The difference matters: False says
-    the operator has lost access, and asserting that from an unrecognised word
-    would tell them to cancel a source they are still paying for.
-
-    `is_free_member` is a second axis, not a status, and that is Patreon's
-    design rather than ours: the capture shows a free follow expressed as a
-    boolean alongside `patron_status`, so a "current" membership can still be
-    one nobody is paying for. Taking status alone would report a free follower
-    as a paying patron, and C4 would then never offer to clean it up.
-
-    (Honest limit: the capture contains no ACTIVE free member, so it cannot
-    demonstrate the two axes coming apart. The separation is what the payload's
-    shape says; the sample only shows it is possible, not that it happens.)
-    """
-    if status is None:
-        return None
-    known = MEMBERSHIP_STATUS.get(platform, {}).get(status)
-    if known is None:
-        return None
-    if not known:
-        return False
-    return not is_free_member
-
 
 async def touch_membership(
     session: AsyncSession,

backend/app/services/native_ingest_common.py

@@ -231,7 +231,7 @@ class Membership:
 
     `status` carries the PLATFORM's own word, verbatim and unmapped
     (`active_patron`, `former_patron`, ...). Deciding what it means is the read
-    site's job — `membership_roster.has_paid_access` — precisely so an
+    site's job — `has_paid_access`, below — precisely so an
     unrecognised word records as evidence rather than as a decision.
 
     `is_free_member` is SEPARATE from status and must stay that way. Patreon
@@ -396,3 +396,81 @@ class BaseNativeDownloader:
         sidecar_path = media_path.with_suffix(".json")
         sidecar_path.write_text(json.dumps(data, indent=2))
         return sidecar_path
+
+# --- membership status vocabulary (#387) ------------------------------------
+#
+# Lives here, beside `Membership`, rather than in `membership_roster`. It is
+# pure platform knowledge with no database behind it, and the platform clients
+# need it too. Patreon's must tell a lapsed membership to a deleted creator
+# (skippable) from a paid one it cannot attribute (drift), and a client may not
+# import `membership_roster`: test_gated_reason.py forbids any fetch path from
+# reaching the roster, so the roster can explain a skip but never cause one.
+#
+# Platform word -> whether the account currently has paid access.
+#
+# Every entry here must come from a CHARACTERISED response, never from API docs
+# or a plausible guess — project rule 130, and inventing a status before seeing
+# it in a real payload is exactly the failure it names.
+#
+# patreon: from a live capture of the operator's own session, 2026-09-10
+# (Scribe note #3886). Only two values were OBSERVED in `patron_status` and
+# only those two are here.
+#
+# `declined_patron` is deliberately ABSENT even though it looks obviously
+# right. It appears in the request's `filter[membership_type]`, and the capture
+# proved that filter is NOT the same vocabulary as the attribute — a row
+# selected by the filter as `free_member` came back with
+# `patron_status: former_patron`, a word the filter does not contain. Reading
+# the filter as an enum is the specific mistake the capture caught; adding
+# `declined_patron` on the strength of it would be repeating that mistake one
+# step later.
+#
+# Unknown words are NOT an error: an unrecognised status means the roster
+# records evidence it cannot yet interpret, which is a better state than
+# dropping the row or asserting a meaning for it.
+#
+# subscribestar: from a live capture of the account's /subscriptions page,
+# 2026-09-13 (Scribe note #3989). SubscribeStar gives NO per-row status word —
+# a membership's state is which of two tables it sits in — so the "word" stored
+# is the table card's own `data-identifier`, verbatim. Those two identifiers are
+# the whole vocabulary; there is nothing further to characterise later.
+MEMBERSHIP_STATUS: dict[str, dict[str, bool]] = {
+    "patreon": {
+        "active_patron": True,
+        "former_patron": False,
+    },
+    "subscribestar": {
+        "active_subscriptions": True,
+        "cancelled_subscriptions": False,
+    },
+}
+
+
+def has_paid_access(
+    platform: str, status: str | None, *, is_free_member: bool = False,
+) -> bool | None:
+    """Does this membership mean the account currently PAYS for access?
+
+    Returns None for a status this code has not been taught, which callers must
+    treat as "unknown" rather than as False. The difference matters: False says
+    the operator has lost access, and asserting that from an unrecognised word
+    would tell them to cancel a source they are still paying for.
+
+    `is_free_member` is a second axis, not a status, and that is Patreon's
+    design rather than ours: the capture shows a free follow expressed as a
+    boolean alongside `patron_status`, so a "current" membership can still be
+    one nobody is paying for. Taking status alone would report a free follower
+    as a paying patron, and C4 would then never offer to clean it up.
+
+    (Honest limit: the capture contains no ACTIVE free member, so it cannot
+    demonstrate the two axes coming apart. The separation is what the payload's
+    shape says; the sample only shows it is possible, not that it happens.)
+    """
+    if status is None:
+        return None
+    known = MEMBERSHIP_STATUS.get(platform, {}).get(status)
+    if known is None:
+        return None
+    if not known:
+        return False
+    return not is_free_member

backend/app/services/patreon_client.py

@@ -58,6 +58,7 @@ from .native_ingest_common import (
     NativeDriftError,
     NativeIngestError,
     basename_from_url,
+    has_paid_access,
     make_session,
     retry_after_seconds,
 )
@@ -631,7 +632,25 @@ class PatreonClient:
                 "cannot tell a complete roster from a truncated one"
             )
 
-    def _membership(self, member: dict, index: dict) -> Membership:
+    def _membership(self, member: dict, index: dict) -> Membership | None:
+        """One member row as a Membership, or None for a row the roster can skip.
+
+        The one skippable row is a LAPSED membership whose creator no longer
+        exists. The live roster (note #3886, CORRECTION 3) returned 104 rows,
+        because FC sends no membership-type filter and so gets lapses going back
+        years. One of them, a membership that ended in 2017, carried no
+        `campaign` relationship at all: the key is absent, not null, and its
+        reward names no campaign either. The creator's page is gone.
+
+        Raising on that row made the whole roster unusable over one membership
+        nobody can act on. Skipping it changes no conclusion. A lapsed
+        membership already means "not paying", absence means the same, and no
+        Source can be matched to a campaign that no longer has an id.
+
+        The refusal stays for every other row. An active or unrecognised
+        membership without a creator is something FC cannot vouch for, and
+        dropping it would read downstream as a cancellation.
+        """
         attrs = member.get("attributes") or {}
         if "patron_status" not in attrs:
             raise PatreonDriftError(
@@ -640,6 +659,17 @@ class PatreonClient:
 
         campaign_ids = self._related_ids(member, "campaign")
         if not campaign_ids:
+            paid = has_paid_access(
+                "patreon", attrs.get("patron_status"),
+                is_free_member=bool(attrs.get("is_free_member")),
+            )
+            if paid is False:
+                log.info(
+                    "Patreon roster: skipping a lapsed membership with no campaign "
+                    "(creator deleted); status=%s access_expires_at=%s",
+                    attrs.get("patron_status"), attrs.get("access_expires_at"),
+                )
+                return None
             raise PatreonDriftError(
                 "Patreon member resource has no campaign relationship — a "
                 "membership we cannot attribute to a creator is not usable"
@@ -700,7 +730,9 @@ class PatreonClient:
             index = self._transform(response)
             rows = [m for m in (response.get("data") or []) if isinstance(m, dict)]
             for member in rows:
-                yield self._membership(member, index)
+                membership = self._membership(member, index)
+                if membership is not None:
+                    yield membership
 
             seen += len(rows)
             total = int(response["meta"]["pagination"]["total"] or 0)

backend/app/services/source_service.py

@@ -19,6 +19,7 @@ from ..models import (
 )
 from .db_helpers import failing_sources_clause
 from .gallery_dl import ErrorType
+from .membership_reconcile import KEPT_KEY, STOPPED_KEY
 from .membership_roster import gated_reasons_for_sources
 from .platforms import known_platform_keys
 from .scheduler_service import compute_next_check_at
@@ -158,6 +159,38 @@ def _is_app_managed(key: str) -> bool:
 BACKFILL_MAX_CHUNKS = 200
 
 
+def arm_backfill(source: Source) -> None:
+    """Arm a fresh run-until-done backfill on `source` (plan #693). Mutation
+    only — the caller commits. Shared by `SourceService.start_backfill` and the
+    sync Discord repair, so both clear exactly the same resume state."""
+    co = dict(source.config_overrides or {})
+    co["_backfill_state"] = "running"
+    for k in ("_backfill_cursor", "_backfill_cursor_stalls", "_backfill_chunks",
+              "_backfill_posts"):
+        co.pop(k, None)
+    source.config_overrides = co
+    source.backfill_runs_remaining = BACKFILL_MAX_CHUNKS
+
+
+def _record_manual_enable_choice(source: Source, *, enabled: bool) -> None:
+    """Keep the membership sweep (#3995) from overriding the operator.
+
+    Turning a source the sweep STOPPED back on is a deliberate choice to keep
+    pulling a lapsed creator, so it is marked kept and the next sweep leaves it
+    alone. Turning a source off by hand drops any sweep marker, so the sweep
+    never switches back on something the operator switched off themselves.
+    """
+    co = dict(source.config_overrides or {})
+    if enabled and STOPPED_KEY in co:
+        co.pop(STOPPED_KEY)
+        co[KEPT_KEY] = True
+    elif not enabled:
+        co.pop(STOPPED_KEY, None)
+    else:
+        return
+    source.config_overrides = co
+
+
 class SourceService:
     def __init__(self, session: AsyncSession):
         self.session = session
@@ -415,6 +448,9 @@ class SourceService:
         for key, value in fields.items():
             setattr(source, key, value)
 
+        if "enabled" in fields:
+            _record_manual_enable_choice(source, enabled=bool(fields["enabled"]))
+
         if url_changed:
             # Repointing a source at a different creator makes a cached campaign
             # id WRONG, not merely stale, and `patreon_resolver` consults that
@@ -473,13 +509,7 @@ class SourceService:
         )).scalar_one_or_none()
         if source is None:
             raise LookupError(f"source id={source_id} not found")
-        co = dict(source.config_overrides or {})
-        co["_backfill_state"] = "running"
-        for k in ("_backfill_cursor", "_backfill_cursor_stalls", "_backfill_chunks",
-                  "_backfill_posts"):
-            co.pop(k, None)
-        source.config_overrides = co
-        source.backfill_runs_remaining = BACKFILL_MAX_CHUNKS
+        arm_backfill(source)
         await self.session.commit()
         return await self._row_to_record(source)
 

backend/app/services/subscribestar_client.py

@@ -316,7 +316,7 @@ _ROSTER_URL = f"{_ROSTER_BASE}/subscriptions"
 # `data-identifier`, the one vocabulary that names a state: the table class
 # inside the cancelled card says `for-unsubscribed_users`, a different word for
 # the same list (note #3989, CORRECTION 1). The identifier is stored verbatim as
-# Membership.status and mapped in membership_roster.MEMBERSHIP_STATUS.
+# Membership.status and mapped in native_ingest_common.MEMBERSHIP_STATUS.
 _ROSTER_ACTIVE = "active_subscriptions"
 _ROSTER_CANCELLED = "cancelled_subscriptions"
 

backend/app/tasks/admin.py

@@ -122,6 +122,28 @@ def prune_missing_file_records_task(self) -> dict:
     return {"checked": checked, "missing": len(missing_ids), "deleted": deleted}
 
 
+@celery.task(
+    name="backend.app.tasks.admin.repair_discord_downloads_task",
+    bind=True,
+    autoretry_for=(OperationalError, DBAPIError),
+    retry_backoff=15, retry_backoff_max=180, max_retries=1,
+    soft_time_limit=1800, time_limit=2400,  # 30 min / 40 min
+)
+def repair_discord_downloads_task(self, dry_run: bool = True) -> dict:
+    """Clean re-download of the Discord files broken by the `None` naming
+    (#3999). dry_run (the default) returns the projection; apply deletes the
+    broken images and their files, makes gallery-dl forget every Discord
+    download, and restarts every Discord source's backfill. Defaults to the SAFE
+    preview because the apply deletes files. Operator-triggered only."""
+    from ..services.discord_repair import repair_discord_downloads
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        return repair_discord_downloads(
+            session, images_root=IMAGES_ROOT, dry_run=dry_run,
+        )
+
+
 @celery.task(
     name="backend.app.tasks.admin.dedup_videos_task",
     bind=True,

backend/app/tasks/library_placement.py

@@ -0,0 +1,125 @@
+"""Placement reconciler tasks — plan, apply, revert (milestone #421).
+
+The service (`services.library_layout`) holds the decisions; this module is
+only the async wrapper, matching `tasks.library_audit`: run on the
+maintenance queue, mark the run `error` with a traceback if anything escapes,
+and return a small summary dict so eager-mode tests can assert on it.
+
+Applying is a long run — 33,789 renames on the operator's library at the time
+of writing — so `apply_placement` persists its ledger in chunks rather than
+at the end. That ledger is the only record of where each file came from, and
+a worker that dies two thirds of the way through must not take the undo
+information for the first two thirds with it.
+"""
+
+import logging
+import traceback
+from datetime import UTC, datetime
+from pathlib import Path
+
+from sqlalchemy.exc import DBAPIError, OperationalError
+
+from ..celery_app import celery
+from ..models import LibraryPlacementRun
+from ..services import library_layout
+from ._sync_engine import sync_session_factory as _sync_session_factory
+
+log = logging.getLogger(__name__)
+
+IMAGES_ROOT = Path("/images")
+
+# Commit the ledger every this many moves. Small enough that a crash loses
+# seconds of work, large enough not to make a COMMIT per rename.
+_APPLY_CHUNK = 200
+
+
+def _fail(session, run_id: int, message: str) -> None:
+    run = session.get(LibraryPlacementRun, run_id)
+    if run is not None:
+        run.status = "error"
+        run.error = message
+        run.finished_at = datetime.now(UTC)
+        session.commit()
+
+
+@celery.task(
+    name="backend.app.tasks.library_placement.plan_placement",
+    autoretry_for=(OperationalError, DBAPIError),
+    retry_backoff=5, retry_backoff_max=60, retry_jitter=True, max_retries=3,
+    soft_time_limit=900, time_limit=1000,
+)
+def plan_placement(artist_id: int | None = None) -> dict:
+    """Build a move plan and leave it `ready` for the operator to read.
+
+    Reads rows and stats destinations; moves nothing.
+    """
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        run = library_layout.plan_placement(
+            session, IMAGES_ROOT, artist_id=artist_id,
+        )
+        session.commit()
+        return {
+            "run_id": run.id, "status": run.status,
+            "planned_count": run.planned_count,
+        }
+
+
+@celery.task(
+    name="backend.app.tasks.library_placement.apply_placement",
+    soft_time_limit=7200, time_limit=7500,
+)
+def apply_placement(run_id: int) -> dict:
+    """Execute a `ready` run's stored plan. Renames files and rewrites rows.
+
+    No autoretry: a retry would re-enter a half-applied plan on a schedule
+    nobody asked for. Re-running IS safe (the applied rows refuse as "row
+    moved since planning"), but that should be the operator's decision after
+    reading what happened, not the queue's.
+    """
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        run = session.get(LibraryPlacementRun, run_id)
+        if run is None:
+            return {"run_id": run_id, "status": "missing"}
+        if run.status != "ready":
+            return {"run_id": run_id, "status": run.status, "skipped": True}
+        try:
+            library_layout.apply_run(session, run, chunk=_APPLY_CHUNK)
+            session.commit()
+        except Exception:
+            log.exception("placement apply failed for run %s", run_id)
+            session.rollback()
+            _fail(session, run_id, traceback.format_exc())
+            return {"run_id": run_id, "status": "error"}
+        return {
+            "run_id": run_id, "status": run.status,
+            "moved": run.moved_count, "refused": run.refused_count,
+        }
+
+
+@celery.task(
+    name="backend.app.tasks.library_placement.revert_placement",
+    soft_time_limit=7200, time_limit=7500,
+)
+def revert_placement(run_id: int) -> dict:
+    """Put an applied run's files back where they came from."""
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        run = session.get(LibraryPlacementRun, run_id)
+        if run is None:
+            return {"run_id": run_id, "status": "missing"}
+        if run.status != "applied":
+            return {"run_id": run_id, "status": run.status, "skipped": True}
+        try:
+            library_layout.revert_run(session, run)
+            session.commit()
+        except Exception:
+            log.exception("placement revert failed for run %s", run_id)
+            session.rollback()
+            _fail(session, run_id, traceback.format_exc())
+            return {"run_id": run_id, "status": "error"}
+        return {
+            "run_id": run_id, "status": run.status,
+            "refused": run.refused_count,
+        }

backend/app/tasks/maintenance.py

@@ -502,10 +502,16 @@ def prune_task_runs() -> dict:
     soft_time_limit=1800, time_limit=2100,
 )
 def backfill_phash() -> int:
-    """Recompute phash for stored images that have none (imported before
-    FC-2d-i+ii). Keyset-paginated by id (restart-safe), NULL-only fill,
-    idempotent. Videos legitimately keep phash NULL. A missing/unreadable
-    file is logged and left NULL — never fails the task."""
+    """Recompute phash for stored images that have none. Keyset-paginated by
+    id (restart-safe), NULL-only fill, idempotent. Videos legitimately keep
+    phash NULL. A missing/unreadable file is logged and left NULL — never
+    fails the task.
+
+    Two sources of NULLs: images imported before FC-2d-i+ii, and migration
+    0098, which cleared every phash so the library could be re-hashed at
+    hash_size=16 (#4223). The daily beat entry exists for the second — until
+    a row is refilled it takes no part in dedup, which is why this runs on a
+    schedule rather than waiting for a deep scan."""
     SessionLocal = _sync_session_factory()
     updated = 0
     last_id = 0
@@ -1247,6 +1253,7 @@ def sync_memberships() -> str:
     from ..services.artist_membership_service import rescan as membership_rescan
     from ..services.credential_crypto import CredentialCrypto
     from ..services.credential_service import CredentialService
+    from ..services.membership_reconcile import apply_membership_lapses
     from ..services.membership_roster import roster_user_id, sync_platform
     from ..services.patreon_client import PatreonClient
     from ..services.subscribestar_client import SubscribeStarClient
@@ -1298,9 +1305,18 @@ def sync_memberships() -> str:
                     )
 
                 async with async_factory() as session:
-                    results.append(
-                        await sync_platform(session, platform=platform, fetch=fetch)
-                    )
+                    result = await sync_platform(session, platform=platform, fetch=fetch)
+                results.append(result)
+
+                # #3995: stop pulling sources whose paid access has ended, and
+                # resume the ones this stopped once they are paid again. Only
+                # right after a successful sync, so it always acts on the roster
+                # just written, never on a stale one.
+                if result.get("ok"):
+                    async with async_factory() as session:
+                        result["lapses"] = await apply_membership_lapses(
+                            session, platform=platform,
+                        )
 
             # #388 E4: offer the freshly-synced roster to the artists FC already
             # tracks. Chained here rather than given its own beat entry because
@@ -1321,7 +1337,12 @@ def sync_memberships() -> str:
         if "skipped" in r:
             parts.append(f"{r['platform']}=skipped({r['skipped']})")
         elif r.get("ok"):
-            parts.append(f"{r['platform']}={r['count']}")
+            lapses = r.get("lapses") or {}
+            detail = (
+                f"(stopped={lapses['stopped']},resumed={lapses['resumed']})"
+                if lapses.get("stopped") or lapses.get("resumed") else ""
+            )
+            parts.append(f"{r['platform']}={r['count']}{detail}")
         else:
             parts.append(f"{r['platform']}=FAILED({r['error']})")
     if res.get("suggested") is not None:

backend/app/utils/paths.py

@@ -60,6 +60,37 @@ def derive_subdir(source_path: Path, import_root: Path) -> str:
     return str(rel) if str(rel) != "." else ""
 
 
+def canonical_subdir(subdir: str, artist_slug: str | None) -> str:
+    """`subdir` with its TOP-LEVEL segment replaced by the artist's slug.
+
+        canonical_subdir("Conto/patreon", "conto")  -> "conto/patreon"
+        canonical_subdir("Conto", "conto")          -> "conto"
+        canonical_subdir("Conto/patreon", None)     -> "Conto/patreon"
+        canonical_subdir("", "conto")               -> ""
+
+    `derive_subdir` mirrors the IMPORT tree's folder names verbatim, so a
+    filesystem import out of `/import/Conto/...` used to write
+    `<images_root>/Conto/...` while the download path wrote `<root>/conto/...`
+    for the very same Artist row. One artist, two directories, forever — 57
+    such families had accumulated by 2026-09-21, and the database never had
+    duplicate artists at all (milestone #421).
+
+    The slug is the canonical name because it is the Artist row's own
+    identifier: it is what `/api/artists` reports, what the ingesters already
+    write, and the one spelling that cannot vary with how a folder happened to
+    be capitalised on the way in.
+
+    Two deliberate pass-throughs. NO artist resolved means there is nothing
+    authoritative to canonicalise against, and an EMPTY subdir is a file
+    landing at the images root — those have no artist folder to correct, and
+    what becomes of them is its own decision (task #4247), not a side effect
+    of this helper.
+    """
+    if not artist_slug or not subdir:
+        return subdir
+    return str(Path(artist_slug, *Path(subdir).parts[1:]))
+
+
 def hash_suffixed_name(stem: str, sha256_hex: str, ext: str) -> str:
     """Builds 'stem__<first10ofhash><ext>'.
 

backend/app/utils/phash.py

@@ -1,57 +1,222 @@
 """Perceptual-hash dedup helpers (ported from ImageRepo).
 
-hash_size=8 -> 64-bit hash -> 16-hex-char string, which fits the existing
-ImageRecord.phash String(32) column (no image_record migration). IR uses
-hash_size=16; the deliberate FC deviation keeps the schema unchanged. The
-Hamming threshold is the operator-exposed dial (ImportSettings).
+hash_size=16 -> 256-bit hash -> 64-hex-char string, which is why
+`ImageRecord.phash` is String(64) (widened in migration 0098).
+
+## Why 16, after running at 8 from FC-2d until 2026-09-21
+
+`hash_size=8` keeps only the top-left 8x8 block of the DCT — 64 bits
+describing an image's coarse light/dark layout and nothing else. Variant
+artwork that shares a composition (same pose and framing, a different
+outfit / expression / overlay) collided OUTRIGHT at that size, so the
+operator's near-duplicate dial could not separate variants from rescales
+even at its floor: `phash_threshold=0` means "the same 64 bits", not "the
+same image", and packs of 15 variants were landing as 3 records
+(issue #4223). IR always used 16; FC's deviation to 8 was made to fit the
+old String(32) column without a migration — a schema convenience that cost
+the operator artwork.
+
+## The hash no longer decides a merge on its own
+
+Dropping a file or superseding one is destructive, so `find_similar` now
+runs three gates, cheapest first:
+
+  1. Hamming distance within the operator's `phash_threshold` — the cheap
+     indexed pre-filter that PROPOSES candidates.
+  2. Aspect ratio within ASPECT_TOL. A crop or a re-canvas is not a
+     rescale, and this is the same identity test the tier-1 video near-dup
+     path already uses (`_VIDEO_DUP_ASPECT_TOL`).
+  3. A pixel-level confirm on the candidate's actual file, supplied by the
+     caller (the importer opens the files; this module stays I/O-free apart
+     from `fingerprint_path`).
+
+Because the confirm is what ACCEPTS a match, the threshold can stay
+generous enough to tolerate a re-encode without putting variants at risk.
+
+Every gate fails CLOSED: unknown dimensions, an unreadable candidate, a
+hash that won't parse — all mean "not a duplicate". The two failure
+directions are not symmetrical. Too strict keeps a redundant lower-res copy,
+which the operator can see and delete; too loose deletes artwork that only
+a re-walk of the source can bring back.
 """
 
 import imagehash
+from PIL import Image, ImageChops, ImageStat
 
-HASH_SIZE = 8
+HASH_SIZE = 16
+
+# Gate 2. Matching `importer._VIDEO_DUP_ASPECT_TOL` — a rescale preserves
+# aspect ratio to within rounding, so this only has to absorb off-by-one
+# pixel dimensions.
+ASPECT_TOL = 0.02
+
+# Gate 3. Both images are reduced to one FINGERPRINT_SIZE-square grayscale
+# thumbnail and compared directly, which is the question actually being
+# asked: "are these the same picture at different resolutions?"
+#
+# Two criteria, because they catch different things. MEAN absolute
+# difference catches a global change (a recolour, a filter, a different
+# shading pass) that leaves the composition intact. The CHANGED-PIXEL
+# fraction catches a LOCAL one — an added overlay, a different expression,
+# an alternate outfit on part of the figure — which a mean over 4096 pixels
+# would otherwise dilute into noise.
+#
+# Tuned to fail closed (see the module docstring). A true rescale lands near
+# zero on both; these ceilings sit well above that and well below a variant.
+FINGERPRINT_SIZE = 64
+FINGERPRINT_MAX_MEAN_DIFF = 6.0
+FINGERPRINT_CHANGED_LEVEL = 64
+FINGERPRINT_MAX_CHANGED_FRACTION = 0.02
+
+
+def _seek_first_frame(pil_image) -> None:
+    """Animated images (multi-frame WebP/GIF/APNG) are hashed and
+    fingerprinted on frame 0 — the conventional choice for animated
+    content, and the one that keeps PIL from iterating every frame."""
+    if getattr(pil_image, "is_animated", False):
+        try:
+            pil_image.seek(0)
+        except Exception:
+            pass
 
 
 def compute_phash(pil_image) -> str | None:
     """Perceptual hash of an opened PIL image, as a hex string. None on any
     failure (videos/unreadable/non-image).
 
-    For animated images (multi-frame WebP/GIF/APNG), explicitly seek to
-    frame 0 first. Without this, some PIL operations downstream of
-    imagehash.phash (convert("L"), resize) can iterate all frames and
-    blow past Celery's hard time limit on large animations
-    (operator-flagged 2026-05-26 against animated WebPs). The pHash of
-    frame 0 is the conventional choice for animated content.
+    Frame 0 for animated images: without the seek, PIL operations
+    downstream of imagehash.phash (convert("L"), resize) can iterate all
+    frames and blow past Celery's hard time limit on large animations
+    (operator-flagged 2026-05-26 against animated WebPs).
     """
     try:
-        if getattr(pil_image, "is_animated", False):
-            try:
-                pil_image.seek(0)
-            except Exception:
-                pass
+        _seek_first_frame(pil_image)
         return str(imagehash.phash(pil_image, hash_size=HASH_SIZE))
     except Exception:
         return None
 
 
+def fingerprint(pil_image):
+    """A small grayscale thumbnail of an opened PIL image, for gate 3.
+
+    Returns a detached PIL image (so the caller may close the original) or
+    None on any failure. PIL-only on purpose: numpy is an imagehash
+    transitive dependency, not a declared one for this path.
+    """
+    try:
+        _seek_first_frame(pil_image)
+        return pil_image.convert("L").resize(
+            (FINGERPRINT_SIZE, FINGERPRINT_SIZE), Image.LANCZOS
+        )
+    except Exception:
+        return None
+
+
+def fingerprint_path(path) -> Image.Image | None:
+    """`fingerprint` for a file on disk. None if it cannot be read — which
+    the gate treats as "not a duplicate"."""
+    try:
+        with Image.open(path) as im:
+            return fingerprint(im)
+    except Exception:
+        return None
+
+
+def fingerprint_diff(
+    a, b, *, changed_level: int = FINGERPRINT_CHANGED_LEVEL,
+) -> tuple[float, float] | None:
+    """(mean absolute difference, fraction of pixels past `changed_level`) for
+    two fingerprints. None if either is missing or the comparison fails.
+
+    This is the MEASUREMENT behind `fingerprints_match`, split out so the
+    calibration report (scripts/phash_gate_report.py) can show how far a pair
+    sat from the limits instead of only which side of them it fell on. The
+    constants were chosen without a real-library sample; the numbers this
+    returns are what moves them.
+    """
+    if a is None or b is None:
+        return None
+    try:
+        diff = ImageChops.difference(a, b)
+        hist = diff.histogram()
+        total = sum(hist)
+        if not total:
+            return None
+        return (ImageStat.Stat(diff).mean[0], sum(hist[changed_level:]) / total)
+    except Exception:
+        return None
+
+
+def fingerprints_match(
+    a, b,
+    *,
+    max_mean_diff: float = FINGERPRINT_MAX_MEAN_DIFF,
+    changed_level: int = FINGERPRINT_CHANGED_LEVEL,
+    max_changed_fraction: float = FINGERPRINT_MAX_CHANGED_FRACTION,
+) -> bool:
+    """True when two fingerprints are the same picture: no large global
+    drift AND no meaningful local region that differs. False on any
+    failure."""
+    measured = fingerprint_diff(a, b, changed_level=changed_level)
+    if measured is None:
+        return False
+    mean, changed_fraction = measured
+    return mean <= max_mean_diff and changed_fraction <= max_changed_fraction
+
+
+def aspect_matches(
+    width: int | None, height: int | None,
+    cand_width: int | None, cand_height: int | None,
+    *, tol: float = ASPECT_TOL,
+) -> bool:
+    """Gate 2. False when either side's dimensions are unknown — an
+    unmeasurable candidate is not a proven duplicate."""
+    if not width or not height or not cand_width or not cand_height:
+        return False
+    a, b = width / height, cand_width / cand_height
+    if a <= 0 or b <= 0:
+        return False
+    return abs(a - b) / max(a, b) <= tol
+
+
 def find_similar(
     phash_hex: str,
     width: int,
     height: int,
     candidates: list[tuple[str, int, int, int]],
     threshold: int,
+    *,
+    confirm=None,
 ) -> tuple[str, int | None]:
     """candidates: (phash_hex, width, height, image_id). Returns one of
     ("none", None) / ("larger_exists", id) / ("smaller_exists", id).
-    First qualifying candidate wins (IR loop order)."""
+    First candidate to pass EVERY gate wins (IR loop order).
+
+    `confirm` is gate 3: an optional callable(image_id) -> bool, called only
+    for a candidate that already passed the hash and aspect gates, and
+    expected to compare the two files' pixels. A rejected candidate does not
+    end the search — the loop moves on, so a false pre-filter hit cannot
+    mask a real duplicate further down the list. Omitting it leaves the
+    hash+aspect behaviour, which is what the unit tests exercise.
+    """
     new_h = imagehash.hex_to_hash(phash_hex)
     for cand_hex, cw, ch, cid in candidates:
         try:
             dist = new_h - imagehash.hex_to_hash(cand_hex)
         except Exception:
+            # Includes the mismatched-length case while a library re-hash
+            # (migration 0098) is still in flight: an old 64-bit hash cannot
+            # be compared to a new 256-bit one, and skipping it degrades to
+            # "no dedup yet" rather than to a wrong merge.
             continue
-        if dist <= threshold:
-            if cw >= width and ch >= height:
-                return ("larger_exists", cid)
-            if width > cw or height > ch:
-                return ("smaller_exists", cid)
+        if dist > threshold:
+            continue
+        if not aspect_matches(width, height, cw, ch):
+            continue
+        if confirm is not None and not confirm(cid):
+            continue
+        if cw >= width and ch >= height:
+            return ("larger_exists", cid)
+        if width > cw or height > ch:
+            return ("smaller_exists", cid)
     return ("none", None)

frontend/public/favicon.svg

@@ -15,7 +15,10 @@
        Colours are theme tokens (frontend/src/theme/fabled-tokens.js): obsidian
        plate, accent gold. The plate is kept here (unlike logo.svg) so the tab
        icon is self-contained against any browser chrome; on the nav it is
-       invisible because it matches --fc-chrome-rgb exactly. -->
+       invisible because it matches the fc-chrome-rgb custom property exactly.
+       No double hyphen may appear inside this comment: XML forbids it, and a
+       browser refuses to render an SVG that does not parse (it happened once —
+       tests/test_public_svgs.py). -->
   <rect width="32" height="32" rx="6" fill="#14171A"/>
   <rect x="6.2" y="4.2" width="19.6" height="23.6" rx="1.4"
         fill="none" stroke="#A87338" stroke-width="2.4"/>

frontend/src/components/AppShell.vue

@@ -17,6 +17,22 @@ const route = useRoute()
 
 <style scoped>
 .fc-content {
+  /* The full brand mark as one large, faint backdrop behind every page,
+     pinned to the viewport so content scrolls over it. Opaque surfaces
+     (cards, the nav) cover it; it shows in the gutters and on bare page
+     ground. The series reader is immersive and skips the shell, so reading
+     is never drawn over it.
+
+     Faded by laying the page colour over it at 94%, NOT with `opacity` on an
+     overlay element: an overlay needs this element to be z-indexed above it,
+     which makes all page content one stacking context under the nav and can
+     trap an in-page overlay beneath it. A background changes no stacking.
+     The mark is gold and parchment, close to the text colours, so it has to
+     stay this faint to keep text over it readable. */
+  background:
+    linear-gradient(rgba(var(--v-theme-background), 0.94), rgba(var(--v-theme-background), 0.94)),
+    url('/logo.svg') center / min(88vmin, 1100px) no-repeat;
+  background-attachment: fixed;
   min-height: 100vh;
   /* NO padding-top: the TopNav is position:sticky, so it already reserves its
      own space in the v-app flex column — content flows directly below it. The

frontend/src/components/posts/PostCard.vue

@@ -1,5 +1,8 @@
 <template>
-  <v-card class="fc-post-card" variant="outlined">
+  <v-card
+    ref="cardEl" class="fc-post-card" variant="outlined"
+    :class="{ 'fc-post-card--wide': wide }"
+  >
     <div class="fc-post-card__head">
       <!-- Posts with no live subscription have source=null (alembic 0030);
            show a "filesystem import" affordance instead of a platform chip. -->
@@ -58,7 +61,7 @@
         </button>
         <div
           v-if="rail.length || moreCount" class="fc-post-card__rail"
-          :style="{ '--fc-rail-cols': railCols }"
+          :style="{ '--fc-rail-cols': railCols, '--fc-grid-cols': Math.min(2, railCols) }"
         >
           <button
             v-for="t in rail" :key="t.image_id" type="button"
@@ -221,20 +224,33 @@ const synthesisTitle = computed(() => {
 })
 
 const hero = computed(() => images.value[0])
-// The thumbnail strip spans the hero's full width (CSS grid, equal columns),
-// rather than a fixed 3-cell cap. Show up to RAIL_MAX cells; when there are
-// more images than fit, the last cell becomes a "+N" overflow tile so the
-// count stays accurate.
-const RAIL_MAX = 5
+
+// Filmstrip layout (milestone #407, option A). On a very wide window a card
+// that just grew would give one post the whole screen, so a WIDE card instead
+// pins the hero to a fixed height and moves the extra images into a 2-column
+// grid BESIDE it. Measured on the card rather than the viewport because the
+// same card renders in the Latest feed, Browse, and the in-context view, each
+// at a different width.
+const WIDE_CARD_PX = 1100
+const cardEl = ref(null)
+const wide = ref(false)
+
+// The narrow layout's strip spans the hero's full width (CSS grid, equal
+// columns); the wide layout's grid is 2×2. Show up to that many cells; when
+// there are more images than fit, the last cell becomes a "+N" overflow tile so
+// the count stays accurate.
+const RAIL_MAX_NARROW = 5
+const RAIL_MAX_WIDE = 4
 const serverMore = computed(() => props.post.thumbnails_more || 0)
 const afterHero = computed(() => images.value.slice(1))
+const railMax = computed(() => (wide.value ? RAIL_MAX_WIDE : RAIL_MAX_NARROW))
 const hasOverflow = computed(
-  () => serverMore.value > 0 || afterHero.value.length > RAIL_MAX,
+  () => serverMore.value > 0 || afterHero.value.length > railMax.value,
 )
 const rail = computed(() =>
   hasOverflow.value
-    ? afterHero.value.slice(0, RAIL_MAX - 1)
-    : afterHero.value.slice(0, RAIL_MAX),
+    ? afterHero.value.slice(0, railMax.value - 1)
+    : afterHero.value.slice(0, railMax.value),
 )
 const visibleCount = computed(() => (images.value.length ? 1 + rail.value.length : 0))
 const moreCount = computed(() => {
@@ -349,8 +365,17 @@ function measureOverflow () {
 }
 
 let ro = null
+let cardRo = null
 onMounted(() => {
   nextTick(measureOverflow)
+  const root = cardEl.value?.$el
+  if (typeof ResizeObserver !== 'undefined' && root) {
+    cardRo = new ResizeObserver((entries) => {
+      const w = entries[0]?.contentRect?.width ?? 0
+      wide.value = w >= WIDE_CARD_PX
+    })
+    cardRo.observe(root)
+  }
   // Re-measure when the card resizes (the container-query clamp differs by
   // width). Guarded for happy-dom / older runtimes without ResizeObserver.
   if (typeof ResizeObserver !== 'undefined' && descEl.value) {
@@ -358,7 +383,10 @@ onMounted(() => {
     ro.observe(descEl.value)
   }
 })
-onBeforeUnmount(() => { if (ro) { ro.disconnect(); ro = null } })
+onBeforeUnmount(() => {
+  if (ro) { ro.disconnect(); ro = null }
+  if (cardRo) { cardRo.disconnect(); cardRo = null }
+})
 
 async function toggleDesc () {
   if (!descExpanded.value) {
@@ -495,6 +523,40 @@ function formatBytes (n) {
   color: rgb(var(--v-theme-accent));
 }
 
+/* --- Filmstrip layout (wide cards, #407 A) ---------------------------------
+   The hero has a HEIGHT, not a width: a wide card must not turn into a
+   full-screen post, so its height stays roughly a third of the viewport
+   whatever the window's width. The extra images sit beside it as square cells
+   whose size derives from that same height, so the grid always ends flush with
+   the hero's bottom edge. */
+.fc-post-card--wide {
+  --fc-hero-h: clamp(260px, 34vh, 460px);
+  --fc-grid-gap: 8px;
+  --fc-cell: calc((var(--fc-hero-h) - var(--fc-grid-gap)) / 2);
+}
+.fc-post-card--wide .fc-post-card__body { flex-direction: row; gap: 24px; }
+.fc-post-card--wide .fc-post-card__media {
+  flex: 0 0 auto;
+  display: flex;
+  gap: var(--fc-grid-gap);
+}
+.fc-post-card--wide .fc-post-card__hero {
+  width: auto;
+  height: var(--fc-hero-h);
+}
+.fc-post-card--wide .fc-post-card__rail {
+  margin-top: 0;
+  gap: var(--fc-grid-gap);
+  grid-template-columns: repeat(var(--fc-grid-cols, 2), var(--fc-cell));
+  grid-auto-rows: var(--fc-cell);
+}
+.fc-post-card--wide .fc-post-card__rail-cell,
+.fc-post-card--wide .fc-post-card__rail-more { height: 100%; }
+.fc-post-card--wide .fc-post-card__text { flex: 1 1 0; min-width: 0; }
+/* Text is secondary here — long reads happen in the expanded view — so the
+   clamp keeps the text column no taller than the images beside it. */
+.fc-post-card--wide .fc-post-card__desc--clamped { -webkit-line-clamp: 4; }
+
 .fc-post-card__title {
   font-family: 'Fraunces', Georgia, serif;
   font-size: 18px; font-weight: 700;

frontend/src/components/posts/PostsFilterBar.vue

@@ -1,21 +1,22 @@
 <template>
   <div class="fc-posts-filters">
+    <!-- The full artist list, filtered client-side as you type. This used to
+         search the server only once something was typed, so opening the
+         dropdown showed an empty menu. -->
     <v-autocomplete
       v-model="artistModel"
       :items="artistOptions"
       :loading="artistLoading"
-      :search="artistQuery"
       item-title="name"
       item-value="id"
       label="Artist"
       density="compact"
       hide-details
       clearable
-      no-filter
       return-object
+      no-data-text="No matching artists"
       class="fc-posts-filters__artist"
-      @update:search="onArtistSearch"
-      @update:model-value="onArtistPicked"
+      @update:model-value="emitFilters"
     />
 
     <v-select
@@ -39,7 +40,8 @@
 
 <script setup>
 import { computed, onMounted, ref, watch } from 'vue'
-import { useSourcesStore } from '../../stores/sources.js'
+
+import { useApi } from '../../composables/useApi.js'
 import { usePlatformsStore } from '../../stores/platforms.js'
 
 const props = defineProps({
@@ -48,18 +50,19 @@ const props = defineProps({
 })
 const emit = defineEmits(['update:filters'])
 
-const sourcesStore = useSourcesStore()
+const api = useApi()
 const platformsStore = usePlatformsStore()
 
-// Artist autocomplete state
-const artistQuery = ref('')
 const artistOptions = ref([])
 const artistLoading = ref(false)
 const artistModel = ref(null)
 
-// Platform v-select state
+// `list`, not `platforms`: the store has never had a `platforms` property, so
+// this read undefined and the dropdown opened empty.
+// test/storeUsage.spec.js now fails on any read of a property the store does
+// not define.
 const platformItems = computed(() =>
-  (platformsStore.platforms || []).map(p => ({ title: p.key, value: p.key }))
+  platformsStore.list.map(p => ({ title: p.name || p.key, value: p.key }))
 )
 const platformModel = ref(props.platform)
 
@@ -67,29 +70,6 @@ const hasFilters = computed(
   () => artistModel.value != null || platformModel.value != null
 )
 
-let _searchTimer = null
-function onArtistSearch(q) {
-  artistQuery.value = q
-  clearTimeout(_searchTimer)
-  if (!q || !q.trim()) {
-    artistOptions.value = artistModel.value ? [artistModel.value] : []
-    return
-  }
-  _searchTimer = setTimeout(async () => {
-    artistLoading.value = true
-    try {
-      const results = await sourcesStore.autocompleteArtist(q, 20)
-      artistOptions.value = results
-    } finally {
-      artistLoading.value = false
-    }
-  }, 200)
-}
-
-function onArtistPicked() {
-  emitFilters()
-}
-
 function emitFilters() {
   emit('update:filters', {
     artist_id: artistModel.value?.id ?? null,
@@ -100,30 +80,38 @@ function emitFilters() {
 function clearAll() {
   artistModel.value = null
   platformModel.value = null
-  artistOptions.value = []
-  artistQuery.value = ''
   emitFilters()
 }
 
-onMounted(async () => {
-  await platformsStore.loadAll()
-  // If a deep-link arrives with an artist_id, hydrate the selected display.
-  if (props.artistId != null) {
-    const seed = { id: props.artistId, name: `Artist #${props.artistId}` }
-    artistModel.value = seed
-    artistOptions.value = [seed]
+// A deep link carries only the id. Once the list is loaded, show the real name
+// rather than a placeholder.
+function selectArtistById(id) {
+  if (id == null) {
+    artistModel.value = null
+    return
   }
+  if (artistModel.value?.id === id) return
+  artistModel.value = artistOptions.value.find(a => a.id === id)
+    || { id, name: `Artist #${id}` }
+}
+
+async function loadArtists() {
+  artistLoading.value = true
+  try {
+    artistOptions.value = await api.get('/api/artists/names')
+  } catch {
+    artistOptions.value = []
+  } finally {
+    artistLoading.value = false
+  }
+}
+
+onMounted(async () => {
+  await Promise.all([platformsStore.loadAll(), loadArtists()])
+  selectArtistById(props.artistId)
 })
 
-watch(() => props.artistId, (val) => {
-  if (val == null) {
-    artistModel.value = null
-  } else if (artistModel.value?.id !== val) {
-    const seed = { id: val, name: `Artist #${val}` }
-    artistModel.value = seed
-    artistOptions.value = [seed]
-  }
-})
+watch(() => props.artistId, (val) => selectArtistById(val))
 
 watch(() => props.platform, (val) => {
   if (platformModel.value !== val) platformModel.value = val || null

frontend/src/components/settings/DiscordRepairCard.vue

@@ -0,0 +1,118 @@
+<template>
+  <!-- #3999: Discord downloads made before the naming fix landed in a `None`
+       folder with no post and a download-time date. This re-downloads them
+       cleanly. Preview first; the apply deletes files. -->
+  <MaintenanceTile
+    icon="mdi-download-off-outline"
+    title="Repair Discord downloads"
+    blurb="Re-download Discord images that were saved with no post and the wrong date."
+    destructive
+    :open="applying || previewing"
+  >
+    <p class="text-body-2 mb-3">
+      Before the naming fix, every Discord download was saved into a folder
+      called <code>None</code>. Those images never got a post, so they show the
+      time Curator downloaded them rather than when they were posted.
+      <strong>Apply</strong> deletes those images, clears Discord from the
+      download history, and starts a fresh backfill of every Discord source so
+      they come back with their posts and dates. Tags you added by hand to those
+      images are lost. Nothing outside a Discord <code>None</code> folder is
+      touched.
+    </p>
+
+    <div class="d-flex align-center flex-wrap" style="gap: 12px;">
+      <v-btn
+        color="primary" variant="tonal" rounded="pill"
+        :loading="previewing" :disabled="applying" @click="preview"
+      >
+        <v-icon start>mdi-magnify</v-icon> Preview
+      </v-btn>
+      <v-btn
+        color="error" rounded="pill"
+        :loading="applying"
+        :disabled="previewing || !canApply"
+        @click="confirmOpen = true"
+      >
+        <v-icon start>mdi-download-off-outline</v-icon> Apply
+      </v-btn>
+    </div>
+
+    <v-alert
+      v-if="summary" :type="summaryType" variant="tonal" class="mt-4"
+      density="comfortable"
+    >
+      <span v-if="applied">
+        Deleted {{ summary.images_deleted }} image(s) and cleared
+        {{ summary.archive_entries }} Discord download record(s). Backfills
+        started on {{ summary.backfills_started }} Discord source(s).
+      </span>
+      <span v-else-if="hasWork">
+        {{ summary.images }} broken image(s) ({{ humanBytes(summary.bytes) }})
+        across {{ summary.directories }} folder(s), and
+        {{ summary.archive_entries }} Discord download record(s) to clear.
+        {{ summary.sources }} Discord source(s) will backfill again.
+      </span>
+      <span v-else>Nothing to repair — no broken Discord downloads found.</span>
+
+      <div v-if="applied && summary.files_failed" class="mt-1 text-caption">
+        {{ summary.files_failed }} file(s) could not be removed — see the worker log.
+      </div>
+      <div v-if="applied && summary.remaining" class="mt-1 text-caption">
+        {{ summary.remaining }} broken image(s) are still present. Run it again.
+      </div>
+    </v-alert>
+
+    <QueueStatusBar queue="maintenance_long" queue-label="Maintenance" />
+
+    <v-dialog v-model="confirmOpen" max-width="440">
+      <v-card>
+        <v-card-title>Repair Discord downloads?</v-card-title>
+        <v-card-text class="text-body-2">
+          This permanently deletes <strong>{{ summary?.images ?? 0 }}</strong>
+          Discord image(s) ({{ humanBytes(summary?.bytes) }}) and re-downloads
+          them from Discord with their posts and dates. Any tags you added to
+          those images by hand will not come back.
+        </v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn variant="text" @click="confirmOpen = false">Cancel</v-btn>
+          <v-btn color="error" @click="apply">Repair</v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { computed, ref } from 'vue'
+
+import { useMaintenanceTask } from '../../composables/useMaintenanceTask.js'
+import { humanBytes } from '../../utils/bytes.js'
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+import QueueStatusBar from './QueueStatusBar.vue'
+
+const confirmOpen = ref(false)
+
+const { previewing, applying, summary, applied, preview, apply: applyTask } = useMaintenanceTask({
+  endpoint: '/api/admin/maintenance/repair-discord-downloads',
+  storageKey: 'fc.maint.repairDiscordDownloads',
+  appliedToast: 'Discord downloads cleared — backfills started',
+})
+
+// The archive count matters too: files could already be gone while gallery-dl
+// still believes it has them, which would stop the backfill re-fetching.
+const hasWork = computed(
+  () => !!summary.value && (summary.value.images > 0 || summary.value.archive_entries > 0),
+)
+const canApply = computed(() => hasWork.value && !applied.value)
+const summaryType = computed(() => {
+  if (applied.value) return 'success'
+  return hasWork.value ? 'info' : 'success'
+})
+
+// The confirm dialog gates the destructive apply; close it, then run.
+function apply () {
+  confirmOpen.value = false
+  applyTask()
+}
+</script>

frontend/src/components/settings/ImportFiltersForm.vue

@@ -10,16 +10,20 @@
       <div class="fc-phash">
         <div class="fc-phash__title">Near-duplicate sensitivity</div>
         <div class="fc-help mb-1">
-          How aggressively imports merge look-alike images (perceptual-hash
-          distance). <strong>Lower it if edits/variants of the same image are
-          being dropped as duplicates;</strong> raise it to collapse more
-          look-alikes. Applies to new imports.
+          How wide a net imports cast when looking for the same image at a
+          different resolution (perceptual-hash distance, out of 256 bits).
+          A match is only merged if the two files also share an aspect ratio
+          <em>and</em> their pixels agree, so variant artwork — a different
+          outfit, expression or overlay on the same pose — is kept even at a
+          generous setting. <strong>Raise it if higher-resolution re-uploads
+          are landing as separate copies;</strong> lower it to merge less.
+          Applies to new imports.
         </div>
         <v-row no-gutters class="align-center">
           <v-col cols="12" sm="9">
             <v-slider
               v-model="local.phash_threshold"
-              :min="0" :max="16" :step="1"
+              :min="0" :max="64" :step="1"
               :ticks="PHASH_TICKS" show-ticks="always" tick-size="4"
               thumb-label color="accent" hide-details
               class="fc-phash__slider"
@@ -139,8 +143,10 @@ const store = useImportStore()
 // instead of relying on the old tab's mount hook.
 onMounted(() => { if (!store.settings) store.loadSettings() })
 // Labelled stops so the less-initiated get the gist without knowing what a
-// Hamming distance is. 0 = byte-for-byte only; 10 = the shipped default.
-const PHASH_TICKS = { 0: 'Exact', 4: 'Strict', 10: 'Default', 16: 'Loose' }
+// Hamming distance is. 0 = an identical hash only; 24 = the shipped default.
+// Bits out of 256 (utils/phash hash_size=16). The scale changed with
+// migration 0098 — these are NOT the old 0-16 stops renamed (#4223).
+const PHASH_TICKS = { 0: 'Exact', 12: 'Strict', 24: 'Default', 48: 'Loose' }
 // Downloader + schedule-defaults fields moved to
 // /subscriptions?tab=settings (operator decision 2026-05-27). This form
 // now only owns image-import filters.
@@ -148,7 +154,7 @@ const local = reactive({
   min_width: 0, min_height: 0,
   skip_transparent: false, transparency_threshold: 0.9,
   skip_single_color: false, single_color_threshold: 0.95,
-  phash_threshold: 10,
+  phash_threshold: 24,
   wip_title_tagging_enabled: true,
   wip_soft_title_tagging_enabled: false,
 })

frontend/src/components/settings/MaintenancePanel.vue

@@ -15,6 +15,7 @@
         <ImportFiltersForm />
         <TranslationCard />
         <DiscordGroupingCard />
+        <DiscordRepairCard />
         <PostAssociationsCard />
         <MembershipRosterCard />
         <MembershipSuggestionsCard />
@@ -53,6 +54,7 @@
         Self-healing and repair: missing files, thumbnails, database upkeep.
       </p>
       <div class="fc-tile-grid">
+        <PlacementCard />
         <MissingFileRepairCard />
         <ThumbnailBackfillCard />
         <DbMaintenanceCard />
@@ -79,12 +81,14 @@ import MLBackfillCard from './MLBackfillCard.vue'
 import ThumbnailBackfillCard from './ThumbnailBackfillCard.vue'
 import ArchiveReextractCard from './ArchiveReextractCard.vue'
 import MissingFileRepairCard from './MissingFileRepairCard.vue'
+import PlacementCard from './PlacementCard.vue'
 import GpuTriageCard from './GpuTriageCard.vue'
 import DbMaintenanceCard from './DbMaintenanceCard.vue'
 import VideoEmbeddingCard from './VideoEmbeddingCard.vue'
 import CropProposersCard from './CropProposersCard.vue'
 import HeadsCard from './HeadsCard.vue'
 import DiscordGroupingCard from './DiscordGroupingCard.vue'
+import DiscordRepairCard from './DiscordRepairCard.vue'
 import MembershipRosterCard from './MembershipRosterCard.vue'
 import MembershipSuggestionsCard from './MembershipSuggestionsCard.vue'
 import PostAssociationsCard from './PostAssociationsCard.vue'

frontend/src/components/settings/PlacementCard.vue

@@ -0,0 +1,312 @@
+<template>
+  <MaintenanceTile
+    icon="mdi-folder-move"
+    title="File placement"
+    blurb="Put every image in its own artist's folder, one artist at a time."
+  >
+    <p class="fc-muted text-body-2 mb-4">
+      The library keeps one folder per artist, named after them. Files written
+      under older rules can sit in another artist's folder — this moves them
+      home, updating the record and the file together. Every run can be
+      reverted, so the safe way to use it is one artist at a time: run it,
+      look at the gallery, then continue or put it back.
+    </p>
+
+    <v-alert
+      v-if="error" type="warning" variant="tonal" density="compact" class="mb-3"
+    >{{ error }}</v-alert>
+
+    <!-- Survey -->
+    <div class="fc-settings-row mb-3">
+      <v-btn
+        variant="tonal" rounded="pill" prepend-icon="mdi-magnify"
+        :loading="surveying" @click="onSurvey"
+      >Check placement</v-btn>
+      <span v-if="layout" class="fc-muted text-body-2">
+        {{ layout.misplaced_rows.toLocaleString() }} of
+        {{ layout.total_rows.toLocaleString() }} images are in the wrong folder
+        <template v-if="layout.misplaced_rows">
+          — across {{ layout.artists.length }} artists
+        </template>
+      </span>
+    </div>
+
+    <v-table v-if="layout && layout.artists.length" density="compact" class="mb-2">
+      <thead>
+        <tr>
+          <th>Artist</th>
+          <th class="text-right">To move</th>
+          <th>Currently in</th>
+          <th class="text-right">Plan</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="a in layout.artists" :key="a.artist_id">
+          <td>{{ a.name }}</td>
+          <td class="text-right fc-tabular">{{ a.misplaced_rows.toLocaleString() }}</td>
+          <td class="fc-muted text-body-2">{{ a.stray_dirs.join(', ') }}</td>
+          <td class="text-right">
+            <v-btn
+              size="small" variant="text" :loading="planningId === a.artist_id"
+              @click="onPlan(a.artist_id)"
+            >Plan</v-btn>
+          </td>
+        </tr>
+      </tbody>
+    </v-table>
+
+    <v-divider class="my-4" />
+
+    <!-- Runs -->
+    <h3 class="fc-section-title">Runs</h3>
+    <v-table density="compact">
+      <thead>
+        <tr>
+          <th>When</th>
+          <th>Scope</th>
+          <th>Status</th>
+          <th class="text-right">Planned</th>
+          <th class="text-right">Moved</th>
+          <th class="text-right">Refused</th>
+          <th class="text-right">Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="r in store.placementRuns" :key="r.id">
+          <td class="fc-tabular" :title="r.started_at">
+            {{ formatRelative(r.started_at) }}
+          </td>
+          <td>{{ artistName(r.artist_id) }}</td>
+          <td>
+            <v-icon size="small" :color="statusColor(r.status)">
+              {{ statusIcon(r.status) }}
+            </v-icon>
+            {{ r.status }}
+          </td>
+          <td class="text-right fc-tabular">{{ r.planned_count.toLocaleString() }}</td>
+          <td class="text-right fc-tabular">{{ r.moved_count.toLocaleString() }}</td>
+          <td class="text-right fc-tabular">
+            <span :class="r.refused_count ? 'text-warning' : 'fc-muted'">
+              {{ r.refused_count.toLocaleString() }}
+            </span>
+          </td>
+          <td class="text-right">
+            <KebabMenu :label="`Actions for placement run ${r.id}`">
+              <v-list-item title="Review…" @click="onReview(r)" />
+              <v-list-item
+                title="Move files" :disabled="r.status !== 'ready' || !r.planned_count"
+                @click="onApply(r)"
+              />
+              <v-list-item
+                title="Put back…" :disabled="r.status !== 'applied'"
+                @click="onRevert(r)"
+              />
+            </KebabMenu>
+          </td>
+        </tr>
+        <tr v-if="!store.placementRuns.length">
+          <td colspan="7" class="text-center fc-muted py-4">
+            No runs yet. Check placement above, then plan one artist.
+          </td>
+        </tr>
+      </tbody>
+    </v-table>
+
+    <!-- Review: the plan, which is what gets agreed to -->
+    <v-dialog v-model="reviewOpen" max-width="900">
+      <v-card>
+        <v-card-title>
+          Run {{ reviewRun?.id }} — {{ reviewRun?.planned_count?.toLocaleString() }} moves
+        </v-card-title>
+        <v-card-text>
+          <p class="fc-muted text-body-2 mb-3">
+            Showing the first {{ REVIEW_LIMIT }}. Each row moves the file and
+            its record together; nothing is overwritten.
+          </p>
+          <v-table density="compact">
+            <tbody>
+              <tr v-for="m in reviewMoves" :key="m.image_id">
+                <td class="fc-muted text-caption">{{ m.from }}</td>
+                <td class="text-caption">→ {{ m.to }}</td>
+              </tr>
+            </tbody>
+          </v-table>
+          <div v-if="reviewRun?.refusals?.length" class="mt-4">
+            <h4 class="fc-section-title">Refused ({{ reviewRun.refusals.length }})</h4>
+            <p class="fc-muted text-body-2">
+              Rows the run declined to touch — the source moved, the
+              destination was taken, or the record changed since planning.
+            </p>
+            <div
+              v-for="f in reviewRun.refusals.slice(0, REVIEW_LIMIT)" :key="f.image_id"
+              class="text-caption fc-muted"
+            >#{{ f.image_id }} — {{ f.reason }}</div>
+          </div>
+        </v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn variant="text" @click="reviewOpen = false">Close</v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+
+    <v-dialog v-model="confirmOpen" max-width="520">
+      <v-card>
+        <v-card-title>{{ confirmTitle }}</v-card-title>
+        <v-card-text class="text-body-2">{{ confirmMessage }}</v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn variant="text" @click="confirmOpen = false">Cancel</v-btn>
+          <v-btn
+            color="accent" variant="flat" rounded="pill"
+            @click="confirmOpen = false; onConfirmed()"
+          >Go ahead</v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+
+import KebabMenu from '../common/KebabMenu.vue'
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+import { useCleanupStore } from '../../stores/cleanup.js'
+import { formatRelative } from '../../utils/date.js'
+import { toast } from '../../utils/toast.js'
+
+// A whole-library plan is tens of thousands of moves. The dialog is for
+// judging whether the moves look right, which a sample answers — the full
+// list is in the run row if anyone needs it.
+const REVIEW_LIMIT = 200
+
+const store = useCleanupStore()
+const layout = ref(null)
+const artists = ref({})
+const surveying = ref(false)
+const planningId = ref(null)
+const error = ref('')
+
+const reviewOpen = ref(false)
+const reviewRun = ref(null)
+const reviewMoves = computed(() => (reviewRun.value?.moves || []).slice(0, REVIEW_LIMIT))
+
+const confirmOpen = ref(false)
+const confirmTitle = ref('')
+const confirmMessage = ref('')
+let confirmAction = null
+
+let poll = null
+
+function artistName(id) {
+  if (id === null || id === undefined) return 'Whole library'
+  return artists.value[id] || `#${id}`
+}
+
+function statusIcon(s) {
+  return {
+    ready: 'mdi-clipboard-text-outline', applied: 'mdi-check-circle',
+    reverted: 'mdi-undo-variant', error: 'mdi-close-circle',
+    running: 'mdi-timer-sand', cancelled: 'mdi-cancel',
+  }[s] || 'mdi-help-circle'
+}
+function statusColor(s) {
+  return {
+    ready: 'accent', applied: 'success', reverted: 'info',
+    error: 'error', running: 'warning',
+  }[s] || 'grey'
+}
+
+async function guard(fn) {
+  error.value = ''
+  try {
+    return await fn()
+  } catch (e) {
+    error.value = e?.message || String(e)
+  }
+}
+
+async function onSurvey() {
+  surveying.value = true
+  try {
+    await guard(async () => { layout.value = await store.loadLayout() })
+  } finally {
+    surveying.value = false
+  }
+}
+
+async function onPlan(artistId) {
+  planningId.value = artistId
+  try {
+    await guard(async () => {
+      await store.planPlacement(artistId)
+      toast('Planning — the run appears below when it is ready')
+      await store.loadPlacementRuns()
+    })
+  } finally {
+    planningId.value = null
+  }
+}
+
+async function onReview(run) {
+  await guard(async () => {
+    reviewRun.value = await store.getPlacementRun(run.id)
+    reviewOpen.value = true
+  })
+}
+
+function ask(title, message, action) {
+  confirmTitle.value = title
+  confirmMessage.value = message
+  confirmAction = action
+  confirmOpen.value = true
+}
+
+function onApply(run) {
+  ask(
+    'Move these files?',
+    `${run.planned_count.toLocaleString()} files move into their artist's `
+    + 'folder. The record and the file move together, and this run can be '
+    + 'put back afterwards.',
+    async () => {
+      await store.applyPlacement(run.id)
+      toast('Moving files — this runs in the background')
+      await store.loadPlacementRuns()
+    },
+  )
+}
+
+function onRevert(run) {
+  ask(
+    'Put these files back?',
+    `${run.moved_count.toLocaleString()} files return to where they were `
+    + 'before this run.',
+    async () => {
+      await store.revertPlacement(run.id)
+      toast('Putting files back — this runs in the background')
+      await store.loadPlacementRuns()
+    },
+  )
+}
+
+async function onConfirmed() {
+  const action = confirmAction
+  confirmAction = null
+  if (action) await guard(action)
+}
+
+onMounted(async () => {
+  await guard(async () => {
+    artists.value = await store.loadArtistNames()
+    await store.loadPlacementRuns()
+  })
+  // Runs change state in a worker, so the table needs refreshing. The rows
+  // are server-side, which is why no localStorage resurfacing is needed here
+  // (useMaintenanceTask's job) — a reload or another machine sees the same
+  // state because the state IS the row.
+  poll = setInterval(() => { store.loadPlacementRuns().catch(() => {}) }, 5000)
+})
+
+onUnmounted(() => { if (poll) clearInterval(poll) })
+</script>

frontend/src/components/subscriptions/MembershipReconcileCard.vue

@@ -1,12 +1,20 @@
 <template>
   <!-- Renders nothing when there is nothing to say — same posture as
        NeedsAttentionCard. A reconciliation card that always shows would train
-       the operator to scroll past it. -->
-  <v-card v-if="anythingToSay" variant="tonal" class="mb-4 fc-recon">
+       the operator to scroll past it. It can also be DISMISSED, and stays
+       dismissed until what it would say changes. -->
+  <v-card v-if="visible" variant="tonal" class="mb-4 fc-recon">
     <v-card-text>
+      <v-btn
+        icon="mdi-close" size="small" variant="text" class="fc-recon__dismiss"
+        title="Hide until something changes" aria-label="Hide until something changes"
+        @click="dismiss"
+      />
       <div v-for="p in interesting" :key="p.platform" class="fc-recon__platform">
-        <!-- Bucket 1: the adoption win. The only direction with an action,
-             because adding a source is the reversible half. -->
+        <!-- The adoption win: subscriptions FC doesn't follow yet. The only
+             bucket shown. Sources you follow but no longer pay for are not
+             listed here (operator, 2026-09-13) — the membership sweep stops
+             pulling those instead (#3995). -->
         <template v-if="p.subscribed_not_tracked.length">
           <div class="fc-recon__head">
             <v-icon icon="mdi-account-plus-outline" size="small" class="me-2" />
@@ -36,37 +44,13 @@
           </div>
         </template>
 
-        <!-- Bucket 2: REPORT ONLY. No disable control here by design — the
-             source list on this same page is where that decision belongs. -->
-        <template v-if="p.tracked_not_subscribed.length">
-          <div class="fc-recon__head">
-            <v-icon icon="mdi-help-circle-outline" size="small" class="me-2" />
-            <strong>
-              {{ p.tracked_not_subscribed.length }}
-              {{ p.platform }}
-              {{ p.tracked_not_subscribed.length === 1 ? 'source' : 'sources' }}
-              your roster doesn't account for
-            </strong>
-          </div>
-          <div v-for="s in p.tracked_not_subscribed" :key="s.id" class="fc-recon__row">
-            <div class="fc-recon__body">
-              <strong>{{ s.artist.name }}</strong>
-              <div class="fc-recon__dim">{{ reasonFor(s) }}</div>
-            </div>
-          </div>
-          <div class="fc-recon__dim fc-recon__note">
-            Nothing has been changed. If you want one of these to stop checking,
-            disable it in the list below.
-          </div>
-        </template>
-
-        <!-- The roster could not be trusted, so bucket 2 was not computed. Said
-             in words: an empty list here must never read as "all clear". -->
+        <!-- The roster could not be trusted. Said in words: an empty list here
+             must never read as "all clear". -->
         <div v-if="!p.fresh" class="fc-recon__dim fc-recon__note">
           <v-icon icon="mdi-clock-alert-outline" size="small" class="me-1" />
           <template v-if="!p.last_success_at">
             Your {{ p.platform }} roster has never synced, so FC can't tell which
-            sources you still subscribe to.
+            creators you subscribe to.
           </template>
           <template v-else>
             Your {{ p.platform }} roster last synced
@@ -81,44 +65,62 @@
 </template>
 
 <script setup>
-import { computed, onMounted } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 
 import { formatRelative } from '../../utils/date.js'
 import { useMembershipReconcileStore } from '../../stores/membershipReconcile.js'
 
-// #387 C4. Two directions, deliberately unequal: subscriptions FC doesn't
-// follow get a one-click add, while sources the roster doesn't account for are
-// REPORTED ONLY (operator decision, 2026-09-11). The asymmetry is the point —
-// adding a source is trivially undone, and "you no longer subscribe to this" is
-// computed from an absence that has three possible causes.
+// #387 C4. Offers the subscriptions FC doesn't follow yet. The other direction
+// (sources FC follows that the roster says you no longer pay for) used to be
+// listed here as a report. The operator didn't want it listed (2026-09-13); the
+// membership sweep stops pulling those sources instead (#3995).
 const store = useMembershipReconcileStore()
 
 // An untrustworthy roster is only worth mentioning when there is something it
 // would have reconciled — otherwise a failed sweep on a platform with no
 // sources yet would put a warning on a page with nothing to warn about.
 const interesting = computed(() => store.platforms.filter(
-  p => p.subscribed_not_tracked.length
-    || p.tracked_not_subscribed.length
-    || (!p.fresh && p.tracked_total)
+  p => p.subscribed_not_tracked.length || (!p.fresh && p.tracked_total)
 ))
-const anythingToSay = computed(() => interesting.value.length > 0)
 
-function reasonFor (s) {
-  if (s.basis === 'lapsed') {
-    return `Your membership reads "${s.membership?.status}" — you're not a paying supporter of this creator right now.`
-  }
-  if (s.basis === 'absent_exact') {
-    return "FC knows this creator's id on the platform, and it isn't in your roster."
-  }
-  // absent_handle — the weakest claim, and it says so. A renamed creator looks
-  // exactly like this, which is why it is not phrased as a conclusion.
-  return "No membership matched this source's address. It may simply have been renamed."
+// Dismissal is keyed to WHAT the card says, not to the card: a fingerprint of
+// the offered memberships and any stale-roster warnings. Dismissing hides this
+// exact set; a new subscription (or a roster going stale) changes the
+// fingerprint and brings the card back. Per-browser, which is enough for a
+// single-operator instance.
+const DISMISS_KEY = 'fc.recon.dismissed'
+const fingerprint = computed(() => interesting.value
+  .flatMap(p => [
+    ...p.subscribed_not_tracked.map(m => `${p.platform}:${m.id}`),
+    ...(p.fresh ? [] : [`${p.platform}:stale`]),
+  ])
+  .sort()
+  .join('|'))
+
+function readDismissed () {
+  try { return localStorage.getItem(DISMISS_KEY) } catch { return null }
 }
+const dismissed = ref(readDismissed())
+
+function dismiss () {
+  dismissed.value = fingerprint.value
+  try { localStorage.setItem(DISMISS_KEY, fingerprint.value) } catch { /* private mode */ }
+}
+
+const visible = computed(
+  () => interesting.value.length > 0 && fingerprint.value !== dismissed.value,
+)
 
 onMounted(() => { store.load() })
 </script>
 
 <style scoped>
+.fc-recon { position: relative; }
+.fc-recon__dismiss {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+}
 .fc-recon__platform + .fc-recon__platform {
   margin-top: 16px;
 }

frontend/src/components/subscriptions/SourceRow.vue

@@ -39,8 +39,25 @@
       {{ formatRelative(source.next_check_at, { future: true }) }}
     </td>
     <td>
+      <!-- #3995: the membership sweep stopped this source because paid access
+           ended. First in the chain — it explains why an otherwise healthy
+           source is off. Neutral, never error: nothing is broken. -->
       <v-chip
-        v-if="(source.consecutive_failures || 0) > 0"
+        v-if="membershipStopped"
+        size="x-small" variant="tonal" label
+        prepend-icon="mdi-account-cancel-outline"
+      >Membership ended
+        <v-tooltip activator="parent" location="top" max-width="420">
+          <span>
+            Curator stopped checking this source because your membership
+            {{ membershipStopped.status ? `reads "${membershipStopped.status}"` : 'ended' }}.
+            It starts again on its own if you resubscribe. Turn it back on to
+            keep checking anyway.
+          </span>
+        </v-tooltip>
+      </v-chip>
+      <v-chip
+        v-else-if="(source.consecutive_failures || 0) > 0"
         size="x-small" color="error" variant="tonal" label
       >{{ source.consecutive_failures }}
         <!-- #1: show the actual failure reason on hover instead of a bare count. -->
@@ -109,6 +126,12 @@ const props = defineProps({
 // operator's subscription, not anything FC can retry. The count is only joined
 // in by the list endpoint, so phrase it without one when it's absent rather
 // than rendering a fabricated zero.
+// #3995: set by the membership sweep when it stops a source whose paid access
+// ended; cleared when it resumes, or when the operator toggles the source.
+const membershipStopped = computed(
+  () => props.source.config_overrides?._membership_stopped || null,
+)
+
 const noAccessTip = computed(() => {
   const n = props.source.tier_gated_count
   const what = n

frontend/src/stores/cleanup.js

@@ -71,10 +71,66 @@ export const useCleanupStore = defineStore('cleanup', () => {
     return await api.post(`/api/cleanup/audit/${id}/cancel`)
   }
 
+  // --- placement reconciler (milestone #421) --------------------------------
+  //
+  // Runs are server-side rows, so the DATABASE is the durable state here —
+  // no localStorage resurfacing (useMaintenanceTask) is needed. Reload the
+  // page, open it on another machine, and the run and its status are simply
+  // there. That also means a plan survives being walked away from for a day.
+
+  const placementRuns = ref([])
+  const layout = ref(null)
+
+  // The survey: which rows sit outside their artist's directory. check_disk
+  // additionally stats every destination (collisions, missing sources) and
+  // costs one stat per misplaced row over NFS, so it is opt-in.
+  async function loadLayout(checkDisk = false) {
+    layout.value = await api.get('/api/cleanup/layout', {
+      params: checkDisk ? { check_disk: 1 } : {},
+    })
+    return layout.value
+  }
+
+  // id -> name, so a run row can say "Conto" instead of "#47". The runs
+  // endpoint carries artist_id alone: the name belongs to the artist, and
+  // denormalising it into every run would go stale the moment one is renamed.
+  async function loadArtistNames() {
+    const rows = await api.get('/api/artists/names')
+    return Object.fromEntries((rows || []).map(a => [a.id, a.name]))
+  }
+
+  async function loadPlacementRuns(limit = 25) {
+    const body = await api.get('/api/cleanup/placement/runs', { params: { limit } })
+    placementRuns.value = body.runs || []
+    return placementRuns.value
+  }
+
+  // Detail carries `moves` — the plan the operator reads before agreeing.
+  async function getPlacementRun(id) {
+    return await api.get(`/api/cleanup/placement/runs/${id}`)
+  }
+
+  async function planPlacement(artistId = null) {
+    return await api.post('/api/cleanup/placement/plan', {
+      body: artistId === null ? {} : { artist_id: artistId },
+    })
+  }
+
+  async function applyPlacement(id) {
+    return await api.post(`/api/cleanup/placement/runs/${id}/apply`)
+  }
+
+  async function revertPlacement(id) {
+    return await api.post(`/api/cleanup/placement/runs/${id}/revert`)
+  }
+
   return {
     defaults, recentRuns,
     loadDefaults,
     previewMinDim, deleteMinDim,
     startAudit, getAudit, loadHistory, latestAuditForRule, applyAudit, cancelAudit,
+    placementRuns, layout,
+    loadLayout, loadArtistNames, loadPlacementRuns, getPlacementRun,
+    planPlacement, applyPlacement, revertPlacement,
   }
 })

frontend/src/utils/platformColor.js

@@ -1,9 +1,13 @@
 // Single source of truth for platform → color + icon mapping. Used by
-// PlatformChip and any other GS-style platform-tagged surface. The five
+// PlatformChip and any other GS-style platform-tagged surface. The four
 // platforms FC supports map 1:1 to the GS palette; unknown platforms fall
 // back to grey + mdi-web — which is deliberately what a retired platform
-// hits: a pre-#3069 deviantart source row still renders, as its raw key on
-// a grey chip. Operator-confirmed scope 2026-05-27. The ICONS key set is
+// hits: a pre-#3069 deviantart source row, or a post from pixiv (retired at
+// milestone #406), still renders, as its raw key on a grey chip. So a
+// retired platform is REMOVED from these maps, never kept "so old rows
+// look right" — the fallback is what makes old rows look right, and keeping
+// the entry would break the contract pin below. Operator-confirmed scope
+// 2026-05-27. The ICONS key set is
 // pinned against backend known_platform_keys() by
 // tests/test_fe_be_contract.py.
 
@@ -12,7 +16,6 @@ const ICONS = {
   subscribestar: 'mdi-star',
   hentaifoundry: 'mdi-palette',
   discord:       'mdi-discord',
-  pixiv:         'mdi-alpha-p-box',
 }
 
 const COLORS = {
@@ -20,7 +23,6 @@ const COLORS = {
   subscribestar: 'amber',
   hentaifoundry: 'purple',
   discord:       'indigo',
-  pixiv:         'blue',
 }
 
 const LABELS = {
@@ -28,7 +30,6 @@ const LABELS = {
   subscribestar: 'SubscribeStar',
   hentaifoundry: 'HentaiFoundry',
   discord:       'Discord',
-  pixiv:         'Pixiv',
 }
 
 export function platformIcon(platform) {

frontend/src/views/ArtistsView.vue

@@ -58,8 +58,9 @@ useInfiniteScroll(sentinelEl, () => {
 
 onMounted(async () => {
   await platformsStore.loadAll()
-  platformItems.value = (platformsStore.platforms || []).map(p => ({
-    title: p.key, value: p.key,
+  // `list` — the store has no `platforms` property (test/storeUsage.spec.js).
+  platformItems.value = platformsStore.list.map(p => ({
+    title: p.name || p.key, value: p.key,
   }))
   // Apply any deep-linked q (and load). setQuery resets + fetches.
   store.setQuery(searchTerm.value || '')

frontend/src/views/PostsView.vue

@@ -1,5 +1,8 @@
 <template>
-  <v-container class="pt-2 pb-6" max-width="900">
+  <!-- Width is set in CSS, not with `max-width` here: below 1600px it is
+       today's 900px column, and above it the feed widens and gains the day
+       gutter (milestone #407). -->
+  <v-container fluid class="pt-2 pb-6 fc-posts">
     <!-- In-context view: deep-linked to one post, with bidirectional infinite
          scroll — newer posts load above, older posts below. -->
     <template v-if="postIdFilter != null">
@@ -48,14 +51,19 @@
     </template>
 
     <!-- Normal feed -->
-    <template v-else>
-      <FeedStatusRibbon v-if="statusRibbon" />
-
-      <PostsFilterBar
-        :artist-id="artistFilter"
-        :platform="platformFilter"
-        @update:filters="onFilters"
-      />
+    <div v-else class="fc-posts__main">
+      <!-- Filters and status sit in one row above the feed. #407 option E put
+           them in a sticky left rail; the operator found it wasted space
+           (2026-09-13), so on a wide window this row lines up with the feed
+           column instead, clear of the day gutter. -->
+      <div class="fc-posts__toolbar">
+        <FeedStatusRibbon v-if="statusRibbon" class="fc-posts__status" />
+        <PostsFilterBar
+          :artist-id="artistFilter"
+          :platform="platformFilter"
+          @update:filters="onFilters"
+        />
+      </div>
 
       <v-alert v-if="store.error" type="error" variant="tonal" closable class="mb-3">
         {{ String(store.error) }}
@@ -74,14 +82,27 @@
       </div>
 
       <div v-else>
-        <PostCard v-for="p in store.items" :key="p.id" :post="p" />
+        <!-- Day groups (#407 D). The heading sits above its posts on a narrow
+             window and in a sticky left gutter on a wide one. -->
+        <section v-for="d in days" :key="d.key" class="fc-posts__day">
+          <header class="fc-posts__day-head">
+            <span class="fc-posts__day-label">{{ d.label }}</span>
+            <span class="fc-posts__day-count">
+              {{ d.posts.length }} post{{ d.posts.length === 1 ? '' : 's' }}
+              · {{ d.artistCount }} artist{{ d.artistCount === 1 ? '' : 's' }}
+            </span>
+          </header>
+          <div class="fc-posts__day-posts">
+            <PostCard v-for="p in d.posts" :key="p.id" :post="p" />
+          </div>
+        </section>
 
         <div ref="sentinel" class="fc-posts__sentinel">
           <v-progress-circular v-if="store.loading" indeterminate color="accent" size="24" />
           <span v-else-if="store.done" class="fc-posts__end">End of stream</span>
         </div>
       </div>
-    </template>
+    </div>
   </v-container>
 </template>
 
@@ -121,6 +142,48 @@ const hasActiveFilter = computed(() =>
   artistFilter.value != null || platformFilter.value != null || searchFilter.value != null
 )
 
+// --- day groups (#407 D) ---
+// CONSECUTIVE runs, not a bucket per date. The feed's sort key includes
+// `resurfaced_at` (a Discord grouping that grew moves back to the top), which
+// the payload does not carry, so a resurfaced post can sit above newer ones.
+// Bucketing by date would pull it out of order; a run gives it its own heading
+// where it actually appears. Counts cover what has LOADED, and grow as the
+// infinite scroll fetches more of the same day.
+function dayKey (iso) {
+  const d = new Date(iso)
+  return `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`
+}
+function dayLabel (iso) {
+  const d = new Date(iso)
+  const today = new Date()
+  const startOf = (x) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime()
+  const days = Math.round((startOf(today) - startOf(d)) / 86400000)
+  if (days === 0) return 'Today'
+  if (days === 1) return 'Yesterday'
+  if (days > 1 && days < 7) return d.toLocaleDateString(undefined, { weekday: 'long' })
+  const sameYear = d.getFullYear() === today.getFullYear()
+  return d.toLocaleDateString(undefined, {
+    month: 'short', day: 'numeric', ...(sameYear ? {} : { year: 'numeric' }),
+  })
+}
+const days = computed(() => {
+  const groups = []
+  for (const p of store.items) {
+    const iso = p.post_date || p.downloaded_at
+    const key = dayKey(iso)
+    let g = groups[groups.length - 1]
+    if (!g || g.dayKey !== key) {
+      // Suffix with the run index so a day that appears twice (see above)
+      // still has a unique v-for key.
+      g = { key: `${key}#${groups.length}`, dayKey: key, label: dayLabel(iso), posts: [], artists: new Set() }
+      groups.push(g)
+    }
+    g.posts.push(p)
+    if (p.artist?.id != null) g.artists.add(p.artist.id)
+  }
+  return groups.map((g) => ({ ...g, artistCount: g.artists.size }))
+})
+
 // Drop only `post_id` and stay where we are — keeps Browse's `tab=posts` (and
 // any active artist/platform scope) intact instead of resetting the surface.
 const allPostsTarget = computed(() => {
@@ -232,6 +295,61 @@ onUnmounted(() => { teardownFeed(); teardownAround() })
 </script>
 
 <style scoped>
+/* Below the breakpoint: today's layout exactly — a 900px column with the
+   filters and ribbon inline above the feed. */
+.fc-posts { max-width: 900px; }
+.fc-posts__day-head {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  padding: 4px 0 8px;
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+.fc-posts__day-label {
+  font-family: 'Fraunces', Georgia, serif;
+  font-weight: 600;
+  font-size: 1rem;
+  color: rgb(var(--v-theme-accent));
+}
+.fc-posts__day-count { font-size: 0.78rem; }
+
+/* Wide window (#407 A + D). Each day's heading moves into a sticky gutter
+   beside its posts; the column widens and the cards switch to their filmstrip
+   layout on their own (PostCard measures itself). The toolbar lines up with the
+   feed column, clear of the gutter. */
+@media (min-width: 1600px) {
+  .fc-posts { max-width: 2080px; }
+  .fc-posts__main { max-width: 2080px; margin: 0 auto; }
+  .fc-posts__toolbar {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px 24px;
+    margin-left: calc(150px + 24px);
+    margin-bottom: 8px;
+  }
+  /* Status reads after the filters on a wide row, but stays first when the
+     narrow layout stacks them (it is the front door's headline). */
+  .fc-posts__status { order: 2; padding: 0; }
+  .fc-posts__toolbar :deep(.fc-posts-filters) { padding-bottom: 0; }
+  .fc-posts__day {
+    display: grid;
+    grid-template-columns: 150px minmax(0, 1fr);
+    gap: 0 24px;
+  }
+  .fc-posts__day-head {
+    position: sticky;
+    top: calc(var(--fc-nav-h, 64px) + 16px);
+    align-self: start;
+    flex-direction: column;
+    align-items: flex-end;
+    gap: 2px;
+    padding-top: 12px;
+    text-align: right;
+  }
+  .fc-posts__day-label { font-size: 1.1rem; }
+}
+
 .fc-posts__loading,
 .fc-posts__empty {
   display: flex;

frontend/test/placement.spec.js

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useCleanupStore } from '../src/stores/cleanup.js'
+import { stubFetch } from './stubFetch.js'
+
+
+describe('placement reconciler store (milestone #421)', () => {
+  beforeEach(() => setActivePinia(createPinia()))
+  afterEach(() => vi.restoreAllMocks())
+
+  it('loadLayout leaves the disk check off by default', async () => {
+    const s = useCleanupStore()
+    let seen = ''
+    stubFetch((url) => {
+      seen = url
+      return { status: 200, body: { total_rows: 10, misplaced_rows: 2, artists: [] } }
+    })
+    await s.loadLayout()
+    // One stat per misplaced row over NFS is the cost; it must be opt-in.
+    expect(seen).not.toContain('check_disk')
+    expect(s.layout.misplaced_rows).toBe(2)
+  })
+
+  it('loadLayout asks for the disk check when requested', async () => {
+    const s = useCleanupStore()
+    let seen = ''
+    stubFetch((url) => {
+      seen = url
+      return { status: 200, body: { total_rows: 0, misplaced_rows: 0, artists: [] } }
+    })
+    await s.loadLayout(true)
+    expect(seen).toContain('check_disk=1')
+  })
+
+  it('planPlacement scopes to an artist when given one', async () => {
+    const s = useCleanupStore()
+    let sent = null
+    stubFetch((url, init) => {
+      sent = JSON.parse(init.body)
+      return { status: 202, body: { status: 'dispatched' } }
+    })
+    await s.planPlacement(47)
+    expect(sent).toEqual({ artist_id: 47 })
+  })
+
+  it('planPlacement sends no scope for the whole library', async () => {
+    const s = useCleanupStore()
+    let sent = null
+    stubFetch((url, init) => {
+      sent = JSON.parse(init.body)
+      return { status: 202, body: { status: 'dispatched' } }
+    })
+    await s.planPlacement()
+    // Not `{artist_id: null}` — the endpoint rejects a non-integer, and an
+    // absent key is how "whole library" is spelled.
+    expect(sent).toEqual({})
+  })
+
+  it('loadPlacementRuns keeps the rows for the table', async () => {
+    const s = useCleanupStore()
+    stubFetch(() => ({
+      status: 200,
+      body: { runs: [{ id: 3, status: 'ready', planned_count: 12 }] },
+    }))
+    await s.loadPlacementRuns()
+    expect(s.placementRuns).toHaveLength(1)
+    expect(s.placementRuns[0].status).toBe('ready')
+  })
+
+  it('getPlacementRun carries the moves — it is the preview', async () => {
+    const s = useCleanupStore()
+    stubFetch(() => ({
+      status: 200,
+      body: {
+        id: 3, status: 'ready', planned_count: 1,
+        moves: [{ image_id: 9, from: '/images/Conto/x.png', to: '/images/conto/x.png' }],
+      },
+    }))
+    const run = await s.getPlacementRun(3)
+    expect(run.moves[0].from).toBe('/images/Conto/x.png')
+    expect(run.moves[0].to).toBe('/images/conto/x.png')
+  })
+
+  it('loadArtistNames maps id to name for the run rows', async () => {
+    const s = useCleanupStore()
+    stubFetch(() => ({
+      status: 200,
+      body: [{ id: 47, name: 'Conto', slug: 'conto' }],
+    }))
+    expect(await s.loadArtistNames()).toEqual({ 47: 'Conto' })
+  })
+
+  it('loadArtistNames survives an empty roster', async () => {
+    const s = useCleanupStore()
+    stubFetch(() => ({ status: 200, body: [] }))
+    expect(await s.loadArtistNames()).toEqual({})
+  })
+
+  it('applyPlacement and revertPlacement post to their own run', async () => {
+    const s = useCleanupStore()
+    const urls = []
+    stubFetch((url) => {
+      urls.push(url)
+      return { status: 202, body: { status: 'dispatched' } }
+    })
+    await s.applyPlacement(5)
+    await s.revertPlacement(5)
+    expect(urls[0]).toContain('/api/cleanup/placement/runs/5/apply')
+    expect(urls[1]).toContain('/api/cleanup/placement/runs/5/revert')
+  })
+})

frontend/test/storeUsage.spec.js

@@ -0,0 +1,63 @@
+// Reads of a store property that does not exist.
+//
+// JavaScript returns `undefined` for a missing property instead of failing, and
+// the frontend CI has no type-checker to catch it. `platformsStore.platforms`
+// was read for months by the Latest feed's filter bar and the Artists view. The
+// store exposes `list` and `byKey`, so both platform dropdowns opened empty and
+// only someone clicking them noticed.
+//
+// This scans the source for `platformsStore.<name>` and checks each name
+// against what the store really defines.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createPinia, setActivePinia } from 'pinia'
+import { describe, expect, it } from 'vitest'
+
+import { usePlatformsStore } from '../src/stores/platforms.js'
+
+const SRC = fileURLToPath(new URL('../src', import.meta.url))
+const READ = /\bplatformsStore\.([A-Za-z_$][\w$]*)/g
+
+function sourceFiles (dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) return sourceFiles(path)
+    return /\.(vue|js)$/.test(name) ? [path] : []
+  })
+}
+
+function unknownReads (text, known) {
+  return [...text.matchAll(READ)].map(m => m[1]).filter(name => !known.has(name))
+}
+
+function storeKeys () {
+  setActivePinia(createPinia())
+  return new Set(Object.keys(usePlatformsStore()))
+}
+
+describe('platforms store usage', () => {
+  it('every platformsStore.<name> read in src names something the store defines', () => {
+    const known = storeKeys()
+    const offenders = sourceFiles(SRC).flatMap((file) =>
+      unknownReads(readFileSync(file, 'utf8'), known)
+        .map(name => `${file.slice(SRC.length + 1)}: platformsStore.${name}`),
+    )
+    expect(offenders).toEqual([])
+  })
+
+  it('the scan finds the read that shipped broken (positive control)', () => {
+    const known = storeKeys()
+    expect(known.has('list')).toBe(true)
+    expect(unknownReads('(platformsStore.platforms || []).map(p => p)', known))
+      .toEqual(['platforms'])
+  })
+
+  it('the scan actually walks the source tree', () => {
+    const hasRead = /\bplatformsStore\./
+    const withReads = sourceFiles(SRC).filter(f => hasRead.test(readFileSync(f, 'utf8')))
+    expect(withReads.length).toBeGreaterThan(2)
+  })
+})

frontend/test/stubFetch.js

@@ -0,0 +1,24 @@
+import { vi } from 'vitest'
+
+// The canonical fetch stub for store specs.
+//
+// `handler(url, init)` returns `{ status, body }`; body is JSON-encoded, and
+// `ok` is derived from the status so a store's error path can be exercised by
+// returning 4xx/5xx. Returns the vi.fn so a caller can assert on calls.
+//
+// Extracted 2026-09-21 from six specs carrying byte-identical copies
+// (adminStore, credentials, dbMaintenance, gallery, suggestions,
+// galleryRelatedStrip). Those still hold their own; migrate each the next
+// time it is touched rather than in one sweep.
+export function stubFetch (handler) {
+  globalThis.fetch = vi.fn(async (url, init) => {
+    const { status, body } = handler(url, init)
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      statusText: String(status),
+      text: async () => (body == null ? '' : JSON.stringify(body)),
+    }
+  })
+  return globalThis.fetch
+}

scripts/phash_gate_report.py

@@ -0,0 +1,197 @@
+"""What the near-duplicate gates would decide about a folder of real artwork.
+
+Read-only. Opens image files, touches no database, imports nothing from the
+app but `utils/phash.py` itself — so what it reports is what the importer
+would actually do, not a re-implementation that could drift from it.
+
+## Why this exists
+
+Issue #4223 replaced a single 64-bit pHash comparison with three gates
+(threshold -> aspect ratio -> pixel confirm). The threshold is the operator's
+dial and the aspect tolerance mirrors the video path, but the three pixel
+constants — FINGERPRINT_MAX_MEAN_DIFF, FINGERPRINT_CHANGED_LEVEL,
+FINGERPRINT_MAX_CHANGED_FRACTION — were chosen without ever measuring real
+artwork, because FC verifies in CI and CI has only synthetic fixtures. This
+prints the measurements those constants should have been chosen from.
+
+Point it at a folder whose right answer you already know — a variant set that
+should stay whole, or an image you have at two resolutions that should
+collapse — and read the MARGIN column. A pair that lands just inside a limit
+is the one that will flip on the next slightly-different file.
+
+## Usage
+
+    python scripts/phash_gate_report.py <dir> [--threshold N] [--recursive]
+    python scripts/phash_gate_report.py <file_a> <file_b> [...]
+
+No local Python environment needed — run it inside the published image, which
+already has PIL and imagehash, with the folder mounted read-only:
+
+    docker run --rm --entrypoint python -e PYTHONPATH=/app \
+      -v /path/to/art:/data:ro -v "$PWD/scripts":/scripts:ro \
+      git.fabledsword.com/bvandeusen/fabledcurator:dev \
+      /scripts/phash_gate_report.py /data
+
+(The image ships `backend/` at /app but not `scripts/`, hence the second
+mount and PYTHONPATH. The `:ro` on the art folder is the point — this reads.)
+
+`:dev` is the rolling channel this branch publishes to (rule 147) — the same
+bytes that would run in the app, without merging anything to main.
+"""
+
+import argparse
+import itertools
+import sys
+from pathlib import Path
+
+import imagehash
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from backend.app.utils.phash import (  # noqa: E402
+    ASPECT_TOL,
+    FINGERPRINT_MAX_CHANGED_FRACTION,
+    FINGERPRINT_MAX_MEAN_DIFF,
+    HASH_SIZE,
+    aspect_matches,
+    compute_phash,
+    find_similar,
+    fingerprint,
+    fingerprint_diff,
+    fingerprints_match,
+)
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tif", ".tiff"}
+DEFAULT_THRESHOLD = 24
+
+
+class Shot:
+    """One image, measured once."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self.phash = None
+        self.width = 0
+        self.height = 0
+        self.fingerprint = None
+        self.error = None
+        try:
+            with Image.open(path) as im:
+                self.width, self.height = im.size
+                self.phash = compute_phash(im)
+                self.fingerprint = fingerprint(im)
+        except Exception as exc:
+            self.error = str(exc)
+
+    @property
+    def ok(self) -> bool:
+        return self.phash is not None and self.fingerprint is not None
+
+    @property
+    def label(self) -> str:
+        return f"{self.path.name} ({self.width}x{self.height})"
+
+
+def collect(paths, recursive: bool) -> list[Path]:
+    found: list[Path] = []
+    for p in paths:
+        p = Path(p)
+        if p.is_dir():
+            walk = p.rglob("*") if recursive else p.glob("*")
+            found += sorted(f for f in walk if f.suffix.lower() in IMAGE_EXTS)
+        elif p.is_file():
+            found.append(p)
+    return found
+
+
+def verdict(a: Shot, b: Shot, threshold: int) -> tuple[str, str]:
+    """Run the REAL find_similar for "a is being imported, b is in the
+    library". Returns (verdict, the gate that decided it)."""
+    rel, _ = find_similar(
+        a.phash, a.width, a.height,
+        [(b.phash, b.width, b.height, 1)],
+        threshold,
+        confirm=lambda _: fingerprints_match(a.fingerprint, b.fingerprint),
+    )
+    if rel == "larger_exists":
+        return ("DROP", f"{a.path.name} dropped; {b.path.name} kept (>= in both)")
+    if rel == "smaller_exists":
+        return ("SUPERSEDE", f"{a.path.name} replaces {b.path.name}'s file")
+    # Not a match — say which gate refused, cheapest first, since that is the
+    # constant to move if the answer is wrong.
+    dist = imagehash.hex_to_hash(a.phash) - imagehash.hex_to_hash(b.phash)
+    if dist > threshold:
+        return ("KEEP BOTH", f"hash distance {dist} > threshold {threshold}")
+    if not aspect_matches(a.width, a.height, b.width, b.height):
+        return ("KEEP BOTH", "aspect ratios differ")
+    return ("KEEP BOTH", "pixels differ")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("paths", nargs="+", help="a directory, or two or more files")
+    ap.add_argument("--threshold", type=int, default=DEFAULT_THRESHOLD,
+                    help=f"phash_threshold to simulate (default {DEFAULT_THRESHOLD})")
+    ap.add_argument("--recursive", action="store_true", help="walk subdirectories")
+    ap.add_argument("--limit", type=int, default=60,
+                    help="refuse more than this many images (pairs grow as N^2)")
+    args = ap.parse_args()
+
+    files = collect(args.paths, args.recursive)
+    if len(files) < 2:
+        print(f"Need at least 2 images; found {len(files)}.", file=sys.stderr)
+        return 2
+    if len(files) > args.limit:
+        print(
+            f"{len(files)} images would be {len(files) * (len(files) - 1) // 2} "
+            f"pairs. Narrow the folder or raise --limit.", file=sys.stderr
+        )
+        return 2
+
+    print(f"hash_size={HASH_SIZE} ({HASH_SIZE * HASH_SIZE} bits)  "
+          f"threshold={args.threshold}  aspect_tol={ASPECT_TOL}")
+    print(f"pixel limits: mean <= {FINGERPRINT_MAX_MEAN_DIFF}, "
+          f"changed <= {FINGERPRINT_MAX_CHANGED_FRACTION:.1%}\n")
+
+    shots = [Shot(f) for f in files]
+    for s in shots:
+        if not s.ok:
+            print(f"  ! unreadable, excluded: {s.path.name} — {s.error}")
+    shots = [s for s in shots if s.ok]
+    if len(shots) < 2:
+        print("Not enough readable images.", file=sys.stderr)
+        return 2
+
+    print(f"{'verdict':<10} {'dist':>5} {'mean':>7} {'changed':>8}  pair")
+    print("-" * 78)
+    counts: dict[str, int] = {}
+    rows = []
+    for a, b in itertools.combinations(shots, 2):
+        v, why = verdict(a, b, args.threshold)
+        counts[v] = counts.get(v, 0) + 1
+        dist = imagehash.hex_to_hash(a.phash) - imagehash.hex_to_hash(b.phash)
+        measured = fingerprint_diff(a.fingerprint, b.fingerprint)
+        mean, changed = measured if measured else (float("nan"), float("nan"))
+        rows.append((v, dist, mean, changed, a, b, why))
+
+    # Closest pairs first: the interesting decisions are the near-misses at
+    # both limits, not the obvious strangers at the bottom of the list.
+    for v, dist, mean, changed, a, b, why in sorted(rows, key=lambda r: r[1]):
+        print(f"{v:<10} {dist:>5} {mean:>7.2f} {changed:>7.2%}  "
+              f"{a.label} vs {b.label}")
+        print(f"{'':<10} {'':>5} {'':>7} {'':>8}  -> {why}")
+
+    print("\n" + "  ".join(f"{k}: {n}" for k, n in sorted(counts.items())))
+    print(
+        "\nRead the margin, not just the verdict. A pair you consider the SAME "
+        f"image should sit far under mean {FINGERPRINT_MAX_MEAN_DIFF} / changed "
+        f"{FINGERPRINT_MAX_CHANGED_FRACTION:.0%}; a pair you consider DIFFERENT "
+        "artwork\nshould sit far over. Anything that only just cleared a limit "
+        "is what will flip on the next file, and is the reason to move a constant."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/fixtures/discord_attachment_sidecar.json

@@ -0,0 +1,28 @@
+{
+  "author": "example-artist",
+  "author_files": [],
+  "author_id": "100000000000000001",
+  "category": "discord",
+  "channel": "nsfw-drops",
+  "channel_id": "200000000000000002",
+  "channel_topic": "",
+  "channel_type": 0,
+  "date": "2024-07-16 16:43:23",
+  "extension": "png",
+  "filename": "image",
+  "files": [],
+  "is_thread": false,
+  "message": "",
+  "message_id": "300000000000000003",
+  "num": 1,
+  "owner_id": "100000000000000001",
+  "parent": "",
+  "parent_id": "",
+  "parent_type": 0,
+  "server": "Example Server",
+  "server_files": [],
+  "server_id": "400000000000000004",
+  "subcategory": "channel",
+  "type": "attachment",
+  "url": "https://cdn.discordapp.com/attachments/200000000000000002/500000000000000005/image.png"
+}

tests/test_api_artists_create.py

@@ -72,3 +72,16 @@ async def test_patch_rename_validation(client):
         f"/api/artists/{created['id']}", json={})).status_code == 400
     assert (await client.patch(
         "/api/artists/999999", json={"name": "Ghost"})).status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_names_lists_every_artist_alphabetically(client):
+    """The Latest feed's artist filter shows this list before anything is typed.
+    `autocomplete` stays empty for an empty query; this is the full list."""
+    for name in ("zed", "Alice", "bob"):
+        await client.post("/api/artists", json={"name": name})
+    resp = await client.get("/api/artists/names")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert [a["name"] for a in body] == ["Alice", "bob", "zed"]
+    assert set(body[0]) == {"id", "name", "slug"}

tests/test_api_placement.py

@@ -0,0 +1,167 @@
+"""The placement reconciler's task + API surface (milestone #421, slice 3b).
+
+The move logic itself is covered in tests/test_library_layout.py; this module
+covers the wrapper — that the tasks are registered and routed, that the
+endpoints gate on run state, and that a list response stays small.
+"""
+
+import pytest
+from sqlalchemy import select
+
+import backend.app.tasks.library_placement  # noqa: F401 — register tasks
+from backend.app.celery_app import celery
+from backend.app.models import Artist, LibraryPlacementRun
+
+pytestmark = pytest.mark.integration
+
+_TASKS = (
+    "backend.app.tasks.library_placement.plan_placement",
+    "backend.app.tasks.library_placement.apply_placement",
+    "backend.app.tasks.library_placement.revert_placement",
+)
+
+
+@pytest.mark.parametrize("name", _TASKS)
+def test_placement_tasks_are_registered(name):
+    assert name in celery.tasks
+
+
+def test_placement_runs_on_the_long_maintenance_lane():
+    """33k renames must not sit in the quick lane, which is where the
+    self-healing sweeps live (the 2026-06-07 starvation)."""
+    routes = celery.conf.task_routes
+    assert routes["backend.app.tasks.library_placement.*"] == {
+        "queue": "maintenance_long"
+    }
+
+
+def _run(db, status="ready", moves=None, artist_id=None):
+    """Adds the row; the caller awaits the COMMIT.
+
+    Commit, not flush: the app under test runs on its own session and
+    connection, so a flush that stays inside this test's transaction is
+    invisible to the endpoint — the row simply is not there yet. Same reason
+    `_seed_runs` in test_api_system_backup commits."""
+    run = LibraryPlacementRun(
+        status=status, artist_id=artist_id, moves=moves or [],
+        planned_count=len(moves or []),
+    )
+    db.add(run)
+    return run
+
+
+@pytest.mark.asyncio
+async def test_runs_list_omits_the_moves(client, db):
+    """An applied whole-library run carries tens of thousands of entries.
+    Fine in Postgres, wrong in every list response."""
+    run = LibraryPlacementRun(
+        status="applied",
+        moves=[{"image_id": 1, "from": "/images/A/x.png", "to": "/images/a/x.png"}],
+        planned_count=1, moved_count=1,
+    )
+    db.add(run)
+    await db.commit()
+
+    resp = await client.get("/api/cleanup/placement/runs")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["runs"][0]["planned_count"] == 1
+    assert "moves" not in body["runs"][0]
+
+
+@pytest.mark.asyncio
+async def test_run_detail_carries_the_moves(client, db):
+    """The detail IS the preview the operator reads before agreeing."""
+    run = LibraryPlacementRun(
+        status="ready",
+        moves=[{"image_id": 7, "from": "/images/Conto/x.png", "to": "/images/conto/x.png"}],
+        planned_count=1,
+    )
+    db.add(run)
+    await db.commit()
+
+    resp = await client.get(f"/api/cleanup/placement/runs/{run.id}")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["moves"][0]["from"] == "/images/Conto/x.png"
+    assert body["moves"][0]["to"] == "/images/conto/x.png"
+
+
+@pytest.mark.asyncio
+async def test_run_detail_404s_for_an_unknown_run(client):
+    resp = await client.get("/api/cleanup/placement/runs/999999")
+    assert resp.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_plan_rejects_a_non_integer_artist(client):
+    resp = await client.post(
+        "/api/cleanup/placement/plan", json={"artist_id": "conto"},
+    )
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "invalid_artist_id"
+
+
+@pytest.mark.asyncio
+async def test_plan_accepts_an_artist_scope(client, db, monkeypatch):
+    sent = {}
+    from backend.app.tasks import library_placement
+
+    monkeypatch.setattr(
+        library_placement.plan_placement, "delay",
+        lambda artist_id=None: sent.update(artist_id=artist_id),
+    )
+    artist = Artist(name="Conto", slug="conto")
+    db.add(artist)
+    await db.commit()
+
+    resp = await client.post(
+        "/api/cleanup/placement/plan", json={"artist_id": artist.id},
+    )
+    assert resp.status_code == 202
+    assert sent["artist_id"] == artist.id
+
+
+@pytest.mark.asyncio
+async def test_apply_refuses_a_run_that_is_not_ready(client, db):
+    """The gate is here as well as in the service — an applied run must not
+    be re-applied by a stray POST."""
+    run = _run(db, status="applied")
+    await db.commit()
+
+    resp = await client.post(f"/api/cleanup/placement/runs/{run.id}/apply")
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "not_ready"
+
+
+@pytest.mark.asyncio
+async def test_revert_refuses_a_run_that_was_never_applied(client, db):
+    run = _run(db, status="ready")
+    await db.commit()
+
+    resp = await client.post(f"/api/cleanup/placement/runs/{run.id}/revert")
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "not_applied"
+
+
+@pytest.mark.asyncio
+async def test_apply_dispatches_for_a_ready_run(client, db, monkeypatch):
+    sent = {}
+    from backend.app.tasks import library_placement
+
+    monkeypatch.setattr(
+        library_placement.apply_placement, "delay",
+        lambda run_id: sent.update(run_id=run_id),
+    )
+    run = _run(db, status="ready")
+    await db.commit()
+
+    resp = await client.post(f"/api/cleanup/placement/runs/{run.id}/apply")
+    assert resp.status_code == 202
+    assert sent["run_id"] == run.id
+    # Dispatch only — the endpoint must not have moved anything itself.
+    still = (await db.execute(
+        select(LibraryPlacementRun.status)
+        .where(LibraryPlacementRun.id == run.id)
+    )).scalar_one()
+    assert still == "ready"

tests/test_api_settings.py

@@ -258,7 +258,7 @@ async def test_patch_rejects_non_object(client):
 async def test_import_settings_phash_threshold_default(client):
     resp = await client.get("/api/settings/import")
     assert resp.status_code == 200
-    assert (await resp.get_json())["phash_threshold"] == 10
+    assert (await resp.get_json())["phash_threshold"] == 24
 
 
 @pytest.mark.asyncio

tests/test_backup_service.py

@@ -134,6 +134,29 @@ def test_backup_images_excludes_backups_and_quarantine(tmp_path, fake_subprocess
     assert any("_quarantine" in e for e in excludes)
 
 
+def test_backup_images_excludes_credentials(tmp_path, fake_subprocess):
+    """#4234: the images tarball carried `secrets/credential_key.b64` — the key
+    that decrypts the stored session cookies — and `cookies/` itself. A media
+    archive must not be a credential leak; encryption at rest is worth nothing
+    if the key travels with the data."""
+    backup_service.backup_images(images_root=tmp_path)
+    excludes = [a for a in fake_subprocess[0] if a.startswith("--exclude=")]
+    assert any(e.endswith("/secrets") for e in excludes)
+    assert any(e.endswith("/cookies") for e in excludes)
+
+
+def test_backup_images_excludes_are_root_relative(tmp_path, fake_subprocess):
+    """tar matches --exclude against the archived path, which is prefixed with
+    the root's own directory name (`-C <parent> <name>`). A bare `secrets`
+    would also match an ARTIST folder called secrets; the prefix is what keeps
+    the exclusion to the top level."""
+    backup_service.backup_images(images_root=tmp_path)
+    excludes = [a for a in fake_subprocess[0] if a.startswith("--exclude=")]
+    assert excludes and all(
+        e.startswith(f"--exclude={tmp_path.name}/") for e in excludes
+    )
+
+
 # --- restore_db ------------------------------------------------------
 
 

tests/test_discord_repair.py

@@ -0,0 +1,170 @@
+"""The Discord repair (#3999): forget the broken downloads, delete them, backfill again.
+
+The danger in a repair like this is reach. It deletes files and clears
+gallery-dl's memory of what it fetched, so most of these tests pin what it must
+NOT touch: other platforms' archive entries, Discord server assets, images
+outside a `discord/None/` folder, and a correctly named Discord file that
+happens to share a folder name.
+"""
+
+import sqlite3
+
+import pytest
+from sqlalchemy import func, select
+
+from backend.app.models import Artist, ImageRecord, Source
+from backend.app.services import discord_repair
+from backend.app.services.gallery_dl import archive_path
+from backend.app.services.source_service import BACKFILL_MAX_CHUNKS
+
+
+def _archive(tmp_path, entries):
+    path = archive_path(tmp_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    # The table gallery-dl itself creates (gallery_dl/archive.py).
+    conn.execute("CREATE TABLE archive (entry TEXT PRIMARY KEY) WITHOUT ROWID")
+    conn.executemany("INSERT INTO archive (entry) VALUES (?)", [(e,) for e in entries])
+    conn.commit()
+    conn.close()
+    return path
+
+
+def _entries(path):
+    conn = sqlite3.connect(path)
+    try:
+        return sorted(r[0] for r in conn.execute("SELECT entry FROM archive"))
+    finally:
+        conn.close()
+
+
+# --- the archive ------------------------------------------------------------
+
+
+def test_only_discord_message_entries_are_forgotten(tmp_path):
+    path = _archive(tmp_path, [
+        "discord300000000000000003_1",
+        "discord300000000000000004_2",
+        "discordasset_400000000000000004_9",
+        "hentaifoundry12345",
+    ])
+    assert discord_repair.count_archive_entries(path) == 2
+    assert discord_repair.forget_archive_entries(path) == 2
+    assert _entries(path) == ["discordasset_400000000000000004_9", "hentaifoundry12345"]
+
+
+def test_counting_changes_nothing(tmp_path):
+    path = _archive(tmp_path, ["discord1_1", "discord2_1"])
+    discord_repair.count_archive_entries(path)
+    assert _entries(path) == ["discord1_1", "discord2_1"]
+
+
+def test_a_missing_archive_or_table_is_zero_not_an_error(tmp_path):
+    assert discord_repair.count_archive_entries(tmp_path / "nope.sqlite3") == 0
+    empty = tmp_path / "empty.sqlite3"
+    sqlite3.connect(empty).close()
+    assert discord_repair.forget_archive_entries(empty) == 0
+
+
+# --- the folders ------------------------------------------------------------
+
+
+def test_broken_directories_finds_every_artist_folder_including_case_twins(tmp_path):
+    for artist in ("Conto", "conto", "knuxy"):
+        (tmp_path / artist / "discord" / "None").mkdir(parents=True)
+    (tmp_path / "conto" / "discord" / "general").mkdir(parents=True)
+    (tmp_path / "conto" / "patreon" / "None").mkdir(parents=True)
+    found = [
+        p.relative_to(tmp_path).as_posix()
+        for p in discord_repair.broken_directories(tmp_path)
+    ]
+    assert found == ["Conto/discord/None", "conto/discord/None", "knuxy/discord/None"]
+
+
+def test_sweep_removes_leftover_sidecars_and_the_empty_folder(tmp_path):
+    d = tmp_path / "conto" / "discord" / "None"
+    d.mkdir(parents=True)
+    (d / "image.json").write_text("{}")
+    (d / "20240716_None_rejected.png").write_bytes(b"x")
+    removed, gone = discord_repair._sweep_directory(d)
+    assert (removed, gone) == (2, True)
+    assert not d.exists()
+
+
+# --- the whole repair, against the database -----------------------------------
+
+
+def _image(db_sync, artist, path, sha):
+    img = ImageRecord(
+        artist_id=artist.id, path=str(path), sha256=sha * 64, size_bytes=100,
+        mime="image/png", origin="downloaded",
+    )
+    db_sync.add(img)
+    return img
+
+
+@pytest.mark.integration
+def test_repair_deletes_only_broken_discord_images_and_rearms_discord_backfills(
+    db_sync, tmp_path,
+):
+    artist = Artist(name="Conto", slug="conto")
+    db_sync.add(artist)
+    db_sync.flush()
+    discord = Source(
+        artist_id=artist.id, platform="discord", url="https://discord.com/channels/1/2",
+        enabled=True, config_overrides={"_backfill_state": "complete", "_backfill_cursor": "x"},
+    )
+    patreon = Source(
+        artist_id=artist.id, platform="patreon", url="https://www.patreon.com/conto",
+        enabled=True, config_overrides={},
+    )
+    db_sync.add_all([discord, patreon])
+
+    broken_dir = tmp_path / "conto" / "discord" / "None"
+    good_dir = tmp_path / "conto" / "discord" / "general"
+    patreon_dir = tmp_path / "conto" / "patreon" / "None"
+    for d in (broken_dir, good_dir, patreon_dir):
+        d.mkdir(parents=True)
+    broken = broken_dir / "20240716_None_image.png"
+    good = good_dir / "20240716_300000000000000003_01_image.png"
+    # A `None` folder under another platform, and a `_None_` name outside one.
+    # Neither is the bug's pair, so neither may be touched.
+    elsewhere = patreon_dir / "20240716_None_image.png"
+    for f in (broken, good, elsewhere):
+        f.write_bytes(b"x")
+    (broken_dir / "image.json").write_text("{}")
+    _image(db_sync, artist, broken, "a")
+    _image(db_sync, artist, good, "b")
+    _image(db_sync, artist, elsewhere, "c")
+    db_sync.commit()
+    _archive(tmp_path, ["discord300000000000000003_1", "hentaifoundry1"])
+
+    preview = discord_repair.repair_discord_downloads(db_sync, images_root=tmp_path, dry_run=True)
+    assert preview["images"] == 1
+    assert preview["archive_entries"] == 1
+    assert broken.exists()
+
+    result = discord_repair.repair_discord_downloads(db_sync, images_root=tmp_path, dry_run=False)
+    assert result["images_deleted"] == 1
+    assert result["remaining"] == 0
+    assert result["backfills_started"] == 1
+
+    assert not broken.exists() and not broken_dir.exists()
+    assert good.exists() and elsewhere.exists()
+    assert _entries(archive_path(tmp_path)) == ["hentaifoundry1"]
+
+    kept = db_sync.execute(select(func.count(ImageRecord.id))).scalar_one()
+    assert kept == 2
+
+    rows = {
+        platform: (runs, overrides)
+        for platform, runs, overrides in db_sync.execute(
+            select(Source.platform, Source.backfill_runs_remaining, Source.config_overrides)
+        ).all()
+    }
+    runs, overrides = rows["discord"]
+    assert runs == BACKFILL_MAX_CHUNKS
+    assert overrides["_backfill_state"] == "running"
+    assert "_backfill_cursor" not in overrides
+    # Only Discord sources are re-armed.
+    assert rows["patreon"][1] == {}

tests/test_gallery_dl_naming.py

@@ -0,0 +1,117 @@
+"""gallery-dl naming patterns, rendered against the metadata gallery-dl really emits.
+
+gallery-dl does not fail on a format field that names a key the extractor never
+sets. It renders "None" and carries on. That is how every Discord download
+landed in a `None/` directory as `<date>_None_<name>`: the patterns asked for
+`{channel[name]}` and `{id}`, and the real metadata has a string `channel` and
+`message_id`, with no `id` at all. The mismatch also broke sidecar pairing, so
+no Discord file ever got a Post or a post date.
+
+The fixture keeps the key set and value TYPES of a real attachment sidecar from
+the operator's instance (2026-09-13), with every value invented. Rendering
+through Python's own formatter raises on a missing key or a subscript into a
+string, which is the loud failure gallery-dl does not give.
+"""
+
+import json
+import string
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+from backend.app.services.gallery_dl import (
+    DISCORD_DIRECTORY,
+    DISCORD_FILENAME,
+    GalleryDLService,
+    SourceConfig,
+    sidecar_name_for,
+)
+from backend.app.utils.sidecar import find_sidecar
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "discord_attachment_sidecar.json"
+
+
+@pytest.fixture
+def kwdict():
+    data = json.loads(_FIXTURE.read_text())
+    # gallery-dl hands the formatter a datetime; the JSON sidecar stores it as text.
+    data["date"] = datetime.strptime(data["date"], "%Y-%m-%d %H:%M:%S")
+    return data
+
+
+def _render(pattern, kwdict):
+    return string.Formatter().vformat(pattern, (), kwdict)
+
+
+def test_the_discord_filename_renders_from_real_keys(kwdict):
+    name = _render(DISCORD_FILENAME, kwdict)
+    assert "None" not in name
+    assert name == "20240716_300000000000000003_01_image.png"
+
+
+def test_the_discord_directory_renders_from_real_keys(kwdict):
+    assert [_render(p, kwdict) for p in DISCORD_DIRECTORY] == ["nsfw-drops"]
+
+
+@pytest.mark.parametrize(
+    "broken", ["{channel[name]}", "{date:%Y%m%d}_{id}_{filename}.{extension}"],
+)
+def test_the_patterns_that_shipped_would_have_failed_here(kwdict, broken):
+    """Positive control: the two patterns that produced `None/..._None_...`
+    must fail this renderer, or the tests above prove nothing."""
+    with pytest.raises((KeyError, TypeError)):
+        _render(broken, kwdict)
+
+
+def test_the_sidecar_is_named_exactly_like_its_media(kwdict, tmp_path):
+    """So `find_sidecar` pairs them on its first candidate, and two attachments
+    that share an original name (`image.png`) can never share a sidecar."""
+    media = tmp_path / _render(DISCORD_FILENAME, kwdict)
+    sidecar = tmp_path / _render(sidecar_name_for(DISCORD_FILENAME), kwdict)
+    media.write_bytes(b"x")
+    sidecar.write_text("{}")
+    assert find_sidecar(media) == sidecar
+
+
+def test_two_attachments_with_the_same_original_name_get_distinct_sidecars(kwdict):
+    other = {**kwdict, "message_id": "300000000000000099"}
+    pattern = sidecar_name_for(DISCORD_FILENAME)
+    assert _render(pattern, kwdict) != _render(pattern, other)
+
+
+def test_sidecar_name_for_needs_an_extension_suffix():
+    assert sidecar_name_for("{a}_{b}.{extension}") == "{a}_{b}.json"
+    assert sidecar_name_for("{a}_{b}") is None
+
+
+# --- the config gallery-dl is actually given -----------------------------------
+
+
+@pytest.fixture
+def gdl(tmp_path):
+    return GalleryDLService(images_root=tmp_path / "images", validate_files=False)
+
+
+def _discord_section(gdl, **overrides):
+    cfg = gdl._build_config_for_source(
+        platform="discord", source_config=SourceConfig(**overrides), artist_slug="a",
+    )
+    return cfg["extractor"]["discord"]
+
+
+def test_discord_config_carries_the_mirrored_sidecar(gdl):
+    section = _discord_section(gdl)
+    assert section["filename"] == DISCORD_FILENAME
+    assert section["directory"] == DISCORD_DIRECTORY
+    assert section["postprocessors"][0]["filename"] == sidecar_name_for(DISCORD_FILENAME)
+
+
+def test_a_filename_override_keeps_the_sidecar_mirrored(gdl):
+    section = _discord_section(gdl, filename_pattern="{message_id}_{num}.{extension}")
+    assert section["postprocessors"][0]["filename"] == "{message_id}_{num}.json"
+
+
+def test_no_metadata_means_no_discord_postprocessor(gdl):
+    section = _discord_section(gdl, save_metadata=False)
+    assert "postprocessors" not in section

tests/test_gallery_similar.py

@@ -146,12 +146,17 @@ async def test_similar_collapses_near_duplicate_phashes(db):
     dupes = []
     for n in range(2, 7):                       # 5 near-identical reposts
         r = await _img(db, n, _vec(1, 0.01 * n))
-        r.phash = "ffffffffffffffff"            # identical perceptual hash
+        r.phash = "f" * 64                      # identical perceptual hash
         dupes.append(r)
+    # 64 hex chars = the 256-bit hash utils.phash emits (#4223, migration
+    # 0098). The widths must match the real ones: _diversify_similar's
+    # dup_threshold moved 8 -> 32 with the hash, so 64-bit fixtures would
+    # now read as near-duplicates of each other and collapse the very rows
+    # this asserts come through.
     distinct_a = await _img(db, 7, _vec(1, 1))
-    distinct_a.phash = "0000000000000000"
+    distinct_a.phash = "0" * 64                 # 256 bits away from the dupes
     distinct_b = await _img(db, 8, _vec(0, 1))
-    distinct_b.phash = "0f0f0f0f0f0f0f0f"
+    distinct_b.phash = "0f" * 32                # 128 bits away
     await db.flush()
 
     res = await GalleryService(db).similar(src.id, limit=10)

tests/test_importer.py

@@ -58,10 +58,36 @@ def test_import_one_happy_path(importer, import_layout):
     result = importer.import_one(src)
     assert result.status == "imported"
     record = importer.session.get(ImageRecord, result.image_id)
-    assert record.path.startswith(str(images_root / "Alice"))
+    # Under the artist's SLUG, not the import folder's "Alice" (milestone
+    # #421) — the import tree's capitalisation is an accident of how the
+    # operator named a folder, and honouring it gave one artist two homes.
+    assert record.path.startswith(str(images_root / "alice"))
     assert record.path.endswith(".jpg")
 
 
+def test_library_path_uses_the_artist_slug_not_the_folder_name(
+    importer, import_layout,
+):
+    """The regression that grew 57 duplicate artist directories: an import
+    from `/import/Conto/...` wrote `<images>/Conto/...` while the downloader
+    wrote `<images>/conto/...` for the same Artist row."""
+    import_root, images_root = import_layout
+    src = import_root / "StickySpoodge" / "patreon" / "a.jpg"
+    _make_jpeg(src)
+    result = importer.import_one(src)
+
+    record = importer.session.get(ImageRecord, result.image_id)
+    artist = importer.session.execute(
+        select(Artist).where(Artist.slug == "stickyspoodge")
+    ).scalar_one()
+    assert artist.name == "StickySpoodge"
+    # Artist segment canonicalised; the post hierarchy below it untouched.
+    assert record.path.startswith(
+        str(images_root / "stickyspoodge" / "patreon")
+    )
+    assert not Path(record.path).is_relative_to(images_root / "StickySpoodge")
+
+
 def test_folder_creates_artist_and_links_artist_id(importer, import_layout):
     # FC-2d-vii-c: folder import creates the Artist and sets the canonical
     # image_record.artist_id — no artist-kind Tag (that path was retired;

tests/test_library_layout.py

@@ -0,0 +1,403 @@
+"""Milestone #421 — the shared predicate behind the consolidation.
+
+`destination_for` is pure and tested without a database; `survey_layout` gets
+the integration treatment because the counts are the number the apply is
+checked against.
+"""
+
+from pathlib import Path
+
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import Artist, ImageRecord
+from backend.app.services.library_layout import (
+    RESERVED_TOP_LEVEL,
+    _misplaced_conditions,
+    canonical_dir,
+    destination_for,
+    survey_layout,
+)
+
+ROOT = Path("/images")
+
+
+# --- destination_for (pure) -------------------------------------------------
+
+
+def test_destination_rewrites_only_the_artist_segment():
+    assert destination_for(
+        "/images/Conto/patreon/2026-01_a_Post/x.png", ROOT, "conto"
+    ) == Path("/images/conto/patreon/2026-01_a_Post/x.png")
+
+
+def test_destination_is_identity_for_a_row_already_in_place():
+    p = "/images/conto/patreon/x.png"
+    assert destination_for(p, ROOT, "conto") == Path(p)
+
+
+def test_destination_pulls_a_root_level_row_under_its_artist():
+    """Diverges from canonical_subdir deliberately: the row CARRIES an
+    artist_id, so a file at the root is an anomaly with a known home."""
+    assert destination_for("/images/loose.png", ROOT, "conto") == Path(
+        "/images/conto/loose.png"
+    )
+
+
+def test_destination_refuses_paths_outside_the_images_root():
+    assert destination_for("/srv/elsewhere/x.png", ROOT, "conto") is None
+
+
+@pytest.mark.parametrize("reserved", sorted(RESERVED_TOP_LEVEL))
+def test_destination_refuses_the_reserved_stores(reserved):
+    """Relocating these would move the thumbnail cache, the attachment blobs
+    or the credential key into an artist folder."""
+    assert destination_for(f"/images/{reserved}/aa/x.png", ROOT, "conto") is None
+
+
+def test_destination_is_idempotent():
+    once = destination_for("/images/Conto/patreon/x.png", ROOT, "conto")
+    assert destination_for(str(once), ROOT, "conto") == once
+
+
+# --- the predicate ----------------------------------------------------------
+
+
+def test_canonical_prefix_carries_a_separator():
+    """Without the trailing slash, artist `ara` matches every path under
+    `arbuzbudesh/` — one artist reads as fully placed while another's rows
+    are silently skipped."""
+    conds = _misplaced_conditions(ROOT, 1, "ara")
+    rendered = str(conds[-1].compile(compile_kwargs={"literal_binds": True}))
+    assert "/images/ara/" in rendered
+
+
+# --- survey_layout (integration) --------------------------------------------
+#
+# Marked per-test rather than with a module-level `pytestmark`: the
+# destination_for cases above are pure and belong in the fast unit lane.
+
+
+def _artist(db, name, slug):
+    a = Artist(name=name, slug=slug)
+    db.add(a)
+    db.flush()
+    return a
+
+
+def _image(db, path, artist=None, n=0):
+    rec = ImageRecord(
+        path=path, sha256=f"{n:064d}", size_bytes=1, mime="image/png",
+        width=10, height=10, origin="imported_filesystem",
+        integrity_status="unknown",
+        artist_id=artist.id if artist else None,
+    )
+    db.add(rec)
+    db.flush()
+    return rec
+
+
+@pytest.mark.integration
+def test_survey_splits_canonical_from_misplaced(db_sync):
+    conto = _artist(db_sync, "Conto", "conto")
+    _image(db_sync, "/images/conto/patreon/a.png", conto, 1)
+    _image(db_sync, "/images/Conto/patreon/b.png", conto, 2)
+    _image(db_sync, "/images/Conto/patreon/c.png", conto, 3)
+
+    report = survey_layout(db_sync, ROOT, check_disk=False)
+
+    assert report.misplaced_rows == 2
+    assert report.canonical_rows == 1
+    row = next(a for a in report.artists if a.slug == "conto")
+    assert row.stray_dirs == ["Conto"]
+
+
+@pytest.mark.integration
+def test_survey_does_not_confuse_a_prefix_sharing_artist(db_sync):
+    """`ara` vs `arbuzbudesh` — the reason the predicate anchors on a
+    separator. Both are real artists in the operator's library."""
+    ara = _artist(db_sync, "Ara", "ara")
+    arbuz = _artist(db_sync, "ArbuzBudesh", "arbuzbudesh")
+    _image(db_sync, "/images/ara/x.png", ara, 4)
+    _image(db_sync, "/images/arbuzbudesh/y.png", arbuz, 5)
+
+    report = survey_layout(db_sync, ROOT, check_disk=False)
+
+    assert report.misplaced_rows == 0
+    assert report.canonical_rows == 2
+
+
+@pytest.mark.integration
+def test_survey_counts_two_rows_landing_on_one_destination(db_sync):
+    """A collision is the case the apply must refuse, so the report has to
+    surface it rather than promise a move that cannot happen."""
+    sticky = _artist(db_sync, "StickySpoodge", "stickyspoodge")
+    _image(db_sync, "/images/StickySpoodge/p/dup.png", sticky, 6)
+    _image(db_sync, "/images/Stickyspoodge/p/dup.png", sticky, 7)
+
+    report = survey_layout(db_sync, ROOT, check_disk=False)
+
+    assert report.collision_count == 1
+    row = next(a for a in report.artists if a.slug == "stickyspoodge")
+    assert row.collisions == ["/images/stickyspoodge/p/dup.png"]
+    assert row.stray_dirs == ["StickySpoodge", "Stickyspoodge"]
+
+
+@pytest.mark.integration
+def test_survey_reports_unattributed_rows_without_moving_them(db_sync):
+    """The 660 loose root files have no artist_id, so no predicate reaches
+    them. They are counted, and left for task #4247."""
+    _image(db_sync, "/images/orphan.png", None, 8)
+
+    report = survey_layout(db_sync, ROOT, check_disk=False)
+
+    assert report.unattributed_rows == 1
+    assert report.misplaced_rows == 0
+
+
+@pytest.mark.integration
+def test_survey_refuses_a_row_under_a_reserved_store(db_sync):
+    thumbs = _artist(db_sync, "Thumbsy", "thumbsy")
+    _image(db_sync, "/images/thumbs/aa/weird.png", thumbs, 9)
+
+    report = survey_layout(db_sync, ROOT, check_disk=False)
+
+    assert report.unmovable == 1
+    row = next(a for a in report.artists if a.slug == "thumbsy")
+    assert row.misplaced_rows == 1
+    assert row.collisions == []
+
+
+@pytest.mark.integration
+def test_survey_counts_a_missing_source_file(db_sync, tmp_path):
+    """check_disk is what separates "would move" from "can move"."""
+    gone = _artist(db_sync, "Gone", "gone")
+    _image(db_sync, str(tmp_path / "Gone" / "missing.png"), gone, 10)
+
+    report = survey_layout(db_sync, tmp_path, check_disk=True)
+
+    assert report.missing_files == 1
+
+
+@pytest.mark.integration
+def test_survey_flags_a_destination_that_already_exists(db_sync, tmp_path):
+    occupied = _artist(db_sync, "Occupied", "occupied")
+    src = tmp_path / "Occupied" / "x.png"
+    src.parent.mkdir(parents=True)
+    src.write_bytes(b"src")
+    dest = canonical_dir(tmp_path, "occupied") / "x.png"
+    dest.parent.mkdir(parents=True)
+    dest.write_bytes(b"already here")
+    _image(db_sync, str(src), occupied, 11)
+
+    report = survey_layout(db_sync, tmp_path, check_disk=True)
+
+    assert report.collision_count == 1
+    assert dest.read_bytes() == b"already here"  # read-only: nothing moved
+
+
+@pytest.mark.integration
+def test_survey_is_read_only(db_sync, tmp_path):
+    a = _artist(db_sync, "Reader", "reader")
+    src = tmp_path / "Reader" / "x.png"
+    src.parent.mkdir(parents=True)
+    src.write_bytes(b"x")
+    rec = _image(db_sync, str(src), a, 12)
+    before = rec.path
+
+    survey_layout(db_sync, tmp_path, check_disk=True)
+
+    db_sync.expire_all()
+    assert db_sync.get(ImageRecord, rec.id).path == before
+    assert src.exists()
+    assert db_sync.execute(
+        select(ImageRecord.path).where(ImageRecord.id == rec.id)
+    ).scalar_one() == before
+
+
+# --- plan / apply / revert (#4246) ------------------------------------------
+
+
+def _staged(db, tmp_path, slug, stray, name="x.png", n=100):
+    """An artist with one file sitting in `stray`'s directory."""
+    artist = _artist(db, slug.title(), slug)
+    src = tmp_path / stray / name
+    src.parent.mkdir(parents=True, exist_ok=True)
+    src.write_bytes(b"pixels")
+    rec = _image(db, str(src), artist, n)
+    return artist, rec, src
+
+
+@pytest.mark.integration
+def test_plan_records_where_each_file_came_from(db_sync, tmp_path):
+    from backend.app.services.library_layout import plan_placement
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=20)
+    run = plan_placement(db_sync, tmp_path)
+
+    assert run.status == "ready"
+    assert run.planned_count == 1
+    assert run.moves == [{
+        "image_id": rec.id,
+        "from": str(src),
+        "to": str(tmp_path / "conto" / "x.png"),
+    }]
+    # Planning touches nothing.
+    assert src.exists()
+    assert db_sync.get(ImageRecord, rec.id).path == str(src)
+
+
+@pytest.mark.integration
+def test_apply_moves_file_and_row_together(db_sync, tmp_path):
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=21)
+    run = apply_run(db_sync, plan_placement(db_sync, tmp_path))
+
+    dest = tmp_path / "conto" / "x.png"
+    assert run.status == "applied"
+    assert run.moved_count == 1 and run.refused_count == 0
+    assert dest.exists() and not src.exists()
+    db_sync.expire_all()
+    assert db_sync.get(ImageRecord, rec.id).path == str(dest)
+
+
+@pytest.mark.integration
+def test_revert_puts_it_back(db_sync, tmp_path):
+    """The whole reason `from` is retained: do one artist, look, undo."""
+    from backend.app.services.library_layout import (
+        apply_run,
+        plan_placement,
+        revert_run,
+    )
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=22)
+    run = revert_run(db_sync, apply_run(db_sync, plan_placement(db_sync, tmp_path)))
+
+    assert run.status == "reverted"
+    assert src.exists()
+    assert not (tmp_path / "conto" / "x.png").exists()
+    db_sync.expire_all()
+    assert db_sync.get(ImageRecord, rec.id).path == str(src)
+
+
+@pytest.mark.integration
+def test_apply_refuses_a_row_that_moved_since_planning(db_sync, tmp_path):
+    """A supersede or an earlier run can rewrite a path between plan and
+    apply. The stale entry is declined, not forced."""
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=23)
+    run = plan_placement(db_sync, tmp_path)
+
+    elsewhere = tmp_path / "conto" / "already-here.png"
+    elsewhere.parent.mkdir(parents=True, exist_ok=True)
+    elsewhere.write_bytes(b"pixels")
+    rec.path = str(elsewhere)
+    db_sync.flush()
+
+    run = apply_run(db_sync, run)
+
+    assert run.moved_count == 0 and run.refused_count == 1
+    assert run.refusals[0]["reason"] == "row moved since planning"
+    assert src.exists()  # untouched
+
+
+@pytest.mark.integration
+def test_apply_never_overwrites_an_occupied_destination(db_sync, tmp_path):
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=24)
+    run = plan_placement(db_sync, tmp_path)
+
+    squatter = tmp_path / "conto" / "x.png"
+    squatter.parent.mkdir(parents=True, exist_ok=True)
+    squatter.write_bytes(b"someone else")
+
+    run = apply_run(db_sync, run)
+
+    assert run.refused_count == 1
+    assert run.refusals[0]["reason"] == "destination occupied"
+    assert squatter.read_bytes() == b"someone else"
+    db_sync.expire_all()
+    assert db_sync.get(ImageRecord, rec.id).path == str(src)
+
+
+@pytest.mark.integration
+def test_apply_leaves_the_row_alone_when_the_source_is_gone(db_sync, tmp_path):
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    _, rec, src = _staged(db_sync, tmp_path, "conto", "Conto", n=25)
+    run = plan_placement(db_sync, tmp_path)
+    src.unlink()
+
+    run = apply_run(db_sync, run)
+
+    assert run.refusals[0]["reason"] == "source missing"
+    db_sync.expire_all()
+    # The row still points at the missing file rather than at a file that
+    # was never created — a broken row is recoverable, a lying one is not.
+    assert db_sync.get(ImageRecord, rec.id).path == str(src)
+
+
+@pytest.mark.integration
+def test_plan_scopes_to_one_artist(db_sync, tmp_path):
+    """Per-artist scope is what makes this incremental instead of one
+    irreversible sweep."""
+    from backend.app.services.library_layout import plan_placement
+
+    conto, _, _ = _staged(db_sync, tmp_path, "conto", "Conto", n=26)
+    _staged(db_sync, tmp_path, "maewix", "Maewix", name="y.png", n=27)
+
+    run = plan_placement(db_sync, tmp_path, artist_id=conto.id)
+
+    assert run.planned_count == 1
+    assert run.artist_id == conto.id
+    assert "Conto" in run.moves[0]["from"]
+
+
+@pytest.mark.integration
+def test_plan_skips_both_rows_when_two_want_one_destination(db_sync, tmp_path):
+    """Which of two colliding rows 'wins' is not this sweep's call."""
+    from backend.app.services.library_layout import plan_placement
+
+    artist = _artist(db_sync, "Sticky", "sticky")
+    for stray, n in (("StickySpoodge", 28), ("Stickyspoodge", 29)):
+        p = tmp_path / stray / "dup.png"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"pixels")
+        _image(db_sync, str(p), artist, n)
+
+    run = plan_placement(db_sync, tmp_path)
+
+    assert run.planned_count == 0
+
+
+@pytest.mark.integration
+def test_thumbnails_do_not_move(db_sync, tmp_path):
+    """Thumbs are sha-addressed (`thumbs/<xx>/<sha>.jpg`), not path-keyed, so
+    a placement move must not touch them. Pinned so nobody 'fixes' it."""
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    artist, rec, _ = _staged(db_sync, tmp_path, "conto", "Conto", n=30)
+    thumb = tmp_path / "thumbs" / "ab" / "abc.jpg"
+    thumb.parent.mkdir(parents=True, exist_ok=True)
+    thumb.write_bytes(b"thumb")
+    rec.thumbnail_path = str(thumb)
+    db_sync.flush()
+
+    apply_run(db_sync, plan_placement(db_sync, tmp_path))
+
+    db_sync.expire_all()
+    assert thumb.exists()
+    assert db_sync.get(ImageRecord, rec.id).thumbnail_path == str(thumb)
+
+
+@pytest.mark.integration
+def test_apply_refuses_a_run_that_is_not_ready(db_sync, tmp_path):
+    from backend.app.services.library_layout import apply_run, plan_placement
+
+    _staged(db_sync, tmp_path, "conto", "Conto", n=31)
+    run = apply_run(db_sync, plan_placement(db_sync, tmp_path))
+    with pytest.raises(ValueError):
+        apply_run(db_sync, run)

tests/test_membership_lapses.py

@@ -0,0 +1,190 @@
+"""#3995: stop pulling a source once the account stops paying, resume on resubscribe.
+
+Operator, 2026-09-13: "if I kill a subscription on patreon I would like the
+pulling to stop on curator as well", with automatic resume when they resubscribe.
+
+Stopping a source is easy. Not stopping the wrong one is the work, so most of
+these pin refusals: an absent membership is never a lapse, an unknown status is
+never a lapse, a stale roster decides nothing, a paid-through period is honoured,
+and the operator's own on/off choice always outranks the sweep in both directions.
+"""
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import Artist, Source
+from backend.app.services.membership_reconcile import (
+    KEPT_KEY,
+    STOPPED_KEY,
+    apply_membership_lapses,
+)
+from backend.app.services.membership_roster import ROSTER_STALE_AFTER
+from backend.app.services.source_service import SourceService
+from tests.roster_builders import membership as _membership
+from tests.roster_builders import synced as _synced
+
+pytestmark = pytest.mark.integration
+
+
+async def _source(
+    db, *, overrides=None, enabled=True, url="https://www.patreon.com/an-old-handle",
+):
+    artist = Artist(name="Maewix", slug="maewix")
+    db.add(artist)
+    await db.flush()
+    s = Source(
+        artist_id=artist.id, platform="patreon", url=url, enabled=enabled,
+        config_overrides={"patreon_campaign_id": "c1", **(overrides or {})},
+        last_error="boom", error_type="tier_limited", consecutive_failures=3,
+    )
+    db.add(s)
+    await db.flush()
+    return s.id
+
+
+async def _state(db, source_id):
+    row = (await db.execute(
+        select(Source.enabled, Source.config_overrides, Source.error_type,
+               Source.consecutive_failures).where(Source.id == source_id)
+    )).one()
+    return row
+
+
+@pytest.mark.asyncio
+async def test_a_lapsed_membership_stops_its_source_with_a_clean_slate(db):
+    sid = await _source(db)
+    await _membership(db, campaign="c1", status="former_patron")
+    await _synced(db)
+    await db.commit()
+
+    out = await apply_membership_lapses(db, platform="patreon")
+    assert out["stopped"] == 1
+
+    enabled, co, error_type, failures = await _state(db, sid)
+    assert enabled is False
+    assert co[STOPPED_KEY]["status"] == "former_patron"
+    assert co["patreon_campaign_id"] == "c1"  # the identity cache survives
+    assert (error_type, failures) == (None, 0)
+
+
+@pytest.mark.asyncio
+async def test_the_paid_through_period_is_honoured(db):
+    """Patreon keeps access until the billing period ends, and says when."""
+    sid = await _source(db)
+    later = (datetime.now(UTC) + timedelta(days=10)).isoformat()
+    await _membership(
+        db, campaign="c1", status="former_patron",
+        details={"member": {"access_expires_at": later}},
+    )
+    await _synced(db)
+    await db.commit()
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["stopped"] == 0
+    assert (await _state(db, sid)).enabled is True
+
+
+@pytest.mark.asyncio
+async def test_an_absent_membership_is_never_a_lapse(db):
+    """No match has innocent causes (a rename, a never-walked source), so
+    absence alone must never switch a source off."""
+    sid = await _source(db, overrides={"patreon_campaign_id": "nobody-has-this"})
+    await _membership(db, campaign="c1", status="former_patron", details={})
+    await _synced(db)
+    await db.commit()
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["stopped"] == 0
+    assert (await _state(db, sid)).enabled is True
+
+
+@pytest.mark.asyncio
+async def test_an_unrecognised_status_is_never_a_lapse(db):
+    sid = await _source(db)
+    await _membership(db, campaign="c1", status="some_word_nobody_characterised")
+    await _synced(db)
+    await db.commit()
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["stopped"] == 0
+    assert (await _state(db, sid)).enabled is True
+
+
+@pytest.mark.asyncio
+async def test_a_stale_roster_decides_nothing(db):
+    sid = await _source(db)
+    await _membership(db, campaign="c1", status="former_patron")
+    await _synced(db, ago=ROSTER_STALE_AFTER + timedelta(hours=1))
+    await db.commit()
+
+    out = await apply_membership_lapses(db, platform="patreon")
+    assert out["skipped"] == "roster not fresh"
+    assert (await _state(db, sid)).enabled is True
+
+
+@pytest.mark.asyncio
+async def test_resubscribing_resumes_only_what_the_sweep_stopped(db):
+    stopped = await _source(
+        db, enabled=False, overrides={STOPPED_KEY: {"status": "former_patron"}},
+    )
+    await _membership(db, campaign="c1", status="active_patron")
+    await _synced(db)
+    await db.commit()
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["resumed"] == 1
+    enabled, co, _e, _f = await _state(db, stopped)
+    assert enabled is True
+    assert STOPPED_KEY not in co
+
+
+@pytest.mark.asyncio
+async def test_a_source_the_operator_switched_off_is_never_switched_back_on(db):
+    sid = await _source(db, enabled=False)
+    await _membership(db, campaign="c1", status="active_patron")
+    await _synced(db)
+    await db.commit()
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["resumed"] == 0
+    assert (await _state(db, sid)).enabled is False
+
+
+@pytest.mark.asyncio
+async def test_turning_a_stopped_source_back_on_keeps_it_on(db):
+    """Re-enabling a stopped source by hand is a choice to keep pulling a lapsed
+    creator. The next sweep must not undo it."""
+    sid = await _source(
+        db, enabled=False, overrides={STOPPED_KEY: {"status": "former_patron"}},
+    )
+    await _membership(db, campaign="c1", status="former_patron")
+    await _synced(db)
+    await db.commit()
+
+    await SourceService(db).update(sid, enabled=True)
+    enabled, co, _e, _f = await _state(db, sid)
+    assert enabled is True
+    assert co.get(KEPT_KEY) is True and STOPPED_KEY not in co
+
+    assert (await apply_membership_lapses(db, platform="patreon"))["stopped"] == 0
+    assert (await _state(db, sid)).enabled is True
+
+
+@pytest.mark.asyncio
+async def test_switching_a_stopped_source_off_by_hand_drops_the_resume_marker(db):
+    sid = await _source(
+        db, enabled=False, overrides={STOPPED_KEY: {"status": "former_patron"}},
+    )
+    await db.commit()
+
+    await SourceService(db).update(sid, enabled=False)
+    _enabled, co, _e, _f = await _state(db, sid)
+    assert STOPPED_KEY not in co
+
+
+@pytest.mark.asyncio
+async def test_a_kept_source_is_released_once_paid_again(db):
+    sid = await _source(db, overrides={KEPT_KEY: True})
+    await _membership(db, campaign="c1", status="active_patron")
+    await _synced(db)
+    await db.commit()
+
+    await apply_membership_lapses(db, platform="patreon")
+    _enabled, co, _e, _f = await _state(db, sid)
+    assert KEPT_KEY not in co

tests/test_membership_roster.py

@@ -10,11 +10,8 @@ import pytest
 from sqlalchemy import select
 
 from backend.app.models import PlatformMembership
-from backend.app.services.membership_roster import (
-    MEMBERSHIP_STATUS,
-    has_paid_access,
-    touch_membership,
-)
+from backend.app.services.membership_roster import touch_membership
+from backend.app.services.native_ingest_common import MEMBERSHIP_STATUS, has_paid_access
 
 pytestmark = pytest.mark.integration
 

tests/test_paths.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from backend.app.utils.paths import (
+    canonical_subdir,
     derive_subdir,
     derive_top_level_artist,
     filehash_from_url,
@@ -59,3 +60,38 @@ def test_derive_top_level_artist_nested():
 
 def test_derive_top_level_artist_root():
     assert derive_top_level_artist(Path("/import/x.png"), IMPORT) is None
+
+
+# --- canonical_subdir (milestone #421) --------------------------------------
+
+
+def test_canonical_subdir_replaces_the_top_segment():
+    assert canonical_subdir("Conto/patreon", "conto") == "conto/patreon"
+    assert canonical_subdir("Conto", "conto") == "conto"
+
+
+def test_canonical_subdir_keeps_everything_below_the_artist():
+    """Only the artist segment is authoritative — post folders below it are
+    the downloader's business and must survive untouched."""
+    assert canonical_subdir(
+        "Big Bang/patreon/2026-01-02_123_A Post", "big-bang"
+    ) == "big-bang/patreon/2026-01-02_123_A Post"
+
+
+def test_canonical_subdir_passes_through_without_an_artist():
+    """No resolved artist means nothing authoritative to canonicalise against,
+    so the import folder's own name stands."""
+    assert canonical_subdir("Conto/patreon", None) == "Conto/patreon"
+    assert canonical_subdir("Conto", "") == "Conto"
+
+
+def test_canonical_subdir_leaves_the_images_root_alone():
+    """An empty subdir is a file landing at the root — there is no artist
+    folder to correct, and what becomes of those is task #4247's call."""
+    assert canonical_subdir("", "conto") == ""
+    assert canonical_subdir("", None) == ""
+
+
+def test_canonical_subdir_is_idempotent():
+    once = canonical_subdir("Conto/patreon", "conto")
+    assert canonical_subdir(once, "conto") == once

tests/test_patreon_memberships.py

@@ -239,14 +239,72 @@ def test_a_missing_data_list_is_drift(client, payload):
         list(client.iter_memberships(user_id="1"))
 
 
-def test_a_member_with_no_campaign_is_drift(client, payload):
+def _index_of(payload, status):
+    return next(
+        i for i, m in enumerate(payload["data"])
+        if m["attributes"]["patron_status"] == status
+    )
+
+
+@pytest.mark.parametrize("shape", ["null", "absent"])
+def test_an_active_member_with_no_campaign_is_drift(client, payload, shape):
+    """A PAID membership FC cannot attribute must refuse the roster. Dropping it
+    would read downstream as the operator having cancelled it."""
     mangled = json.loads(json.dumps(payload))
-    mangled["data"][0]["relationships"]["campaign"] = {"data": None}
+    rels = mangled["data"][_index_of(mangled, "active_patron")]["relationships"]
+    if shape == "null":
+        rels["campaign"] = {"data": None}
+    else:
+        del rels["campaign"]
     client._request = lambda *a, **k: mangled
     with pytest.raises(PatreonDriftError, match="campaign"):
         list(client.iter_memberships(user_id="1"))
 
 
+def test_an_unrecognised_status_with_no_campaign_is_drift(client, payload):
+    """Only a status KNOWN to mean "not paying" may be skipped. An unknown word
+    could be a paid membership (has_paid_access returns None for it)."""
+    mangled = json.loads(json.dumps(payload))
+    row = mangled["data"][_index_of(mangled, "active_patron")]
+    row["attributes"]["patron_status"] = "some_new_status"
+    del row["relationships"]["campaign"]
+    client._request = lambda *a, **k: mangled
+    with pytest.raises(PatreonDriftError, match="campaign"):
+        list(client.iter_memberships(user_id="1"))
+
+
+def test_a_lapsed_member_whose_creator_is_gone_is_skipped(client, payload):
+    """The live roster's shape (note #3886, CORRECTION 3). A membership that
+    lapsed in 2017 came back with no `campaign` key at all, because the creator's
+    page no longer exists. It used to fail the whole roster. Now it is the only
+    row missing, and every other row still arrives."""
+    mangled = json.loads(json.dumps(payload))
+    lapsed = _index_of(mangled, "former_patron")
+    del mangled["data"][lapsed]["relationships"]["campaign"]
+    client._request = lambda *a, **k: mangled
+    rows = list(client.iter_memberships(user_id="1"))
+    assert len(rows) == len(payload["data"]) - 1
+    assert all(r.campaign_id for r in rows)
+    assert all(r.status == "active_patron" for r in rows)
+
+
+def test_skipping_does_not_end_paging_early(client, payload):
+    """Paging counts the rows the SERVER sent, not the ones kept. Counting kept
+    rows would re-request an offset that was already read, or stop one page
+    short, whenever a row is skipped."""
+    first = json.loads(json.dumps(payload))
+    del first["data"][_index_of(first, "former_patron")]["relationships"]["campaign"]
+    total = 2 * len(payload["data"])
+    first["meta"]["pagination"]["total"] = total
+    second = json.loads(json.dumps(payload))
+    second["meta"]["pagination"]["total"] = total
+    calls = _serve(client, first, second)
+    rows = list(client.iter_memberships(user_id="1"))
+    assert len(calls) == 2
+    assert calls[1][1]["page[offset]"] == str(len(payload["data"]))
+    assert len(rows) == total - 1
+
+
 def test_a_member_with_no_patron_status_is_drift(client, payload):
     mangled = json.loads(json.dumps(payload))
     del mangled["data"][0]["attributes"]["patron_status"]

tests/test_phash_dedup.py

@@ -81,7 +81,7 @@ def test_non_similar_imports_with_phash(importer, import_layout):
     r = importer.import_one(src)
     assert r.status == "imported"
     row = importer.session.get(ImageRecord, r.image_id)
-    assert row.phash is not None and len(row.phash) == 16
+    assert row.phash is not None and len(row.phash) == 64  # 256-bit
 
 
 def test_larger_existing_skips_new_phash_dup(importer, import_layout):
@@ -223,6 +223,74 @@ def test_threshold_controls_match(importer, import_layout):
     assert r.status == "imported"  # threshold 0 + far → independent import
 
 
+# --- The three gates (#4223) ------------------------------------------------
+#
+# Each of these opens the hash gate all the way (threshold 256 = every
+# candidate passes) so the test is about the gate named in its title, and not
+# about whether two fixtures happen to hash apart. That is the regression
+# being guarded: the operator ran the dial down to 0 and STILL lost variants,
+# because the hash was never the thing that could tell them apart.
+
+
+def _wide_open(importer):
+    _set_threshold(importer, 256)
+
+
+def test_variant_survives_a_wide_open_threshold(importer, import_layout):
+    """Same aspect, same size, different picture — only the pixel confirm can
+    save it, and it must."""
+    import_root, _ = import_layout
+    a = import_root / "v.png"
+    _write_split(a, "v", (400, 400))
+    _wide_open(importer)
+    assert importer.import_one(a).status == "imported"
+
+    b = import_root / "h.png"
+    _write_split(b, "h", (400, 400))
+    assert importer.import_one(b).status == "imported"
+    assert importer.session.execute(
+        select(func.count()).select_from(ImageRecord)
+    ).scalar_one() == 2
+
+
+def test_rescale_still_supersedes_at_a_wide_open_threshold(importer, import_layout):
+    """The other half of the deal: the merge the operator DOES want still
+    happens, and keeps the higher resolution."""
+    import_root, _ = import_layout
+    small = import_root / "small.png"
+    _write_split(small, "v", (200, 200))
+    _wide_open(importer)
+    r1 = importer.import_one(small)
+    assert r1.status == "imported"
+
+    big = import_root / "big.png"
+    _write_split(big, "v", (900, 900))
+    r2 = importer.import_one(big)
+    assert r2.status == "superseded"
+    assert r2.image_id == r1.image_id
+
+    importer.session.expire_all()
+    row = importer.session.get(ImageRecord, r1.image_id)
+    assert row.width == 900 and row.height == 900
+
+
+def test_different_aspect_is_never_a_duplicate(importer, import_layout):
+    """Solid colours are pixel-identical once fingerprinted, so the aspect
+    gate is the only thing standing between a crop and a supersede."""
+    import_root, _ = import_layout
+    square = import_root / "square.png"
+    _write(square, (90, 40, 180), (400, 400))
+    _wide_open(importer)
+    assert importer.import_one(square).status == "imported"
+
+    wide = import_root / "wide.png"
+    _write(wide, (90, 40, 180), (800, 400))
+    assert importer.import_one(wide).status == "imported"
+    assert importer.session.execute(
+        select(func.count()).select_from(ImageRecord)
+    ).scalar_one() == 2
+
+
 def test_import_task_maps_superseded_to_complete_and_requeues():
     from backend.app.services.importer import ImportResult
     from backend.app.tasks.import_file import _map_result_to_status

tests/test_phash_util.py

@@ -3,7 +3,13 @@ import io
 import imagehash
 from PIL import Image
 
-from backend.app.utils.phash import compute_phash, find_similar
+from backend.app.utils.phash import (
+    aspect_matches,
+    compute_phash,
+    find_similar,
+    fingerprint,
+    fingerprints_match,
+)
 
 
 def _img(color, size=(64, 64)):
@@ -25,7 +31,7 @@ def _split(orient, size=64):
 def test_compute_phash_stable_and_hex():
     h1 = compute_phash(_img((10, 120, 200)))
     h2 = compute_phash(_img((10, 120, 200)))
-    assert isinstance(h1, str) and len(h1) == 16  # hash_size=8 -> 64-bit -> 16 hex
+    assert isinstance(h1, str) and len(h1) == 64  # hash_size=16 -> 256-bit -> 64 hex
     assert h1 == h2
 
 
@@ -62,3 +68,73 @@ def test_find_similar_threshold_boundary_inclusive_and_first_match():
     assert rel == "larger_exists"
     rel2, _ = find_similar(h, 10, 10, [(far, 999, 999, 1)], threshold=d - 1)
     assert rel2 == "none"
+
+
+# --- Gate 2: aspect ratio (#4223) -------------------------------------------
+
+def test_aspect_matches_tolerates_rounding_but_not_a_crop():
+    assert aspect_matches(1000, 1000, 250, 250)
+    assert aspect_matches(1999, 1000, 1000, 500)     # off-by-one on a rescale
+    assert not aspect_matches(1000, 1000, 1000, 500)  # 1:1 vs 2:1
+    # Unmeasurable is not a proven duplicate — the gate fails closed.
+    assert not aspect_matches(1000, 1000, None, None)
+    assert not aspect_matches(0, 0, 100, 100)
+
+
+def test_find_similar_skips_a_hash_twin_with_a_different_aspect():
+    """A crop or re-canvas keeps the composition, so it can land inside the
+    threshold. Dimensions are what say it is not a rescale."""
+    h = compute_phash(_img((123, 50, 7)))
+    rel, mid = find_similar(h, 100, 100, [(h, 400, 200, 9)], threshold=64)
+    assert rel == "none" and mid is None
+
+
+# --- Gate 3: the pixel confirm (#4223) --------------------------------------
+
+def test_fingerprints_match_across_a_rescale():
+    assert fingerprints_match(
+        fingerprint(_split("v", 64)), fingerprint(_split("v", 512))
+    )
+
+
+def test_fingerprints_reject_a_local_change():
+    """The case the hash cannot see: same composition, one region redrawn."""
+    base = _split("v", 128)
+    variant = base.copy()
+    for y in range(20, 60):
+        for x in range(80, 120):        # a patch on the white half
+            variant.putpixel((x, y), (0, 0, 0))
+    assert not fingerprints_match(fingerprint(base), fingerprint(variant))
+
+
+def test_fingerprints_match_is_false_when_either_side_is_missing():
+    assert not fingerprints_match(fingerprint(_split("v")), None)
+    assert not fingerprints_match(None, None)
+
+
+def test_find_similar_confirm_can_veto_a_hash_and_aspect_match():
+    h = compute_phash(_img((123, 50, 7)))
+    cand = [(h, 400, 400, 9)]
+    rel, mid = find_similar(h, 100, 100, cand, threshold=64, confirm=lambda _: True)
+    assert rel == "larger_exists" and mid == 9
+    rel2, mid2 = find_similar(h, 100, 100, cand, threshold=64, confirm=lambda _: False)
+    assert rel2 == "none" and mid2 is None
+
+
+def test_find_similar_keeps_looking_after_a_veto():
+    """A vetoed candidate must not end the search, or one false pre-filter hit
+    would hide the real duplicate sitting behind it."""
+    h = compute_phash(_img((123, 50, 7)))
+    candidates = [(h, 400, 400, 1), (h, 400, 400, 2)]
+    rel, mid = find_similar(
+        h, 100, 100, candidates, threshold=64, confirm=lambda cid: cid == 2
+    )
+    assert rel == "larger_exists" and mid == 2
+
+
+def test_find_similar_skips_a_hash_of_the_wrong_width():
+    """Mid-re-hash (migration 0098): a leftover 64-bit hash cannot be compared
+    to a 256-bit one. Skipping it degrades to no dedup, never to a merge."""
+    h = compute_phash(_img((123, 50, 7)))
+    rel, mid = find_similar(h, 100, 100, [("ffffffffffffffff", 400, 400, 3)], threshold=64)
+    assert rel == "none" and mid is None

tests/test_public_svgs.py

@@ -0,0 +1,40 @@
+"""Every SVG the browser loads from `frontend/public/` must parse as XML.
+
+A browser renders an SVG used as an image only if it is well-formed XML, and
+when it is not, nothing reports it: no console error in most browsers, no
+failed build, no failed request — the icon is simply blank. `favicon.svg`
+shipped that way (merge #251) because its comment contained a CSS custom
+property name, and `--` is illegal inside an XML comment. Both the tab icon and
+the nav brand mark went missing, and only a person looking at the page noticed.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+import pytest
+
+PUBLIC = Path(__file__).resolve().parent.parent / "frontend" / "public"
+SVGS = sorted(PUBLIC.rglob("*.svg"))
+
+
+def test_the_public_dir_has_svgs_to_check():
+    """Guards the guard: a moved directory would otherwise pass vacuously."""
+    assert {p.name for p in SVGS} >= {"favicon.svg", "logo.svg"}
+
+
+@pytest.mark.parametrize("svg", SVGS, ids=lambda p: p.name)
+def test_svg_is_well_formed_xml(svg):
+    root = ET.parse(svg).getroot()
+    assert root.tag == "{http://www.w3.org/2000/svg}svg"
+
+
+def test_the_parser_rejects_the_shape_that_broke_the_favicon():
+    """Positive control: the exact defect must fail this parser, or the
+    parametrized test above proves nothing."""
+    broken = (
+        '<svg xmlns="http://www.w3.org/2000/svg">'
+        "<!-- matches --fc-chrome-rgb exactly --></svg>"
+    )
+    with pytest.raises(ET.ParseError):
+        ET.fromstring(broken)

tests/test_source_service.py

@@ -388,14 +388,17 @@ async def test_update_while_enabled_keeps_failure_state(db):
 async def _source_with_content(db, svc, artist):
     """A source under `artist` with one post + one image it contributed."""
     from backend.app.models import ImageProvenance, ImageRecord, Post
+    # Any registered platform will do — reassign never reads the platform, and
+    # never moves files (the storage path is immutable). This used pixiv until
+    # pixiv was retired (milestone #406) and `create` began refusing it.
     rec = await svc.create(
-        artist_id=artist.id, platform="pixiv",
-        url=f"https://www.pixiv.net/users/{artist.id}",
+        artist_id=artist.id, platform="hentaifoundry",
+        url=f"https://www.hentai-foundry.com/user/{artist.slug}/profile",
     )
     post = Post(source_id=rec.id, artist_id=artist.id, external_post_id="p1")
     db.add(post)
     img = ImageRecord(
-        path=f"/images/{artist.slug}/pixiv/pixiv/1_a_00.jpg",
+        path=f"/images/{artist.slug}/hentaifoundry/hentaifoundry/1_a_00.jpg",
         sha256=str(artist.id).rjust(64, "0"), size_bytes=1, mime="image/jpeg",
         width=1, height=1, origin="imported_filesystem",
         integrity_status="unknown", artist_id=artist.id,

tests/test_subscribestar_memberships.py

@@ -22,8 +22,8 @@ from types import SimpleNamespace
 
 import pytest
 
-from backend.app.services.membership_roster import has_paid_access, roster_user_id
-from backend.app.services.native_ingest_common import Membership
+from backend.app.services.membership_roster import roster_user_id
+from backend.app.services.native_ingest_common import Membership, has_paid_access
 from backend.app.services.subscribestar_client import (
     SubscribeStarAuthError,
     SubscribeStarClient,