Sync from kink_cli (Docker Space)

api.py

@@ -247,6 +247,10 @@ async def lifespan(_app: FastAPI):
         user_snapshot_hub = None  # type: ignore[assignment]
     if user_snapshot_hub is not None and user_snapshot_hub.snapshot_enabled():
         interval_s = float(os.environ.get("KINK_USER_SNAPSHOT_INTERVAL_S", "60") or "60")
+        print(
+            f"[kink_cli] user-state snapshot ENABLED — repo={user_snapshot_hub.snapshot_repo()} "
+            f"file={user_snapshot_hub.snapshot_filename()} interval={interval_s:.0f}s"
+        )
 
         async def _start_when_ready() -> None:
             while _backend_impl is None:
@@ -254,6 +258,13 @@ async def lifespan(_app: FastAPI):
             await _user_snapshot_flusher(_backend_impl.path, interval_s)
 
         flusher_task = asyncio.create_task(_start_when_ready())
+    else:
+        repo = user_snapshot_hub.snapshot_repo() if user_snapshot_hub is not None else "<no module>"
+        has_token = bool((os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN") or "").strip())
+        print(
+            f"[kink_cli] user-state snapshot DISABLED — repo={repo!r} HF_TOKEN={'set' if has_token else 'missing'}; "
+            "users will NOT persist across container restarts. Set HF_TOKEN (and KINK_USER_SNAPSHOT_REPO if needed) to enable."
+        )
 
     try:
         yield
@@ -567,6 +578,17 @@ def health() -> dict:
         if isinstance(cache_payload, dict) and isinstance(cache_payload.get("users", {}), dict)
         else None
     )
+    snapshot_payload: dict[str, Any] = {"enabled": False}
+    try:
+        from backend import user_snapshot_hub as _hub
+        snapshot_payload = {
+            "enabled": _hub.snapshot_enabled(),
+            "repo": _hub.snapshot_repo() or None,
+            "filename": _hub.snapshot_filename(),
+            "has_hf_token": bool((os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN") or "").strip()),
+        }
+    except Exception:  # noqa: BLE001
+        pass
     return {
         "ok": True,
         "store_path": str(store_path),
@@ -575,6 +597,7 @@ def health() -> dict:
         "warnings": warnings,
         "media": _media_health_payload(),
         "stats": b.catalog_stats(),
+        "user_snapshot": snapshot_payload,
         "recsys": {
             "source": b.recsys_settings.source,
             "settings_path": str(settings_path),

backend/user_snapshot_hub.py

@@ -1,9 +1,13 @@
 """Hugging Face Hub dataset I/O for the user-state snapshot.
 
-Auth + repo come from environment so the snapshotter is a no-op when not configured:
-  KINK_USER_SNAPSHOT_REPO     ``owner/dataset`` of a private Hub dataset (required to enable)
-  KINK_USER_SNAPSHOT_FILENAME default ``user_state.db``
-  HF_TOKEN                    write token; reuses the same secret as the catalog/Space deploy
+Snapshot subsystem activates whenever an HF_TOKEN is present and a snapshot repo is configured.
+The repo defaults to the deploy owner's ``kink-userstate`` dataset so user persistence works
+out of the box without needing a Space-variable flip:
+
+  HF_TOKEN                    write token; reuses the same secret as the catalog/Space deploy.
+  KINK_USER_SNAPSHOT_REPO     overrides ``owner/dataset`` of the private Hub dataset.
+  KINK_USER_SNAPSHOT_FILENAME defaults to ``user_state.db``.
+  HF_SPACE_REPO               when set, falls back to ``<owner>/kink-userstate``.
 """
 from __future__ import annotations
 
@@ -14,10 +18,28 @@ from pathlib import Path
 logger = logging.getLogger(__name__)
 
 DEFAULT_SNAPSHOT_FILENAME = "user_state.db"
+# Hard-coded fallback so persistence works on the canonical Perplexed7675 deploy without any
+# Space-variable setup. Override with KINK_USER_SNAPSHOT_REPO for any other deploy.
+HARDCODED_SNAPSHOT_REPO_FALLBACK = "Perplexed7675/kink-userstate"
+
+
+def _derive_snapshot_repo_from_space() -> str:
+    """If HF_SPACE_REPO=owner/space, default the snapshot dataset to ``owner/kink-userstate``."""
+    space = (os.environ.get("HF_SPACE_REPO") or "").strip()
+    if "/" not in space:
+        return ""
+    owner = space.split("/", 1)[0].strip()
+    return f"{owner}/kink-userstate" if owner else ""
 
 
 def snapshot_repo() -> str:
-    return (os.environ.get("KINK_USER_SNAPSHOT_REPO") or "").strip()
+    explicit = (os.environ.get("KINK_USER_SNAPSHOT_REPO") or "").strip()
+    if explicit:
+        return explicit
+    derived = _derive_snapshot_repo_from_space()
+    if derived:
+        return derived
+    return HARDCODED_SNAPSHOT_REPO_FALLBACK
 
 
 def snapshot_filename() -> str:
@@ -25,7 +47,9 @@ def snapshot_filename() -> str:
 
 
 def snapshot_enabled() -> bool:
-    return bool(snapshot_repo())
+    """True only when both a repo and a write token are available; otherwise the flusher would
+    silently fail every minute and we'd rather log the miss once on boot."""
+    return bool(snapshot_repo()) and bool(_hf_token())
 
 
 def _hf_token() -> str | None:

frontend/discover.js

@@ -39,8 +39,6 @@ export function DiscoverView({
   const [searchDebounced, setSearchDebounced] = useState("");
   const [infoExpanded, setInfoExpanded] = useState(false);
   const [submittingRating, setSubmittingRating] = useState(false);
-  const [savedFlashKey, setSavedFlashKey] = useState(0);
-  const savedFlashTimerRef = useRef(null);
   /** Synchronous guard so rapid taps (Playwright ``force``) cannot fire before ``setSubmittingRating`` re-renders. */
   const ratingBusyRef = useRef(false);
   const [scenarioHint, setScenarioHint] = useState(null);
@@ -177,9 +175,6 @@ export function DiscoverView({
     try {
       const directionsOverride = (kink?.direction_shape === "mutual") ? ["together"] : null;
       await Promise.resolve(onRate(kinkId, rating, directionsOverride));
-      setSavedFlashKey((k) => k + 1);
-      if (savedFlashTimerRef.current) clearTimeout(savedFlashTimerRef.current);
-      savedFlashTimerRef.current = setTimeout(() => setSavedFlashKey(0), 1200);
       onDiscoverSheetDirectionsChange(["together"]);
       setImageRevealed(false);
       setInfoExpanded(false);
@@ -384,9 +379,6 @@ export function DiscoverView({
                     </div>
                   </div>
                 `}
-            ${savedFlashKey
-              ? html`<div className="discover-saved-flash" data-testid="discover-saved-flash" key=${savedFlashKey}>Saved ✓</div>`
-              : null}
             <${ActionBar} onRate=${handleRate} />
           `
         : null}

frontend/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Play List</title>
     <link rel="icon" href="/favicon.ico" type="image/jpeg" />
-    <script type="module" crossorigin src="/frontend/assets/index-Cu3GV3BP.js"></script>
+    <script type="module" crossorigin src="/frontend/assets/index-Rd0bHvq-.js"></script>
     <link rel="stylesheet" crossorigin href="/frontend/assets/index-DUwIsfuc.css">
   </head>
   <body>

scripts/collect_fetlife_profile_pictures.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import hmac
+import json
+import random
+import re
+import secrets
+import sys
+import time
+from dataclasses import dataclass
+from html import unescape
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+from bs4 import BeautifulSoup
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from fetlife_collect import (
+    BASE_URL,
+    DEFAULT_HEADERS,
+    RAW_ROOT,
+    CDPFetcher,
+    best_image_url_from_img,
+    classify_html,
+    cookies_client,
+    trusted_profile,
+)
+
+
+DEFAULT_OUT_ROOT = Path("data/cached_assets/fetlife_profiles")
+DEFAULT_SALT_PATH = Path("data/fetlife_auth/profile_hash_salt")
+PROFILE_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_-]*$")
+USER_ID_RE = re.compile(r"^users/(?P<user_id>\d+)(?:/.*)?$")
+
+
+@dataclass(frozen=True)
+class ProfileSeed:
+    nickname: str
+    locale: str = ""
+    consent_basis: str = ""
+
+
+@dataclass(frozen=True)
+class ProfilePictureCard:
+    picture_path: str
+    image_url: str
+    picture_hash: str
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Collect profile-picture thumbnails for a consented list of FetLife profiles."
+    )
+    parser.add_argument("--input", required=True, help="TXT or CSV of consented profile nicknames/URLs.")
+    parser.add_argument("--locale", default="Tulsa, Oklahoma", help="Locale tag written to manifests.")
+    parser.add_argument("--profile", default=None, help="Chrome profile dir override.")
+    parser.add_argument("--out-root", default=str(DEFAULT_OUT_ROOT), help="Private image cache root.")
+    parser.add_argument("--raw-root", default=str(RAW_ROOT), help="Raw HTML capture root.")
+    parser.add_argument("--salt-file", default=str(DEFAULT_SALT_PATH), help="Salt file for profile/path hashes.")
+    parser.add_argument("--limit", type=int, default=0, help="Max profiles to process; 0 means all.")
+    parser.add_argument("--offset", type=int, default=0, help="Skip this many input profiles.")
+    parser.add_argument("--min-delay-ms", type=int, default=2200)
+    parser.add_argument("--jitter-ms", type=int, default=1200)
+    parser.add_argument("--force", action="store_true", help="Redownload images and overwrite existing manifest.")
+    parser.add_argument("--dry-run", action="store_true", help="Fetch/parse pages but do not download images.")
+    parser.add_argument(
+        "--use-existing-html",
+        action="store_true",
+        help="Parse existing raw HTML instead of opening the browser. Useful for tests/reports; signed image URLs may expire.",
+    )
+    return parser.parse_args()
+
+
+def load_or_create_salt(path: Path) -> bytes:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        text = path.read_text(encoding="utf-8").strip()
+        if text:
+            return text.encode("utf-8")
+    salt = secrets.token_hex(32)
+    path.write_text(salt + "\n", encoding="utf-8")
+    path.chmod(0o600)
+    return salt.encode("utf-8")
+
+
+def keyed_hash(value: str, salt: bytes, length: int = 16) -> str:
+    digest = hmac.new(salt, value.lower().encode("utf-8"), hashlib.sha256).hexdigest()
+    return digest[:length]
+
+
+def normalize_profile_token(value: str) -> str | None:
+    token = value.strip()
+    if not token or token.startswith("#"):
+        return None
+    parsed = urlparse(token)
+    path = parsed.path.strip("/") if parsed.scheme or parsed.netloc else token.strip("/")
+    if not path:
+        return None
+    user_id = USER_ID_RE.match(path)
+    if user_id:
+        return f"users/{user_id.group('user_id')}"
+    first_segment = path.split("/", 1)[0]
+    if PROFILE_RE.match(first_segment):
+        return first_segment
+    return None
+
+
+def load_profile_seeds(path: Path, default_locale: str) -> list[ProfileSeed]:
+    if path.suffix.lower() == ".csv":
+        return load_profile_seeds_csv(path, default_locale)
+    return load_profile_seeds_text(path, default_locale)
+
+
+def load_profile_seeds_text(path: Path, default_locale: str) -> list[ProfileSeed]:
+    seeds: list[ProfileSeed] = []
+    seen: set[str] = set()
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        token = normalize_profile_token(raw_line)
+        if not token or token.lower() in seen:
+            continue
+        seen.add(token.lower())
+        seeds.append(ProfileSeed(nickname=token, locale=default_locale))
+    return seeds
+
+
+def load_profile_seeds_csv(path: Path, default_locale: str) -> list[ProfileSeed]:
+    seeds: list[ProfileSeed] = []
+    seen: set[str] = set()
+    with path.open(newline="", encoding="utf-8") as fh:
+        sample = fh.read(2048)
+        fh.seek(0)
+        has_header = csv.Sniffer().has_header(sample) if sample.strip() else False
+        if has_header:
+            reader = csv.DictReader(fh)
+            for row in reader:
+                token = normalize_profile_token(
+                    row.get("nickname", "") or row.get("profile_url", "") or row.get("url", "")
+                )
+                if not token or token.lower() in seen:
+                    continue
+                seen.add(token.lower())
+                seeds.append(
+                    ProfileSeed(
+                        nickname=token,
+                        locale=(row.get("locale") or default_locale).strip(),
+                        consent_basis=(row.get("consent_basis") or "").strip(),
+                    )
+                )
+        else:
+            reader = csv.reader(fh)
+            for row in reader:
+                if not row:
+                    continue
+                token = normalize_profile_token(row[0])
+                if not token or token.lower() in seen:
+                    continue
+                seen.add(token.lower())
+                seeds.append(ProfileSeed(nickname=token, locale=default_locale))
+    return seeds
+
+
+def profile_path(seed: ProfileSeed) -> str:
+    return f"/{seed.nickname}" if not seed.nickname.startswith("users/") else f"/{seed.nickname}"
+
+
+def profile_pictures_url(seed: ProfileSeed) -> str:
+    return f"{BASE_URL}{profile_path(seed)}/pictures"
+
+
+def parse_profile_picture_cards(html: str, seed: ProfileSeed, salt: bytes) -> list[ProfilePictureCard]:
+    soup = BeautifulSoup(html, "html.parser")
+    path_prefix = re.escape(profile_path(seed))
+    picture_path_re = re.compile(rf"^{path_prefix}/pictures/\d+$")
+    cards: list[ProfilePictureCard] = []
+    seen_paths: set[str] = set()
+    for link in soup.find_all("a", href=True):
+        raw_href = link["href"]
+        path = urlparse(raw_href).path if raw_href.startswith("http") else raw_href.split("?", 1)[0]
+        if not picture_path_re.match(path) or path in seen_paths:
+            continue
+        img = link.find("img")
+        if not img:
+            continue
+        image_url = unescape(best_image_url_from_img(img))
+        if not image_url.startswith("http"):
+            continue
+        if "picv2-" not in image_url and "picture/attachments/" not in image_url:
+            continue
+        seen_paths.add(path)
+        cards.append(
+            ProfilePictureCard(
+                picture_path=path,
+                image_url=image_url,
+                picture_hash=keyed_hash(path, salt),
+            )
+        )
+    return cards
+
+
+def content_suffix(url: str, content_type: str = "") -> str:
+    suffix = Path(urlparse(url).path).suffix.lower()
+    if suffix in {".jpg", ".jpeg", ".webp", ".png"}:
+        return suffix
+    if "png" in content_type:
+        return ".png"
+    if "webp" in content_type:
+        return ".webp"
+    return ".jpg"
+
+
+def serial_delay(min_delay_ms: int, jitter_ms: int) -> None:
+    delay_ms = max(0, min_delay_ms) + random.randint(0, max(0, jitter_ms))
+    if delay_ms:
+        time.sleep(delay_ms / 1000.0)
+
+
+def existing_manifest_complete(manifest_path: Path) -> bool:
+    if not manifest_path.exists():
+        return False
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return False
+    return payload.get("state") == "ok"
+
+
+def fetch_html(
+    seed: ProfileSeed,
+    *,
+    cdp: CDPFetcher | None,
+    raw_path: Path,
+    use_existing_html: bool,
+) -> tuple[str, str]:
+    if use_existing_html:
+        existing_path = raw_path
+        if not existing_path.exists():
+            legacy_stem = re.sub(r"[^a-zA-Z0-9._-]+", "__", seed.nickname)
+            legacy_path = raw_path.parent / f"{legacy_stem}__pictures.html"
+            if legacy_path.exists():
+                existing_path = legacy_path
+        if not existing_path.exists():
+            raise FileNotFoundError(f"missing raw html for {seed.nickname}: {raw_path}")
+        return existing_path.read_text(encoding="utf-8", errors="ignore"), "existing_html"
+    if cdp is None:
+        raise RuntimeError("CDP fetcher is required unless --use-existing-html is set")
+    capture = cdp.fetch(profile_pictures_url(seed), scroll=True)
+    html = str(capture["html"])
+    raw_path.parent.mkdir(parents=True, exist_ok=True)
+    raw_path.write_text(html, encoding="utf-8")
+    return html, str(capture.get("url", ""))
+
+
+def download_cards(
+    client: httpx.Client,
+    cards: list[ProfilePictureCard],
+    *,
+    out_dir: Path,
+    dry_run: bool,
+    force: bool,
+) -> list[dict[str, object]]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    rows: list[dict[str, object]] = []
+    for index, card in enumerate(cards, start=1):
+        referer = f"{BASE_URL}{card.picture_path}"
+        planned_name = f"profile_picture_{index:03d}_{card.picture_hash}"
+        existing = next(out_dir.glob(planned_name + ".*"), None)
+        if existing and not force:
+            rows.append(
+                {
+                    "index": index,
+                    "ok": True,
+                    "state": "exists",
+                    "file": existing.name,
+                    "bytes": existing.stat().st_size,
+                    "picture_hash": card.picture_hash,
+                }
+            )
+            continue
+        if dry_run:
+            rows.append(
+                {
+                    "index": index,
+                    "ok": True,
+                    "state": "dry_run",
+                    "picture_hash": card.picture_hash,
+                }
+            )
+            continue
+        try:
+            response = client.get(card.image_url, headers={**DEFAULT_HEADERS, "referer": referer})
+        except httpx.HTTPError as exc:
+            rows.append({"index": index, "ok": False, "state": "http_error", "error": str(exc)})
+            continue
+        content_type = response.headers.get("content-type", "")
+        if response.status_code != 200 or not content_type.startswith("image/"):
+            rows.append(
+                {
+                    "index": index,
+                    "ok": False,
+                    "state": "download_failed",
+                    "status": response.status_code,
+                    "content_type": content_type,
+                }
+            )
+            continue
+        target = out_dir / f"{planned_name}{content_suffix(card.image_url, content_type)}"
+        target.write_bytes(response.content)
+        rows.append(
+            {
+                "index": index,
+                "ok": True,
+                "state": "downloaded",
+                "file": target.name,
+                "bytes": len(response.content),
+                "picture_hash": card.picture_hash,
+            }
+        )
+    return rows
+
+
+def process_seed(
+    seed: ProfileSeed,
+    *,
+    profile_hash: str,
+    salt: bytes,
+    raw_root: Path,
+    out_root: Path,
+    cdp: CDPFetcher | None,
+    client: httpx.Client,
+    use_existing_html: bool,
+    dry_run: bool,
+    force: bool,
+) -> dict[str, object]:
+    out_dir = out_root / profile_hash
+    manifest_path = out_dir / "manifest.json"
+    if not force and not dry_run and existing_manifest_complete(manifest_path):
+        return {
+            "profile_hash": profile_hash,
+            "state": "skipped_existing",
+            "output_dir": str(out_dir),
+        }
+    raw_path = raw_root / f"profile_pictures__{profile_hash}.html"
+    html, final_url = fetch_html(seed, cdp=cdp, raw_path=raw_path, use_existing_html=use_existing_html)
+    page_state = classify_html(html)
+    cards = parse_profile_picture_cards(html, seed, salt)
+    downloads = download_cards(client, cards, out_dir=out_dir, dry_run=dry_run, force=force)
+    ok_downloads = sum(1 for row in downloads if row.get("ok"))
+    manifest = {
+        "schema": "fetlife_profile_pictures_v1",
+        "state": "ok" if page_state == "ok" else page_state,
+        "profile_hash": profile_hash,
+        "locale": seed.locale,
+        "consent_basis": seed.consent_basis,
+        "source": "consented_seed_list",
+        "profile_path_hash": keyed_hash(profile_path(seed), salt),
+        "pictures_path_hash": keyed_hash(f"{profile_path(seed)}/pictures", salt),
+        "source_html": str(raw_path),
+        "final_url_hash": keyed_hash(final_url, salt) if final_url else "",
+        "candidate_count": len(cards),
+        "downloaded_ok": ok_downloads,
+        "downloads": downloads,
+    }
+    out_dir.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return {
+        "profile_hash": profile_hash,
+        "state": manifest["state"],
+        "candidates": len(cards),
+        "downloaded_ok": ok_downloads,
+        "output_dir": str(out_dir),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    input_path = Path(args.input)
+    out_root = Path(args.out_root)
+    raw_root = Path(args.raw_root)
+    salt = load_or_create_salt(Path(args.salt_file))
+    seeds = load_profile_seeds(input_path, args.locale)
+    if args.offset:
+        seeds = seeds[args.offset :]
+    if args.limit:
+        seeds = seeds[: args.limit]
+    if not seeds:
+        print(json.dumps({"state": "no_profiles", "input": str(input_path)}), file=sys.stderr)
+        return 1
+
+    cdp: CDPFetcher | None = None
+    client = cookies_client()
+    results: list[dict[str, object]] = []
+    try:
+        if not args.use_existing_html:
+            cdp = CDPFetcher(args.profile or trusted_profile())
+        for index, seed in enumerate(seeds, start=1):
+            profile_hash = keyed_hash(seed.nickname, salt)
+            try:
+                result = process_seed(
+                    seed,
+                    profile_hash=profile_hash,
+                    salt=salt,
+                    raw_root=raw_root,
+                    out_root=out_root,
+                    cdp=cdp,
+                    client=client,
+                    use_existing_html=args.use_existing_html,
+                    dry_run=args.dry_run,
+                    force=args.force,
+                )
+            except Exception as exc:  # noqa: BLE001
+                result = {"profile_hash": profile_hash, "state": "failed", "error": str(exc)}
+            result["index"] = index
+            results.append(result)
+            print(json.dumps(result), flush=True)
+            if index < len(seeds):
+                serial_delay(args.min_delay_ms, args.jitter_ms)
+    finally:
+        client.close()
+        if cdp is not None:
+            cdp.close()
+    summary = {
+        "state": "done",
+        "profiles": len(results),
+        "ok": sum(1 for row in results if row.get("state") in {"ok", "skipped_existing"}),
+        "failed": sum(1 for row in results if row.get("state") == "failed"),
+        "downloaded_ok": sum(int(row.get("downloaded_ok") or 0) for row in results),
+    }
+    print(json.dumps(summary), flush=True)
+    return 0 if summary["failed"] == 0 else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/filter_fetlife_profile_candidates.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import random
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from scripts.collect_fetlife_profile_pictures import normalize_profile_token
+
+
+TRUTHY = {"1", "true", "yes", "y", "on"}
+FALSEY = {"0", "false", "no", "n", "off"}
+PROFILE_URL_PREFIX = "https://fetlife.com/"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Filter a supplied FetLife profile candidate CSV for review.")
+    parser.add_argument("--input", required=True, help="CSV containing supplied profile metadata.")
+    parser.add_argument("--output", required=True, help="Filtered CSV to write.")
+    parser.add_argument("--locale", action="append", default=[], help="Case-insensitive substring match on locale/location.")
+    parser.add_argument("--city", action="append", default=[], help="Case-insensitive city filter.")
+    parser.add_argument("--state", action="append", default=[], help="Case-insensitive state/region filter.")
+    parser.add_argument("--gender", action="append", default=[], help="Case-insensitive gender filter; repeatable.")
+    parser.add_argument("--role", action="append", default=[], help="Case-insensitive role filter; repeatable.")
+    parser.add_argument("--orientation", action="append", default=[], help="Case-insensitive orientation filter; repeatable.")
+    parser.add_argument("--age-min", type=int, default=None)
+    parser.add_argument("--age-max", type=int, default=None)
+    parser.add_argument("--has-pictures", action="store_true", help="Keep rows whose has_pictures column is truthy.")
+    parser.add_argument("--consent-status", action="append", default=[], help="Optional consent_status filter.")
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--sample", type=int, default=0, help="Randomly sample N rows after filtering.")
+    parser.add_argument("--seed", type=int, default=1, help="Random seed for --sample.")
+    return parser.parse_args()
+
+
+def split_terms(values: list[str]) -> list[str]:
+    terms: list[str] = []
+    for value in values:
+        for part in value.split(","):
+            term = part.strip().lower()
+            if term:
+                terms.append(term)
+    return terms
+
+
+def first_value(row: dict[str, str], names: tuple[str, ...]) -> str:
+    lower_map = {key.strip().lower(): value for key, value in row.items()}
+    for name in names:
+        value = lower_map.get(name)
+        if value is not None and str(value).strip():
+            return str(value).strip()
+    return ""
+
+
+def normalized_profile(row: dict[str, str]) -> tuple[str, str]:
+    raw = first_value(row, ("nickname", "profile_url", "url", "profile", "handle"))
+    nickname = normalize_profile_token(raw) or ""
+    profile_url = first_value(row, ("profile_url", "url"))
+    if nickname and not profile_url:
+        profile_url = PROFILE_URL_PREFIX + nickname
+    return nickname, profile_url
+
+
+def parse_age(value: str) -> int | None:
+    text = value.strip()
+    if not text:
+        return None
+    match = re.search(r"\d{1,3}", text)
+    if not match:
+        return None
+    age = int(match.group(0))
+    if 18 <= age <= 120:
+        return age
+    return None
+
+
+def truthy(value: str) -> bool | None:
+    normalized = value.strip().lower()
+    if normalized in TRUTHY:
+        return True
+    if normalized in FALSEY:
+        return False
+    return None
+
+
+def contains_any(value: str, terms: list[str]) -> bool:
+    if not terms:
+        return True
+    haystack = value.lower()
+    return any(term in haystack for term in terms)
+
+
+def exactish_any(value: str, terms: list[str]) -> bool:
+    if not terms:
+        return True
+    normalized = value.strip().lower()
+    return any(normalized == term or term in normalized for term in terms)
+
+
+def row_matches(row: dict[str, str], args: argparse.Namespace) -> bool:
+    locale_terms = split_terms(args.locale)
+    city_terms = split_terms(args.city)
+    state_terms = split_terms(args.state)
+    gender_terms = split_terms(args.gender)
+    role_terms = split_terms(args.role)
+    orientation_terms = split_terms(args.orientation)
+    consent_terms = split_terms(args.consent_status)
+
+    locale = first_value(row, ("locale", "location", "region"))
+    city = first_value(row, ("city", "town"))
+    state = first_value(row, ("state", "province", "region"))
+    gender = first_value(row, ("gender", "sex"))
+    role = first_value(row, ("role", "relationship_role"))
+    orientation = first_value(row, ("orientation", "sexual_orientation"))
+    consent_status = first_value(row, ("consent_status", "consent"))
+
+    if not contains_any(" ".join([locale, city, state]), locale_terms):
+        return False
+    if not exactish_any(city, city_terms):
+        return False
+    if not exactish_any(state, state_terms):
+        return False
+    if not exactish_any(gender, gender_terms):
+        return False
+    if not exactish_any(role, role_terms):
+        return False
+    if not exactish_any(orientation, orientation_terms):
+        return False
+    if not exactish_any(consent_status, consent_terms):
+        return False
+
+    age = parse_age(first_value(row, ("age", "years_old")))
+    if args.age_min is not None and (age is None or age < args.age_min):
+        return False
+    if args.age_max is not None and (age is None or age > args.age_max):
+        return False
+    if args.has_pictures:
+        has_pictures = truthy(first_value(row, ("has_pictures", "pictures", "profile_pictures")))
+        if has_pictures is not True:
+            return False
+
+    nickname, _ = normalized_profile(row)
+    return bool(nickname)
+
+
+def output_fieldnames(input_fieldnames: list[str]) -> list[str]:
+    fields = ["nickname", "profile_url"]
+    for field in input_fieldnames:
+        if field not in fields:
+            fields.append(field)
+    for field in ("consent_status", "consent_basis", "review_notes"):
+        if field not in fields:
+            fields.append(field)
+    return fields
+
+
+def filter_rows(rows: list[dict[str, str]], args: argparse.Namespace) -> list[dict[str, str]]:
+    filtered: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for row in rows:
+        if not row_matches(row, args):
+            continue
+        nickname, profile_url = normalized_profile(row)
+        dedupe_key = nickname.lower()
+        if dedupe_key in seen:
+            continue
+        seen.add(dedupe_key)
+        updated = dict(row)
+        updated["nickname"] = nickname
+        updated["profile_url"] = profile_url
+        updated.setdefault("consent_status", "")
+        updated.setdefault("consent_basis", "")
+        updated.setdefault("review_notes", "")
+        filtered.append(updated)
+
+    if args.sample:
+        rng = random.Random(args.seed)
+        filtered = rng.sample(filtered, min(args.sample, len(filtered)))
+    if args.limit:
+        filtered = filtered[: args.limit]
+    return filtered
+
+
+def main() -> int:
+    args = parse_args()
+    input_path = Path(args.input)
+    output_path = Path(args.output)
+    with input_path.open(newline="", encoding="utf-8") as fh:
+        reader = csv.DictReader(fh)
+        rows = list(reader)
+        input_fieldnames = list(reader.fieldnames or [])
+    filtered = filter_rows(rows, args)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with output_path.open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=output_fieldnames(input_fieldnames), extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(filtered)
+    print(f"read={len(rows)} wrote={len(filtered)} output={output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify_hf_stack.py

@@ -68,7 +68,7 @@ def _assert_live_frontend_recs_error_shaping_once(root: str) -> tuple[str, str]:
     for label, needle in {
         "HTML API error shaping": "the response was a web page, not JSON",
         "generic API failure shaping": "Request failed (",
-        "recommendations UI fallback": "Could not load recommendations (server error)",
+        "recommendations retry control": "discover-recs-retry",
     }.items():
         if needle not in bundle_js:
             raise RuntimeError(

tests/test_collect_fetlife_profile_pictures.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from scripts.collect_fetlife_profile_pictures import (
+    ProfileSeed,
+    load_profile_seeds,
+    normalize_profile_token,
+    parse_profile_picture_cards,
+)
+
+
+def test_normalize_profile_token_accepts_nickname_and_url() -> None:
+    assert normalize_profile_token("art6b") == "art6b"
+    assert normalize_profile_token("https://fetlife.com/art6b/pictures") == "art6b"
+    assert normalize_profile_token(" https://fetlife.com/users/12345 ") == "users/12345"
+    assert normalize_profile_token(" https://fetlife.com/users/12345/pictures ") == "users/12345"
+    assert normalize_profile_token("# comment") is None
+
+
+def test_load_profile_seeds_text_deduplicates(tmp_path: Path) -> None:
+    seed_file = tmp_path / "profiles.txt"
+    seed_file.write_text("art6b\nhttps://fetlife.com/art6b\nOther_User\n", encoding="utf-8")
+
+    seeds = load_profile_seeds(seed_file, "Tulsa, Oklahoma")
+
+    assert seeds == [
+        ProfileSeed(nickname="art6b", locale="Tulsa, Oklahoma"),
+        ProfileSeed(nickname="Other_User", locale="Tulsa, Oklahoma"),
+    ]
+
+
+def test_parse_profile_picture_cards_uses_profile_picture_paths_only() -> None:
+    html = """
+    <a href="/art6b/pictures">Pictures</a>
+    <a href="/art6b/pictures/101">
+      <img
+        src="https://picv2-c160.cdn.fetlife.com/7398125/a/c160.jpg"
+        srcset="https://picv2-c160.cdn.fetlife.com/7398125/a/c160.jpg 1x,
+                https://picv2-c400.cdn.fetlife.com/7398125/a/c400.jpg 2x">
+    </a>
+    <a href="/SomeoneElse/pictures/202">
+      <img src="https://picv2-c400.cdn.fetlife.com/1/b/c400.jpg">
+    </a>
+    <a href="/art6b/pictures/303">
+      <img src="https://static.example/not-a-profile-image.jpg">
+    </a>
+    """
+
+    cards = parse_profile_picture_cards(html, ProfileSeed(nickname="art6b"), b"test-salt")
+
+    assert len(cards) == 1
+    assert cards[0].picture_path == "/art6b/pictures/101"
+    assert "c400.jpg" in cards[0].image_url

tests/test_filter_fetlife_profile_candidates.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from argparse import Namespace
+
+from scripts.filter_fetlife_profile_candidates import filter_rows
+
+
+def _args(**overrides: object) -> Namespace:
+    defaults = {
+        "locale": [],
+        "city": [],
+        "state": [],
+        "gender": [],
+        "role": [],
+        "orientation": [],
+        "age_min": None,
+        "age_max": None,
+        "has_pictures": False,
+        "consent_status": [],
+        "limit": 0,
+        "sample": 0,
+        "seed": 1,
+    }
+    defaults.update(overrides)
+    return Namespace(**defaults)
+
+
+def test_filter_rows_by_locale_gender_age_and_pictures() -> None:
+    rows = [
+        {
+            "profile_url": "https://fetlife.com/alpha",
+            "city": "Tulsa",
+            "state": "Oklahoma",
+            "gender": "Female",
+            "age": "35",
+            "has_pictures": "yes",
+        },
+        {
+            "profile_url": "https://fetlife.com/bravo",
+            "city": "Tulsa",
+            "state": "Oklahoma",
+            "gender": "Male",
+            "age": "39",
+            "has_pictures": "yes",
+        },
+        {
+            "profile_url": "https://fetlife.com/charlie",
+            "city": "Oklahoma City",
+            "state": "Oklahoma",
+            "gender": "Female",
+            "age": "35",
+            "has_pictures": "yes",
+        },
+    ]
+
+    filtered = filter_rows(
+        rows,
+        _args(city=["Tulsa"], state=["Oklahoma"], gender=["Female"], age_min=30, age_max=40, has_pictures=True),
+    )
+
+    assert [row["nickname"] for row in filtered] == ["alpha"]
+    assert filtered[0]["profile_url"] == "https://fetlife.com/alpha"
+
+
+def test_filter_rows_dedupes_and_adds_review_columns() -> None:
+    rows = [
+        {"nickname": "alpha", "city": "Tulsa", "state": "Oklahoma"},
+        {"profile_url": "https://fetlife.com/alpha/pictures", "city": "Tulsa", "state": "Oklahoma"},
+    ]
+
+    filtered = filter_rows(rows, _args(city=["Tulsa"]))
+
+    assert len(filtered) == 1
+    assert filtered[0]["consent_status"] == ""
+    assert filtered[0]["consent_basis"] == ""
+    assert filtered[0]["review_notes"] == ""