feather_reader/

web.rs

//! The axum web layer — server-rendered HTML + a dash of htmx, **no SPA**.
//!
//! This module owns the HTTP surface: [`router`] builds an `axum::Router` over
//! the shared [`AppState`], wiring the store, feed, atproto, and config seams into
//! a small set of typography-first, dark-mode-ready views rendered with
//! `askama` templates (under `templates/`). Progressive enhancement is a single
//! vendored `htmx` script plus a tiny keyboard handler (`static/keyboard.js`);
//! every interaction also works as a plain HTML form POST, so the reader is fully
//! usable with JavaScript disabled.
//!
//! ## HTTP surface
//!
//! * `GET  /health` — liveness + version, as `text/plain`.
//! * `GET  /about`, `/standard-site`, `/stats`, `/privacy`, `/terms` — static
//!   and status pages.
//! * `GET  /manage` — feed and folder management.
//! * `GET  /` — the reader: a folders/feeds sidebar (from the PDS records layer)
//!   plus the main article list. Query params pick the scope (`?feed=…` /
//!   `?folder=…` / all) and the view (`?view=unread|all|starred`).
//! * `GET  /entries/{id}` — the clean, distraction-free reader for one entry,
//!   with prev/next within the current list.
//! * `POST /entries/{id}/read` — mark an entry read/unread (htmx row swap).
//! * `POST /entries/{id}/star` — star/unstar; writes a
//!   `community.lexicon.rss.saved` record to the user's PDS.
//! * `POST /saved/{rkey}/delete` — unsave a `saved` record.
//! * `POST /read-all` — mark-all-read (per feed via `?feed=…`, else everything).
//! * `POST /subscriptions` — subscribe by URL (autodiscover → PDS record).
//! * `POST /subscriptions/{rkey}/delete` — unsubscribe (delete the PDS record).
//! * `POST /subscriptions/{rkey}/rename` — retitle / move a feed to a folder.
//! * `POST /folders` — create a folder record.
//! * `POST /folders/{rkey}/rename` — rename a folder record.
//! * `POST /folders/{rkey}/delete` — delete a folder record.
//! * `POST /opml` — OPML import (multipart upload *or* pasted textarea) → bulk
//!   subscription records in the PDS.
//! * `GET  /opml/export` — OPML export (records → a downloadable document).
//! * `GET /login` + `POST /login` + `/oauth/callback` + `/logout` — the atproto
//!   OAuth sign-in flow, on whichever backend `FEATHERREADER_REPO_BACKEND`
//!   selects. `GET /oauth/client-metadata.json` and `/oauth/jwks.json` publish
//!   the Rust client's identity.
//! * `POST /account/delete` — revoke the session and drop this DID's local state.
//! * `GET|POST /beta/redeem` — closed-beta invite redemption.
//! * `GET /claim?t=<token>` — the follow→invite bot's claim link: an opaque token
//!   reserving a pre-minted invite code; behaves like a successful `/beta/redeem`
//!   (sets the reserving cookie → `/login`).
//! * `POST /bot/claims` — headless, shared-secret (`X-Bot-Secret`) mint of a claim
//!   code + token/url for the bot to post. Cap-aware (409 when full).
//! * `POST /admin/invites`, `GET /admin/metrics` — admin-only invite minting and
//!   the backend metrics view.
//!
//! ## Identity — a cookie-resolved atproto session
//!
//! Per-request identity comes from a **signed session cookie** (`fr_session`)
//! keyed by the logged-in DID, set by `oauth_callback` and read by
//! `current_session` / `current_did`. For local runs without the sidecar,
//! [`Config::dev_did`] (env `FEATHERREADER_DEV_DID`) supplies a fallback identity.
//! All PDS reads and writes route through [`AppState::repo`], which dispatches to
//! the sidecar or the Rust OAuth client by `FEATHERREADER_REPO_BACKEND`.

use std::collections::HashMap;
use std::net::IpAddr;
use std::sync::Mutex;
use std::time::{Duration, Instant};

use askama::Template;
use axum::{
    extract::{ConnectInfo, DefaultBodyLimit, Multipart, Path, Query, State},
    http::{header, HeaderMap, StatusCode},
    middleware::{self, Next},
    response::{Html, IntoResponse, Redirect, Response},
    routing::{get, post},
    Form, Router,
};
use serde::Deserialize;
use std::net::SocketAddr;
use tower_http::services::{ServeDir, ServeFile};
use tower_http::set_header::SetResponseHeaderLayer;
use tower_http::trace::TraceLayer;
use tracing::{info, warn};

use crate::config::Config;
use crate::lexicon::{self, Folder, Saved, Subscription};
use crate::safe_link::SafeLink;
use crate::{feed, store, AppState, Session, VERSION};

// The OPML import/export module lives at `src/opml.rs` but isn't declared in the
// crate root (`lib.rs`), which is outside this phase's edit surface. Wire it in
// here via an explicit path so the reader's OPML routes can use the canonical
// `parse_opml` / `to_opml` without duplicating that logic.
#[path = "opml.rs"]
mod opml;

/// The name of the signed session cookie.
const SESSION_COOKIE: &str = "fr_session";

/// The name of the short-lived signed **invite** cookie.
///
/// Set by `POST /beta/redeem` on a valid, capacity-ok code and consumed by the
/// OAuth callback. It reserves *intent* to redeem a specific code before the
/// visitor ever starts the OAuth handshake, so a non-invited visitor can't burn
/// a sidecar handshake (pre-handshake gate). It carries the invite code, HMAC-
/// signed with the same key as the session cookie.
const INVITE_COOKIE: &str = "fr_invite";

/// Browser-binding cookie for an in-flight OAuth login (Rust backend only).
///
/// `state` alone cannot stop a login CSRF: it lives in a server-global table, so
/// a stolen `state` replayed from ANOTHER browser matches just as well as from
/// the one that started the flow. This cookie is what makes the callback
/// browser-specific — the pending row stores only its hash, and a callback that
/// cannot present it is refused.
const OAUTH_BINDING_COOKIE: &str = "fr_oauth";

/// How long an in-flight login may sit, matching the pending row's own TTL.
const OAUTH_BINDING_MAX_AGE_SECS: i64 = 600;

/// TTL (seconds) for a minted invite code and for the reserving invite cookie.
/// Short enough that a reserved-but-unclaimed seat frees quickly.
const INVITE_TTL_SECS: i64 = 1800;

/// The canonical AGPL-3.0 source repository — surfaced in the footer, the
/// sign-in pitch, and `/about`.
const REPO_URL: &str = "https://github.com/justin-stanley/feather-reader";

/// The tip / support link (cloud plan public-experiment UI).
const KOFI_URL: &str = "https://ko-fi.com/justinstanley";

/// The published crate on crates.io — surfaced on the signed-out landing page.
const CRATES_URL: &str = "https://crates.io/crates/feather-reader";

/// The Content-Security-Policy applied to every response.
///
/// Tuned to keep the app fully working while neutralising injected script:
/// * `default-src 'self'` — same-origin baseline.
/// * `script-src 'self'` — only our vendored `htmx.min.js` + `keyboard.js` from
///   `/static`; **no** `'unsafe-inline'`, so an injected `<script>` or a
///   `javascript:` href (F4) cannot execute. (The design's templates carry no
///   inline event handlers — every control is wired in `keyboard.js`.)
/// * `style-src 'self' 'unsafe-inline'` — the linked stylesheet plus the small
///   inline styles htmx toggles for its request indicators.
/// * `img-src 'self' https: data:` — feed content routinely embeds remote
///   images; allow https + data URIs but not other schemes.
/// * `form-action 'self'`, `base-uri 'self'`, `frame-ancestors 'none'` — lock
///   down form posts, `<base>` hijacking, and clickjacking.
/// * `object-src 'none'` — no plugins.
const CONTENT_SECURITY_POLICY: &str = "default-src 'self'; \
     script-src 'self'; \
     style-src 'self' 'unsafe-inline'; \
     img-src 'self' https: data:; \
     font-src 'self'; \
     connect-src 'self'; \
     form-action 'self'; \
     base-uri 'self'; \
     frame-ancestors 'none'; \
     object-src 'none'";

/// The resolved identity for the current request.
///
/// `did` is the primary key for all per-user local state; `handle` is display
/// only; `sid` is the opaque server-side session id the cookie carried (needed
/// so logout can revoke exactly this session). Sourced from the signed cookie
/// (real login) or, if none, the configured dev DID fallback.
#[derive(Clone, Debug)]
struct CurrentUser {
    did: String,
    handle: Option<String>,
    /// The opaque session id, if this identity came from a real cookie session
    /// (absent for the dev-DID fallback, which has no server-side session row).
    sid: Option<String>,
}

/// Resolve the current request's session from the signed cookie, falling back to
/// the configured dev DID (env `FEATHERREADER_DEV_DID`) for local runs.
///
/// The cookie carries an opaque server-minted session id (not the DID). We
/// verify its HMAC, look the id up in the registry, and — crucially —
/// **re-check the DID against the closed-beta gate on every request**
/// ([`store::has_beta_access`]), not just at the OAuth callback, so revoking a
/// DID's beta seat takes effect immediately for already-issued cookies. (The
/// gate replaced the old static `ALLOWED_DIDS` check; `ALLOWED_DIDS` remains the
/// admin-bootstrap seed, granted a seat at startup via `ensure_seed`.)
async fn current_session(state: &AppState, headers: &HeaderMap) -> Option<CurrentUser> {
    if let Some(sid) = cookie::verify_session(headers, &state.config.cookie_secret) {
        if let Some(session) = state.sessions.get(&sid) {
            if store::has_beta_access(&state.db, &session.did)
                .await
                .unwrap_or(false)
            {
                return Some(CurrentUser {
                    did: session.did,
                    handle: session.handle,
                    sid: Some(sid),
                });
            }
            // DID no longer holds a beta seat: treat as logged out (and drop the
            // stale server-side session so the dead cookie can't linger).
            state.sessions.remove(&sid);
        }
    }
    // No valid cookie: dev fallback only if explicitly configured *and* still
    // inside the beta gate (seeded via ensure_seed / a redeemed code).
    if let Some(did) = state.config.dev_did.clone() {
        if store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false)
        {
            return Some(CurrentUser {
                did,
                handle: None,
                sid: None,
            });
        }
    }
    None
}

/// The current request's DID, or `None` when logged out (no cookie, no dev DID).
async fn current_did(state: &AppState, headers: &HeaderMap) -> Option<String> {
    current_session(state, headers).await.map(|u| u.did)
}

/// Build the application router over shared [`AppState`].
///
/// Wires the reader routes, the health check, and the `/static` asset mount
/// (the stylesheet, vendored htmx, and the keyboard handler, served from
/// `static/` via `ServeDir`). A `TraceLayer` gives per-request tracing.
pub fn router(state: AppState) -> Router {
    // The shared per-IP rate limiter for the abuse-prone paths (login, redeem,
    // and the write endpoints). One instance is cloned into the state closure of
    // the `rate_limit` middleware.
    let limiter = RateLimiter::shared();
    // The trusted client-IP source for the limiter (a proxy header the operator
    // controls, or the socket peer when unset). Bundled with the limiter so the
    // middleware derives a spoof-resistant IP.
    let rl_state = RateLimitState {
        limiter,
        trusted_header: state.config.trusted_ip_header.clone(),
    };

    Router::new()
        .route("/health", get(health))
        .route("/about", get(about))
        .route("/standard-site", get(standard_site))
        .route("/stats", get(stats))
        .route("/privacy", get(privacy))
        .route("/terms", get(terms))
        .route("/manage", get(manage))
        .route("/", get(index))
        .route("/entries/{id}", get(entry_view))
        .route("/entries/{id}/read", post(mark_read))
        .route("/entries/{id}/star", post(toggle_star))
        .route("/saved/{rkey}/delete", post(unsave_record))
        .route("/read-all", post(mark_all_read))
        .route("/subscriptions", post(add_subscription))
        .route("/subscriptions/{rkey}/delete", post(delete_subscription))
        .route("/subscriptions/{rkey}/rename", post(rename_subscription))
        .route("/folders", post(create_folder))
        .route("/folders/{rkey}/rename", post(rename_folder))
        .route("/folders/{rkey}/delete", post(delete_folder))
        // OPML import takes untrusted uploads: cap the body so a huge upload
        // can't OOM (residual body-cap), on top of the streamed feed-fetch cap.
        .route(
            "/opml",
            post(import_opml).layer(DefaultBodyLimit::max(OPML_BODY_LIMIT)),
        )
        .route("/opml/export", get(export_opml))
        .route("/login", get(login_form).post(login_submit))
        .route(
            "/beta/redeem",
            get(beta_redeem_form).post(beta_redeem_submit),
        )
        // The follow→invite bot's claim link: a public skeet points a new
        // follower here with an opaque token that reserves a pre-minted code.
        .route("/claim", get(claim))
        // Headless bot mint endpoint (shared-secret, not OAuth). Mints a claim
        // code + returns its token/url for the bot to post.
        .route("/bot/claims", post(bot_mint_claim))
        .route("/admin/invites", post(admin_mint_invites))
        .route("/admin/metrics", get(admin_metrics))
        .route("/oauth/client-metadata.json", get(oauth_client_metadata))
        .route("/oauth/jwks.json", get(oauth_jwks))
        .route("/account/delete", post(account_delete))
        .route("/oauth/callback", get(oauth_callback))
        .route("/logout", post(logout))
        .nest_service("/static", ServeDir::new("static"))
        // Browsers (and some feed clients) request /favicon.ico at the root
        // regardless of the <link rel="icon"> tags; serve the same icon that
        // lives under /static so the bare path stops 404-ing.
        .route_service("/favicon.ico", ServeFile::new("static/favicon.ico"))
        // Cache-Control (viral/CDN plan): `public, max-age=300` on the cacheable
        // logged-out landing + static assets, `no-store` on anything that
        // rendered a session's private view. Runs *inside* the security layers so
        // the CSP/nosniff/frame headers are untouched.
        .layer(middleware::from_fn(cache_control))
        // Per-IP rate limit on the abuse-prone paths (429 over the limit). Runs
        // as a middleware so it sees the matched path + the peer IP.
        .layer(middleware::from_fn_with_state(rl_state, rate_limit))
        .layer(TraceLayer::new_for_http())
        // Baseline security headers on *every* response (F4). The CSP is the
        // backstop that neutralises any XSS that slips past sanitization; the
        // others harden sniffing, framing, and referrer leakage.
        .layer(static_header_layer(
            "content-security-policy",
            CONTENT_SECURITY_POLICY,
        ))
        .layer(static_header_layer("x-content-type-options", "nosniff"))
        .layer(static_header_layer(
            "referrer-policy",
            "strict-origin-when-cross-origin",
        ))
        .layer(static_header_layer("x-frame-options", "DENY"))
        .with_state(state)
}

/// Body-size ceiling for the OPML import upload: **1 MiB, deliberately below
/// axum's 2 MiB default.**
///
/// The value used to BE the framework default, which made the route's own
/// `DefaultBodyLimit` layer a no-op: removing the layer changed nothing, so
/// nothing could test it, and the ceiling this route wanted was whatever the
/// framework happened to pick. Sized to this route instead — one outline is
/// ~92 bytes, so 1 MiB carries ~11 000 of them against a per-DID cap
/// (`max_subs_per_did`, default 500) the import trims to anyway. Anything
/// larger is not a subscription list.
///
/// Being strictly tighter than the default is what makes the layer both real
/// and pinnable: `opml_import_over_the_route_cap_is_refused_below_the_framework_default`
/// uploads a payload that only this limit refuses.
const OPML_BODY_LIMIT: usize = 1024 * 1024;

/// axum's own `DefaultBodyLimit` (2 MiB as of axum 0.8), for the test that
/// uploads a payload between the two ceilings.
///
/// **What matters is only that it EXCEEDS [`OPML_BODY_LIMIT`]**, not that this
/// number is exact — axum does not export it, so it cannot be imported. The
/// exceeding is what the test's mutation demonstrates: with the route's layer
/// removed, a payload of this size is accepted. If axum ever lowers its
/// default below ours, that mutation stops failing and the compile-time
/// assertion below is the thing to revisit.
#[cfg(test)]
const AXUM_DEFAULT_BODY_LIMIT: usize = 2 * 1024 * 1024;

/// The route's cap must stay strictly tighter than the framework's, or its
/// layer is a no-op again. A compile error, not a test failure: this is a
/// property of the two constants, and nothing should be able to build a binary
/// where it is false.
#[cfg(test)]
const _: () = assert!(
    OPML_BODY_LIMIT < AXUM_DEFAULT_BODY_LIMIT,
    "OPML_BODY_LIMIT must be tighter than axum's default, or the route's layer does nothing"
);

/// A response-header layer that sets `name: value` on every response, overriding
/// any existing header of that name. `name`/`value` must be valid static header
/// tokens (they are, for our fixed security headers).
fn static_header_layer(
    name: &'static str,
    value: &'static str,
) -> SetResponseHeaderLayer<header::HeaderValue> {
    SetResponseHeaderLayer::overriding(
        header::HeaderName::from_static(name),
        header::HeaderValue::from_static(value),
    )
}

// ---------------------------------------------------------------------------
// Per-IP rate limiting (token bucket, self-contained — no extra crate)
// ---------------------------------------------------------------------------

/// The abuse-prone paths the rate limiter guards (429 over the limit): the OAuth
/// kick-off and callback, the invite redeem, logout, the mutating write
/// endpoints, and mark-read/star/mark-all. Plain read-only navigation is
/// intentionally *not* limited.
///
/// The criterion is **does this path make an outbound request**, not "does it
/// mutate" — the two diverge, and every miss so far has been on the outbound
/// side. This is an allowlist a new route has to be added to by hand, which is
/// exactly why it has now been missed three times: `/saved/` (fixed), then
/// `/oauth/callback` and `/logout`. The callback was the bad one — it is the
/// only path here reachable with no session at all.
///
/// Known and deliberate gaps: `GET /`, `GET /manage` and `GET /opml/export` each
/// make PDS calls but are ordinary authenticated navigation, and throttling them
/// would degrade normal reading. They are bounded by needing a valid session.
fn is_rate_limited_path(path: &str, method: &axum::http::Method) -> bool {
    use axum::http::Method;
    // `/claim` is a GET (a link the bot posts), but it consumes a reservation and
    // a claim token in a public URL is grabbable, so it MUST be per-IP limited
    // like the other abuse-prone entry points — not just `/login`.
    // `/oauth/callback` is a GET, is UNAUTHENTICATED, and every hit performs a
    // real outbound round-trip — a sidecar `resolve_session` or a full token
    // exchange against a PDS. Anyone could spend one outbound request per hit.
    // It is the only entry point here that needs no session at all.
    if method != Method::POST
        && !(method == Method::GET
            && (path == "/login" || path == "/claim" || path == "/oauth/callback"))
    {
        return false;
    }
    match path {
        // `/logout` and `/oauth/callback` are here because they make outbound
        // calls, not because they mutate: logout revokes at the PDS (up to two
        // round-trips) and the callback exchanges a code. The list is by
        // *network cost*, which is what the limiter is actually for.
        "/login" | "/claim" | "/oauth/callback" | "/logout" | "/beta/redeem" | "/subscriptions"
        | "/opml" | "/read-all" | "/admin/invites" | "/bot/claims" | "/account/delete"
        | "/folders" => true,
        // Every per-record subscription/folder mutation (delete/rename) and the
        // star/mark-read taps make a sidecar/PDS round-trip, so limit them too.
        p => {
            (p.starts_with("/entries/") && (p.ends_with("/read") || p.ends_with("/star")))
                // Unsaving makes a DPoP-signed deleteRecord round-trip to the
                // PDS, which is exactly the reason the neighbours above are
                // limited. It was added as a new route and not added here.
                || p.starts_with("/saved/")
                || p.starts_with("/subscriptions/")
                || p.starts_with("/folders/")
        }
    }
}

/// Middleware state for [`rate_limit`]: the shared limiter plus the trusted
/// client-IP header (if any). Cloned into every request; both fields are cheap.
#[derive(Clone)]
struct RateLimitState {
    limiter: RateLimiter,
    /// The lowercased proxy header the operator trusts for the client IP, or
    /// `None` to trust only the socket peer. See [`client_ip`].
    trusted_header: Option<String>,
}

/// A tiny per-IP token-bucket rate limiter. Each IP gets [`RATE_BURST`] tokens
/// that refill at [`RATE_REFILL_PER_SEC`]/sec; a request costs one token and is
/// rejected (429) when the bucket is empty. Self-contained (no `tower_governor`
/// dependency → no network fetch at build, deterministic offline CI).
#[derive(Clone)]
struct RateLimiter {
    inner: std::sync::Arc<Mutex<RateLimiterState>>,
}

/// The limiter's shared state: the buckets plus when they were last swept.
struct RateLimiterState {
    buckets: HashMap<IpAddr, Bucket>,
    last_sweep: Instant,
}

/// One IP's token bucket: a fractional token count + the last-refill instant.
struct Bucket {
    tokens: f64,
    last: Instant,
}

/// Burst capacity per IP — how many requests can arrive back-to-back.
const RATE_BURST: f64 = 20.0;
/// Steady-state refill rate (tokens/sec) once the burst is spent.
const RATE_REFILL_PER_SEC: f64 = 1.0;
/// Evict idle buckets older than this so the map can't grow unbounded.
const RATE_IDLE_EVICT: Duration = Duration::from_secs(3600);

/// How often the idle sweep may actually run.
///
/// The sweep used to run on EVERY guarded request — an O(n) scan of the whole
/// map to find entries that, by construction, can only age out on an hour
/// boundary. `GET /login` and `GET /claim` are guarded and unauthenticated, so
/// under any volume of distinct source IPs the server spent its single shared
/// core re-walking a map whose contents had not changed. Once a minute is
/// plenty: it bounds bucket lifetime at `RATE_IDLE_EVICT + RATE_SWEEP_EVERY`.
const RATE_SWEEP_EVERY: Duration = Duration::from_secs(60);

/// Most buckets kept. At roughly 100 bytes each this is ~1 MB — a bound, not a
/// target, sized so ordinary traffic never reaches it.
///
/// The idle eviction above was the only bound, and it is a TIME bound, which
/// says nothing about how many distinct IPs can arrive inside one hour.
/// `net.rs` bounds the equivalent structure by count (`MAX_PINNED_CLIENTS`);
/// this one did not.
const MAX_RATE_BUCKETS: usize = 10_000;

/// When the cap is hit, evict down to this fraction of it rather than removing
/// a single entry — so the O(n) eviction happens once per `cap/8` requests
/// instead of once per request while the map sits full.
const RATE_EVICT_DOWN_TO: usize = MAX_RATE_BUCKETS * 7 / 8;

impl RateLimiter {
    /// A fresh, shared limiter (cloned into the middleware state).
    fn shared() -> Self {
        Self {
            inner: std::sync::Arc::new(Mutex::new(RateLimiterState {
                buckets: HashMap::new(),
                last_sweep: Instant::now(),
            })),
        }
    }

    /// Charge one token for `ip`; returns `true` if allowed, `false` if the
    /// bucket is empty (→ 429).
    fn check(&self, ip: IpAddr) -> bool {
        self.check_at(ip, Instant::now())
    }

    /// [`check`](Self::check) with the clock injected, so the sweep and eviction
    /// paths below are reachable in a test without sleeping through an hour.
    fn check_at(&self, ip: IpAddr, now: Instant) -> bool {
        let mut state = match self.inner.lock() {
            Ok(m) => m,
            // A poisoned lock shouldn't take the site down — fail open.
            Err(p) => p.into_inner(),
        };

        // Idle sweep, at most once per `RATE_SWEEP_EVERY`.
        if now.duration_since(state.last_sweep) >= RATE_SWEEP_EVERY {
            state
                .buckets
                .retain(|_, b| now.duration_since(b.last) < RATE_IDLE_EVICT);
            state.last_sweep = now;
        }

        // Hard size bound, independent of the time bound above.
        //
        // Evicting LEAST-RECENTLY-USED is what makes this safe to do at all. An
        // attacker cannot use eviction to clear their OWN throttled bucket: that
        // bucket is by definition the most recently touched, so it is the last
        // thing this removes. Going quiet long enough to become the oldest entry
        // is exactly what the refill already grants for free.
        if state.buckets.len() >= MAX_RATE_BUCKETS && !state.buckets.contains_key(&ip) {
            let mut by_age: Vec<(IpAddr, Instant)> =
                state.buckets.iter().map(|(k, b)| (*k, b.last)).collect();
            by_age.sort_unstable_by_key(|(_, last)| *last);
            for (victim, _) in by_age
                .into_iter()
                .take(state.buckets.len().saturating_sub(RATE_EVICT_DOWN_TO))
            {
                state.buckets.remove(&victim);
            }
            warn!(
                buckets = state.buckets.len(),
                "rate-limit bucket cap reached; evicted the least recently seen clients"
            );
        }

        let bucket = state.buckets.entry(ip).or_insert(Bucket {
            tokens: RATE_BURST,
            last: now,
        });
        let elapsed = now.duration_since(bucket.last).as_secs_f64();
        bucket.tokens = (bucket.tokens + elapsed * RATE_REFILL_PER_SEC).min(RATE_BURST);
        bucket.last = now;
        if bucket.tokens >= 1.0 {
            bucket.tokens -= 1.0;
            true
        } else {
            false
        }
    }
}

/// The **trusted** client IP for a request.
///
/// Security: a naive limiter that trusts the *left-most* `X-Forwarded-For` hop
/// is fully bypassable — the left-most value is attacker-supplied (any client
/// can send `X-Forwarded-For: <random>`), so each forged value lands in a fresh
/// bucket and the per-IP limit never bites. We therefore derive the IP only from
/// a source the operator controls:
///
/// * If `trusted_header` is configured (e.g. `Fly-Client-IP`,
///   `CF-Connecting-IP`), we read the client IP from THAT header only — it is
///   set by the proxy we run in front and overwrites any client-supplied copy.
///   We take the LAST value if the header happens to be a comma list (the hop
///   the trusted proxy appended), which is also the correct read for a
///   right-most-`X-Forwarded-For` deployment where the operator points
///   `trusted_header` at `x-forwarded-for`.
/// * Otherwise we ignore all forwarding headers and use the socket peer
///   (`ConnectInfo`) — correct for a direct bind with no proxy.
///
/// Returns `None` only when neither source yields a parseable IP (the limiter
/// then fails open for that one request).
fn client_ip(
    headers: &HeaderMap,
    conn: Option<&SocketAddr>,
    trusted_header: Option<&str>,
) -> Option<IpAddr> {
    if let Some(name) = trusted_header {
        if let Some(raw) = headers.get(name).and_then(|v| v.to_str().ok()) {
            // Right-most hop is the one the trusted proxy appended; earlier
            // entries may be client-forged, so never trust the left-most.
            if let Some(last) = raw.split(',').next_back() {
                if let Ok(ip) = last.trim().parse::<IpAddr>() {
                    return Some(ip);
                }
            }
        }
        // Trusted header absent/unparseable → fall through to the socket peer.
    }
    conn.map(|s| s.ip())
}

/// Rate-limit middleware: 429 on the abuse-prone paths once an IP's bucket is
/// empty; every other request (and every non-guarded path) passes through. The
/// peer `SocketAddr` is read from the request extension `ConnectInfo` sets (via
/// `into_make_service_with_connect_info`), preferring `X-Forwarded-For`.
async fn rate_limit(
    State(rl): State<RateLimitState>,
    req: axum::extract::Request,
    next: Next,
) -> Response {
    let path = req.uri().path().to_string();
    let method = req.method().clone();
    if is_rate_limited_path(&path, &method) {
        let conn = req
            .extensions()
            .get::<ConnectInfo<SocketAddr>>()
            .map(|c| c.0);
        let ip = client_ip(req.headers(), conn.as_ref(), rl.trusted_header.as_deref());
        // Deliberately fail OPEN when no client IP is derivable (no trusted
        // header / no socket peer): there is no per-IP key to enforce, and a
        // blanket 429 would self-DoS every guarded path (incl. /login). This is
        // safe precisely because we never key on an attacker-forged XFF — see
        // `rate_limit_ignores_spoofed_xff_rotation`.
        if let Some(ip) = ip {
            if !rl.limiter.check(ip) {
                warn!(%ip, %path, "rate limit exceeded");
                return (
                    StatusCode::TOO_MANY_REQUESTS,
                    [(header::RETRY_AFTER, "1")],
                    "rate limit exceeded\n",
                )
                    .into_response();
            }
        }
    }
    next.run(req).await
}

// ---------------------------------------------------------------------------
// Cache-Control (viral / CDN vs. private authenticated views)
// ---------------------------------------------------------------------------

/// Cache-Control middleware. Emits `public, max-age=300` on the cacheable
/// logged-out surfaces (the `/login` landing without a handle, `/about`,
/// `/standard-site`, `/privacy`, `/terms`, and the `/static/*` assets) and `no-store` on the
/// authenticated app pages, so a CDN /
/// browser can hold the viral landing while never caching a signed-in user's
/// private view. Never overrides a handler that already set Cache-Control.
async fn cache_control(req: axum::extract::Request, next: Next) -> Response {
    let path = req.uri().path().to_string();
    // The logged-out landing is only cacheable when it's the bare form — a
    // `?handle=` GET kicks off OAuth (a redirect), which must not be cached.
    let is_login_landing = path == "/login"
        && req.method() == axum::http::Method::GET
        && !req.uri().query().unwrap_or("").contains("handle=");
    let public = is_login_landing
        || path == "/about"
        || path == "/standard-site"
        || path == "/privacy"
        || path == "/terms"
        || path.starts_with("/static/");

    let mut resp = next.run(req).await;
    if resp.headers().contains_key(header::CACHE_CONTROL) {
        return resp;
    }
    let value = if public {
        "public, max-age=300"
    } else {
        "no-store"
    };
    if let Ok(hv) = header::HeaderValue::from_str(value) {
        resp.headers_mut().insert(header::CACHE_CONTROL, hv);
    }
    resp
}

// ---------------------------------------------------------------------------
// Health
// ---------------------------------------------------------------------------

/// Run `/health`'s database probe. **The single path, so a test cannot assert
/// on a string the handler is free to ignore** — a named constant alone was not
/// enough: the test read the constant while the handler passed `query_scalar`
/// whatever it liked, so degrading the real call to `SELECT 1` shipped green.
async fn health_db_probe(pool: &store::Pool) -> Result<Option<i64>, sqlx::Error> {
    sqlx::query_scalar::<_, i64>(HEALTH_DB_PROBE_SQL)
        .fetch_optional(pool)
        .await
}

/// The statement `/health` uses to prove the database is readable.
///
/// **A named constant so the test can assert on the query that actually runs.**
/// `the_health_probe_opens_a_real_table` used to `EXPLAIN` a hand-typed copy of
/// this string, so degrading the real probe to `SELECT 1` — which opens no page
/// and therefore cannot detect a broken database — left the suite green.
const HEALTH_DB_PROBE_SQL: &str = "SELECT 1 FROM feeds LIMIT 1";

/// How long `/health` will wait for its database ping before calling it broken.
///
/// Under `fly.toml`'s 3 s check timeout, so a hung pool produces a 503 this
/// handler chose rather than a timeout Fly inferred — the difference between a
/// log line that says why and one that says nothing.
const HEALTH_DB_TIMEOUT: Duration = Duration::from_secs(2);

/// Floor for the poll-heartbeat staleness threshold. **Reported, never fatal** —
/// see the handler for why.
///
/// The threshold itself is derived from the configured tick
/// ([`health_tick_stale_secs`]): hardcoding 15 minutes meant an operator who
/// raised `FEATHERREADER_POLL_TICK_SECS` above 900 got a permanent `poller:
/// stale` in the body the deployment docs now tell them to alert on.
const HEALTH_TICK_STALE_FLOOR_SECS: i64 = 15 * 60;

/// How long without a completed tick before the poller reads as stale: several
/// tick intervals, floored, so a normally-paced loop never trips it and a
/// genuinely wedged one always does.
fn health_tick_stale_secs(tick: Duration) -> i64 {
    let tick = i64::try_from(tick.as_secs()).unwrap_or(i64::MAX);
    tick.saturating_mul(5).max(HEALTH_TICK_STALE_FLOOR_SECS)
}

/// The poll tick this instance is configured for. Read from the same env var
/// `scheduler.rs` reads, because the scheduler lives in the binary crate and the
/// handler cannot see its constants.
fn configured_poll_tick() -> Duration {
    std::env::var("FEATHERREADER_POLL_TICK_SECS")
        .ok()
        .and_then(|v| v.trim().parse::<u64>().ok())
        .filter(|s| *s > 0)
        .map_or(DEFAULT_POLL_TICK_SECS, Duration::from_secs)
}

/// Mirrors `scheduler::DEFAULT_POLL_TICK`, which lives in the BINARY crate and
/// so cannot be imported here. Duplicated deliberately and named, rather than
/// left as a bare `60` inside the parse chain, so the drift is at least visible
/// if the scheduler's value ever moves.
const DEFAULT_POLL_TICK_SECS: Duration = Duration::from_secs(60);

/// Grace period after boot before a poller that has never ticked is called
/// `stale` rather than `not-yet-ticked`.
///
/// Without this the two are indistinguishable forever, which matters precisely
/// in the case the startup delays were added for: in a crash loop with 30 s+ boot
/// cycles the poller never reaches its first tick, so `/health` reported the
/// benign `not-yet-ticked` on every single probe and the heartbeat could not
/// detect the failure mode it exists for. `run_poller` returning early — a failed
/// HTTP client build — has the same shape and was equally invisible.
///
/// Sized off the poller's own startup delay plus its tick, with slack.
const HEALTH_FIRST_TICK_GRACE_SECS: i64 = 5 * 60;

/// `GET /health` — does this process still work, and what are its loops doing?
///
/// This used to return a constant string, touching no database, no pool and no
/// scheduler state — while being the ONLY automated signal in `fly.toml`, whose
/// sole other failure detector is a child process exiting. It proved the HTTP
/// listener was up and nothing else.
///
/// **What can fail the check: the database, and only the database.** A process
/// that cannot reach its store serves nothing, so a restart is the right
/// response and this returns 503. The probe is a read (`SELECT 1`), which in WAL
/// mode is not blocked by any writer — so the retention sweep, the poller and a
/// login burst cannot make this flap. That property is the reason it is a read
/// and not, say, a write canary.
///
/// **What is reported but never fails the check: everything else.** A stale poll
/// heartbeat, a watermark pause, a missing OAuth runtime — all real problems,
/// and none of them a reason to stop serving.
///
/// That last clause is the whole justification, and it is NOT the one this
/// comment used to give. It said "Fly restarts on a failed check", which is
/// false — verified against Fly's own docs, which state it three times: *"your
/// Machines won't automatically restart or stop due to failing their health
/// checks"*. A failing `[[http_service.checks]]` check makes Fly Proxy stop
/// ROUTING to the Machine. Nothing restarts it. That capability existed on Apps
/// V1 (`restart_limit`) and has no successor on Machines.
///
/// The corrected model makes the conclusion stronger, not weaker. With one
/// Machine there is no healthy peer to shift traffic to, so a 503 here is not a
/// failover — it is a total outage that lasts exactly as long as the condition,
/// and it also fails a `fly deploy` (rolling strategy, no auto-rollback). So the
/// question the status code answers is not "would a restart fix this" but **"can
/// this process still serve a useful request at all"**. A stale poller can. A
/// database it cannot read cannot.
///
/// Re-registration is automatic: the proxy keeps probing and routes again the
/// moment the check passes. That is what makes a 503 recoverable without
/// intervention — not a restart, which never comes.
///
/// The body is machine facts only — no user counts, no DIDs, no feed URLs — so
/// it is publishable on the same terms as `/stats`. It is also the non-session
/// diagnostic for an OAuth outage: when nobody can log in, `/admin/metrics`
/// (which needs a live admin session) is exactly as unreachable as the thing it
/// would diagnose, while this is reachable with `curl`.
async fn health(State(state): State<AppState>) -> Response {
    let now = chrono::Utc::now().timestamp();
    let rh = &state.runtime_health;

    use crate::runtime_health::DbProbe;
    let db = match rh.begin_db_probe() {
        // A probe is already in flight; report its predecessor rather than
        // starting a second one. See `RuntimeHealth::begin_db_probe`.
        Err(borrowed) => borrowed,
        Ok(probe) => {
            // **Spawned, so the probe cannot be cancelled by the caller.**
            //
            // Axum drops the handler future when a client disconnects. With the
            // probe inline, that dropped it mid-flight and released the claim
            // WITHOUT recording a verdict — which let an unauthenticated caller
            // manufacture the no-verdict state on demand and freeze what every
            // other caller, Fly's check included, reads. Running it detached
            // means the verdict is always recorded and the claim is always
            // released after it.
            let pool = state.db.clone();
            let task = tokio::spawn(async move {
                // **`SELECT 1` was not a database probe.** It compiles to
                // `Init/Integer/ResultRow/Halt` — there is no `OpenRead`, so it
                // never touches a b-tree, never reads a page, and never consults
                // the file. Against a corrupted database it returns success
                // while every real query returns SQLITE_CORRUPT. Reading one row
                // from a real table costs the same and actually proves what the
                // check claims. `LIMIT 1` keeps it to a single page; an empty
                // table still opens the b-tree root, which is the part that
                // matters.
                let verdict =
                    match tokio::time::timeout(HEALTH_DB_TIMEOUT, health_db_probe(&pool)).await {
                        Ok(Ok(_)) => DbProbe::Ok,
                        // Coarse, not the raw error. An unauthenticated caller
                        // learning exactly which failure it hit is an
                        // attack-progress oracle; the detail belongs in the log,
                        // which gets it here.
                        Ok(Err(err)) => {
                            warn!(%err, "health: database probe failed");
                            DbProbe::Failed("unavailable".to_string())
                        }
                        Err(_) => {
                            warn!(
                                timeout_s = HEALTH_DB_TIMEOUT.as_secs(),
                                "health: database probe timed out (pool exhausted?)"
                            );
                            DbProbe::Failed("timeout".to_string())
                        }
                    };
                probe.record(verdict.clone());
                verdict
            });
            // A panicking task drops the guard, which releases the claim without
            // a verdict — the only remaining path to that state, and not one a
            // caller can drive.
            task.await.unwrap_or(DbProbe::Unknown)
        }
    };

    let uptime = rh.uptime_secs(now);
    let poller = if !rh.schedulers_enabled() {
        // Not a fault. Dev runs and the seam tests disable the loops on purpose,
        // and reporting that as "stale" would be a false alarm on every one.
        "disabled".to_string()
    } else {
        match rh.secs_since_poll_tick(now) {
            // "Never ticked" is benign right after boot and alarming well after
            // it — so it is read against UPTIME, not left permanently benign.
            None => match uptime {
                Some(up) if up > HEALTH_FIRST_TICK_GRACE_SECS => {
                    format!("stale never-ticked {up}s")
                }
                _ => "not-yet-ticked".to_string(),
            },
            Some(secs) if secs > health_tick_stale_secs(configured_poll_tick()) => {
                format!("stale {secs}s")
            }
            Some(secs) => format!("ok {secs}s"),
        }
    };

    // **Only a MEASURED failure fails the check.**
    //
    // `Unknown` means no probe has completed — a concurrent request arrived
    // before the first one finished, or a previous owner was cancelled before
    // recording. It is reported and returns 200, because an unmeasured database
    // is not evidence of a broken one, and this endpoint is reachable by
    // unauthenticated callers who can manufacture that state. Treating it as a
    // failure handed them a lever on the only signal the platform acts on.
    let mut body = String::new();
    let status = match &db {
        DbProbe::Ok => {
            body.push_str(&format!("ok featherreader/{VERSION}\n"));
            body.push_str("db: ok\n");
            StatusCode::OK
        }
        // **Not `ok`.** The first token is the state, and this one is neither
        // healthy nor failed. It used to print a line byte-identical to the
        // healthy branch, which mattered because `fly.toml` tells operators to
        // alert on the BODY for everything the status code deliberately ignores
        // — so a monitor keying on `^ok` read green in exactly the state this
        // enum exists to make visible.
        DbProbe::Unknown => {
            body.push_str(&format!("unknown featherreader/{VERSION}\n"));
            body.push_str("db: unknown (no probe has completed yet)\n");
            StatusCode::OK
        }
        DbProbe::Failed(why) => {
            body.push_str(&format!("FAIL featherreader/{VERSION}\n"));
            body.push_str(&format!("db: {why}\n"));
            StatusCode::SERVICE_UNAVAILABLE
        }
    };
    // Uptime answers the first question anyone asks about a container under a
    // supervisor that tears the machine down whenever a child exits: is this
    // thing restarting? Nothing else on any surface could tell you.
    body.push_str(&format!(
        "uptime: {}\n",
        match uptime {
            Some(secs) => format!("{secs}s"),
            None => "unknown".to_string(),
        }
    ));
    body.push_str(&format!("poller: {poller}\n"));
    body.push_str(&format!(
        "polling-paused: {}\n",
        if rh.watermark_paused() { "yes" } else { "no" }
    ));
    // Deliberately NOT the measured database size. `/health` is the one path
    // exempted from the Caddy origin lock, so it answers direct hits to the Fly
    // IP that never passed Cloudflare — which caps what belongs here at the
    // class of facts `/stats` already publishes to anyone. "Polling is paused"
    // is that; the exact byte count is a precise internal number that adds
    // nothing an operator cannot get from `/stats` or the logs.
    body.push_str(&format!(
        "backend: {}\n",
        state.config.repo_backend.as_str()
    ));
    body.push_str(&format!(
        "oauth-runtime: {}\n",
        if state.oauth.is_some() {
            "built"
        } else {
            "absent"
        }
    ));

    // Never cached: a stale health response is worse than none, and Cloudflare
    // sits in front of this.
    let mut resp = (status, body).into_response();
    if let Ok(hv) = header::HeaderValue::from_str("no-store") {
        resp.headers_mut().insert(header::CACHE_CONTROL, hv);
    }
    resp
}

/// `GET /about` — the public-experiment page: the full disclaimer (experimental,
/// no SLA, may pause anytime), the OSS / self-host pitch, and the tip link.
/// Readable whether or not a session exists.
///
/// Optionally carries one quiet line about network adoption
/// (`design/NETWORK-SPEC.md` §4.4). With `FEATHERREADER_SHOW_ADOPTION` off — the
/// default — the handler issues **zero** queries and the page is byte-identical
/// to what it was before the probe existed.
async fn about(State(state): State<AppState>) -> Response {
    let adoption = if state.config.show_adoption {
        adoption_line(&state).await
    } else {
        None
    };
    render(&AboutTemplate {
        card: Card::public(
            &state.config,
            "/about",
            "About — FeatherReader",
            "What FeatherReader is and isn't: an open-source, atproto-native reader for \
             RSS feeds and standard.site publications, run as an experiment, free to \
             self-host under the AGPL.",
        ),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        adoption,
        standard_site: state.config.standard_site,
    })
}

/// `GET /standard-site` — the public feature page for standard.site
/// publications: what a publication is, what FeatherReader shows from one, how
/// to subscribe, the limits, and the latest releases. Readable whether or not
/// a session exists, like `/about`. Every how-to-subscribe line is conditional
/// on `Config::standard_site`, as on the other public pages.
async fn standard_site(State(state): State<AppState>) -> Response {
    render(&StandardSiteTemplate {
        card: Card::public(
            &state.config,
            "/standard-site",
            "standard.site — FeatherReader",
            "Read standard.site publications beside your RSS feeds: articles \
             published as atproto records, followed with the same portable \
             subscription record.",
        ),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        standard_site: state.config.standard_site,
        releases: RELEASES,
    })
}

/// `POST /saved/:rkey/delete` — remove a saved record that has no local entry.
///
/// The normal star toggle is keyed on an entry id, which a PDS-only saved row
/// does not have. This deletes the record straight from the repo by its rkey,
/// and then clears any LOCAL star for the same article.
///
/// That second step is not belt-and-braces. "Has no local entry" is how the
/// starred view classifies a record, and it decides that through `sub_ref` — so
/// an article that really is cached, and really is starred, lands here whenever
/// the reader has unsubscribed from its feed. Deleting only the record left
/// `entry_state.starred = 1` behind: invisible, because the starred list is
/// `sub_ref`-scoped too, until a resubscribe brought the star back with nothing
/// in the PDS backing it. A reader who clicks "remove" gets it removed from both
/// places it lives.
async fn unsave_record(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Response {
    let Some(did) = current_did(&state, &headers).await else {
        return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response();
    };

    // Read the record's identity BEFORE deleting it — afterwards there is
    // nothing left to learn it from. Best-effort: a failure here must not block
    // the deletion the reader actually asked for, so it degrades to the old
    // behaviour (record gone, local star possibly stale) and says so.
    let identity = match state.repo().list_saved(&did).await {
        Ok(records) => records
            .into_iter()
            .find(|(k, _)| *k == rkey)
            .map(|(_, rec)| (rec.url, rec.entry_id)),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not read the saved record before deleting it; \
                                      a local star for the same article may survive");
            None
        }
    };

    match state.repo().remove_saved(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "removed a saved record with no cached entry"),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not remove the saved record");
            return (StatusCode::BAD_GATEWAY, "could not remove that item\n").into_response();
        }
    }

    // Deliberately AFTER the delete: the PDS is the source of truth for what was
    // saved, so clearing the local star before knowing the record is gone would
    // be the desync in the other direction.
    if let Some((url, guid)) = identity {
        match store::clear_star_by_identity(&state.db, &did, Some(&url), guid.as_deref()).await {
            Ok(0) => {}
            Ok(n) => {
                info!(%did, %rkey, cleared = n, "cleared the local star for an unsaved record")
            }
            Err(err) => warn!(%err, %did, %rkey, "could not clear the local star after unsaving"),
        }
    }
    // htmx swaps the row out; a plain form post goes back to the starred list.
    if is_htmx(&headers) {
        return (StatusCode::OK, "").into_response();
    }
    Redirect::to("/?view=starred").into_response()
}

/// What the poller is doing, as one word for `/stats`.
///
/// **Parity with `/health` is the point.** `polling_paused` alone reported
/// "running" for three different states including the two where nothing polls,
/// on the page added to answer exactly that. The first attempt at fixing it
/// added `off` and `starting` and claimed parity — but left out `stale`, so a
/// poll loop that ticked once at boot and then WEDGED still read as running.
/// That is the wedged-loop case `/health`'s heartbeat exists for, and the
/// original finding's exact shape surviving its own fix.
///
/// Shares the staleness threshold with `/health` rather than picking its own, so
/// the two pages cannot disagree about what "stale" means.
fn fetching_state(rh: &crate::runtime_health::RuntimeHealth, now_unix: i64) -> &'static str {
    if !rh.schedulers_enabled() {
        return "off";
    }
    // Checked before the pause: a wedged poller cannot clear a pause either, so
    // reporting "paused" would name the symptom and hide the cause.
    match rh.secs_since_poll_tick(now_unix) {
        None => {
            // Never ticked. Benign at boot, a dead loop long after — read
            // against uptime, exactly as `/health` does.
            match rh.uptime_secs(now_unix) {
                Some(up) if up > HEALTH_FIRST_TICK_GRACE_SECS => "stale",
                _ => "starting",
            }
        }
        Some(secs) if secs > health_tick_stale_secs(configured_poll_tick()) => "stale",
        _ if rh.watermark_paused() => "paused",
        _ => "running",
    }
}

/// `GET /stats` — public poll health.
async fn stats(State(state): State<AppState>) -> Response {
    let now = chrono::Utc::now();
    let health = match store::poll_health(
        &state.db,
        &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
    )
    .await
    {
        Ok(health) => health,
        Err(err) => {
            warn!(%err, "could not compute poll health");
            return (StatusCode::INTERNAL_SERVER_ERROR, "stats unavailable\n").into_response();
        }
    };

    // Percentage of a zero-feed instance is 100, not a divide-by-zero: a fresh
    // instance is not behind on anything.
    let polled_pct = if health.feeds_tracked == 0 {
        100
    } else {
        health.polled_last_hour * 100 / health.feeds_tracked
    };

    render(&StatsTemplate {
        card: Card::public(
            &state.config,
            "/stats",
            "Stats — FeatherReader",
            "Is this instance's poller keeping up? Aggregate feed-polling health — \
             counts only; no feed and no reader is named.",
        ),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        feeds_tracked: health.feeds_tracked,
        polled_last_hour: health.polled_last_hour,
        polled_pct,
        overdue: health.overdue,
        last_poll: humanise_ago(health.last_poll_secs_ago),
        oldest_poll: if health.never_polled > 0 {
            "never".to_string()
        } else {
            humanise_ago(health.oldest_poll_secs_ago)
        },
        never_polled: health.never_polled,
        poll_interval_mins: state.config.poll_interval.as_secs() as i64 / 60,
        // **The two states that actually stop feeds updating.**
        //
        // Neither was visible anywhere. `overdue` and `polled_last_hour` move in
        // both and distinguish neither — and `overdue` moves the WRONG WAY for
        // backoff, since backoff is applied by pushing `next_poll` forward, so a
        // feed failing every fetch drops out of the backlog and makes the page
        // read healthier. Both of these are machine facts with no per-feed
        // detail, so they sit inside the page's stated contract.
        in_backoff: health.in_backoff,
        badly_broken: health.badly_broken,
        failure_kinds: health.failure_kinds,
        fetching: fetching_state(&state.runtime_health, now.timestamp()),
    })
}

/// "3h 11m ago", or "never" when there has been no poll at all.
///
/// `None` must not render as `0` — on a fresh instance that would read as
/// "polled just now", which is the opposite of the truth.
fn humanise_ago(secs: Option<i64>) -> String {
    let Some(secs) = secs else {
        return "never".to_string();
    };
    match secs {
        s if s < 60 => format!("{s}s ago"),
        s if s < 3600 => format!("{}m ago", s / 60),
        s => format!("{}h {}m ago", s / 3600, (s % 3600) / 60),
    }
}

/// The `/about` adoption line's data, or `None` (no successful probe yet, an
/// observation of zero, or a store failure).
///
/// A read failure degrades to `None` plus a `warn!` rather than propagating: the
/// probe is never allowed to affect the reader, and that rule applies at the
/// display end too — a locked or corrupt DB costs the About page one log line,
/// not a 500.
async fn adoption_line(state: &AppState) -> Option<AdoptionLine> {
    match store::latest_network_stat(&state.db, store::ADOPTION_STAT_KEY).await {
        // A legitimate zero renders nothing rather than a sad "0 accounts".
        Ok(Some(stat)) if stat.value > 0 => Some(AdoptionLine {
            repos: stat.value,
            truncated: stat.truncated,
            observed_on: stat
                .observed_at
                .split('T')
                .next()
                .unwrap_or_default()
                .to_string(),
        }),
        Ok(_) => None,
        Err(err) => {
            warn!(%err, "about: adoption stat read failed; omitting the line");
            None
        }
    }
}

/// `GET /privacy` — the plain-language privacy page: no account/tracking, data
/// lives in the user's PDS, what the server caches, and the session-token
/// handling. A static render; readable whether or not a session exists.
async fn privacy(State(state): State<AppState>) -> Response {
    render(&PrivacyTemplate {
        card: Card::public(
            &state.config,
            "/privacy",
            "Privacy — FeatherReader",
            "No account and no tracking: your subscriptions and reading state live in \
             your own PDS. What this server caches, for how long, and how the session \
             token is handled.",
        ),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
    })
}

/// `GET /terms` — the terms of use: the experimental / as-is disclaimer,
/// acceptable use, the AGPL/self-host note, and the liability limitation. A
/// static render; readable whether or not a session exists.
async fn terms(State(state): State<AppState>) -> Response {
    render(&TermsTemplate {
        card: Card::public(
            &state.config,
            "/terms",
            "Terms — FeatherReader",
            "The terms of use: an experimental service offered as-is with no warranty, \
             what acceptable use means here, and the AGPL self-host note.",
        ),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
    })
}

// ---------------------------------------------------------------------------
// View models
// ---------------------------------------------------------------------------

/// A feed as shown in the sidebar (title + its unread count + a stable scope key
/// and the PDS subscription rkey for management actions).
struct FeedView {
    /// PDS subscription rkey — addresses the record for rename/unsubscribe.
    rkey: String,
    /// Canonical feed URL — the sidebar filter key (`?feed=<url>`).
    url: String,
    title: String,
    unread: i64,
    /// Whether this feed is the currently-selected scope.
    selected: bool,
    /// The feed's current folder `at://` URI (from its subscription record), or
    /// `None` if un-foldered. Drives the pre-selected `<option>` in the manage
    /// rename row so an untouched folder dropdown does not silently un-folder the
    /// feed on save.
    folder: Option<String>,
}

/// A folder grouping in the sidebar, sourced from the PDS `folder` records.
struct FolderView {
    /// PDS folder rkey — addresses the record for rename/delete.
    rkey: String,
    /// The folder's `at://` URI — the sidebar filter key (`?folder=<uri>`).
    uri: String,
    name: String,
    feeds: Vec<FeedView>,
    /// Whether this folder is the currently-selected scope.
    selected: bool,
}

/// One entry as shown in the article list / after an htmx swap.
struct EntryRow {
    id: i64,
    title: String,
    feed_title: String,
    published: String,
    read: bool,
    starred: bool,
    /// The reader link href, already carrying the scope/view query so opening an
    /// entry and paging back stays within the list it came from.
    link: SafeLink,
    /// Whether the article itself is in this instance's cache.
    ///
    /// `false` for a saved record that exists in the reader's PDS but whose
    /// entry was never cached here — starred in another atproto reader, or
    /// starred here and since evicted. There is no local row, so the row has no
    /// usable `id`: it links straight out to the article and carries no
    /// mark-read control, because there is nothing local to mark.
    cached: bool,
    /// The PDS record key, for un-saving a row that has no local entry.
    rkey: String,
}

/// A folder as an option in the "move feed to folder" select.
struct FolderOption {
    uri: String,
    name: String,
}

/// The shared navigation "rail" model: the same DOM element is the
/// mobile drawer and the desktop sidebar, so every chrome page (list / reader /
/// manage) renders it from this one struct. Feed management lives on `/manage`,
/// not here — the rail is navigation only.
struct Nav {
    /// `@handle` for the identity chip (falls back to the DID's tail).
    handle: String,
    /// Two-letter avatar initials for the identity chip.
    avatar: String,
    /// The active filter: `"unread" | "all" | "starred"` (drives `aria-current`).
    view: String,
    /// The scope query suffix (`feed=…` / `folder=…`) carried onto filter links,
    /// empty for the unscoped "everything" views.
    scope_qs: String,
    /// Folders (each with its feeds) then un-foldered feeds, for the rail lists.
    /// Per-feed `selected` flags drive the rail's feed `aria-current`.
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
    /// Whether the "Manage feeds" rail tool is the current page.
    manage_active: bool,
}

/// The subscribe input's `pattern` when standard.site is on, and the input is
/// `type="text"` (see `templates/manage.html`). It keeps the browser asking for
/// a scheme, as `type="url"` did, while admitting `at://`. Matched in any case,
/// because the handler canonicalises the scheme. Browsers compile `pattern`
/// with the `v` flag and anchor it at both ends. Unlike `type="url"`, a text
/// input does not strip surrounding whitespace before checking, so the pattern
/// allows it: a URL pasted with a leading space is common, and the handler
/// trims it.
pub(crate) const FEED_URL_PATTERN: &str = "\\s*(?:[Hh][Tt][Tt][Pp][Ss]?|[Aa][Tt])://.+";

// ---------------------------------------------------------------------------
// Link cards (Open Graph / Twitter / Bluesky)
// ---------------------------------------------------------------------------

/// The site's own title: the landing page's, and the one every private view
/// shows instead of its own.
const SITE_TITLE: &str = "FeatherReader — read, quietly";

/// The site's one-paragraph description: the landing page's, and the one every
/// private view shows instead of its own.
const SITE_DESCRIPTION: &str = "A minimalist, atproto-native reader for RSS feeds and \
standard.site publications. Your subscriptions live in your own PDS — no signup, no \
password, no tracking.";

/// Where the share image is served, relative to the public origin. The file is
/// `static/social-card.png`, rendered from `static/social-card.svg` by
/// `scripts/social-card.sh`; `base.html` advertises its dimensions, and a test
/// checks the PNG's own header agrees.
const SHARE_IMAGE_PATH: &str = "/static/social-card.png";

/// What a link to a page unfurls as when it is posted — on Bluesky, in a chat,
/// anywhere that reads Open Graph tags. `base.html` renders it into `<head>`.
///
/// Measured before this existed: Bluesky's card service
/// (`cardyb.bsky.app/v1/extract?url=https://feather-reader.com/`) returned
/// `{"title":"FeatherReader — read, quietly","description":"","image":""}`,
/// because `<title>` was the only tag it could find. Card fetchers read the
/// initial HTML server-side, run no JS, and resolve nothing relative, so every
/// URL here is absolute on [`Config::public_url`] — `https://feather-reader.com`
/// in production, whatever `FEATHERREADER_PUBLIC_URL` says elsewhere.
#[derive(Debug, Clone)]
pub(crate) struct Card {
    /// `og:title`. On a public page, the same text as its `<title>`.
    pub title: String,
    /// `og:description` and `<meta name="description">`: one or two plain
    /// sentences about THIS page, not the site.
    pub description: String,
    /// `og:url` and `<link rel="canonical">`: absolute, on the public origin.
    pub url: String,
    /// `og:image`: absolute, on the public origin.
    pub image: String,
    /// Set on a page that renders a session's private view. The card is then
    /// the site's generic one — nothing from the view reaches `<head>` — and
    /// the page is `noindex`.
    pub private: bool,
}

impl Card {
    /// The card of the public page at `path` (leading slash) on this instance.
    fn public(
        config: &Config,
        path: &str,
        title: impl Into<String>,
        description: impl Into<String>,
    ) -> Self {
        let origin = config.public_url.trim_end_matches('/');
        Card {
            title: title.into(),
            description: description.into(),
            url: format!("{origin}{path}"),
            image: format!("{origin}{SHARE_IMAGE_PATH}"),
            private: false,
        }
    }

    /// The landing page's card: the site's own title and description.
    fn site(config: &Config) -> Self {
        Card::public(config, "/", SITE_TITLE, SITE_DESCRIPTION)
    }

    /// The card of a page that renders a session's private view: the site's
    /// generic card pointing at the front door, plus `noindex`. The view's
    /// heading, feed names and handle stay out of `<head>`.
    fn private(config: &Config) -> Self {
        Card {
            private: true,
            ..Card::site(config)
        }
    }
}

/// The reader index (`GET /`).
#[derive(Template)]
#[template(path = "index.html")]
struct IndexTemplate {
    /// The link card. A private view: the site's generic card, `noindex`.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    flash: String,
    /// Shown as `role="alert"` when the subscription list is the cached one
    /// because the PDS listing failed; empty otherwise.
    alert: String,
    /// The shared rail (drawer + desktop sidebar) navigation model.
    nav: Nav,
    /// The article list for the selected scope + view.
    entries: Vec<EntryRow>,
    /// The list heading (the selected view/feed/folder name).
    heading: String,
    /// Whether a feed scope is active (enables per-feed mark-all-read).
    feed_scope: Option<String>,
    /// Total CACHED entries in this scope + view across ALL pages. The count used
    /// to be `entries.len()`, which was the same number only because the list was
    /// unpaged — the thing this change exists to stop.
    ///
    /// The pager is derived from this, so it must not include the uncached PDS
    /// rows below: they are appended to the last page rather than paged, and
    /// counting them here advertised a page the clamp could never reach.
    total: i64,
    /// How many of `total` are PDS saved records the cache cannot show.
    ///
    /// A subset of `total`, not an addition to it — the heading says "N entries
    /// (M saved elsewhere)". An earlier version rendered "N entries, plus M",
    /// which double counted once `total` started including them, against an M
    /// that had become page-local in the same commit while the template stayed
    /// put.
    uncached_total: i64,
    /// 1-based current page.
    page: i64,
    /// Total pages, at least 1 (an empty list is page 1 of 1).
    page_count: i64,
    /// Link to the previous (newer) page, or `None` on the first.
    prev_href: Option<String>,
    /// Link to the next (older) page, or `None` on the last.
    next_href: Option<String>,
}

/// The feed-management page (`GET /manage`) — subscribe / your-feeds / OPML.
#[derive(Template)]
#[template(path = "manage.html")]
struct ManageTemplate {
    /// The link card. A private view: the site's generic card, `noindex`.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    flash: String,
    /// See [`IndexTemplate::alert`].
    alert: String,
    nav: Nav,
    /// All folders as move-targets for the subscribe folder select.
    folder_options: Vec<FolderOption>,
    /// Folders (each with feeds) + loose feeds, for the "Your feeds" list.
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
    /// `Config::standard_site`. With it on, the subscribe form says a
    /// `site.standard.publication` URI is accepted and its input drops
    /// `type="url"`, whose browser validation rejects the DID form. With it off
    /// `add_subscription` refuses every `at://` paste, so the form must not
    /// advertise one.
    standard_site: bool,
}

/// The optional one-line adoption fact at the bottom of `/about`
/// (`design/NETWORK-SPEC.md` §4.4). `None` whenever the display flag is off, no
/// probe has succeeded yet, or the read failed — the line then simply does not
/// render.
struct AdoptionLine {
    /// Repos a relay has indexed as holding the subscription collection.
    repos: i64,
    /// The probe hit its page cap, so the copy must say "at least".
    truncated: bool,
    /// Observation date, `YYYY-MM-DD` (UTC), sliced from the stored RFC3339 stamp.
    observed_on: String,
}

/// The public-experiment `/about` page — disclaimer + OSS pitch + tip link, plus
/// the optional adoption line.
#[derive(Template)]
#[template(path = "about.html")]
struct AboutTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    adoption: Option<AdoptionLine>,
    /// `Config::standard_site`: whether the publications section may tell the
    /// reader how to subscribe to one here. See [`ManageTemplate::standard_site`].
    standard_site: bool,
}

/// The public `/standard-site` feature page. Carries the same footer fields
/// as the other public pages, the standard.site flag, and the release list for
/// the "latest releases" call-out.
#[derive(Template)]
#[template(path = "standard_site.html")]
struct StandardSiteTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    /// `Config::standard_site`: whether the page may tell a visitor how to
    /// subscribe to a publication here. See [`ManageTemplate::standard_site`].
    standard_site: bool,
    /// [`RELEASES`], newest first, for `templates/releases.html`.
    releases: &'static [Release],
}

/// One tagged release, as the "latest releases" call-out
/// (`templates/releases.html`) shows it on `/standard-site` and the landing
/// page. The links are derived from `version` and `date`, so a release is
/// described in exactly one place: an entry in [`RELEASES`].
pub(crate) struct Release {
    /// The crate version, without the `v` (`"0.4.1"`). The tag is `v{version}`.
    pub(crate) version: &'static str,
    /// The release date, `YYYY-MM-DD`, as the CHANGELOG heading has it.
    pub(crate) date: &'static str,
    /// One or two plain sentences for a visitor. No markup: the template escapes it.
    pub(crate) summary: &'static str,
}

impl Release {
    /// The GitHub release page: `{REPO_URL}/releases/tag/v{version}`.
    pub(crate) fn url(&self) -> String {
        format!("{REPO_URL}/releases/tag/v{}", self.version)
    }

    /// The release's section of `CHANGELOG.md` on `main`. GitHub derives the
    /// anchor for a heading `## 0.4.1 — 2026-10-04` as `041--2026-10-04`: the
    /// dots dropped, the em dash dropped, each space a hyphen.
    pub(crate) fn changelog_url(&self) -> String {
        format!(
            "{REPO_URL}/blob/main/CHANGELOG.md#{}--{}",
            self.version.replace('.', ""),
            self.date
        )
    }
}

/// **The one place a release is described for the website.** Newest first.
/// To announce the next release, add one entry at the top; the call-out on
/// `/standard-site` and the landing page, and both links, follow from it.
/// `releases_are_newest_first_and_link_the_tag_and_changelog` pins the shape.
pub(crate) const RELEASES: &[Release] = &[
    Release {
        version: "0.4.6",
        date: "2026-10-06",
        summary: "Renaming a subscription or a folder no longer overwrites \
                  what another app changed at the same moment, and a folder \
                  rename keeps everything but the name.",
    },
    Release {
        version: "0.4.5",
        date: "2026-10-06",
        summary: "An operator teardown now signs every user out at their own \
                  server before deleting anything, and the session-writing \
                  code is hardened against the races that work exposed.",
    },
    Release {
        version: "0.4.4",
        date: "2026-10-05",
        summary: "The feed parser moves to feed-rs 3.0 with entry ids and \
                  links unchanged and real RSS bylines, and the address guard \
                  refuses the reserved ranges it missed.",
    },
    Release {
        version: "0.4.3",
        date: "2026-10-05",
        summary: "Two write-path fixes for any PDS: large OPML imports and \
                  read-state syncs are sent in calls the PDS accepts, and a \
                  read-state sync that disagreed with the PDS recovers instead \
                  of failing every round.",
    },
    Release {
        version: "0.4.2",
        date: "2026-10-04",
        summary: "A public standard.site feature page with this list of recent \
                  releases, and link cards: a posted feather-reader.com link \
                  now unfurls with a description and an image.",
    },
    Release {
        version: "0.4.1",
        date: "2026-10-04",
        summary: "The public pages explain standard.site publications, and the \
                  subscribe form can submit the DID form of a publication URI, \
                  which browsers refused in 0.4.0.",
    },
    Release {
        version: "0.4.0",
        date: "2026-10-03",
        summary: "standard.site support: publications are read from their \
                  authors' atproto repos as subscriptions, beside RSS, on their \
                  own polling loop. Every stored field from a feed or a \
                  publication now has a size bound.",
    },
];

/// The public `/stats` page — is the poller keeping up?
///
/// Aggregate only, deliberately. It is published to anyone, so it carries no
/// user counts and no per-feed detail: a reader does not need to know how many
/// people use an instance or which feeds are failing. What it does answer is the
/// question that decides whether an instance can take more readers — whether the
/// poller is servicing the feeds it already has.
///
/// The counts below are aggregate machine facts, which is why they fit that
/// contract: "12 feeds are in backoff" names no feed and no reader, while
/// answering the question the page was previously unable to answer at all.
#[derive(Template)]
#[template(path = "stats.html")]
struct StatsTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    feeds_tracked: i64,
    polled_last_hour: i64,
    polled_pct: i64,
    overdue: i64,
    last_poll: String,
    oldest_poll: String,
    never_polled: i64,
    poll_interval_mins: i64,
    /// Feeds in error backoff. Invisible before, and excluded from `overdue`.
    in_backoff: i64,
    /// Of those, the ones retried hours apart rather than minutes. **Not
    /// "effectively dead"** — see `store::BADLY_BROKEN_ERRORS`; they recover on
    /// their next successful poll, and most of this instance's did.
    badly_broken: i64,
    /// Failing feeds by cause, descending — counts only, never which feed.
    failure_kinds: Vec<(String, i64)>,
    /// What the poller is actually doing: `running`, `paused` (at the size
    /// watermark), `starting` (no tick completed yet) or `off` (schedulers
    /// disabled). Three of those four used to render as "running".
    fetching: &'static str,
}

/// The public `/privacy` page — what the server holds vs. what lives in the
/// user's PDS. Carries the same `repo_url`/`kofi_url`/`version` the shared
/// footer include needs.
#[derive(Template)]
#[template(path = "privacy.html")]
struct PrivacyTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
}

/// The public `/terms` page — the as-is / no-warranty terms of use. Carries the
/// same fields the shared footer include needs.
#[derive(Template)]
#[template(path = "terms.html")]
struct TermsTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
}

/// The signed-out landing page (`GET /` with no session) — the public front
/// door at feather-reader.com. A static render, no session required.
#[derive(Template)]
#[template(path = "landing.html")]
struct LandingTemplate {
    /// The link card: the site's own title and description.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    crates_url: &'static str,
    kofi_url: &'static str,
    /// `Config::standard_site`: whether the publications point may tell a
    /// visitor how to subscribe to one here. See [`ManageTemplate::standard_site`].
    standard_site: bool,
    /// [`RELEASES`], newest first, for the quiet "latest releases" strip.
    releases: &'static [Release],
}

/// The single-entry reader view (`GET /entries/:id`).
#[derive(Template)]
#[template(path = "entry.html")]
struct EntryTemplate {
    /// The link card. A private view: the site's generic card, `noindex`.
    card: Card,
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    nav: Nav,
    id: i64,
    title: String,
    feed_title: String,
    author: Option<String>,
    published: String,
    /// The entry's own link, for `entry.html`'s two `href`s.
    ///
    /// `Option<SafeLink>`, not `Option<String>`: the column it comes from holds
    /// a remote feed's `<link>`. Ingest scheme-checks it, but that guard is a
    /// long way from the `href` and holds only while every future writer to
    /// `entries.url` remembers to go through `feed.rs` — the same procedural
    /// defence that, on the saved-record row, turned out to be deletable with
    /// all 679 tests still green. `None` is the refusal: the template's
    /// no-URL branch already renders a disabled open-original button.
    url: Option<SafeLink>,
    content_html: Option<String>,
    read: bool,
    starred: bool,
    /// The query string to carry the reading context back to the list.
    back_qs: String,
    /// Prev/next entry ids within the current list, for keyboard/paging nav.
    prev_id: Option<i64>,
    next_id: Option<i64>,
    /// Rendered inline (not an out-of-band swap fragment): always `false` here.
    oob: bool,
}

/// The htmx swap fragment for a single entry row (`entry_row.html`).
#[derive(Template)]
#[template(path = "entry_row.html")]
struct EntryRowTemplate {
    e: EntryRow,
}

/// The reader's action-bar fragment (`entry_actionbar.html`) returned as an
/// out-of-band swap after a mark-read / star toggle FROM THE READER, so the
/// button's hidden value + `aria-pressed` update in place (the reader `<li>`
/// isn't in the DOM to swap, unlike the list view's `entry_row.html`).
#[derive(Template)]
#[template(path = "entry_actionbar.html")]
struct EntryActionBarTemplate {
    id: i64,
    read: bool,
    starred: bool,
    /// Emit the `hx-swap-oob` attribute: `true` for the handler's OOB response.
    oob: bool,
}

/// The login stub (`GET /login`).
#[derive(Template)]
#[template(path = "login.html")]
struct LoginTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    repo_url: &'static str,
    error: String,
    /// A neutral/success banner (e.g. the post-delete "signed out" confirmation),
    /// distinct from `error`. Empty renders nothing.
    flash: String,
}

/// The closed-beta invite-redeem page (`GET /beta/redeem`).
#[derive(Template)]
#[template(path = "beta_redeem.html")]
struct BetaRedeemTemplate {
    /// The link card: this page's own title and description.
    card: Card,
    repo_url: &'static str,
    error: String,
    /// When true the seat cap is full: hide the form and show the "capacity
    /// full — try self-hosting" message instead.
    capacity_full: bool,
}

// ---------------------------------------------------------------------------
// Rendering + error helpers
// ---------------------------------------------------------------------------

/// Render an askama template into an HTML response, mapping a render failure to
/// a `500` rather than panicking (no `unwrap` in the request path).
fn render<T: Template>(tmpl: &T) -> Response {
    match tmpl.render() {
        Ok(body) => Html(body).into_response(),
        Err(err) => {
            warn!(%err, "template render failed");
            (StatusCode::INTERNAL_SERVER_ERROR, "template render error").into_response()
        }
    }
}

/// A minimal web error type so handlers can `?`-propagate `anyhow` failures and
/// still return an `impl IntoResponse`. Renders as a `500` with a short message
/// by default; a handler may override the status (e.g. `413` for an over-cap
/// upload) via [`WebError::with_status`].
struct WebError {
    err: anyhow::Error,
    status: StatusCode,
}

impl<E: Into<anyhow::Error>> From<E> for WebError {
    fn from(err: E) -> Self {
        WebError {
            err: err.into(),
            status: StatusCode::INTERNAL_SERVER_ERROR,
        }
    }
}

impl WebError {
    /// Attach an explicit HTTP status to render instead of the default `500`.
    fn with_status(err: impl Into<anyhow::Error>, status: StatusCode) -> Self {
        WebError {
            err: err.into(),
            status,
        }
    }
}

impl IntoResponse for WebError {
    fn into_response(self) -> Response {
        warn!(error = %self.err, status = %self.status, "request failed");
        let body = if self.status == StatusCode::INTERNAL_SERVER_ERROR {
            "internal error"
        } else {
            self.status.canonical_reason().unwrap_or("error")
        };
        (self.status, body).into_response()
    }
}

/// Map an axum [`MultipartError`] to a [`WebError`] that preserves the error's
/// own HTTP status. When a request exceeds the route's `DefaultBodyLimit` the
/// multipart extractor reports `413 Payload Too Large`; a malformed body reports
/// `400`. Either way this avoids collapsing the failure into a generic `500`.
fn multipart_response(err: axum::extract::multipart::MultipartError) -> WebError {
    let status = err.status();
    WebError::with_status(err, status)
}

/// A short, human display of a feed/site title for the sidebar/list, falling
/// back to the host of a URL and finally to the raw string.
fn display_title(title: Option<&str>, url: &str) -> String {
    if let Some(t) = title {
        let t = t.trim();
        if !t.is_empty() {
            return t.to_string();
        }
    }
    url::Url::parse(url)
        .ok()
        .and_then(|u| u.host_str().map(str::to_string))
        .unwrap_or_else(|| url.to_string())
}

/// A display `@handle` for the identity chip: the stored handle if present,
/// else the tail of the DID so the chip is never empty.
fn display_handle(handle: Option<&str>, did: &str) -> String {
    match handle {
        Some(h) if !h.trim().is_empty() => format!("@{}", h.trim().trim_start_matches('@')),
        _ => did.rsplit(':').next().unwrap_or(did).to_string(),
    }
}

/// Two-letter, lowercase avatar initials from a handle/DID.
fn avatar_initials(handle: Option<&str>, did: &str) -> String {
    let source = handle
        .map(|h| h.trim().trim_start_matches('@'))
        .filter(|h| !h.is_empty())
        .unwrap_or_else(|| did.rsplit(':').next().unwrap_or(did));
    let letters: String = source
        .chars()
        .filter(|c| c.is_alphanumeric())
        .take(2)
        .collect::<String>()
        .to_lowercase();
    if letters.is_empty() {
        "fr".to_string()
    } else {
        letters
    }
}

/// Trim a stored RFC3339 timestamp down to the `YYYY-MM-DD` date for calm,
/// low-noise display. Falls back to the raw string if it doesn't look like one.
fn display_date(published: Option<&str>) -> String {
    // CHARACTERS, not bytes. `p[..10]` panics when byte 10 lands inside a
    // multi-byte character, and every caller used to pass a timestamp the feed
    // parser had produced. The saved-record path passes `createdAt` straight off
    // a PDS record, which the lexicon types as a bare string with no validation
    // — written by whatever atproto client the reader used. A `createdAt` of
    // "日本語日本語日本" took down the whole starred view, and there is no
    // catch-panic layer in the stack, so the page stayed down until the record
    // was removed from the very view that would not render.
    match published {
        Some(p) => p.chars().take(10).collect(),
        None => String::new(),
    }
}

/// Percent-encode a value for use in a query string (RFC 3986 unreserved kept).
/// Small and dependency-free — the `url` crate's form-encoding isn't exposed for
/// a bare value, and this keeps the scope-preserving links honest.
fn qenc(s: &str) -> String {
    let mut out = String::with_capacity(s.len() * 3);
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char)
            }
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

// ---------------------------------------------------------------------------
// Reader: index
// ---------------------------------------------------------------------------

/// Query for `GET /` — the scope + view selector.
#[derive(Debug, Deserialize, Default)]
struct IndexQuery {
    /// Filter to a single feed by its canonical URL.
    #[serde(default)]
    feed: Option<String>,
    /// Filter to a folder by its `at://` URI (shows every feed in the folder).
    #[serde(default)]
    folder: Option<String>,
    /// `unread` (default) | `all` | `starred`.
    #[serde(default)]
    view: Option<String>,
    /// 1-based page within the selected scope + view. Absent/0 means page 1.
    #[serde(default)]
    page: Option<u32>,
    /// Optional flash message (e.g. after an action redirect).
    #[serde(default)]
    flash: Option<String>,
}

/// Rows per page in the reader's list views.
///
/// The list projection no longer carries article bodies ([`store::EntryListRow`]),
/// so a page is on the order of tens of kilobytes rather than the tens or
/// hundreds of megabytes an unbounded list of full entries could reach. The page
/// bound is the second half of that fix: without it, a reader with a long
/// backlog still decides how much memory a single request allocates.
const ENTRIES_PER_PAGE: i64 = 100;

/// How many pages `total` entries occupy. An empty list is page 1 of 1, so the
/// pager reads "1 / 1" rather than "1 / 0".
fn page_count_for(total: i64) -> i64 {
    ((total + ENTRIES_PER_PAGE - 1) / ENTRIES_PER_PAGE).max(1)
}

/// Ceiling on the reader's prev/next id list.
///
/// Unlike the page above, this genuinely spans the whole list — prev/next is the
/// reader's position within it — so it is bounded by count rather than paged. At
/// 8 bytes per id this is ~40 KB at the cap. Past it the neighbour links stop
/// resolving; the article itself still opens, and the list view still pages.
const PREV_NEXT_MAX: i64 = 5_000;

/// Ceiling on the cached-starred identity set matched against PDS saved records.
///
/// Deliberately generous: under-reading this set makes a cached article look
/// uncached, and an uncached starred row's button deletes the PDS RECORD rather
/// than un-starring the entry. Truncating here would change what a click
/// destroys, so the cap exists only as a backstop against an absurd starred
/// count, not as a routine bound.
const STARRED_IDENTITY_MAX: i64 = 20_000;

/// Most uncached PDS saved records this handler will hold in memory for one
/// request.
///
/// **A memory bound, not a visibility bound.** These rows are PAGED alongside
/// the cached entries, so `ENTRIES_PER_PAGE` decides how many are rendered and
/// this only caps how many are collected before slicing. An earlier version used
/// it to cap what was SHOWN, which left everything past it invisible and —
/// because the un-save control lives on the row, and nothing else in the app
/// lists these — unremovable.
///
/// Well above the PDS list ceiling's practical reach for one reader, so a reader
/// meeting it has thousands of saved records and gets a logged, ordered prefix
/// rather than a failure.
const MAX_UNCACHED_SAVED_ROWS: usize = 5_000;

/// A subscription resolved against the local cache: the PDS record + its
/// (possibly-missing) cached feed row.
struct ResolvedSub {
    rkey: String,
    sub: Subscription,
    feed: Option<store::Feed>,
}

/// Pull the user's subscriptions (source of truth = PDS), ensure each has a
/// local cache row so unread counts work, and return them resolved. Best-effort
/// on the sidecar: a failure falls back to the local cache alone.
async fn resolve_subscriptions(state: &AppState, did: &str) -> Vec<ResolvedSub> {
    resolve_subscriptions_noting(state, did).await.0
}

/// What to tell a reader whose subscription list could not be read from their
/// PDS, so the last-known list being shown does not pass for a fresh one.
///
/// **A malformed record is named as such** (#177): the walk refuses rather than
/// drop that subscription, and "unreachable" would send the reader looking at
/// their network when the cause is a record some client wrote into their repo.
fn subscriptions_alert(err: &anyhow::Error) -> String {
    match err.downcast_ref::<crate::atproto::MalformedRecords>() {
        Some(m) => format!(
            "{} record(s) in your subscription list could not be read, so it was not \
             refreshed. Showing your last-known subscriptions; nothing was removed.",
            m.count
        ),
        None => "Your subscription list could not be read from your PDS just now. \
                 Showing your last-known subscriptions."
            .to_string(),
    }
}

/// [`resolve_subscriptions`], plus the alert to show when the list shown is the
/// cached one because the PDS listing failed.
async fn resolve_subscriptions_noting(
    state: &AppState,
    did: &str,
) -> (Vec<ResolvedSub>, Option<String>) {
    let pool = &state.db;
    let subs = match state.repo().list_subscriptions_sorted(did).await {
        Ok(s) => s,
        Err(err) => {
            let alert = subscriptions_alert(&err);
            warn!(%err, %did, "could not list PDS subscriptions; showing this DID's cached subscriptions only");
            // Fail CLOSED: the PDS is the source of truth for what this DID
            // follows. When it is unreachable we must NOT widen the caller's
            // authorization surface. Serve from the DID's OWN last-known
            // `sub_ref` projection (its own feeds, possibly stale) and leave
            // `sub_ref` untouched — never synthesize from every cached feed,
            // which would grant cross-tenant read+mutate during any outage.
            // A DB failure here is NOT the same as "this DID follows nothing",
            // but `unwrap_or_default` rendered it as exactly that: an empty
            // sidebar and an empty reader, which arrives as "all my feeds
            // vanished". It still degrades to empty — there is nothing better to
            // show — but it says so, so the support ticket and the log line can
            // be matched up.
            let feeds = store::feeds_for_did(pool, did).await.unwrap_or_else(|err| {
                warn!(%err, %did, "the PDS is unreachable AND the local subscription \
                                   projection could not be read; rendering an EMPTY \
                                   feed list, which is not the same as having none");
                Vec::new()
            });
            let cached = feeds
                .into_iter()
                .map(|f| ResolvedSub {
                    rkey: String::new(),
                    sub: Subscription::new(f.url.clone(), now_rfc3339()),
                    feed: Some(f),
                })
                .collect();
            return (cached, Some(alert));
        }
    };

    // **Deliberately NOT truncated to `max_subs_per_did`.**
    //
    // The PDS list is unbounded in practice — any client can write subscription
    // records, and only the 20,000-record list ceiling stops it — and the first
    // attempt at bounding it truncated the list right here. That was the wrong
    // place: `sync_sub_refs` below writes `sub_ref` from exactly this set, and
    // `sub_ref` is THE per-DID authorization hook, so dropping entries silently
    // removed the reader's ability to read OR mutate those feeds. A query-shape
    // problem would have become an access problem.
    //
    // The shape problem was the scope filter emitting one SQL placeholder per
    // feed; `store::list_query_sql` now passes the whole set as a single
    // `json_each` bind, so there is no size to defend against here and nothing
    // to truncate. `max_subs_per_did` stays what it is — a policy cap on ADDING
    // feeds — rather than becoming a silent read-time filter.
    let mut out = Vec::with_capacity(subs.len());
    for (rkey, sub) in subs {
        let feed = match store::get_feed_by_url(pool, &sub.url).await {
            Ok(Some(f)) => Some(f),
            Ok(None) => {
                // `sub.url` came out of an atproto record. The lexicon is open —
                // ANY client can write a subscription into a user's repo — so
                // this is untrusted input on the hot path of `GET /`, and it was
                // being stored with none of the three checks the add and import
                // paths apply. Two of those are capacity ceilings; this one is
                // the invariant in `FeedPrivacy`'s doc comment, which promises a
                // private feed URL is "never stored". Writing a
                // `…/feed/private/<token>` into the SHARED `feeds` table breaks
                // that promise even though `net::guarded_get` still refuses to
                // fetch it.
                if !feed::is_storable_feed_url(&sub.url, state.config.standard_site)
                    || feed::classify_feed_privacy(&sub.url).is_private()
                {
                    warn!(
                        %did,
                        "skipping cache row for a subscription URL that is private or not http(s)"
                    );
                    out.push(ResolvedSub {
                        rkey,
                        sub,
                        feed: None,
                    });
                    continue;
                }
                // Upsert a cache row so the sidebar reflects the real follow-list.
                //
                // A silent failure here is a support ticket with no evidence: no
                // `feeds` row means the poller never selects this subscription,
                // so the reader sees "I added a feed and it never updates" while
                // the PDS record looks perfect. Logged with the URL so the
                // failing subscription is identifiable.
                if let Err(err) = store::upsert_feed(
                    pool,
                    &store::NewFeed {
                        url: sub.url.clone(),
                        title: sub.title.clone(),
                        site_url: sub.site_url.clone(),
                        ..Default::default()
                    },
                )
                .await
                {
                    warn!(%err, url = %sub.url, %did, "could not cache a subscribed feed; \
                                                       it will not be polled");
                }
                store::get_feed_by_url(pool, &sub.url).await.ok().flatten()
            }
            Err(err) => {
                warn!(%err, url = %sub.url, "get_feed_by_url failed");
                None
            }
        };
        out.push(ResolvedSub { rkey, sub, feed });
    }
    // Mirror the caller's resolved subscription set into `sub_ref`, so every
    // scoped entry/feed read + read/star mutation authorizes against exactly
    // the feeds this DID follows right now. This is THE per-DID isolation hook.
    sync_sub_refs(pool, did, &out).await;
    (out, None)
}

/// Refresh the `sub_ref` projection for `did` to exactly the feed ids present
/// in `subs`. Best-effort: a failure here only degrades the scoped reads (they
/// fail closed / show fewer rows), never leaks another user's entries.
async fn sync_sub_refs(pool: &store::Pool, did: &str, subs: &[ResolvedSub]) {
    let feed_ids: Vec<i64> = subs
        .iter()
        .filter_map(|s| s.feed.as_ref().map(|f| f.id))
        .collect();
    if let Err(err) = store::replace_sub_refs(pool, did, &feed_ids).await {
        warn!(%err, %did, "failed to sync sub_ref projection");
    }
}

/// `GET /` — the reader. Renders the sidebar (folders + feeds from the PDS
/// records layer) and the article list for the selected scope + view.
async fn index(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<IndexQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        // Signed out: serve the public landing page rather than bouncing to
        // /login. /login remains the entry point for the actual OAuth sign-in.
        None => {
            return Ok(render(&LandingTemplate {
                card: Card::site(&state.config),
                version: VERSION,
                repo_url: REPO_URL,
                crates_url: CRATES_URL,
                kofi_url: KOFI_URL,
                standard_site: state.config.standard_site,
                releases: RELEASES,
            }))
        }
    };
    let did = user.did.clone();
    let pool = &state.db;

    let (subs, alert) = resolve_subscriptions_noting(&state, &did).await;

    // View: unread (default) | all | starred.
    let view = match q.view.as_deref() {
        Some("all") => "all",
        Some("starred") => "starred",
        _ => "unread",
    }
    .to_string();
    let list_view = list_view_of(q.view.as_deref());

    // Which feed URLs are in scope?
    let scope_urls = scope_urls_for(&subs, q.feed.as_deref(), q.folder.as_deref());
    // …and the feed ids they resolve to. Scope is applied inside the query now,
    // so a page is a page of rows the reader will actually see. Filtering after
    // a `LIMIT` would have made pages arbitrarily short — sometimes empty — for
    // any scope narrower than the whole subscription list.
    let scope_ids = scoped_feed_ids(&subs, &scope_urls);

    let feed_title_by_id = |id: i64| -> String {
        subs.iter()
            .find(|s| s.feed.as_ref().map(|f| f.id) == Some(id))
            .map(|s| {
                display_title(
                    s.sub
                        .title
                        .as_deref()
                        .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
                    &s.sub.url,
                )
            })
            .unwrap_or_default()
    };

    // **One page of the chosen view, filtered, ordered and bounded in SQL.**
    //
    // All three views used to materialize every matching entry — `SELECT e.*`,
    // no `LIMIT`, article bodies included — and the "all" view additionally ran
    // one such query PER SUBSCRIBED FEED and merged the results in memory. None
    // of the row fields below read the body. See `store::EntryListRow`.
    // **Saved records the cache cannot show.**
    //
    // The starred view is built from local `entries`, so a saved record whose
    // article was never cached here is invisible — the case that matters is
    // starring in ANOTHER atproto reader, which is the portability the shared
    // lexicon exists for. Those rows are rendered from the PDS record alone.
    let mut uncached: Vec<EntryRow> = Vec::new();
    if view == "starred" {
        // **Match against every SUBSCRIBED cached starred entry, not `source`.**
        //
        // `source` has already been filtered by feed/folder. Matching against it
        // meant an entry that IS cached but sits outside the current filter
        // looked uncached — so it rendered as a "not cached" row whose star
        // button deletes the PDS RECORD instead of un-starring the entry. A
        // scope filter must not change what is destroyed. Paging is the same
        // hazard in a new form: matching against the visible PAGE would make
        // every cached article outside it look uncached. Hence a dedicated
        // identity query over the whole starred set — urls and guids only, no
        // bodies — rather than reusing `source`.
        //
        // One gap remains BY DESIGN, and is handled at the other end. This query
        // still carries the `sub_ref` predicate, so a starred, cached entry in a
        // feed the reader has UNSUBSCRIBED from is absent here and its record
        // renders as uncached. That is the right rendering — the article is no
        // longer part of any feed the reader follows, and the PDS record is what
        // still holds it — but it means the un-save button is the record-deleting
        // one. `unsave_record` therefore clears the local star too, so the two
        // stores agree however the row got classified. Dropping the predicate
        // here instead would have made the row link to `/entries/{id}`, which is
        // `sub_ref`-scoped and would 404.
        //
        // **Three ways this can be unusable, and all three fail CLOSED.** With an
        // incomplete identity set, a cached article looks uncached and renders an
        // un-save button that deletes the PDS RECORD. Showing no uncached rows
        // loses rows for one render; getting this wrong loses data permanently,
        // so every uncertain case suppresses them.
        let identities = match store::starred_identities(pool, &did, STARRED_IDENTITY_MAX).await {
            Ok(store::StarredIdentities::All(rows)) => Some(rows),
            // The cap is a memory backstop, and reaching it means the set is an
            // arbitrary subset. It used to return that subset with no way to
            // tell, so every starred article outside it got the destructive
            // button.
            Ok(store::StarredIdentities::Truncated) => {
                warn!(
                    %did,
                    cap = STARRED_IDENTITY_MAX,
                    "cached-starred set exceeded its cap; suppressing uncached saved rows \
                     rather than rendering record-deleting buttons for cached articles"
                );
                None
            }
            Err(err) => {
                warn!(%err, %did, "cached-starred identity lookup failed; \
                                    suppressing uncached saved rows this render");
                None
            }
        };
        // The escape hatch asks whether this DID has ANY cached starred entry —
        // not whether the current SCOPE does. `total` is narrowed by
        // `?feed=`/`?folder=` while the identity set spans every feed, so
        // comparing them waved the fail-closed condition through for any narrow
        // scope: a record whose `feedUrl` matched the filter while its cached
        // entry lived under another feed rendered as uncached.
        let identities_ok = identities.is_some();
        let identities = identities.unwrap_or_default();
        let cached_urls: std::collections::HashSet<&str> = identities
            .iter()
            .filter_map(|(url, _)| url.as_deref())
            .collect();
        let cached_guids: std::collections::HashSet<&str> =
            identities.iter().map(|(_, guid)| guid.as_str()).collect();

        // Collected in full here, sliced per page later. They sort after every
        // cached row, so the two lists form one sequence that the pager walks —
        // see the slice below. Collected BEFORE the page is chosen because the
        // page count depends on how many there are.
        // Bounded like everything else on this page. These come from the PDS
        // (up to the list ceiling — 20,000 on the sidecar backend, 5,000 on
        // `backend=rust`, whose caps are a quarter of the other's) and are
        // appended whole to the last page, so `ENTRIES_PER_PAGE` does not
        // constrain them at all. The
        // cap is generous — a reader with more saved-elsewhere records than this
        // is not the case being designed for — but a response has to have a size
        // an operator can reason about.
        let mut uncached_dropped = 0usize;
        match state.repo().list_saved_sorted(&did).await {
            Ok(saved) if identities_ok => {
                for (rkey, item) in saved {
                    let known = cached_urls.contains(item.url.as_str())
                        || item
                            .entry_id
                            .as_deref()
                            .is_some_and(|g| cached_guids.contains(g));
                    if known {
                        continue;
                    }
                    // And the scope filter applies to these rows too. Without
                    // it, `?feed=X` still listed saved records from every other
                    // feed — the filter silently did nothing for them.
                    if let Some(urls) = &scope_urls {
                        match item.feed_url.as_deref() {
                            Some(feed_url) if urls.iter().any(|u| u == feed_url) => {}
                            // A saved record with no `feedUrl` cannot be placed
                            // in any feed's scope, so it belongs only to the
                            // unfiltered view.
                            _ => continue,
                        }
                    }
                    // **`safe_link` FIRST, and a failure no longer drops the row.**
                    //
                    // `item.url` is attacker-controlled — a saved record written
                    // by any client — and it lands in an `href`. Askama escapes
                    // HTML metacharacters but not SCHEMES, so `javascript:`
                    // survives escaping intact. This project already built the
                    // helper for exactly that, and `feed.rs` uses it on the
                    // equivalent link; this path was simply not routed through it.
                    //
                    // The real defect was what a failure DID: it `continue`d, so
                    // the row vanished entirely — no badge, no count, nothing —
                    // and the only trace was a `debug!` below any realistic
                    // filter. That makes the record unremovable FROM HERE, because
                    // the un-save button lives on the row; the reader has to open
                    // a different atproto client to get rid of it. A bad URL is a
                    // reason to withhold the LINK, not the row.
                    //
                    // The check also moved ABOVE the poll nudge. That is ordering
                    // hygiene rather than a fix: the nudge keys on `feed_url`, not
                    // on the URL being rejected here, and is already gated on the
                    // reader actually subscribing to that feed — so it was never
                    // reachable by an unusable `item.url`. Deciding whether a
                    // record is renderable before doing anything outbound on its
                    // behalf is simply the order that stays correct if either of
                    // those two facts later stops being true.
                    let link = SafeLink::external(&item.url);
                    if link.is_empty() {
                        warn!(
                            %did, %rkey,
                            "a saved record has an unusable URL; rendering it without a link \
                             so it can still be removed"
                        );
                    }

                    // Opportunistic re-fetch: if the reader still subscribes to
                    // the feed, make it due now. If the article is still inside
                    // the feed's window the poller caches it normally and this
                    // row becomes a real entry on its own — no synthetic rows in
                    // the shared cache, which every subscriber would otherwise
                    // see as a content-less entry.
                    // **Bound the WORK, not just the response.** This check sat
                    // after the nudge and the `subs` scan below, so every render
                    // still walked all ≤20,000 PDS records, ran a subs-length
                    // string scan per record, and issued up to that many
                    // `mark_feed_due` round-trips on a 5-connection pool — then
                    // discarded everything past the cap. A cap that runs after
                    // the expensive part is a cap on the output only.
                    if uncached.len() >= MAX_UNCACHED_SAVED_ROWS {
                        uncached_dropped += 1;
                        continue;
                    }
                    if let Some(feed_url) = item.feed_url.as_deref() {
                        if subs.iter().any(|s| s.sub.url == feed_url) {
                            // Bounded to one nudge per feed per poll interval —
                            // see `mark_feed_due`. Unbounded, a reload loop here
                            // becomes outbound amplification.
                            let stale_before = (chrono::Utc::now()
                                - chrono::Duration::from_std(state.config.poll_interval)
                                    .unwrap_or_else(|_| chrono::Duration::hours(1)))
                            .to_rfc3339_opts(chrono::SecondsFormat::Secs, true);
                            if let Err(err) =
                                store::mark_feed_due(pool, feed_url, &stale_before).await
                            {
                                tracing::debug!(%err, %feed_url, "could not nudge a feed for a saved article");
                            }
                        }
                    }
                    uncached.push(EntryRow {
                        id: 0,
                        title: item
                            .title
                            .clone()
                            .filter(|t| !t.trim().is_empty())
                            // Falling back to the URL is fine for a link we are
                            // willing to render, and wrong for one we are not:
                            // it would put the exact string `safe_link` just
                            // rejected into the page as the record's name. The
                            // rkey is what the un-save button acts on, so it is
                            // the honest identifier for a row that has nothing
                            // else trustworthy to show.
                            .unwrap_or_else(|| {
                                if link.is_empty() {
                                    format!("Saved item {rkey}")
                                } else {
                                    item.url.clone()
                                }
                            }),
                        feed_title: item.feed_url.clone().unwrap_or_default(),
                        published: display_date(Some(&item.created_at)),
                        read: false,
                        starred: true,
                        // Empty = "render this row without an anchor". The
                        // template branches on it, so the rejected URL never
                        // reaches an `href` even as an escaped string.
                        link,
                        cached: false,
                        rkey,
                    });
                }
            }
            // Identity lookup was unusable — see the fail-closed note above.
            Ok(_) => {}
            Err(err) => warn!(%err, %did, "could not list saved records from the PDS"),
        }
        if uncached_dropped > 0 {
            warn!(
                %did,
                dropped = uncached_dropped,
                cap = MAX_UNCACHED_SAVED_ROWS,
                "more saved records than this instance will hold in one response; the \
                 rest are not reachable from here"
            );
        }
    }

    // **One sequence, two sources.** The cached rows come from SQL, the uncached
    // PDS records follow them, and the pager walks the concatenation.
    //
    // The first version appended the uncached rows to the last page only and
    // kept them out of `total`, which left everything past a cap invisible AND
    // unremovable — the un-save button lives on the row, and there is no other
    // surface in the app that lists these. That is the same "unremovable FROM
    // HERE" hazard the `safe_link` fix above exists to prevent, reintroduced
    // forty lines later by a bound meant to protect memory.
    //
    // Paging the concatenation makes every record reachable and needs no cap on
    // what is RENDERED — one page is one page either way. The version before
    // that inflated `total` while clamping on the cached count, which advertised
    // a page the clamp could never reach; both numbers come from the same total
    // now, which is what makes that impossible rather than merely fixed.
    let total_cached =
        store::count_entries_for_view(pool, &did, list_view, scope_ids.as_deref()).await?;
    let uncached_len = uncached.len();
    let total = total_cached + uncached_len as i64;
    // Clamped to the range that exists. Past the end the list is empty, and the
    // empty state renders instead of the pager — which would strand a reader who
    // typed a page number, or who paged to the end and then marked entries read
    // out from under their own URL. Showing the last page is the answer to both.
    let page = i64::from(q.page.unwrap_or(1).max(1)).min(page_count_for(total));
    let offset = (page - 1) * ENTRIES_PER_PAGE;
    // Past the cached rows this returns nothing, which is exactly right: the
    // page is then made up entirely of uncached ones.
    let source = store::list_entries(
        pool,
        &did,
        list_view,
        scope_ids.as_deref(),
        ENTRIES_PER_PAGE,
        offset,
    )
    .await?;
    // **Both halves of the page are computed from the COUNT alone.**
    //
    // `total_cached` (a COUNT) and `source` (a SELECT) are separate unsynchronised
    // queries, so they can disagree about how many cached rows exist. Any part of
    // the page composition that reads `source.len()` inherits that disagreement.
    //
    // `cached_allotment` is this page's cached share according to the snapshot,
    // and it is what the uncached `skip`/`take` are derived from — so consecutive
    // pages tile the uncached list exactly, whichever way the count drifted.
    // `source` is then truncated to it only to avoid rendering rows the next page
    // will also claim.
    //
    // The previous version took `skip` from the count but `take` from
    // `source.len()`, which agreed only when the count UNDERSTATED. Overstating —
    // an un-star or a retention delete landing between the two queries — made
    // page N render `uncached[0..70]` while page N+1 rendered `uncached[50..80]`,
    // putting twenty rows, each carrying the record-DELETING un-save button, on
    // two pages at once. The comment claimed that shape was impossible; it was
    // merely rarer.
    let cached_allotment = (total_cached - offset).clamp(0, ENTRIES_PER_PAGE) as usize;
    let cached_here = cached_allotment.min(source.len());
    // Only compose when there is something to compose WITH. `uncached` is empty
    // on every view but `starred`, and truncating there just drops trailing rows
    // that no page then shows — the poller inserting between the COUNT and the
    // SELECT was enough to trigger it.
    let source = if uncached_len == 0 {
        &source[..]
    } else {
        &source[..cached_here]
    };
    let uncached_page: Vec<EntryRow> = {
        let skip = (offset - total_cached).max(0) as usize;
        let take = (ENTRIES_PER_PAGE as usize) - cached_allotment;
        uncached.into_iter().skip(skip).take(take).collect()
    };
    // This page's slice, used only to append below. The heading needs the
    // WHOLE-list figure, which is the set's size before slicing.
    let uncached_total = uncached_len as i64;

    // The scope/view suffix carried onto every entry link (built once).
    let entry_scope_qs = {
        let mut parts = Vec::new();
        if let Some(f) = q.feed.as_deref() {
            parts.push(format!("feed={}", qenc(f)));
        }
        if let Some(f) = q.folder.as_deref() {
            parts.push(format!("folder={}", qenc(f)));
        }
        if view != "unread" {
            parts.push(format!("view={}", qenc(&view)));
        }
        parts.join("&")
    };
    let entries: Vec<EntryRow> = source
        .iter()
        .map(|e| EntryRow {
            id: e.id,
            title: e
                .title
                .clone()
                .filter(|t| !t.trim().is_empty())
                .unwrap_or_else(|| "(untitled)".to_string()),
            feed_title: feed_title_by_id(e.feed_id),
            published: display_date(e.published.as_deref()),
            // Both bits ride along on the row's own `entry_state` join now. They
            // used to be membership tests against the full unread and starred
            // sets, which is why those two lists were fetched in their entirety
            // on every render even when the page showed a hundred rows.
            read: e.read,
            starred: e.starred,
            link: SafeLink::entry(e.id, &entry_scope_qs),
            cached: true,
            rkey: String::new(),
        })
        .collect();

    // The uncached slice for this page follows the cached rows.
    let mut entries = entries;
    entries.extend(uncached_page);
    let entries = entries;

    let selected_feed = q.feed.as_deref();
    let selected_folder = q.folder.as_deref();

    // Build the shared sidebar (folders + loose feeds, with unread counts).
    let (folder_views, loose_feeds, _folder_options) =
        build_sidebar(&state, &did, &subs, selected_feed, selected_folder).await;

    // Heading + scope query-string suffix.
    let (heading, scope_qs) = if let Some(feed_url) = selected_feed {
        let name = subs
            .iter()
            .find(|s| s.sub.url == feed_url)
            .map(|s| {
                display_title(
                    s.sub
                        .title
                        .as_deref()
                        .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
                    &s.sub.url,
                )
            })
            .unwrap_or_else(|| display_title(None, feed_url));
        (name, format!("feed={}", qenc(feed_url)))
    } else if let Some(folder_uri) = selected_folder {
        let name = folder_views
            .iter()
            .find(|f| f.uri == folder_uri)
            .map(|f| f.name.clone())
            .unwrap_or_else(|| "Folder".to_string());
        (name, format!("folder={}", qenc(folder_uri)))
    } else {
        let h = match view.as_str() {
            "all" => "All",
            "starred" => "Starred",
            _ => "Unread",
        };
        (h.to_string(), String::new())
    };

    let feed_scope = selected_feed.map(str::to_string);
    let nav = build_nav(&user, &view, scope_qs, folder_views, loose_feeds, false);

    // Pager links. `entry_scope_qs` already carries feed/folder/view, so the
    // page number is the only thing appended — which keeps a paged link
    // identical to an unpaged one in every other respect.
    let page_href = |n: i64| -> String {
        let mut parts = Vec::new();
        if !entry_scope_qs.is_empty() {
            parts.push(entry_scope_qs.clone());
        }
        if n > 1 {
            parts.push(format!("page={n}"));
        }
        if parts.is_empty() {
            "/".to_string()
        } else {
            format!("/?{}", parts.join("&"))
        }
    };
    let prev_href = (page > 1).then(|| page_href(page - 1));
    let next_href = (page * ENTRIES_PER_PAGE < total).then(|| page_href(page + 1));

    let tmpl = IndexTemplate {
        card: Card::private(&state.config),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        flash: q.flash.unwrap_or_default(),
        alert: alert.unwrap_or_default(),
        nav,
        entries,
        heading,
        feed_scope,
        total,
        // Whole-list figure, so it sits beside `total` without double counting.
        // The per-page slice is composed above and is not a heading number.
        uncached_total,
        page,
        page_count: page_count_for(total),
        prev_href,
        next_href,
    };
    Ok(render(&tmpl))
}

/// Query for `GET /manage` — carries an optional flash after an action redirect.
#[derive(Debug, Deserialize, Default)]
struct ManageQuery {
    #[serde(default)]
    flash: Option<String>,
}

/// `GET /manage` — the feed-management page. Renders the rail plus the subscribe
/// / your-feeds / OPML surfaces; the forms POST to the existing routes
/// (`/subscriptions`, `/folders`, `/opml`, …). A read/render route only — no
/// mutation logic of its own.
async fn manage(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<ManageQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();

    let (subs, alert) = resolve_subscriptions_noting(&state, &did).await;
    let (folder_views, loose_feeds, folder_options) =
        build_sidebar(&state, &did, &subs, None, None).await;

    // Clone the sidebar for the rail; the page body reuses folders/loose feeds.
    let nav = build_nav(
        &user,
        "unread",
        String::new(),
        folder_views.iter().map(clone_folder_view).collect(),
        loose_feeds.iter().map(clone_feed_view).collect(),
        true,
    );

    let tmpl = ManageTemplate {
        card: Card::private(&state.config),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        flash: q.flash.unwrap_or_default(),
        alert: alert.unwrap_or_default(),
        nav,
        folder_options,
        folders: folder_views,
        loose_feeds,
        standard_site: state.config.standard_site,
    };
    Ok(render(&tmpl))
}

/// Shallow clone helpers so `/manage` can hand the same sidebar to both the rail
/// (`Nav`) and the page body without an extra DB round-trip.
fn clone_feed_view(f: &FeedView) -> FeedView {
    FeedView {
        rkey: f.rkey.clone(),
        url: f.url.clone(),
        title: f.title.clone(),
        unread: f.unread,
        selected: f.selected,
        folder: f.folder.clone(),
    }
}

fn clone_folder_view(f: &FolderView) -> FolderView {
    FolderView {
        rkey: f.rkey.clone(),
        uri: f.uri.clone(),
        name: f.name.clone(),
        feeds: f.feeds.iter().map(clone_feed_view).collect(),
        selected: f.selected,
    }
}

/// The set of feed URLs a scope covers: `Some([one url])` for a single-feed
/// scope, `Some([urls…])` for a folder (its member feeds), or `None` for the
/// unscoped "everything" view. A folder scope takes the feed scope when both are
/// somehow present (feed wins, matching the query precedence elsewhere).
fn scope_urls_for(
    subs: &[ResolvedSub],
    feed: Option<&str>,
    folder: Option<&str>,
) -> Option<Vec<String>> {
    if let Some(feed_url) = feed {
        Some(vec![feed_url.to_string()])
    } else {
        folder.map(|folder_uri| {
            subs.iter()
                .filter(|s| s.sub.folder.as_deref() == Some(folder_uri))
                .map(|s| s.sub.url.clone())
                .collect()
        })
    }
}

/// The `at://` URI for a folder record given the owner DID + rkey.
fn folder_uri(did: &str, rkey: &str) -> String {
    format!("at://{did}/{}/{rkey}", lexicon::nsid::FOLDER)
}

/// Build the sidebar folder/loose-feed views (with per-feed unread counts) for a
/// DID — the shared source for both the reader index and the rail on every
/// chrome page. `selected_feed` / `selected_folder` drive `aria-current`.
async fn build_sidebar(
    state: &AppState,
    did: &str,
    subs: &[ResolvedSub],
    selected_feed: Option<&str>,
    selected_folder: Option<&str>,
) -> (Vec<FolderView>, Vec<FeedView>, Vec<FolderOption>) {
    let pool = &state.db;
    // Counted in SQL. This used to fetch every unread ENTRY — article bodies and
    // all — purely to `.filter().count()` them in Rust, on every page that
    // renders chrome, which made the sidebar the most frequently executed
    // instance of the unbounded-projection problem.
    let unread_counts = store::unread_counts_by_feed(pool, did)
        .await
        .unwrap_or_else(|err| {
            warn!(%err, %did, "sidebar unread counts failed; rendering zeroes");
            Default::default()
        });
    let folders = state
        .repo()
        .list_folders_sorted(did)
        .await
        .unwrap_or_default();

    let unread_count = |feed_id: Option<i64>| -> i64 {
        feed_id
            .and_then(|id| unread_counts.get(&id).copied())
            .unwrap_or(0)
    };
    let mk_feed_view = |s: &ResolvedSub| FeedView {
        rkey: s.rkey.clone(),
        url: s.sub.url.clone(),
        title: display_title(
            s.sub
                .title
                .as_deref()
                .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
            &s.sub.url,
        ),
        unread: unread_count(s.feed.as_ref().map(|f| f.id)),
        selected: selected_feed == Some(s.sub.url.as_str()),
        folder: s.sub.folder.clone(),
    };

    let mut folder_views = Vec::with_capacity(folders.len());
    for (rkey, folder) in &folders {
        let uri = folder_uri(did, rkey);
        let feeds: Vec<FeedView> = subs
            .iter()
            .filter(|s| s.sub.folder.as_deref() == Some(uri.as_str()))
            .map(mk_feed_view)
            .collect();
        folder_views.push(FolderView {
            rkey: rkey.clone(),
            uri: uri.clone(),
            name: folder.name.clone(),
            feeds,
            selected: selected_folder == Some(uri.as_str()),
        });
    }

    let known_uris: std::collections::HashSet<String> =
        folders.iter().map(|(r, _)| folder_uri(did, r)).collect();
    let loose_feeds: Vec<FeedView> = subs
        .iter()
        .filter(|s| {
            s.sub
                .folder
                .as_deref()
                .map(|f| !known_uris.contains(f))
                .unwrap_or(true)
        })
        .map(mk_feed_view)
        .collect();

    let folder_options: Vec<FolderOption> = folders
        .iter()
        .map(|(rkey, folder)| FolderOption {
            name: folder.name.clone(),
            uri: folder_uri(did, rkey),
        })
        .collect();

    (folder_views, loose_feeds, folder_options)
}

/// Assemble the shared rail [`Nav`] for a chrome page.
fn build_nav(
    user: &CurrentUser,
    view: &str,
    scope_qs: String,
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
    manage_active: bool,
) -> Nav {
    Nav {
        handle: display_handle(user.handle.as_deref(), &user.did),
        avatar: avatar_initials(user.handle.as_deref(), &user.did),
        view: view.to_string(),
        scope_qs,
        folders,
        loose_feeds,
        manage_active,
    }
}

// ---------------------------------------------------------------------------
// Reader: single entry
// ---------------------------------------------------------------------------

/// Query for `GET /entries/:id` — carries the reading context (scope + view) so
/// prev/next and "back" stay within the list the reader came from.
#[derive(Debug, Deserialize, Default)]
struct EntryQuery {
    #[serde(default)]
    feed: Option<String>,
    #[serde(default)]
    folder: Option<String>,
    #[serde(default)]
    view: Option<String>,
}

/// `GET /entries/:id` — the clean reader view for one entry, with prev/next
/// within the current reading list.
async fn entry_view(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(id): Path<i64>,
    Query(q): Query<EntryQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();
    let pool = &state.db;

    // Resolve subscriptions FIRST: this refreshes the `sub_ref` projection so
    // the per-DID entry gate below authorizes against the caller's current PDS
    // subscription set (not another user's cached feeds).
    let subs = resolve_subscriptions(&state, &did).await;

    let entry = match get_entry_by_id(pool, &did, id).await? {
        Some(e) => e,
        None => return Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    };

    let feed_title = feed_title_by_entry(pool, entry.feed_id).await;

    let read = entry_is_read(pool, &did, id).await?;
    let starred = entry_is_starred(pool, &did, id).await?;

    // Reconstruct the current list to compute prev/next, so paging in the reader
    // matches what the list showed.
    let (prev_id, next_id) = neighbors_in_scope(&state, &did, &q, id).await;

    let back_qs = scope_query(&q);

    let (folder_views, loose_feeds, _) =
        build_sidebar(&state, &did, &subs, q.feed.as_deref(), q.folder.as_deref()).await;
    let nav_view = match q.view.as_deref() {
        Some("all") => "all",
        Some("starred") => "starred",
        _ => "unread",
    };
    let nav = build_nav(
        &user,
        nav_view,
        back_qs.clone(),
        folder_views,
        loose_feeds,
        false,
    );

    let tmpl = EntryTemplate {
        card: Card::private(&state.config),
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        nav,
        id: entry.id,
        title: entry
            .title
            .clone()
            .filter(|t| !t.trim().is_empty())
            .unwrap_or_else(|| "(untitled)".to_string()),
        feed_title,
        author: entry.author.clone().filter(|a| !a.trim().is_empty()),
        published: display_date(entry.published.as_deref()),
        url: entry.url.as_deref().and_then(SafeLink::external_opt),
        content_html: entry.content_html.clone(),
        read,
        starred,
        back_qs,
        prev_id,
        next_id,
        oob: false,
    };
    Ok(render(&tmpl))
}

/// Compute the prev/next entry ids around `current` within the reader's current
/// scope + view, so the reader view can offer keyboard/paging navigation.
async fn neighbors_in_scope(
    state: &AppState,
    did: &str,
    q: &EntryQuery,
    current: i64,
) -> (Option<i64>, Option<i64>) {
    let idx_q = IndexQuery {
        feed: q.feed.clone(),
        folder: q.folder.clone(),
        view: q.view.clone(),
        // Neighbours span the whole list, not the page the reader arrived from.
        page: None,
        flash: None,
    };
    let ids = list_entry_ids(state, did, &idx_q).await;
    let pos = ids.iter().position(|&x| x == current);
    match pos {
        Some(p) => {
            let prev = if p > 0 { Some(ids[p - 1]) } else { None };
            let next = ids.get(p + 1).copied();
            (prev, next)
        }
        None => (None, None),
    }
}

/// The ordered entry ids for a scope + view — the same ordering `index` renders,
/// used for reader prev/next. Best-effort; PDS failures degrade to local cache.
async fn list_entry_ids(state: &AppState, did: &str, q: &IndexQuery) -> Vec<i64> {
    let pool = &state.db;
    let subs = resolve_subscriptions(state, did).await;

    let scope_urls = scope_urls_for(&subs, q.feed.as_deref(), q.folder.as_deref());

    // Ids only, and bounded. This used to fetch whole entries — bodies included
    // — for all three views and then throw everything but `id` away; the "all"
    // branch additionally ran one unbounded query PER FEED and sorted the union
    // in memory. Scope is now a feed-id restriction inside the query, so the
    // database does the filtering and the ordering exactly once.
    store::list_entry_ids(
        pool,
        did,
        list_view_of(q.view.as_deref()),
        scoped_feed_ids(&subs, &scope_urls).as_deref(),
        PREV_NEXT_MAX,
    )
    .await
    .unwrap_or_else(|err| {
        warn!(%err, %did, "prev/next id list failed; the reader loses its neighbour links");
        Vec::new()
    })
}

/// Map the `?view=` query value onto the store's list view. Anything
/// unrecognised is the unread default, matching `index`.
fn list_view_of(view: Option<&str>) -> store::ListView {
    match view {
        Some("all") => store::ListView::All,
        Some("starred") => store::ListView::Starred,
        _ => store::ListView::Unread,
    }
}

/// Translate a feed/folder scope into the feed ids to restrict a list query to.
///
/// `None` means unscoped (every subscribed feed). `Some(&[])` means the scope
/// matched no local feed, which must return nothing rather than everything — so
/// the empty vec is deliberately preserved, not collapsed back into `None`.
fn scoped_feed_ids(subs: &[ResolvedSub], scope_urls: &Option<Vec<String>>) -> Option<Vec<i64>> {
    let urls = scope_urls.as_ref()?;
    Some(
        subs.iter()
            .filter(|s| urls.contains(&s.sub.url))
            .filter_map(|s| s.feed.as_ref().map(|f| f.id))
            .collect(),
    )
}

/// Build a `?…` query string that preserves the reading scope + view for links.
fn scope_query(q: &EntryQuery) -> String {
    let mut parts = Vec::new();
    if let Some(f) = q.feed.as_deref() {
        parts.push(format!("feed={}", qenc(f)));
    }
    if let Some(f) = q.folder.as_deref() {
        parts.push(format!("folder={}", qenc(f)));
    }
    if let Some(v) = q.view.as_deref() {
        if v != "unread" {
            parts.push(format!("view={}", qenc(v)));
        }
    }
    parts.join("&")
}

// ---------------------------------------------------------------------------
// Mark read / unread
// ---------------------------------------------------------------------------

/// Form body for `POST /entries/:id/read`.
#[derive(Debug, Deserialize)]
struct ReadForm {
    #[serde(default)]
    read: Option<String>,
}

/// `POST /entries/:id/read` — toggle an entry's read-state for the current DID.
async fn mark_read(
    State(state): State<AppState>,
    Path(id): Path<i64>,
    headers: HeaderMap,
    Form(form): Form<ReadForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    let read = matches!(
        form.read.as_deref(),
        Some("true") | Some("1") | Some("on") | None
    );

    // Refresh the caller's `sub_ref` projection, then apply the AUTHORIZED
    // mutation: `mark_read` only writes when `did` subscribes to the entry's
    // feed. A non-subscriber gets a 404, never a mutation of someone else's
    // (or the shared cache's) state.
    resolve_subscriptions(&state, &did).await;
    if !store::mark_read(pool, &did, id, read).await? {
        return Ok((StatusCode::NOT_FOUND, "entry not found").into_response());
    }

    if !is_htmx(&headers) {
        return Ok(Redirect::to("/").into_response());
    }

    // The reader view swaps an out-of-band action-bar fragment (its `<li>` isn't
    // in the DOM), so its button's hidden value + aria-pressed update in place
    // and a second keypress can reverse the toggle. The list view swaps the row.
    if is_reader_request(&headers) {
        let starred = entry_is_starred(pool, &did, id).await?;
        return Ok(render(&EntryActionBarTemplate {
            id,
            read,
            starred,
            oob: true,
        }));
    }

    let row = build_entry_row(pool, &did, id, Some(read)).await?;
    match row {
        Some(r) => Ok(render(&EntryRowTemplate { e: r })),
        None => Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    }
}

// ---------------------------------------------------------------------------
// Star / save
// ---------------------------------------------------------------------------

/// Form body for `POST /entries/:id/star`.
#[derive(Debug, Deserialize)]
struct StarForm {
    #[serde(default)]
    starred: Option<String>,
}

/// `POST /entries/:id/star` — star/unstar an entry.
///
/// Sets the local `starred` bit (fast working copy) and writes/removes a
/// `community.lexicon.rss.saved` record in the user's PDS (stars are worth
/// owning). The PDS write is best-effort — the local star still lands.
async fn toggle_star(
    State(state): State<AppState>,
    Path(id): Path<i64>,
    headers: HeaderMap,
    Form(form): Form<StarForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    let starred = matches!(
        form.starred.as_deref(),
        Some("true") | Some("1") | Some("on") | None
    );

    // Refresh the caller's `sub_ref` projection, then apply the AUTHORIZED
    // mutation: `mark_starred` only writes when `did` subscribes to the entry's
    // feed. A non-subscriber gets a 404, never a mutation.
    resolve_subscriptions(&state, &did).await;
    if !store::mark_starred(pool, &did, id, starred).await? {
        return Ok((StatusCode::NOT_FOUND, "entry not found").into_response());
    }

    // Reflect into the PDS saved-records collection. `get_entry_by_id` is scoped
    // to the caller's subscriptions, so this only ever acts on the caller's feed.
    if let Ok(Some(entry)) = get_entry_by_id(pool, &did, id).await {
        let entry_url = entry.url.clone().unwrap_or_default();
        if !entry_url.is_empty() {
            if starred {
                let mut saved = Saved::new(entry_url.clone(), now_rfc3339());
                saved.title = entry.title.clone();
                saved.feed_url = feed_url_for_id(pool, entry.feed_id).await;
                saved.entry_id = Some(entry.guid.clone());
                match state.repo().add_saved(&did, &saved).await {
                    Ok(rkey) => info!(%did, url = %entry_url, %rkey, "wrote saved record to PDS"),
                    Err(err) => warn!(%err, %did, "PDS saved write failed (starred locally)"),
                }
            } else {
                // Un-star: find and delete the matching saved record by URL.
                match state.repo().list_saved(&did).await {
                    Ok(records) => {
                        for (rkey, _rec) in records.iter().filter(|(_, r)| r.url == entry_url) {
                            if let Err(err) = state.repo().remove_saved(&did, rkey).await {
                                warn!(%err, %did, %rkey, "PDS saved delete failed");
                            }
                        }
                    }
                    Err(err) => warn!(%err, %did, "could not list saved records to un-star"),
                }
            }
        }
    }

    if !is_htmx(&headers) {
        return Ok(Redirect::to("/").into_response());
    }

    // Reader → out-of-band action-bar fragment; list → the row (see mark_read).
    if is_reader_request(&headers) {
        let read = entry_is_read(pool, &did, id).await?;
        return Ok(render(&EntryActionBarTemplate {
            id,
            read,
            starred,
            oob: true,
        }));
    }

    let row = build_entry_row(pool, &did, id, None).await?;
    match row {
        Some(r) => Ok(render(&EntryRowTemplate { e: r })),
        None => Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    }
}

/// The feed URL for a cached feed id, if the row exists.
async fn feed_url_for_id(pool: &store::Pool, feed_id: i64) -> Option<String> {
    sqlx::query_scalar::<_, String>("SELECT url FROM feeds WHERE id = ?1")
        .bind(feed_id)
        .fetch_optional(pool)
        .await
        .ok()
        .flatten()
}

// ---------------------------------------------------------------------------
// Mark-all-read
// ---------------------------------------------------------------------------

/// Query for `POST /read-all` — an optional `?feed=<url>` scopes it to one feed;
/// absent means mark everything read.
#[derive(Debug, Deserialize, Default)]
struct ReadAllQuery {
    #[serde(default)]
    feed: Option<String>,
}

/// `POST /read-all` — mark every entry read for the current DID, optionally
/// scoped to one feed (mark-all-read per feed or globally).
async fn mark_all_read(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<ReadAllQuery>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    // Refresh the caller's `sub_ref` projection so the scoped mark-read writes
    // only ever touch feeds this DID actually subscribes to.
    resolve_subscriptions(&state, &did).await;

    if let Some(feed_url) = q.feed.as_deref() {
        if let Ok(Some(feed)) = store::get_feed_by_url(pool, feed_url).await {
            store::mark_feed_read(pool, &did, feed.id, true).await?;
        }
        return Ok(Redirect::to(&format!("/?feed={}", qenc(feed_url))).into_response());
    }

    // Global: mark every subscribed feed read. Fan out over the DID's feeds
    // (bounded by the per-DID subscription cap) using the batched per-feed path,
    // rather than one UPDATE round-trip per unread entry (unbounded) — same end
    // state, but O(feeds) statements instead of O(unread entries).
    for feed_id in store::subscribed_feed_ids(pool, &did).await? {
        store::mark_feed_read(pool, &did, feed_id, true).await?;
    }
    Ok(Redirect::to("/").into_response())
}

// ---------------------------------------------------------------------------
// Subscribe by URL
// ---------------------------------------------------------------------------

/// Flash for a URL this instance cannot store as a feed — not private, just
/// not a kind of feed it supports (an `at://` publication with
/// `FEATHERREADER_STANDARD_SITE` off, an unsupported scheme). Distinct from
/// [`PRIVATE_FEED_REFUSAL`], whose "not saved or sent anywhere" would be a
/// false promise for a record that may already exist in the user's PDS.
const UNSUPPORTED_FEED_URL_REFUSAL: &str =
    "That isn't a kind of feed this instance can subscribe to. Nothing was saved.";

/// Shown when an OPML export is refused because the subscription list could not
/// be read in full.
///
/// **An empty export is worse than no export.** This path used to
/// `unwrap_or_default()`, so a failed read produced a 200 carrying a zero-feed
/// file — a blank backup, handed over at the moment the reader reached for one.
const EXPORT_INCOMPLETE_REFUSAL: &str =
    "Could not read your subscriptions in full, so nothing was exported. Your \
     feeds are unchanged — try again, and if it keeps failing the list may be \
     larger than this reader can page through.";

/// Refusal message shown when a private/paid feed is submitted. FeatherReader
/// stores subscriptions in the user's PUBLIC PDS, so it supports public feeds
/// only for now — a private feed's secret URL is never saved, fetched, or sent
/// anywhere. Kept as a constant so the add and OPML paths share the exact wording
/// and the boot-smoke can assert on it.
const PRIVATE_FEED_REFUSAL: &str = "Private/paid feeds aren't supported yet. \
    FeatherReader stores your subscriptions in your public PDS, so it supports public \
    feeds for now — private-feed support arrives when atproto's private data \
    (permissioned records) ships. Your feed URL was not saved or sent anywhere.";

/// Form body for `POST /subscriptions`.
#[derive(Debug, Deserialize)]
struct SubscribeForm {
    url: String,
    /// Optional folder `at://` URI to file the new feed under.
    #[serde(default)]
    folder: Option<String>,
}

/// The DID-form URL to store for a pasted `at://` publication, or the flash
/// to refuse it with.
///
/// - The scheme is canonicalised: `At://` is the same publication, and
///   storing a second spelling makes a second row for it (#183).
/// - It must name a `site.standard.publication`; anything else is not a feed
///   this instance can read.
/// - A handle is resolved to its DID: a handle is a mutable name, and
///   `feeds.url` is keyed on identity, so only the DID form is stored.
async fn publication_url_from_paste(state: &AppState, input: &str) -> Result<String, String> {
    let unsupported = || UNSUPPORTED_FEED_URL_REFUSAL.to_string();
    let canonical = format!(
        "{}{}",
        crate::atproto::AT_URI_PREFIX,
        &input[crate::atproto::AT_URI_PREFIX.len()..]
    );
    let uri = crate::standard_site::AtUri::parse(&canonical).ok_or_else(unsupported)?;
    if uri.collection != lexicon::nsid::STANDARD_PUBLICATION {
        return Err(unsupported());
    }
    let did = if crate::oauth::identity::is_atproto_did(&uri.authority) {
        uri.authority.clone()
    } else {
        let handle =
            // Validated as a handle before it is sent anywhere: an authority
            // that is neither a DID nor a handle (`did:plc:TOOSHORT`, an
            // uppercase DID, a newline) is unsupported, not a lookup (found in
            // review).
            crate::oauth::identity::normalize_handle(&uri.authority).map_err(|_| unsupported())?;
        crate::atproto::resolve_handle(&state.http, &state.config.resolver_base, &handle)
            .await
            .map_err(|err| {
                warn!(%err, handle = %uri.authority, "could not resolve a pasted publication's handle");
                format!("Couldn't resolve the handle {} to an account.", uri.authority)
            })?
    };
    let url = format!(
        "{}{did}/{}/{}",
        crate::atproto::AT_URI_PREFIX,
        uri.collection,
        uri.rkey
    );
    if !feed::is_storable_feed_url(&url, true) {
        return Err(unsupported());
    }
    Ok(url)
}

/// `POST /subscriptions` — subscribe by URL.
async fn add_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<SubscribeForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;
    let input = form.url.trim().to_string();
    if input.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }

    // Per-DID subscription cap: bound one account's storage/poller footprint on
    // the small box. Checked BEFORE any fetch/resolve so an over-cap account
    // can't even trigger an outbound request. `<= 0` disables the cap.
    let cap = state.config.max_subs_per_did;
    if cap > 0 {
        match store::count_subscriptions_for_did(pool, &did).await {
            Ok(n) if n >= cap => {
                info!(%did, current = n, cap, "refused subscribe: per-DID subscription cap reached");
                return Ok(Redirect::to(&format!(
                    "/?flash={}",
                    qenc(&format!(
                        "Subscription limit reached ({cap}). Remove a feed before adding another."
                    ))
                ))
                .into_response());
            }
            Ok(_) => {}
            Err(err) => warn!(%err, %did, "could not count subscriptions for cap check; allowing"),
        }
    }

    // **An at:// paste is a standard.site publication, read by the poller
    // since 0.4.0**: canonicalised and resolved to its DID form here, then it
    // joins the ordinary path below. With the flag off it is refused as it
    // always was — the flag gates what may be stored.
    let is_at_uri = input
        .get(..crate::atproto::AT_URI_PREFIX.len())
        .is_some_and(|p| p.eq_ignore_ascii_case(crate::atproto::AT_URI_PREFIX));
    let publication_url = if is_at_uri {
        if !state.config.standard_site {
            info!(url = %input, %did, "refused an at:// paste: standard.site is off (not stored)");
            return Ok(
                Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                    .into_response(),
            );
        }
        match publication_url_from_paste(&state, &input).await {
            Ok(url) => Some(url),
            Err(flash) => {
                info!(url = %input, %did, %flash, "refused an at:// paste (not stored)");
                return Ok(Redirect::to(&format!("/?flash={}", qenc(&flash))).into_response());
            }
        }
    } else {
        None
    };

    if let feed::FeedPrivacy::Private(reason) =
        feed::classify_feed_privacy(publication_url.as_deref().unwrap_or(&input))
    {
        info!(url = %input, %reason, %did, "refused private/paid feed at add (not fetched or stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
        );
    }

    let resolved = match publication_url {
        Some(url) => Ok(url),
        None => resolve_feed_url(&state.config, &input).await,
    };
    let feed_url = match resolved {
        Ok(u) => u,
        Err(err) => {
            warn!(%err, url = %input, "could not resolve a feed from the given URL");
            return Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("Couldn't find a feed at that URL")
            ))
            .into_response());
        }
    };

    // Defensive: resolution may have discovered a feed URL that itself carries a
    // secret (e.g. a public site page linking a tokened feed). Re-check the
    // resolved URL and refuse before storing/writing anything.
    if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&feed_url) {
        info!(url = %feed_url, %reason, %did, "refused private/paid feed after resolution (not stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
        );
    }

    // The URL about to be STORED is what must be storable — not the one the
    // user typed. Autodiscovery already yields only http(s), but this is the
    // path that writes the row and the PDS record, so the check lives here too:
    // the same gate the OPML and rename paths apply, on the same terms.
    if !feed::is_storable_feed_url(&feed_url, state.config.standard_site) {
        info!(url = %feed_url, %did, "refused unsupported feed URL after resolution (not stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                .into_response(),
        );
    }

    // Global feeds ceiling: a brand-new distinct feed is refused once the shared
    // cache is full (an existing/duplicate feed URL is always fine — it adds no
    // row). Bounds total cache size across all users on the box. `<= 0` disables.
    let feeds_cap = state.config.max_feeds_global;
    if feeds_cap > 0 && store::get_feed_by_url(pool, &feed_url).await?.is_none() {
        match store::count_feeds(pool).await {
            Ok(n) if n >= feeds_cap => {
                warn!(%did, feeds = n, cap = feeds_cap, feed = %feed_url, "refused subscribe: global feeds ceiling reached");
                return Ok(Redirect::to(&format!(
                    "/?flash={}",
                    qenc(
                        "This instance is at its feed capacity right now. Please try again later."
                    )
                ))
                .into_response());
            }
            Ok(_) => {}
            Err(err) => warn!(%err, "could not count feeds for global-cap check; allowing"),
        }
    }

    store::upsert_feed(
        pool,
        &store::NewFeed {
            url: feed_url.clone(),
            ..Default::default()
        },
    )
    .await?;

    if let Ok(client) = feed::build_client() {
        if let Some(feed_row) = store::get_feed_by_url(pool, &feed_url).await? {
            match feed::poll_feed_by_kind(pool, &client, &state.config, &feed_row).await {
                Ok(outcome) => {
                    info!(feed = %feed_url, ?outcome, "polled new subscription");
                    // **This path is not the scheduler, so it must settle the
                    // error columns itself.** `poll_feed` writes validators and
                    // `last_polled` and nothing else.
                    feed::settle_poll(pool, &feed_url, &outcome, state.config.poll_interval).await;
                }
                Err(err) => warn!(%err, feed = %feed_url, "initial poll failed"),
            }
        }
    }

    let mut sub = Subscription::new(feed_url.clone(), now_rfc3339());
    if let Ok(Some(feed_row)) = store::get_feed_by_url(pool, &feed_url).await {
        sub.title = feed_row.title.clone();
        sub.site_url = feed_row.site_url.clone();
    }
    sub.folder = form
        .folder
        .map(|f| f.trim().to_string())
        .filter(|f| !f.is_empty());

    match state.repo().add_subscription(&did, &sub).await {
        Ok(rkey) => info!(feed = %feed_url, %rkey, %did, "wrote subscription record to PDS"),
        Err(err) => {
            warn!(%err, feed = %feed_url, %did, "PDS subscription write failed (cached locally)")
        }
    }

    Ok(Redirect::to("/").into_response())
}

/// `POST /subscriptions/:rkey/delete` — unsubscribe (delete the PDS record).
async fn delete_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    match state.repo().remove_subscription(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "unsubscribed (deleted PDS subscription record)"),
        Err(err) => warn!(%err, %did, %rkey, "PDS unsubscribe failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// Form body for `POST /subscriptions/:rkey/rename`.
#[derive(Debug, Deserialize)]
struct RenameSubForm {
    url: String,
    #[serde(default)]
    title: Option<String>,
    #[serde(default)]
    site_url: Option<String>,
    #[serde(default)]
    folder: Option<String>,
    /// What the `url` input held when the page was rendered. With the `seen_*`
    /// fields the handler tells what the reader CHANGED from what they merely
    /// saw: every input is always posted, so its value alone cannot (#149).
    /// Absent (a hand-made POST, or a page from an older build), the handler's
    /// first read stands in for it.
    #[serde(default)]
    seen_url: Option<String>,
    /// What the title input was pre-filled with — the DISPLAY title, which
    /// falls back to the cached feed title or the URL for an untitled record.
    #[serde(default)]
    seen_title: Option<String>,
    /// The folder the select was pre-selected with (`""` for none). Posted
    /// only when the select is, so the two are present or absent together —
    /// and both absent means the reader never saw a folder to change.
    #[serde(default)]
    seen_folder: Option<String>,
}

/// `POST /subscriptions/:rkey/rename` — retitle a feed and/or move it to a
/// folder, rewriting the whole subscription record via `putRecord`.
async fn rename_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
    Form(form): Form<RenameSubForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let feed_url = form.url.trim().to_string();

    // Reject an empty/blank resolved URL — a rename with no usable URL must not
    // write a junk row to the cache or a malformed subscription record to the
    // PDS (add_subscription refuses an empty input the same way).
    if feed_url.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }

    // **A compare-and-swap, retried once (#149).** Each attempt reads the
    // record with its CID and writes with `swapRecord` set to it, so another
    // atproto client's write between the two is refused by the PDS rather than
    // erased by our whole-record put. A refused attempt reads again and
    // re-applies the form's fields — and only those — to the FRESH record,
    // re-running every gate against it. A second refusal is reported as a
    // conflict, never as success: a record that keeps moving is being edited
    // somewhere, and the reader is the one to decide which edit wins.
    //
    // **A retry MERGES; it does not replay the form.** Every input is always
    // posted, so replaying the form on the fresh record would put back each
    // field the reader never touched — a URL another client repointed, a title
    // another client changed. `base` is the record as first read, and each
    // attempt applies only what the reader changed relative to it; see
    // [`merge_rename`].
    let mut base: Option<Subscription> = None;
    for attempt in 1..=RENAME_ATTEMPTS {
        match rename_subscription_once(&state, &did, &rkey, &form, &mut base).await? {
            RenameAttempt::Done(resp) => return Ok(resp),
            RenameAttempt::Raced => {
                info!(%did, %rkey, attempt, "subscription changed between read and write; re-reading");
            }
        }
    }
    warn!(%did, %rkey, attempts = RENAME_ATTEMPTS, "refused rename: the subscription kept changing elsewhere");
    Ok(rename_conflict_response())
}

/// The answer to a rename that conflicts with another client's write: nothing
/// was written, and the reader decides which edit wins.
fn rename_conflict_response() -> Response {
    Redirect::to(&format!(
        "/?flash={}",
        qenc(
            "This subscription was changed elsewhere while you were editing it — \
             nothing was renamed or moved. Reload and try again."
        )
    ))
    .into_response()
}

/// Trim, and read an empty value as absent — how the form's optional fields
/// have always been taken.
fn form_value(v: Option<&str>) -> Option<String> {
    v.map(str::trim)
        .filter(|t| !t.is_empty())
        .map(str::to_string)
}

/// The record a rename should write, from [`merge_rename`].
#[derive(Debug, PartialEq, Eq)]
struct MergedRename {
    /// The record to write.
    sub: Subscription,
    /// Whether THIS write repoints the subscription to a different feed URL.
    repoint: bool,
    /// Every field the reader changed already holds the reader's value — a
    /// double-submitted Save whose first request landed. Nothing to write.
    already_saved: bool,
}

/// Which field the reader and another client both changed, differently.
#[derive(Debug, PartialEq, Eq)]
struct RenameConflict(&'static str);

/// Apply the reader's edits to `fresh`: a three-way merge of the form against
/// `base`, the record as the handler FIRST read it (#149). Returns the record
/// to write and whether the reader repointed it to a different URL.
///
/// For each field the form carries (`url`, `title`, `folder`, `site_url`):
///
/// - **the reader did not change it** — the posted value equals the value the
///   input was pre-filled with (`seen_*`, or `base` when the form lacks it) —
///   so `fresh`'s value stands, whoever wrote it;
/// - **the reader changed it, and `fresh` still has `base`'s value** — the
///   reader's value is applied;
/// - **the reader changed it, and `fresh` already holds the reader's value** —
///   both made the same edit (or a double-submitted Save landed first): no
///   conflict, nothing to write for that field;
/// - **the reader changed it, and so did someone else, differently** — a
///   conflict; nothing is written.
///
/// A field whose input the page did not render (the folder select, without
/// folders to list) is untouched by the reader.
///
/// On the first attempt `fresh` IS `base`, so the only question is what the
/// reader changed. The repoint semantics — dropping `siteUrl` and `fetchHint`
/// as properties of the old feed — follow the READER's change, never the
/// difference between the form and a record another client moved.
///
/// **What `seen_*` closes, and what it leaves.** Without it, a field another
/// client changed between page load and the first read (so no swap fails)
/// read as the reader's change — the stale hidden URL repointed the record
/// back. With it, an untouched field is never written. A field BOTH changed
/// in that window is still last-writer-wins: the conflict check compares
/// against the first read, not the page-load record, because `seen_title` is
/// the display title (a fallback for an untitled record), not the record's.
fn merge_rename(
    form: &RenameSubForm,
    base: &Subscription,
    fresh: Subscription,
) -> Result<MergedRename, RenameConflict> {
    let mut sub = fresh;
    // Fields the reader changed, and how many of those still need writing:
    // a change `fresh` already holds — both sides made the same edit, or this
    // is a double-submitted Save whose first request landed — is agreement,
    // not a conflict, and there is nothing to write for it.
    let mut edited = 0;
    let mut to_write = 0;

    let posted_url = form.url.trim();
    let seen_url = form.seen_url.as_deref().unwrap_or(&base.url).trim();
    let mut repoint = false;
    if posted_url != seen_url {
        edited += 1;
        if sub.url.trim() == posted_url {
            // Already there. Not a repoint by THIS write, so the fresh
            // record's siteUrl and fetchHint — perhaps the new feed's — stay.
        } else if sub.url.trim() != base.url.trim() {
            return Err(RenameConflict("url"));
        } else {
            to_write += 1;
            repoint = true;
        }
    }
    // Like for like: a record another client wrote may carry padding.
    sub.url = if repoint { posted_url } else { sub.url.trim() }.to_string();

    let posted_title = form_value(form.title.as_deref());
    let seen_title = match form.seen_title.as_deref() {
        Some(seen) => form_value(Some(seen)),
        None => base.title.clone(),
    };
    if posted_title != seen_title {
        edited += 1;
        if sub.title == posted_title {
            // Already there.
        } else if sub.title != base.title {
            return Err(RenameConflict("title"));
        } else {
            to_write += 1;
            sub.title = posted_title;
        }
    }

    // **The folder select is conditional; absent, the reader never saw a
    // folder.** The manage row renders it — and `seen_folder` with it — only
    // when it has folders to list, which a reader without folders, or a page
    // whose folder listing failed, does not. Posted with neither, the folder
    // is untouched; reading the absence as "no folder" un-foldered every
    // subscription retitled from such a page. (The title input is always
    // rendered, so an absent title keeps its old meaning.)
    if form.folder.is_some() || form.seen_folder.is_some() {
        let posted_folder = form_value(form.folder.as_deref());
        let seen_folder = match form.seen_folder.as_deref() {
            Some(seen) => form_value(Some(seen)),
            None => base.folder.clone(),
        };
        if posted_folder != seen_folder {
            edited += 1;
            if sub.folder == posted_folder {
                // Already there.
            } else if sub.folder != base.folder {
                return Err(RenameConflict("folder"));
            } else {
                to_write += 1;
                sub.folder = posted_folder;
            }
        }
    }

    // `createdAt` and `private` carry over untouched — neither is a property
    // of which feed URL the subscription points at.
    //
    // `siteUrl` and `fetchHint` ARE properties of the specific feed, so a
    // repoint drops them rather than leaving a site link for the old feed
    // hanging off the new one. The manage row does not post `site_url`; a
    // value that is posted and differs from the base is an edit like any
    // other.
    match form_value(form.site_url.as_deref()) {
        Some(site) if Some(&site) != base.site_url.as_ref() => {
            edited += 1;
            if sub.site_url.as_ref() == Some(&site) {
                // Already there.
            } else if sub.site_url != base.site_url {
                return Err(RenameConflict("siteUrl"));
            } else {
                to_write += 1;
                sub.site_url = Some(site);
            }
        }
        Some(_) => {}
        None if repoint => sub.site_url = None,
        None => {}
    }
    if repoint {
        sub.fetch_hint = None;
    }
    Ok(MergedRename {
        sub,
        repoint,
        // A form with no edits is not "already saved": it writes, as it always
        // has — it is the reader asking for exactly this record.
        already_saved: edited > 0 && to_write == 0,
    })
}

/// How many times [`rename_subscription`] and [`rename_folder`] read and
/// write before giving up on a record that keeps changing: the first try and
/// one retry.
const RENAME_ATTEMPTS: u32 = 2;

/// The outcome of one read-then-write of a rename.
enum RenameAttempt {
    /// Answered: renamed, refused by a gate, or failed for a reason a re-read
    /// cannot fix.
    Done(Response),
    /// The PDS refused the write with `InvalidSwap`: the record moved after
    /// this attempt read it. Nothing was written.
    Raced,
}

/// One attempt at [`rename_subscription`]: read the record and its CID, apply
/// the form to it, and write it back on the condition that it is still at
/// that CID.
///
/// `base` is the record as the FIRST attempt read it; this sets it on that
/// attempt, and every attempt merges against it — see [`merge_rename`].
async fn rename_subscription_once(
    state: &AppState,
    did: &str,
    rkey: &str,
    form: &RenameSubForm,
    base: &mut Option<Subscription>,
) -> Result<RenameAttempt, WebError> {
    use RenameAttempt::Done;

    // **Read before write — `update_subscription` is a `putRecord`, and a
    // putRecord replaces the WHOLE record** (see its doc on `atproto.rs`).
    //
    // This used to build a fresh `Subscription::new(feed_url, now_rfc3339())`
    // and hand that over, so every field the form does not carry was written
    // back as its default. `templates/manage_row.html` posts `url`, `title` and
    // `folder` — and nothing else — so a rename silently destroyed four fields:
    // `siteUrl`, `fetchHint`, `private`, and `createdAt`.
    //
    // `createdAt` is the one that matters most: it is the reader's subscribe
    // time, it is the sort key for "when did I subscribe", it lives in THEIR
    // repo rather than our cache, and once overwritten it is gone with nothing
    // in the UI to say so.
    //
    // There is no single-record read on `Repo` (no `getRecord`), so this lists
    // and filters. That is one extra round trip on an action that is already
    // doing a PDS write, and it is bounded. A `get_subscription` was weighed
    // for #149 and not added: the sidecar has no `get` action, so it would be
    // new surface on the backend being retired, and the listing already
    // carries each record's CID.
    //
    // **A failed read refuses the rename.** Falling back to the old
    // rebuild-from-scratch here would reinstate the data loss on exactly the
    // flaky path, which is the worst place to have it. The write below already
    // takes this stance — "a failure here means nothing was renamed or moved" —
    // and the read gets the same one.
    //
    // **The CID comes with the record**, and the write below names it: that is
    // the whole compare-and-swap (#149).
    let found = match state.repo().list_subscriptions_with_cids(did).await {
        Ok(subs) => subs
            .into_iter()
            .find(|(k, _, _)| k == rkey)
            .map(|(_, cid, s)| (cid, s)),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not read the subscription before renaming it");
            return Ok(Done(
                Redirect::to(&format!(
                    "/?flash={}",
                    qenc("Could not reach your PDS — nothing was renamed or moved.")
                ))
                .into_response(),
            ));
        }
    };
    let Some((read_cid, fresh)) = found else {
        // The rkey is not in the reader's repo. Renaming a record that is not
        // there would CREATE one, which is not what "rename" means and would
        // give it a fresh `createdAt` — the bug this read exists to prevent.
        warn!(%did, %rkey, "refused rename: no such subscription in the repo");
        return Ok(Done(
            Redirect::to(&format!(
                "/?flash={}",
                qenc("That subscription is no longer in your repo — nothing was renamed or moved.")
            ))
            .into_response(),
        ));
    };

    // The subscription can be repointed at a different feed URL. **Every gate
    // on the URL applies to a repoint and only a repoint** — the three below
    // were each, at one time, run before this line on the URL as posted, and
    // each refused a pure retitle of a record that already existed:
    //
    // - privacy: the narrowed at:// arm fails closed as `Private` for an
    //   at-URI that is not a publication (a feed generator another client
    //   subscribed to), so the record became un-editable with a flash saying
    //   it "was not saved or sent anywhere";
    // - the global feeds ceiling keyed on "URL not in the cache", and an
    //   at:// record is never cached with the flag off, so at capacity a
    //   retitle was refused for a row the handler would not insert;
    // - storability, the same way.
    //
    // An unchanged URL is already in the reader's repo; refusing to retitle
    // it protects nothing and takes their own record away from them.
    // Like for like: the form value is trimmed, and a record another client
    // wrote may carry padding — compared raw, every retitle of it was a repoint.
    //
    // Whether this IS a repoint is the reader's change, from the merge — not
    // the form against a record another client may have moved (#149).
    let base = base.get_or_insert_with(|| fresh.clone());
    let MergedRename {
        sub,
        repoint: url_changed,
        already_saved,
    } = match merge_rename(form, base, fresh) {
        Ok(merged) => merged,
        Err(RenameConflict(field)) => {
            warn!(%did, %rkey, field, "refused rename: the reader and another client both changed the same field");
            return Ok(Done(rename_conflict_response()));
        }
    };
    // Every change the reader made is already in the record: a Save submitted
    // twice, whose first request landed. Success, with nothing to write — and
    // no cache write either, since the request that wrote it made that too.
    if already_saved {
        info!(%did, %rkey, "rename already in the record; nothing to write");
        return Ok(Done(Redirect::to("/").into_response()));
    }
    let feed_url = sub.url.clone();

    // **Storability, on the same terms as the add and OPML paths — for a
    // REPOINT, and FIRST.** A target this instance cannot store gets that
    // answer, not "private" (the at:// arm fails closed) or "at capacity"
    // (it would never be inserted) — the ordering the add path has. This handler writes `feeds` via `upsert_feed` and had only the
    // privacy check above, so `FEATHERREADER_STANDARD_SITE` was bypassable
    // here; a review found it by enumerating every writer of the table. The
    // first fix ran this check before the repo lookup, on the URL as posted —
    // which refused a pure retitle of a subscription that already IS an
    // at-URI, on every instance with the flag off. The flag gates what the
    // cache may store, not whether a reader may edit their own record: an
    // unchanged non-storable URL keeps its PDS write and simply gets no cache
    // row below.
    let storable = feed::is_storable_feed_url(&feed_url, state.config.standard_site);
    if url_changed && !storable {
        info!(url = %feed_url, %did, %rkey, "refused a repoint to a non-storable feed URL");
        return Ok(Done(
            Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                .into_response(),
        ));
    }

    // Block private/paid feeds on a repoint. `url` is attacker-controllable,
    // and rename both upserts it to the local cache AND rewrites the PDS
    // subscription record (a public `putRecord`), so without this guard a
    // crafted rename could land a secret-bearing URL in the public PDS — the
    // exact leak the add and OPML paths already prevent.
    if url_changed {
        if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&feed_url) {
            info!(url = %feed_url, %reason, %did, %rkey, "refused private/paid feed at rename (not stored or written)");
            return Ok(Done(
                Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
            ));
        }
    }

    // Global feeds ceiling parity with add_subscription: a repoint to a
    // brand-new feed URL would insert a NEW `feeds` row. Refuse that when the
    // shared cache is at capacity (an existing/duplicate URL adds no row and
    // is always fine). `<= 0` disables.
    let feeds_cap = state.config.max_feeds_global;
    if url_changed
        && feeds_cap > 0
        && store::get_feed_by_url(&state.db, &feed_url)
            .await?
            .is_none()
    {
        match store::count_feeds(&state.db).await {
            Ok(n) if n >= feeds_cap => {
                warn!(%did, %rkey, feeds = n, cap = feeds_cap, feed = %feed_url, "refused rename: global feeds ceiling reached");
                return Ok(Done(
                    Redirect::to(&format!(
                        "/?flash={}",
                        qenc(
                            "This instance is at its feed capacity right now. Please try again later."
                        )
                    ))
                    .into_response(),
                ));
            }
            Ok(_) => {}
            Err(err) => warn!(%err, "could not count feeds for global-cap check; allowing"),
        }
    }

    // **The PDS write decides what the reader is told.**
    //
    // This used to `warn!` on failure and then redirect exactly as it does on
    // success, so a rename that did not happen was indistinguishable from one
    // that did — the reader saw their old title come back and had no reason to
    // think anything had gone wrong. The PDS record IS the subscription; a
    // failure here means nothing was renamed or moved.
    //
    // **Conditional on the CID read above (#149).** A listing with no CID is
    // a PDS outside the lexicon (`listRecords` requires one); the write then
    // goes unconditionally, as every write did before this, and says so.
    if read_cid.is_none() {
        warn!(%did, %rkey, "the PDS listed this subscription without a CID; renaming without a compare-and-swap");
    }
    let res = match state
        .repo()
        .update_subscription(did, rkey, &sub, read_cid.as_deref())
        .await
    {
        Ok(res) => res,
        // Another client wrote the record after the read above: nothing was
        // written, and the caller decides whether to read again.
        Err(err) if crate::atproto::is_invalid_swap(&err) => return Ok(RenameAttempt::Raced),
        Err(err) => {
            warn!(%err, %did, %rkey, "PDS subscription update failed");
            return Ok(Done(
                Redirect::to(&format!(
                    "/?flash={}",
                    qenc("Could not save that change to your PDS — nothing was renamed or moved.")
                ))
                .into_response(),
            ));
        }
    };
    info!(%did, %rkey, uri = %res.uri, "renamed/moved subscription");

    // **The cache follows the PDS, so it is written only now** — after the
    // write landed. It used to be written before the put, so a rename the PDS
    // refused (a failed save, or both attempts of a lost race, #149) still
    // left the new title on the cached row, or a fresh `feeds` row for a
    // repoint's URL that the poller then fetched for nobody. Every gate on
    // that URL (storability, privacy, the ceiling) ran above, before the put;
    // only the write itself moved.
    //
    // Keep the local cache title in step for the loose-feed fallback path —
    // for a row this instance would have. Two cases write nothing:
    //
    // - not storable (an existing at-URI with the flag off): the record is the
    //   reader's to edit, the cache row is not this instance's to create;
    // - an unchanged URL with no cache row: a retitle is never the write that
    //   CREATES a row. That covers two findings at once — the ceiling is
    //   checked on a repoint only, so a retitle must not insert past it; and
    //   a secret-bearing URL another client subscribed to has no row (the
    //   privacy gate above runs on a repoint only, and `resolve_subscriptions`
    //   refuses to cache it), so it cannot enter the shared table here, be
    //   polled, fail, and be printed on the admin page. A privacy re-check on
    //   this write was the first draft; mutation showed it dead — the row
    //   rule already refused every case it would have.
    //
    // A failed lookup skips the cache rather than failing the request: the
    // rename has already landed, and the reader must be told so.
    let cache_write = storable
        && (url_changed
            || match store::get_feed_by_url(&state.db, &sub.url).await {
                Ok(row) => row.is_some(),
                Err(err) => {
                    warn!(%err, %did, url = %sub.url, "could not look up the cached feed row after a rename");
                    false
                }
            });
    if !cache_write {
        info!(%did, %rkey, url = %sub.url, "renamed a subscription without touching the cache");
    } else if let Err(err) = store::upsert_feed(
        &state.db,
        &store::NewFeed {
            url: sub.url.clone(),
            title: sub.title.clone(),
            site_url: sub.site_url.clone(),
            ..Default::default()
        },
    )
    .await
    {
        // Not fatal to the rename — the PDS record is the source of truth —
        // but a missing `feeds` row means this subscription is never polled.
        warn!(%err, %did, url = %sub.url, "could not update the cached feed row on rename");
    }

    Ok(Done(Redirect::to("/").into_response()))
}

// ---------------------------------------------------------------------------
// Folders
// ---------------------------------------------------------------------------

/// Form body for `POST /folders`.
#[derive(Debug, Deserialize)]
struct FolderForm {
    name: String,
}

/// `POST /folders` — create a folder record.
async fn create_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<FolderForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let name = form.name.trim();
    if name.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }
    let folder = Folder::new(name.to_string(), now_rfc3339());
    match state.repo().add_folder(&did, &folder).await {
        Ok(rkey) => info!(%did, %rkey, name, "created folder record"),
        Err(err) => warn!(%err, %did, "PDS folder create failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// Form body for `POST /folders/:rkey/rename`.
#[derive(Debug, Deserialize)]
struct RenameFolderForm {
    name: String,
    /// The name the input was pre-filled with — the record's own name, so it
    /// is the common ancestor of the reader's edit and any other client's
    /// (#268). Absent (a hand-made POST, or a page from an older build), the
    /// handler's first read stands in for it.
    #[serde(default)]
    seen_name: Option<String>,
}

/// `POST /folders/:rkey/rename` — rename a folder record, changing its `name`
/// and nothing else.
///
/// **An edit of the record, not a replacement (#268).** This used to put
/// `Folder::new(name, now)` over the record, which reset `position`, replaced
/// `createdAt` with the rename time and dropped every field another
/// `community.lexicon.rss` client had added — and reported success whether or
/// not the write landed. It now reads the record with its CID, changes only
/// the name ([`Folder::extra`] carries the fields this build does not know),
/// and writes it back with `swapRecord` set to that CID, retried once on
/// `InvalidSwap` with a three-way merge — the same compare-and-swap as
/// [`rename_subscription`] (#149).
async fn rename_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
    Form(form): Form<RenameFolderForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    if form.name.trim().is_empty() {
        return Ok(Redirect::to("/").into_response());
    }
    let mut base: Option<Folder> = None;
    for attempt in 1..=RENAME_ATTEMPTS {
        match rename_folder_once(&state, &did, &rkey, &form, &mut base).await {
            RenameAttempt::Done(resp) => return Ok(resp),
            RenameAttempt::Raced => {
                info!(%did, %rkey, attempt, "folder changed between read and write; re-reading");
            }
        }
    }
    warn!(%did, %rkey, attempts = RENAME_ATTEMPTS, "refused folder rename: the folder kept changing elsewhere");
    Ok(folder_flash(FOLDER_RENAME_CONFLICT))
}

/// The answer to a folder rename that conflicts with another client's write.
const FOLDER_RENAME_CONFLICT: &str = "This folder was changed elsewhere while you were renaming \
     it — it was not renamed. Reload and try again.";

/// Redirect home with `message` as the flash.
fn folder_flash(message: &str) -> Response {
    Redirect::to(&format!("/?flash={}", qenc(message))).into_response()
}

/// What a folder rename should do, from [`merge_folder_rename`].
#[derive(Debug, PartialEq, Eq)]
enum FolderMerge {
    /// Write this record: the fresh one, renamed.
    Write(Folder),
    /// The record already has the reader's name — a double-submitted Save
    /// whose first request landed, or the same rename made elsewhere.
    AlreadySaved,
    /// The reader did not change the name. Nothing to write.
    Unchanged,
}

/// A three-way merge of the reader's rename against `fresh`, the record as
/// just read (#268).
///
/// The ancestor is `seen` — the name the input showed — or, without it,
/// `base`, the record as the handler first read it. The name is the folder's
/// only field the form edits; everything else comes from `fresh` untouched.
///
/// - the reader left the name as it was shown → [`FolderMerge::Unchanged`],
///   whatever `fresh` holds;
/// - `fresh` already has the reader's name → [`FolderMerge::AlreadySaved`];
/// - `fresh` still has the ancestor's name → write `fresh` renamed;
/// - otherwise someone else renamed it differently → a conflict.
///
/// Compared trimmed: the posted name is trimmed, and a record another client
/// wrote may carry padding.
fn merge_folder_rename(
    posted: &str,
    seen: Option<&str>,
    base: &Folder,
    fresh: Folder,
) -> Result<FolderMerge, RenameConflict> {
    let posted = posted.trim();
    let ancestor = seen.unwrap_or(&base.name).trim();
    if posted == ancestor {
        return Ok(FolderMerge::Unchanged);
    }
    let current = fresh.name.trim();
    if current == posted {
        return Ok(FolderMerge::AlreadySaved);
    }
    if current != ancestor {
        return Err(RenameConflict("name"));
    }
    let mut folder = fresh;
    folder.name = posted.to_string();
    Ok(FolderMerge::Write(folder))
}

/// One attempt at [`rename_folder`]: read the folder and its CID, merge the
/// reader's rename into it, and write it back on the condition that it is
/// still at that CID. `base` is set by the first attempt's read.
async fn rename_folder_once(
    state: &AppState,
    did: &str,
    rkey: &str,
    form: &RenameFolderForm,
    base: &mut Option<Folder>,
) -> RenameAttempt {
    use RenameAttempt::Done;

    // No single-record read on `Repo`, as for subscriptions: the sidecar has
    // no `get` action, and the listing already carries each record's CID.
    // A failed read refuses the rename — rebuilding the record from the form
    // is the loss this read exists to prevent.
    let found = match state.repo().list_folders_with_cids(did).await {
        Ok(folders) => folders
            .into_iter()
            .find(|(k, _, _)| k == rkey)
            .map(|(_, cid, f)| (cid, f)),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not read the folder before renaming it");
            return Done(folder_flash(
                "Could not reach your PDS — the folder was not renamed.",
            ));
        }
    };
    let Some((read_cid, fresh)) = found else {
        // Deleted elsewhere (or never there). A put at a missing rkey would
        // CREATE the folder, which is not what "rename" means.
        warn!(%did, %rkey, "refused folder rename: no such folder in the repo");
        return Done(folder_flash(
            "That folder no longer exists — it may have been deleted elsewhere. \
             Nothing was renamed.",
        ));
    };

    let base = base.get_or_insert_with(|| fresh.clone());
    let folder = match merge_folder_rename(&form.name, form.seen_name.as_deref(), base, fresh) {
        Ok(FolderMerge::Write(folder)) => folder,
        Ok(FolderMerge::AlreadySaved) => {
            info!(%did, %rkey, "folder already has this name; nothing to write");
            return Done(Redirect::to("/").into_response());
        }
        Ok(FolderMerge::Unchanged) => return Done(Redirect::to("/").into_response()),
        Err(RenameConflict(field)) => {
            warn!(%did, %rkey, field, "refused folder rename: the reader and another client both renamed it");
            return Done(folder_flash(FOLDER_RENAME_CONFLICT));
        }
    };

    if read_cid.is_none() {
        warn!(%did, %rkey, "the PDS listed this folder without a CID; renaming without a compare-and-swap");
    }
    match state
        .repo()
        .rename_folder(did, rkey, &folder, read_cid.as_deref())
        .await
    {
        Ok(res) => {
            info!(%did, %rkey, uri = %res.uri, "renamed folder");
            Done(Redirect::to("/").into_response())
        }
        Err(err) if crate::atproto::is_invalid_swap(&err) => RenameAttempt::Raced,
        Err(err) => {
            warn!(%err, %did, %rkey, "PDS folder rename failed");
            Done(folder_flash(
                "Could not save that change to your PDS — the folder was not renamed.",
            ))
        }
    }
}

/// `POST /folders/:rkey/delete` — delete a folder record (feeds referencing it
/// simply become un-foldered).
async fn delete_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    match state.repo().remove_folder(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "deleted folder record"),
        Err(err) => warn!(%err, %did, %rkey, "PDS folder delete failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// Resolve a user-pasted URL to a canonical feed URL: if fetching it yields a
/// feed document we take it as-is; if it yields an HTML page we run
/// autodiscovery over its `<link rel="alternate">` tags.
async fn resolve_feed_url(_config: &Config, input: &str) -> anyhow::Result<String> {
    let parsed =
        url::Url::parse(input).map_err(|e| anyhow::anyhow!("not a valid URL {input:?}: {e}"))?;

    let client = feed::build_client()?;
    // Fetch through the SSRF guard: scheme + resolved-IP checks on the URL and
    // every redirect hop, so a user-pasted URL can't reach cloud metadata /
    // loopback / private hosts.
    let resp = crate::net::guarded_get(&client, parsed.as_str(), &[]).await?;
    let final_url = resp.url().clone();
    let content_type = resp
        .headers()
        .get(axum::http::header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .unwrap_or("")
        .to_ascii_lowercase();
    // Cap the body (streamed, aborts over 8 MiB) — never trust Content-Length,
    // gzip strips it, and this response is reflected into the UI.
    let raw = crate::net::read_capped(resp).await?;
    let body = String::from_utf8_lossy(&raw).into_owned();

    let looks_like_feed = content_type.contains("xml")
        || content_type.contains("rss")
        || content_type.contains("atom")
        || content_type.contains("application/feed+json")
        || {
            let head = body.trim_start();
            head.starts_with("<?xml")
                || head.starts_with("<rss")
                || head.starts_with("<feed")
                || head.contains("<rss")
                || head.contains("<feed")
        };
    if looks_like_feed {
        return Ok(final_url.to_string());
    }

    match feed::discover_feed(&body, Some(&final_url)) {
        Some(u) => Ok(u.to_string()),
        None => anyhow::bail!("no feed found at {input} (no autodiscovery link)"),
    }
}

// ---------------------------------------------------------------------------
// Login (atproto OAuth via the sidecar)
// ---------------------------------------------------------------------------

/// Query for `GET /login`.
#[derive(Debug, Deserialize, Default)]
struct LoginQuery {
    #[serde(default)]
    handle: Option<String>,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    flash: Option<String>,
}

/// `GET /login` — start the atproto OAuth flow, or render the handle form.
///
/// **Pre-handshake gate:** starting OAuth (a `?handle=` GET) is refused unless
/// the visitor is allowed by [`may_start_oauth`] — an existing beta seat (via
/// session cookie *or* the submitted handle resolving to a seated DID) or a
/// valid reserving invite cookie. Refusal redirects to `/beta/redeem`. The bare
/// form (no handle) always renders.
async fn login_form(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<LoginQuery>,
) -> Response {
    if let Some(handle) = q
        .handle
        .map(|h| h.trim().to_string())
        .filter(|h| !h.is_empty())
    {
        if !may_start_oauth(&state, &headers, &handle).await {
            return Redirect::to("/beta/redeem").into_response();
        }
        return start_oauth(&state, &handle).await;
    }
    render(&LoginTemplate {
        card: login_card(&state.config),
        repo_url: REPO_URL,
        error: q.error.unwrap_or_default(),
        flash: q.flash.unwrap_or_default(),
    })
}

/// `POST /login` — the handle-form submit: redirect into the sidecar OAuth flow.
/// Subject to the same pre-handshake invite gate as `GET /login?handle=`.
async fn login_submit(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<LoginForm>,
) -> Response {
    let handle = form.handle.trim();
    if handle.is_empty() {
        return login_error(&state, "Enter your atproto handle.");
    }
    if !may_start_oauth(&state, &headers, handle).await {
        return Redirect::to("/beta/redeem").into_response();
    }
    start_oauth(&state, handle).await
}

/// Whether this visitor is allowed to *start* the OAuth handshake. The gate
/// admits, in order of cost:
///
/// 1. an existing beta member's cookie session whose DID already holds a seat;
/// 2. a fresh visitor carrying a valid reserving invite cookie;
/// 3. a cookie-less visitor whose submitted `handle` resolves to a DID that
///    already holds a seat — this honors the **seeded admin's first login** on a
///    fresh deploy (and any returning member who cleared cookies) without a
///    session cookie or an invite code.
///
/// The cookie/invite fast paths run FIRST and short-circuit, so the network
/// handle→DID resolution is only attempted when neither applies. It fails
/// CLOSED: a malformed/unresolvable handle, a resolution error/timeout, or a
/// resolved DID with no seat all leave the visitor bounced to `/beta/redeem`.
/// This keeps the anti-abuse intent — a rando now pays a cheap handle
/// resolution instead of a burned sidecar handshake (and `/login` is already in
/// the rate-limited path set).
async fn may_start_oauth(state: &AppState, headers: &HeaderMap, handle: &str) -> bool {
    // The production resolver is the app's existing atproto handle→DID path,
    // routed through the SSRF guard. Resolution is injected so tests can exercise
    // the gate without a live network call (the guard forbids loopback mocks).
    may_start_oauth_with(state, headers, handle, |h| async move {
        crate::atproto::resolve_handle(&state.http, &state.config.resolver_base, &h)
            .await
            .ok()
    })
    .await
}

/// Core of [`may_start_oauth`] with the handle→DID resolver injected as `resolve`
/// (returning `Some(did)` on success, `None` on any failure/unresolvable handle).
/// The cookie + invite fast paths run FIRST and short-circuit, so `resolve` is
/// only called when neither admits — keeping the network round-trip off the hot
/// path and preserving the fail-closed contract on resolution failure.
async fn may_start_oauth_with<F, Fut>(
    state: &AppState,
    headers: &HeaderMap,
    handle: &str,
    resolve: F,
) -> bool
where
    F: FnOnce(String) -> Fut,
    Fut: std::future::Future<Output = Option<String>>,
{
    // 1. An already-beta'd session may re-auth freely.
    if let Some(did) = current_did(state, headers).await {
        if store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false)
        {
            return true;
        }
    }
    // 2. A valid reserving invite cookie.
    if invite_cookie_code(headers, &state.config.cookie_secret).is_some() {
        return true;
    }
    // 3. Cookie-less: honor an existing seat by resolving the submitted handle to
    //    a DID (the seeded-admin first-login / cleared-cookies case). Fail closed
    //    on any resolution error or unresolvable/malformed handle.
    match resolve(handle.to_string()).await {
        Some(did) => store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false),
        None => {
            warn!(%handle, "handle resolution failed in pre-handshake beta gate");
            false
        }
    }
}

/// Begin the OAuth handshake for `handle`, on whichever backend is live.
///
/// **On `form-action 'self'` and this redirect.** The Rust arm answers a form
/// POST with a redirect straight to the PDS — cross-origin — while the app's CSP
/// carries `form-action 'self'`. Browsers have historically disagreed about
/// whether that directive applies to redirects following a form submission, and
/// if it did here, login would break in a browser while every test passed.
///
/// It does not, and the evidence is the SIDECAR path, which is live in
/// production today: `POST /login` -> 303 to the same-origin `/oauth/login` ->
/// 302 to the PDS, cross-origin, under this same CSP. A browser checking the
/// whole redirect chain would already be blocking that. One checking only the
/// form's action URL sees `/login` in both cases. The two arms differ only in
/// how many same-origin hops precede the cross-origin one, so any policy that
/// permits the sidecar flow permits this one.
///
/// The two arms differ in SHAPE, not just in implementation. The sidecar owns
/// its own `/login` and its own callback, so starting a login is one redirect
/// and nothing is stored here. The Rust backend pushes the authorization
/// request itself, which means this app now holds the pending login — and must
/// set the browser-binding cookie that the callback will be checked against.
async fn start_oauth(state: &AppState, handle: &str) -> Response {
    match state.config.repo_backend {
        crate::metrics::Backend::Sidecar => {
            let url = state.sidecar.login_url(handle, None);
            info!(%handle, "redirecting to OAuth sidecar login");
            Redirect::to(&url).into_response()
        }
        crate::metrics::Backend::Rust => {
            let Some(runtime) = state.oauth.as_deref() else {
                warn!("the rust backend is live but its OAuth runtime is absent");
                return login_error(state, "Login is not available right now.");
            };
            match crate::oauth::login::start(
                runtime,
                &state.http,
                &state.db,
                handle,
                crate::store::now_unix(),
            )
            .await
            {
                Ok(started) => {
                    info!(%handle, "pushed authorization request; redirecting to the PDS");
                    let mut resp = Redirect::to(&started.authorize_url).into_response();
                    set_cookie(
                        &mut resp,
                        &cookie::sign_value(
                            OAUTH_BINDING_COOKIE,
                            &started.binding_token,
                            &state.config.cookie_secret,
                            OAUTH_BINDING_MAX_AGE_SECS,
                        ),
                    );
                    resp
                }
                Err(err) => {
                    // The handle the user typed is logged; the error is not shown
                    // to them verbatim, since it can name internal hosts.
                    warn!(%err, %handle, "could not start the OAuth login");
                    login_error(state, "Could not start login for that handle.")
                }
            }
        }
    }
}

/// Clear the browser-binding cookie. Called on every terminal outcome of a
/// callback, successful or not: the pending row is consumed either way, so a
/// lingering cookie can only ever match a login that no longer exists.
fn clear_binding_cookie(resp: &mut Response) {
    set_cookie(
        resp,
        &format!("{OAUTH_BINDING_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
}

/// Form body for `POST /login`.
#[derive(Debug, Deserialize)]
struct LoginForm {
    handle: String,
}

/// Query for `GET /oauth/callback`.
///
/// Carries BOTH shapes, because the two backends deliver different things to
/// the same URL: the sidecar hands back a one-shot `session_id` it has already
/// exchanged, while the PDS redirects here directly with `code`/`state`/`iss`
/// for this app to exchange itself. Which fields are populated is decided by
/// which backend started the login, not by which is live now — so a flip with a
/// login already in flight still lands in the right arm.
#[derive(Debug, Deserialize, Default)]
struct CallbackQuery {
    /// Sidecar backend: the handoff id.
    #[serde(default)]
    session_id: Option<String>,
    /// Rust backend: the authorization code and its envelope.
    #[serde(default)]
    code: Option<String>,
    #[serde(default)]
    state: Option<String>,
    #[serde(default)]
    iss: Option<String>,
    /// JARM, which is not supported — carried only so it can be refused
    /// explicitly rather than read as "no code".
    #[serde(default)]
    response: Option<String>,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    error_description: Option<String>,
}

/// `GET /oauth/callback` — establish the cookie session.
///
/// **Invite gate:** the verified DID must hold beta access. If it already does
/// (existing member / seeded admin) it's admitted directly. Otherwise we bind
/// the DID to the reserved invite cookie: `redeem_code` atomically consumes the
/// code and grants the seat. A DID with neither is bounced to `/beta/redeem`.
async fn oauth_callback(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<CallbackQuery>,
) -> Response {
    // An error response is handled by the SAME arm that would have handled a
    // success, not short-circuited here.
    //
    // Returning early looks obviously right and is wrong on the Rust path: it
    // skips `verify_callback`, which validates `iss` BEFORE reporting the error
    // precisely because RFC 9207 §2.4 says a client "MUST NOT assume that the
    // error originates from the intended AS". It also leaves the pending row
    // unconsumed, so a `state` that has already produced a callback stays usable
    // until it expires.
    //
    // The sidecar arm has no such check to reach, so it is short-circuited
    // below, preserving exactly what it did before.
    // **The arm is chosen by what the SERVER knows, not by what the caller
    // sent.** A `session_id` in the query used to select the sidecar arm on its
    // own — so a caller could pick which code path ran, and the sidecar arm has
    // no browser-binding check at all. It also short-circuited the error path
    // below, skipping the `iss` validation.
    //
    // Requiring the Rust runtime to be absent, or a sidecar backend to be the
    // configured one, means the selection follows this deployment's own
    // configuration. A login started before a flip still completes, because the
    // Rust arm is reached whenever the Rust runtime exists and can match the
    // `state` against a pending row it actually wrote.
    // The sidecar hands off in TWO shapes, not one: `?session_id=…` on success
    // and `?error=…&error_description=…` on its own failure. Keying only on
    // `session_id` sent the failure shape down the Rust arm, which then failed
    // with "no `state`" and replaced the specific reason with a generic one —
    // and `error_description` is exactly what the sidecar Caddy routing matches
    // to send that request here in the first place.
    let sidecar_shape =
        q.session_id.as_deref().is_some_and(|s| !s.is_empty()) || q.error_description.is_some();
    let sidecar_handoff = sidecar_shape
        && (state.oauth.is_none() || state.config.repo_backend == crate::metrics::Backend::Sidecar);
    if let Some(err) = q.error.clone() {
        // **Neither the code nor the description is echoed as sent.**
        //
        // Both are server-controlled free text arriving on a public GET, so
        // anyone who can make a browser fetch this URL chooses them. The raw
        // `error` used to go into a `warn!` AND into the rendered login page,
        // and `error_description` — arbitrary text, newlines included — went
        // into the log verbatim: a log-injection surface on one side and
        // attacker-chosen copy in the product's own voice on the other.
        //
        // `oauth::flow` already decided this exact question for the Rust arm:
        // reduce the code to a known slug, drop the description entirely. That
        // reasoning is not specific to which arm handles the callback, and this
        // one simply never got the same treatment. The description's LENGTH is
        // kept, because "the server sent a 4 KB explanation" is occasionally
        // worth knowing and cannot be used to inject anything.
        let slug = crate::oauth::flow::known_error_slug(&err);
        warn!(
            error = slug,
            desc_len = q.error_description.as_deref().map_or(0, str::len),
            "OAuth callback returned an error"
        );
        if sidecar_handoff || state.oauth.is_none() {
            return login_error(&state, &format!("Login failed: {slug}"));
        }
        // Fall through: the Rust arm consumes the pending row and validates
        // `iss` against it, and reports the failure afterwards.
    }

    // Which arm runs is decided by WHAT ARRIVED, not by which backend is
    // currently selected: a login started before a flip must still complete.
    let session = if sidecar_handoff {
        let session_id = q.session_id.clone().unwrap_or_default();
        match state.sidecar.resolve_session(&session_id).await {
            Ok(Some(s)) => s,
            Ok(None) => {
                warn!("OAuth callback session_id did not resolve (expired/unknown)");
                return login_error(&state, "Login session expired — please try again.");
            }
            Err(err) => {
                warn!(%err, "failed to resolve OAuth session via the sidecar");
                return login_error(&state, "Login failed talking to the auth service.");
            }
        }
    } else {
        let Some(runtime) = state.oauth.as_deref() else {
            warn!("an OAuth callback arrived with no sidecar session and no Rust runtime");
            return login_error(&state, "Login failed: this login could not be completed.");
        };
        let params = crate::oauth::flow::CallbackParams {
            code: q.code.clone(),
            state: q.state.clone(),
            iss: q.iss.clone(),
            // Passed through, NOT dropped: `verify_callback` checks `iss`
            // against the pending row's issuer before it reports the error, and
            // it cannot do that for an error it never sees.
            error: q.error.clone(),
            error_description: q.error_description.clone(),
            response: q.response.clone(),
        };
        let binding =
            cookie::verify_value(&headers, OAUTH_BINDING_COOKIE, &state.config.cookie_secret);
        match crate::oauth::login::complete(
            runtime,
            &state.http,
            &state.db,
            &params,
            binding.as_deref(),
            crate::store::now_unix(),
        )
        .await
        {
            Ok(done) => crate::atproto::SidecarSession {
                did: done.did,
                handle: done.handle,
            },
            Err(err) => {
                // Never echoed to the browser: the message can name the issuer,
                // the PDS, and why a binding check failed.
                warn!(%err, "could not complete the OAuth callback");
                let mut resp = login_error(&state, "Login failed — please try again.");
                clear_binding_cookie(&mut resp);
                return resp;
            }
        }
    };

    // Bind the verified DID to the invite gate. Returns a response only on the
    // (rare) failure paths; `Ok(())` means the DID now holds beta access.
    let mut clear_invite = false;
    if !store::has_beta_access(&state.db, &session.did)
        .await
        .unwrap_or(false)
    {
        // Not yet a member: consume the reserved invite code, if any.
        let code = match invite_cookie_code(&headers, &state.config.cookie_secret) {
            Some(c) => c,
            None => {
                warn!(did = %session.did, "OAuth callback with no beta access and no invite cookie");
                return Redirect::to("/beta/redeem").into_response();
            }
        };
        match store::redeem_code(
            &state.db,
            &code,
            &session.did,
            session.handle.as_deref(),
            state.config.beta_cap,
        )
        .await
        {
            Ok(Ok(())) => {
                clear_invite = true;
                info!(did = %session.did, "invite code redeemed at OAuth callback; beta access granted");
            }
            Ok(Err(policy)) => {
                warn!(did = %session.did, ?policy, "invite redeem failed at callback");
                let mut resp = redeem_bounce(&state, &policy).into_response();
                // The reservation is spent/invalid — drop the stale invite cookie.
                clear_invite_cookie(&mut resp);
                return resp;
            }
            Err(err) => {
                warn!(%err, did = %session.did, "invite redeem infra error at callback");
                return login_error(&state, "Login failed while confirming your invite.");
            }
        }
    }

    // Mint an opaque, random server-side session id and store the identity under
    // it; the cookie carries the (HMAC-signed) sid, never the DID.
    let sid = state.sessions.create(Session {
        did: session.did.clone(),
        handle: session.handle.clone(),
    });
    let cookie = cookie::sign_session(&sid, &state.config.cookie_secret);
    info!(did = %session.did, handle = ?session.handle, "OAuth login OK; session cookie set");

    let mut resp = Redirect::to("/").into_response();
    set_cookie(&mut resp, &cookie);
    clear_binding_cookie(&mut resp);
    if clear_invite {
        clear_invite_cookie(&mut resp);
    }
    resp
}

/// Revoke a DID's OAuth session on BOTH backends, best-effort.
///
/// Not "whichever backend is live": during a cutover a user's tokens can be in
/// either store — they logged in under one backend and are logging out under
/// the other. Revoking only the live one would leave a live refresh token
/// behind in the other, which is the exact failure sign-out exists to prevent,
/// and it would be invisible because the sign-out itself looks successful.
///
/// Both arms are best-effort. The caller has already decided to sign the user
/// out, and a network failure must not trap them in a half-logged-out state.
/// How long sign-out will wait for a final read-state flush before revoking
/// anyway.
///
/// Bounded because the flush talks to the user's PDS, and a user trying to leave
/// must never be held by a server that is not answering. Three seconds is long
/// enough for a healthy `applyWrites` (the production samples run 100–970 ms)
/// and short enough that a dead PDS is an inconvenience rather than a trap.
const SIGN_OUT_FLUSH_BUDGET: std::time::Duration = std::time::Duration::from_secs(3);

/// Flush whatever read-state is still dirty for `did`, then give up quietly.
///
/// **Called before revoking, because revoking first strands it (#117).**
/// `revoke_everywhere` deletes the OAuth session, and a dirty cursor with no
/// session cannot be sent by anyone — it parks until the user signs in again,
/// which may be never. Flushing first is what stops the common case from
/// becoming that.
///
/// Best-effort by construction: every failure path here falls through to the
/// revoke. A flush that times out or errors leaves the cursors dirty, which is
/// the parked state the flusher now handles deliberately rather than retrying
/// forever.
async fn flush_before_revoke(state: &AppState, did: &str) {
    match tokio::time::timeout(
        SIGN_OUT_FLUSH_BUDGET,
        crate::readstate::flush_did(state, did),
    )
    .await
    {
        Ok(Ok(())) => {}
        Ok(Err(err)) => {
            warn!(%did, %err, "sign-out: final read-state flush failed; it will park until next sign-in")
        }
        Err(_) => warn!(
            %did,
            budget = ?SIGN_OUT_FLUSH_BUDGET,
            "sign-out: final read-state flush timed out; it will park until next sign-in"
        ),
    }
}

async fn revoke_everywhere(state: &AppState, did: &str) {
    // **Counted under Backend::Sidecar, not left uncounted.** A review found
    // that recording only the rust arm let `oauth_revoke` report a clean success
    // while every sidecar revocation failed — and for anyone who logged in before
    // the cutover, the sidecar store is the ONLY one that held tokens, so the
    // rust arm correctly returns NoSession and the metric reads all-clear while
    // live refresh tokens sit at the PDS.
    //
    // Same op name, different backend: the backend column is what distinguishes
    // them, so "no revocation failures" means checking both rows, not one.
    let sidecar_started = std::time::Instant::now();
    let sidecar_ok = match state.sidecar.revoke_session(did).await {
        Ok(res) => {
            info!(%did, revoked = res.revoked, "sidecar session revoked");
            true
        }
        Err(err) => {
            warn!(%did, %err, "sidecar revoke failed; continuing");
            false
        }
    };
    state.metrics.record(
        crate::metrics::Backend::Sidecar,
        "oauth_revoke",
        sidecar_started.elapsed().as_micros() as u64,
        sidecar_ok,
    );

    if let Some(runtime) = state.oauth.as_deref() {
        let revoke_started = std::time::Instant::now();
        let outcome = crate::oauth::revoke::sign_out_discovering(
            runtime,
            &state.http,
            &state.db,
            did,
            crate::store::now_unix(),
        )
        .await;
        // **Counted, because a warn! nobody reads is not observability.** Until
        // this existed, a revocation failure left exactly one trace: a log line.
        // "No revocation failures this week" was therefore a statement about
        // nobody having looked, which is not the same claim.
        //
        // NoSession counts as a SUCCESS, deliberately. Logout is idempotent —
        // there being nothing to revoke is the correct outcome, not a failure,
        // and counting it as an error would make the metric noisy in exactly
        // the case that is fine. Only `Failed` means the PDS still holds live
        // tokens we asked it to drop.
        let revoke_ok = !matches!(outcome, crate::oauth::revoke::Revocation::Failed(_));
        state.metrics.record(
            crate::metrics::Backend::Rust,
            "oauth_revoke",
            revoke_started.elapsed().as_micros() as u64,
            revoke_ok,
        );
        match outcome {
            crate::oauth::revoke::Revocation::Revoked => {
                info!(%did, "rust OAuth session revoked at the PDS")
            }
            crate::oauth::revoke::Revocation::NoSession => {}
            crate::oauth::revoke::Revocation::Failed(reason) => {
                warn!(%did, %reason, "rust OAuth revoke failed; the local session is gone regardless")
            }
        }
    }
}

/// `POST /logout` — end the session everywhere, not just in this browser.
///
/// Clearing the cookie only stops *this* device from presenting the session;
/// the sidecar still holds live OAuth tokens for the DID. So logout now also
/// calls the sidecar `POST /internal/revoke {did}`, which revokes the refresh +
/// access tokens at the PDS and drops the sidecar's session rows. The local
/// registry entry is dropped and the cookie cleared regardless of whether the
/// revoke round-trip succeeds (best-effort — a network blip must not trap the
/// user in a half-logged-out state).
async fn logout(State(state): State<AppState>, headers: HeaderMap) -> Response {
    if let Some(user) = current_session(&state, &headers).await {
        // Only a real cookie session (`sid` present) has sidecar-held tokens to
        // revoke; the dev-DID fallback never handshook the sidecar.
        if let Some(sid) = user.sid {
            state.sessions.remove(&sid);
            // BEFORE the revoke: afterwards there is no session to send it with.
            flush_before_revoke(&state, &user.did).await;
            revoke_everywhere(&state, &user.did).await;
        }
    }
    let mut resp = Redirect::to("/login").into_response();
    set_cookie(
        &mut resp,
        &format!("{SESSION_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
    resp
}

/// Form body for `POST /account/delete` — the confirm-gate. The user must type
/// `DELETE` into this field for the purge to run.
#[derive(Debug, Deserialize)]
struct DeleteAccountForm {
    #[serde(default)]
    confirm: String,
}

/// The literal a user must type to confirm the destructive delete.
const DELETE_CONFIRM_PHRASE: &str = "DELETE";

/// `POST /account/delete` (authed) — the "delete my data" endpoint.
///
/// Confirm-gated: the form must carry `confirm=DELETE` or we bounce back to
/// `/manage` with an explanatory flash and touch nothing. On confirmation it:
///   1. purges **every** local row owned by the caller DID (`entry_state`,
///      `read_cursor`, `sub_ref`, `beta_access` seat, and any invite codes the
///      DID created) via [`store::purge_did_data`], then
///   2. revokes the OAuth session at the PDS via `revoke_everywhere` — the
///      sidecar's `POST /internal/revoke {did}` and, when the Rust OAuth runtime
///      is configured, its RFC 7009 revocation too — then
///   3. drops the in-memory session and clears the cookie, signing the user out.
///
/// The subscription/folder/saved *records* in the user's own PDS are
/// intentionally left alone — they are the user's data on their own server; the
/// `/about` copy and this page's UI both say so, and export stays available.
async fn account_delete(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<DeleteAccountForm>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();

    // Confirm-gate: require the exact typed phrase before doing anything.
    if form.confirm.trim() != DELETE_CONFIRM_PHRASE {
        return Ok(Redirect::to(&format!(
            "/manage?flash={}",
            qenc("Type DELETE to confirm — nothing was deleted.")
        ))
        .into_response());
    }

    // 1. Purge every local row this DID owns (single transaction).
    let counts = store::purge_did_data(&state.db, &did).await?;
    info!(
        %did,
        total = counts.total(),
        entry_state = counts.entry_state,
        read_cursor = counts.read_cursor,
        sub_ref = counts.sub_ref,
        beta_access = counts.beta_access,
        invite_codes = counts.invite_codes,
        "account/delete: local rows purged"
    );

    // 2. Revoke the OAuth session at the sidecar/PDS (best-effort — the local
    //    rows are already gone; a network blip must not block the sign-out).
    revoke_everywhere(&state, &did).await;

    // 3. Drop the in-memory session and clear the cookie: sign the user out.
    if let Some(sid) = user.sid {
        state.sessions.remove(&sid);
    }
    let mut resp = Redirect::to(&format!(
        "/login?flash={}",
        qenc("Your data was deleted and you've been signed out. Thanks for trying FeatherReader.")
    ))
    .into_response();
    set_cookie(
        &mut resp,
        &format!("{SESSION_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
    Ok(resp)
}

/// The `/login` card, shared by the form and its error re-render.
fn login_card(config: &Config) -> Card {
    Card::public(
        config,
        "/login",
        "Sign in — FeatherReader",
        "Sign in to FeatherReader with your atproto handle. You approve access on \
         your own server — no signup, no password.",
    )
}

/// Re-render the login form with an error banner.
fn login_error(state: &AppState, msg: &str) -> Response {
    render(&LoginTemplate {
        card: login_card(&state.config),
        repo_url: REPO_URL,
        error: msg.to_string(),
        flash: String::new(),
    })
}

// ---------------------------------------------------------------------------
// Closed-beta invite gate (self-serve redeem + admin mint)
// ---------------------------------------------------------------------------

/// Form body for `POST /beta/redeem`.
#[derive(Debug, Deserialize)]
struct RedeemForm {
    code: String,
}

/// `GET /beta/redeem` — render the invite-redeem page. If the seat cap is
/// already full we render the "capacity full" variant (no form).
async fn beta_redeem_form(State(state): State<AppState>) -> Response {
    let full = store::count_beta_access(&state.db)
        .await
        .map(|n| n >= state.config.beta_cap)
        .unwrap_or(false);
    render(&BetaRedeemTemplate {
        card: redeem_card(&state.config),
        repo_url: REPO_URL,
        error: String::new(),
        capacity_full: full,
    })
}

/// `POST /beta/redeem` — the **pre-handshake** reservation.
///
/// Validates the pasted code is *redeemable right now* (exists, active,
/// unexpired, and a seat is free) WITHOUT consuming it or binding a DID — the
/// visitor has no DID yet. On success it sets a short-lived signed invite cookie
/// reserving intent to redeem this code, then sends the visitor to `/login`. The
/// OAuth callback later binds the verified DID and atomically consumes the code
/// (`store::redeem_code`). This ordering means a non-invited visitor can never
/// start OAuth (and burn a sidecar handshake).
async fn beta_redeem_submit(
    State(state): State<AppState>,
    Form(form): Form<RedeemForm>,
) -> Response {
    let code = form.code.trim().to_uppercase();
    if code.is_empty() {
        return render(&BetaRedeemTemplate {
            card: redeem_card(&state.config),
            repo_url: REPO_URL,
            error: "Enter your invite code.".to_string(),
            capacity_full: false,
        });
    }

    match preflight_code(&state, &code).await {
        Ok(()) => {
            let cookie = sign_invite(&code, &state.config.cookie_secret);
            let mut resp = Redirect::to("/login").into_response();
            set_cookie(&mut resp, &cookie);
            info!("invite code preflight OK; reserving intent + redirecting to /login");
            resp
        }
        Err(policy) => {
            warn!(?policy, "invite code preflight rejected");
            redeem_bounce(&state, &policy)
        }
    }
}

/// Read-only preflight of an invite code for the pre-handshake reservation:
/// verify it exists, is active, is not past `expires_at`, and that a seat is
/// free — mirroring the checks `store::redeem_code` will re-run atomically at
/// callback time. Does NOT consume the code or grant a seat. Returns the same
/// typed [`store::RedeemError`] variants so the two paths share one message map.
async fn preflight_code(state: &AppState, code: &str) -> Result<(), store::RedeemError> {
    // Cap check first: a clear "capacity full" beats "code invalid" when both.
    // FAIL CLOSED on a count error — an `unwrap_or(0)` would let a DB blip read as
    // "0 seats used" and wave the redeem through the preflight. (`redeem_code`
    // still backstops the real cap inside its tx, so this is a consistency /
    // defence-in-depth fix, not the only guard.) Treat an unverifiable count as
    // capacity-full: the redeemer sees "at capacity, try later" rather than a mint
    // that might overrun the cap.
    let count = match store::count_beta_access(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "preflight_code: count_beta_access failed; failing closed");
            return Err(store::RedeemError::CapacityFull);
        }
    };
    if count >= state.config.beta_cap {
        return Err(store::RedeemError::CapacityFull);
    }
    // Look up the code's current status + expiry (read-only).
    let row = sqlx::query_as::<_, (String, i64)>(
        "SELECT status, expires_at FROM invite_codes WHERE code = ?1",
    )
    .bind(code)
    .fetch_optional(&state.db)
    .await
    .ok()
    .flatten();
    let (status, expires_at) = match row {
        Some(r) => r,
        None => return Err(store::RedeemError::NotFound),
    };
    let now = chrono::Utc::now().timestamp();
    match status.as_str() {
        "active" if expires_at >= now => Ok(()),
        "active" => Err(store::RedeemError::Expired),
        "expired" => Err(store::RedeemError::Expired),
        // "redeemed" or anything else non-active.
        _ => Err(store::RedeemError::AlreadyRedeemed),
    }
}

/// Map a [`store::RedeemError`] to the invite page with the right message. Used
/// by both the preflight (`POST /beta/redeem`) and the callback bind path.
fn redeem_bounce(state: &AppState, policy: &store::RedeemError) -> Response {
    use store::RedeemError::*;
    let (msg, capacity_full) = match policy {
        NotFound => ("That invite code isn't valid.", false),
        Expired => ("That invite code has expired.", false),
        AlreadyRedeemed => ("That invite code has already been used.", false),
        CapacityFull => ("", true),
    };
    render(&BetaRedeemTemplate {
        card: redeem_card(&state.config),
        repo_url: REPO_URL,
        error: msg.to_string(),
        capacity_full,
    })
}

/// The `/beta/redeem` card, shared by the form, its re-renders and the claim
/// link's bounce.
fn redeem_card(config: &Config) -> Card {
    Card::public(
        config,
        "/beta/redeem",
        "Redeem an invite — FeatherReader",
        "Redeem a closed-beta invite code for this FeatherReader instance, then sign \
         in with your atproto handle.",
    )
}

/// Query for `POST /admin/invites` — how many codes to mint (`?n=`, default 1).
#[derive(Debug, Deserialize, Default)]
struct MintQuery {
    #[serde(default)]
    n: Option<u32>,
}

/// `POST /admin/invites?n=N` — mint N invite codes.
///
/// `GET /oauth/client-metadata.json` — the client's published identity.
///
/// **This URL IS the `client_id`.** The PDS fetches it during every login and
/// caches it against every existing grant, so it must keep answering at exactly
/// this path across the cutover — the sidecar serves the same document at the
/// same URL today, proxied by the edge.
///
/// Served whatever backend is live: a request that arrives here is from a PDS
/// resolving our identity, and it has no idea which of our two implementations
/// is currently answering repo calls.
async fn oauth_client_metadata(State(state): State<AppState>) -> Response {
    let Some(runtime) = state.oauth.as_deref() else {
        // The sidecar is serving this path in front of us, or nothing is.
        return (StatusCode::NOT_FOUND, "no client metadata\n").into_response();
    };
    axum::Json(crate::oauth::metadata::client_metadata(&runtime.client)).into_response()
}

/// `GET /oauth/jwks.json` — the client's public signing key.
///
/// Production only. The localhost dev client is a PUBLIC client: it registers no
/// key and signs no assertions, so publishing a JWKS there would advertise a
/// credential that is never used — and would make a dev deployment look like a
/// confidential client to anyone reading it.
async fn oauth_jwks(State(state): State<AppState>) -> Response {
    let Some(runtime) = state.oauth.as_deref() else {
        return (StatusCode::NOT_FOUND, "no jwks\n").into_response();
    };
    match runtime.client_key.as_ref() {
        Some(key) => match key.jwks_document() {
            Ok(doc) => axum::Json(doc).into_response(),
            Err(err) => {
                warn!(%err, "could not render the client JWKS");
                (StatusCode::INTERNAL_SERVER_ERROR, "jwks unavailable\n").into_response()
            }
        },
        None => (StatusCode::NOT_FOUND, "this client publishes no jwks\n").into_response(),
    }
}

/// How many failing feeds `/admin/metrics` will name. One response, so bounded.
const ADMIN_FAILING_FEED_LIMIT: i64 = 200;

/// `GET /admin/metrics` — repo-op latency for both backends, as plain text.
///
/// Admin-gated on the same rule as the invite minter: the table names every
/// operation the reader performs and how often each fails, which is an
/// operational picture rather than public information.
///
/// Text, not JSON or HTML: it is read by a person deciding whether the cutover
/// is safe, and the comparison is two rows side by side.
async fn admin_metrics(State(state): State<AppState>, headers: HeaderMap) -> Response {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response(),
    };
    if !state.config.admin_seed_dids().iter().any(|d| d == &did) {
        warn!(%did, "admin metrics denied: not an admin-seed DID");
        return (StatusCode::FORBIDDEN, "not an admin\n").into_response();
    }

    // Flush first, so the table includes this process's traffic up to now.
    // Then read the PERSISTED rows, which is the only place both backends can
    // appear at once -- a flip is a restart, and in-process memory only ever
    // holds the backend currently running.
    if let Err(err) =
        crate::metrics::flush(&state.metrics, &state.db, crate::store::now_unix()).await
    {
        warn!(%err, "could not flush repo timings before rendering");
    }
    let rows = match crate::metrics::persisted_rows(&state.db).await {
        Ok(rows) => rows,
        Err(err) => {
            warn!(%err, "could not read persisted repo timings");
            return (StatusCode::INTERNAL_SERVER_ERROR, "metrics unavailable\n").into_response();
        }
    };

    // The live backend is named at the top: a table of two populated rows is
    // ambiguous about which one is currently serving users.
    // Parked read-state, alongside the timings. The flusher no longer logs
    // these every round (#117), so without a number here the state would be
    // silent — which is the failure the noisy loop at least did not have.
    let parked = match crate::store::parked_readstate_dids(&state.db).await {
        Ok(n) => n.to_string(),
        Err(err) => {
            warn!(%err, "could not count parked read-state DIDs");
            "unknown".to_string()
        }
    };
    // **The half the public histogram cannot carry.** `/stats` reports counts by
    // cause and nothing else, deliberately — but `fetch` covers DNS failure,
    // timeout, SSRF refusal AND this reader's own bugs, so the count alone
    // cannot separate "the publishers are gone" from "we are broken". #159 was
    // the latter and took a production investigation to establish. Named feeds
    // and their error text belong here, behind ALLOWED_DIDS.
    let failing = match crate::store::failing_feeds(&state.db, ADMIN_FAILING_FEED_LIMIT).await {
        Ok(f) => f,
        Err(err) => {
            warn!(%err, "could not list failing feeds");
            Vec::new()
        }
    };
    let mut failing_block = String::new();
    if !failing.is_empty() {
        failing_block.push_str("\nfailing feeds (worst first)\n");
        for f in &failing {
            failing_block.push_str(&format!(
                "  {:>4}x  {:<8}  {}\n          {}\n",
                f.consecutive_errors,
                f.kind.as_deref().unwrap_or("unknown"),
                f.url,
                f.detail.as_deref().unwrap_or("(no detail recorded)"),
            ));
        }
    }

    // **Capacity that no other page can show.** The global ceiling counts every
    // row (`store::count_feeds`), but `/stats` measures the poller and excludes
    // unpollable ones — so an instance can be at its cap with every public
    // number saying otherwise. A review found exactly that gap.
    let unpollable = match crate::store::unpollable_feeds(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "could not count unpollable feeds");
            -1
        }
    };
    let cached = crate::store::count_feeds(&state.db).await.unwrap_or(-1);

    let body = format!(
        "live backend: {}\nparked read-state DIDs: {}\n\
         feeds cached: {} (ceiling {}), of which unpollable: {}\n\n{}{}",
        state.config.repo_backend.as_str(),
        parked,
        cached,
        state.config.max_feeds_global,
        unpollable,
        crate::metrics::render(&rows),
        failing_block,
    );
    (StatusCode::OK, body).into_response()
}

/// Authorized ONLY for a live session whose DID is in the `ALLOWED_DIDS` admin
/// seed (`config.admin_seed_dids`). Returns the freshly-minted codes as
/// newline-separated `text/plain`. Deliberately minimal (no HTML UI).
async fn admin_mint_invites(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<MintQuery>,
) -> Response {
    // Require a real, current session (not just a DID string) whose DID is an
    // admin-seed DID. `current_did` already re-checks the beta gate.
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response(),
    };
    if !state.config.admin_seed_dids().iter().any(|d| d == &did) {
        warn!(%did, "admin mint denied: not an admin-seed DID");
        return (StatusCode::FORBIDDEN, "not an admin\n").into_response();
    }

    let n = q.n.unwrap_or(1).clamp(1, 100);
    let mut codes = Vec::with_capacity(n as usize);
    for _ in 0..n {
        match store::mint_code(&state.db, &did, INVITE_TTL_SECS).await {
            Ok(code) => codes.push(code),
            Err(err) => {
                warn!(%err, %did, "admin mint_code failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
            }
        }
    }
    info!(%did, count = codes.len(), "admin minted invite codes");
    let mut body = codes.join("\n");
    body.push('\n');
    (StatusCode::OK, body).into_response()
}

// ---------------------------------------------------------------------------
// Bot claim link: /claim?t=<token>  +  POST /bot/claims (shared-secret mint)
// ---------------------------------------------------------------------------

/// Query for `GET /claim`.
#[derive(Debug, Deserialize)]
struct ClaimQuery {
    /// The opaque claim token from the bot's public follow-back skeet.
    t: Option<String>,
}

/// `GET /claim?t=<token>` — redeem a bot-issued claim link.
///
/// The follow→invite bot posts a public skeet mentioning a new follower with a
/// link here. The token wraps a pre-minted invite code (never the raw code — see
/// [`sign_claim_token`]). On a valid, still-redeemable token this behaves exactly
/// like a successful `POST /beta/redeem`: it sets the reserving `fr_invite`
/// cookie and sends the visitor to `/login`, so they flow through OAuth and the
/// callback atomically consumes the code (`store::redeem_code`) — the same
/// machinery as a pasted code. On any failure it bounces to the invite page with
/// the matching message.
///
/// Single-use / grabbability: a token in a public URL is grabbable. The code it
/// wraps is single-use (redeem flips `active→redeemed`), and `preflight_code`
/// here rejects an already-used / expired / capacity-full code before reserving,
/// so a replayed link past the first successful claim is refused. The residual
/// window is the same as any pasted invite code: whoever completes OAuth *first*
/// with a live reservation wins the seat. The per-IP rate limit on `/claim`
/// blunts brute-force enumeration.
async fn claim(State(state): State<AppState>, Query(q): Query<ClaimQuery>) -> Response {
    let token = match q.t {
        Some(t) if !t.is_empty() => t,
        _ => {
            warn!("claim link with no token");
            return redeem_bounce(&state, &store::RedeemError::NotFound);
        }
    };

    // Unwrap the token → the invite code it reserves. A tampered/forged token
    // yields nothing → treat as an invalid code (don't leak whether it parsed).
    let code = match claim_token_code(&token, &state.config.cookie_secret) {
        Some(c) => c,
        None => {
            warn!("claim token invalid (bad signature / malformed)");
            return redeem_bounce(&state, &store::RedeemError::NotFound);
        }
    };

    // Re-run the same preflight as the pasted-code path: exists, active,
    // unexpired, seat free. This is what makes a replayed link past first-claim
    // (or past cap) fail cleanly.
    match preflight_code(&state, &code).await {
        Ok(()) => {
            let cookie = sign_invite(&code, &state.config.cookie_secret);
            let mut resp = Redirect::to("/login").into_response();
            set_cookie(&mut resp, &cookie);
            info!("claim token preflight OK; reserving intent + redirecting to /login");
            resp
        }
        Err(policy) => {
            warn!(?policy, "claim token preflight rejected");
            redeem_bounce(&state, &policy)
        }
    }
}

/// The JSON body `POST /bot/claims` accepts — the follower the claim is FOR.
///
/// Passing the follower DID makes the APP the authoritative deduper: the app can
/// short-circuit a DID that already holds a seat, and return the SAME code for a
/// DID that already has an outstanding claim — so a bot-host state loss cannot
/// re-mint or re-post per follower. Handle is advisory (logs only).
#[derive(Debug, Default, Deserialize)]
struct BotClaimRequest {
    /// The follower's DID (the idempotency key). Optional for backward-compat: an
    /// omitted DID falls back to the old un-keyed mint (no server-side dedupe).
    #[serde(default)]
    did: Option<String>,
    /// The follower's handle (advisory; recorded for operator logs only).
    #[serde(default)]
    #[allow(dead_code)]
    handle: Option<String>,
}

/// The JSON body `POST /bot/claims` returns on success.
#[derive(Debug, serde::Serialize)]
struct BotClaimResponse {
    /// Server-side dedupe outcome, so the bot knows whether to post:
    /// `"minted"` (a fresh code — post the claim link), `"existing"` (this DID
    /// already had an outstanding claim; the SAME code/token/url is returned, so an
    /// idempotent re-post is safe), or `"already_seated"` (this DID already holds
    /// beta access; code/token/url are empty and the bot should post NOTHING).
    status: &'static str,
    /// The bare invite code (`FEATHER-…`) — for the bot's own logs/idempotency
    /// store. NEVER post this publicly; post the `url` instead. Empty when
    /// `already_seated`.
    code: String,
    /// The opaque claim token (the code wrapped + signed). Empty when
    /// `already_seated`.
    token: String,
    /// The full claim URL to put in the public skeet: `${public_url}/claim?t=…`.
    /// Empty when `already_seated`.
    url: String,
}

/// `POST /bot/claims` — headless, shared-secret mint of a claim link.
///
/// Auth is a bearer shared secret in the `X-Bot-Secret` header (== the Fly secret
/// `FEATHERREADER_BOT_SECRET`), NOT an OAuth cookie — so the homelab-hosted bot
/// can call it. When `FEATHERREADER_BOT_SECRET` is unset the endpoint is DISABLED
/// (503), so a bare/dev instance never exposes an unauthenticated mint.
///
/// Server-side DID idempotency (the authoritative dedupe backstop): the request
/// body carries the follower `did`. The app — not the bot's local SQLite — is the
/// source of truth, so a bot-host state loss cannot re-mint or re-post per
/// follower:
///   * DID already holds beta access → `200 {status:"already_seated"}` (empty
///     code/url; the bot marks it handled and posts NOTHING);
///   * DID already has an outstanding active claim → `200 {status:"existing"}`
///     returning the SAME code/token/url (idempotent — never a second mint);
///   * otherwise mint a fresh code recorded FOR that DID → `200 {status:"minted"}`.
///
/// Cap accounting: the bot must not promise more claims than seats remain, so
/// this refuses with `409 Conflict {"error":"full"}` when
/// `beta_access + outstanding active codes >= FEATHERREADER_BETA_CAP`. (The
/// redeem-time cap in `store::redeem_code` is still the hard backstop.) The count
/// queries FAIL CLOSED: a DB error propagates as `500` rather than reading 0 and
/// minting past the cap.
///
/// On a fresh mint it uses the generous claim TTL (`FEATHERREADER_CLAIM_TTL_SECS`,
/// default 14d — the admin browser flow's 30-min TTL would expire before the
/// follower taps an async-delivered link).
async fn bot_mint_claim(
    State(state): State<AppState>,
    headers: HeaderMap,
    body: axum::body::Bytes,
) -> Response {
    // 1. The endpoint is OFF unless a bot secret is configured.
    let bot_secret = match state.config.bot_secret.as_deref() {
        Some(s) => s,
        None => {
            warn!(
                "POST /bot/claims called but FEATHERREADER_BOT_SECRET is unset (endpoint disabled)"
            );
            return (
                StatusCode::SERVICE_UNAVAILABLE,
                "bot mint endpoint disabled (FEATHERREADER_BOT_SECRET unset)\n",
            )
                .into_response();
        }
    };

    // 2. Constant-time bearer check on the X-Bot-Secret header.
    let presented = headers
        .get("x-bot-secret")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    if !bot_secret_matches(presented, bot_secret) {
        warn!("POST /bot/claims rejected: bad or missing X-Bot-Secret");
        return (StatusCode::UNAUTHORIZED, "bad bot secret\n").into_response();
    }

    // 2b. Parse the (optional) JSON body → the follower DID/handle. An empty body
    // (legacy caller) parses to an all-None request; a malformed body is a 400.
    let req: BotClaimRequest = if body.is_empty() {
        BotClaimRequest::default()
    } else {
        match serde_json::from_slice(&body) {
            Ok(r) => r,
            Err(err) => {
                warn!(%err, "POST /bot/claims: bad JSON body");
                return (StatusCode::BAD_REQUEST, "bad json body\n").into_response();
            }
        }
    };
    let follower_did = req.did.as_deref().filter(|d| !d.is_empty());

    // 3. Server-side DID idempotency (only when a DID was supplied):
    if let Some(did) = follower_did {
        // 3a. Already seated → tell the bot to post nothing.
        match store::has_beta_access(&state.db, did).await {
            Ok(true) => {
                info!("bot mint: DID already holds beta access; already_seated");
                return bot_claim_json(BotClaimResponse {
                    status: "already_seated",
                    code: String::new(),
                    token: String::new(),
                    url: String::new(),
                });
            }
            Ok(false) => {}
            Err(err) => {
                // Fail closed: a DB error must not fall through to a fresh mint.
                warn!(%err, "bot mint: has_beta_access failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "lookup failed\n").into_response();
            }
        }
        // 3b. Outstanding active claim for this DID → return the SAME code (no
        // second mint). This is what survives a bot-host state loss.
        match store::find_active_code_for_did(&state.db, did).await {
            Ok(Some(code)) => {
                info!("bot mint: existing outstanding claim for DID; returning same code");
                let token = sign_claim_token(&code, &state.config.cookie_secret);
                let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
                return bot_claim_json(BotClaimResponse {
                    status: "existing",
                    code,
                    token,
                    url,
                });
            }
            Ok(None) => {}
            Err(err) => {
                warn!(%err, "bot mint: find_active_code_for_did failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "lookup failed\n").into_response();
            }
        }
    }

    // 4. Cap accounting: seats already granted + outstanding unredeemed codes.
    //    FAIL CLOSED — a count error is a 500, not a silent mint past the cap.
    let granted = match store::count_beta_access(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "bot mint: count_beta_access failed; failing closed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "count failed\n").into_response();
        }
    };
    let outstanding = match store::count_active_codes(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "bot mint: count_active_codes failed; failing closed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "count failed\n").into_response();
        }
    };
    if granted + outstanding >= state.config.beta_cap {
        info!(
            granted,
            outstanding,
            cap = state.config.beta_cap,
            "bot mint refused: at capacity"
        );
        return (
            StatusCode::CONFLICT,
            [(header::CONTENT_TYPE, "application/json")],
            "{\"error\":\"full\"}\n",
        )
            .into_response();
    }

    // 5. Mint with the generous claim TTL, recording the follower DID (when given)
    //    so a re-request for the same DID returns THIS code idempotently.
    let bot_did = state
        .config
        .admin_seed_dids()
        .first()
        .cloned()
        .unwrap_or_else(|| "did:bot:featherreader".to_string());
    let minted = match follower_did {
        Some(did) => {
            store::mint_code_for_did(&state.db, &bot_did, state.config.claim_ttl_secs, did).await
        }
        None => store::mint_code(&state.db, &bot_did, state.config.claim_ttl_secs).await,
    };
    let code = match minted {
        Ok(c) => c,
        // S4: the dedupe check (3b) and this mint are separate statements, so two
        // concurrent requests for one DID can both fall through 3b's `Ok(None)`.
        // The partial unique index `idx_invite_codes_intended_active` makes the
        // loser's INSERT fail (only one active row per intended DID), which
        // surfaces here as a conflict. Recover by returning the winner's existing
        // code (same shape as the 3b idempotent path) instead of a 500.
        Err(err) if follower_did.is_some() && store::is_intended_active_conflict(&err) => {
            match store::find_active_code_for_did(&state.db, follower_did.unwrap()).await {
                Ok(Some(code)) => {
                    info!("bot mint: lost the mint race; returning the concurrently-minted code");
                    let token = sign_claim_token(&code, &state.config.cookie_secret);
                    let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
                    return bot_claim_json(BotClaimResponse {
                        status: "existing",
                        code,
                        token,
                        url,
                    });
                }
                // The winner's row vanished between the conflict and this lookup
                // (redeemed/expired/purged in the gap) — nothing to hand back.
                // Fail closed rather than silently mint past the just-hit guard.
                Ok(None) => {
                    warn!("bot mint: conflict but no active code found on recovery");
                    return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
                }
                Err(err) => {
                    warn!(%err, "bot mint: recovery lookup after conflict failed");
                    return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
                }
            }
        }
        Err(err) => {
            warn!(%err, "bot mint_code failed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
        }
    };
    let token = sign_claim_token(&code, &state.config.cookie_secret);
    let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
    info!("bot minted a claim code + token");

    bot_claim_json(BotClaimResponse {
        status: "minted",
        code,
        token,
        url,
    })
}

/// Serialize a [`BotClaimResponse`] to a `200 application/json` response (or a
/// `500` if serialization somehow fails).
fn bot_claim_json(resp: BotClaimResponse) -> Response {
    match serde_json::to_string(&resp) {
        Ok(body) => (
            StatusCode::OK,
            [(header::CONTENT_TYPE, "application/json")],
            body,
        )
            .into_response(),
        Err(err) => {
            warn!(%err, "serializing bot claim response failed");
            (StatusCode::INTERNAL_SERVER_ERROR, "serialize failed\n").into_response()
        }
    }
}

/// Constant-time equality for the bot bearer secret (avoid a timing side-channel
/// on the shared secret). Delegates to the same `cookie::constant_time_eq` used
/// by the HMAC checks so there is one comparator to audit; a length mismatch
/// short-circuits to `false`, which is fine — the secret length isn't sensitive.
fn bot_secret_matches(presented: &str, expected: &str) -> bool {
    cookie::constant_time_eq(presented.as_bytes(), expected.as_bytes())
}

// ---------------------------------------------------------------------------
// Signed, short-lived invite cookie (reuses the session-cookie HMAC helper)
// ---------------------------------------------------------------------------

/// Sign the reserved invite `code` into a short-lived `Set-Cookie` value. Reuses
/// the same HMAC-SHA256 helper as the session cookie; the payload is the code
/// itself (base64url) rather than an opaque sid, since the code IS the reserved
/// intent the callback consumes.
fn sign_invite(code: &str, secret: &str) -> String {
    cookie::sign_value(INVITE_COOKIE, code, secret, INVITE_TTL_SECS)
}

/// Verify + read the reserved invite code out of the request's invite cookie
/// (`None` if absent, tampered, or forged). No expiry is enforced here beyond
/// the cookie's own `Max-Age`; the atomic `redeem_code` at the callback is the
/// authority on the code's live status.
fn invite_cookie_code(headers: &HeaderMap, secret: &str) -> Option<String> {
    cookie::verify_value(headers, INVITE_COOKIE, secret)
}

/// Domain-separation label for the claim TOKEN's HMAC (distinct from the
/// `fr_invite`/`fr_session` cookie names), so a token can never be replayed as a
/// cookie value and vice-versa.
const CLAIM_TOKEN_LABEL: &str = "claim-token";

/// Sign an invite `code` into a URL-safe claim TOKEN: `b64url(code).<sig>`
/// (HMAC-SHA256 over `"claim-token" || 0x00 || code`).
///
/// NOTE — the token is NOT confidential: the `b64url(code)` half is trivially
/// decodable by anyone, so the raw `FEATHER-…` code is effectively public in the
/// claim URL. The token's security is INTEGRITY + SINGLE-USE, not secrecy: the
/// `<sig>` HMAC means only this instance can MINT a valid token (a forged/guessed
/// code won't verify), the wrapped code is single-use (redeem flips
/// `active→redeemed`), and `/claim` is per-IP rate-limited. Wrapping keeps the
/// token one self-contained string needing no server-side token table; it does
/// NOT hide the code.
fn sign_claim_token(code: &str, secret: &str) -> String {
    cookie::sign_token(CLAIM_TOKEN_LABEL, code, secret)
}

/// Verify a claim token and return the invite code it wraps (`None` on a tampered
/// / forged / malformed token). The code's live status (active/unexpired/seat
/// free) is re-checked by `preflight_code`; this only proves the token was minted
/// by this instance.
fn claim_token_code(token: &str, secret: &str) -> Option<String> {
    cookie::verify_token(CLAIM_TOKEN_LABEL, token, secret)
}

/// Clear the invite cookie on a response (after a successful bind, or when the
/// reservation turned out to be stale).
fn clear_invite_cookie(resp: &mut Response) {
    set_cookie(
        resp,
        &format!("{INVITE_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
}

// ---------------------------------------------------------------------------
// OPML import + export
// ---------------------------------------------------------------------------

/// `POST /opml` — import subscriptions from an OPML document.
///
/// Accepts either a multipart file upload (field `file`) or a pasted textarea
/// (field `opml`). The parsed feeds each become a `community.lexicon.rss.folder`
/// (for any named folders) + a `community.lexicon.rss.subscription` record in the
/// user's PDS via the records layer's bulk-add (`add_subscriptions_bulk`, one
/// `applyWrites` round-trip per 200 feeds). Feeds are also upserted into the local cache so
/// they show immediately; polling is left to the background poller.
async fn import_opml(
    State(state): State<AppState>,
    headers: HeaderMap,
    mut multipart: Multipart,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    // Collect the OPML text from whichever field carried it. Multipart errors
    // are mapped to their axum-native response so that an over-cap upload (the
    // `DefaultBodyLimit` on this route, see `OPML_BODY_LIMIT`) surfaces as
    // `413 Payload Too Large` rather than being swallowed by the blanket
    // `WebError` → `500` conversion.
    let mut opml_text = String::new();
    while let Some(field) = multipart.next_field().await.map_err(multipart_response)? {
        let name = field.name().unwrap_or("").to_string();
        if name == "opml" || name == "file" {
            let bytes = field.bytes().await.map_err(multipart_response)?;
            if !bytes.is_empty() {
                opml_text = String::from_utf8_lossy(&bytes).into_owned();
                if name == "file" {
                    break;
                }
            }
        }
    }

    // A parse FAILURE and an empty-but-valid file are different things, and
    // `unwrap_or_default` collapsed them: a malformed export was reported to the
    // reader as "No feeds found in that OPML", which sends them looking at their
    // old reader for feeds that are right there in the file.
    let feeds =
        match opml::parse_opml(&opml_text) {
            Ok(feeds) => feeds,
            Err(err) => {
                warn!(%err, %did, "OPML import could not parse the uploaded file");
                return Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("That file could not be read as OPML. Export it again from your other reader?")
            ))
                .into_response());
            }
        };
    if feeds.is_empty() {
        info!(%did, "OPML import found no feeds");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc("No feeds found in that OPML")))
                .into_response(),
        );
    }

    // Create any named folders first, mapping folder name → at:// URI so
    // subscriptions can reference them.
    let now = now_rfc3339();
    let mut folder_uris: std::collections::HashMap<String, String> =
        std::collections::HashMap::new();
    // Reuse existing folders where the name already exists.
    if let Ok(existing) = state.repo().list_folders_sorted(&did).await {
        for (rkey, folder) in existing {
            folder_uris
                .entry(folder.name.clone())
                .or_insert_with(|| folder_uri(&did, &rkey));
        }
    }
    let mut wanted_folders: Vec<String> = feeds
        .iter()
        .filter_map(|f| f.folder.clone())
        .filter(|n| !n.is_empty())
        .collect();
    wanted_folders.sort();
    wanted_folders.dedup();
    for name in wanted_folders {
        if folder_uris.contains_key(&name) {
            continue;
        }
        let folder = Folder::new(name.clone(), now.clone());
        match state.repo().add_folder(&did, &folder).await {
            Ok(rkey) => {
                folder_uris.insert(name, folder_uri(&did, &rkey));
            }
            Err(err) => warn!(%err, %did, "OPML folder create failed"),
        }
    }

    // Build one subscription record per PUBLIC feed + upsert the local cache row.
    // Private/paid feeds are SKIPPED entirely (never stored, fetched, or written)
    // and reported back to the user — the same public-feeds-only stance as the
    // single-add path, so an OPML import can't leak a Substack/Patreon/podcast
    // token onto the public network either.
    // Per-DID subscription cap: an OPML import must not blow past the cap. Compute
    // the remaining headroom (cap − existing) once; public feeds beyond it are
    // TRIMMED (not imported) and reported. `<= 0` disables the cap.
    let sub_cap = state.config.max_subs_per_did;
    let mut headroom: Option<i64> = if sub_cap > 0 {
        let existing = store::count_subscriptions_for_did(pool, &did)
            .await
            .unwrap_or(0);
        Some((sub_cap - existing).max(0))
    } else {
        None
    };
    let mut trimmed_over_cap: usize = 0;

    // Global feeds ceiling: an OPML import must not blow past the shared cache
    // ceiling any more than the single-add path may. Seed the remaining global
    // headroom (cap − current feeds) once, and only a BRAND-NEW feed URL (one
    // not already cached) consumes it. Existing/duplicate URLs add no row and
    // are always allowed. Feeds past the ceiling are TRIMMED and reported.
    // `<= 0` disables the ceiling.
    let feeds_cap = state.config.max_feeds_global;
    let mut global_headroom: Option<i64> = if feeds_cap > 0 {
        let existing = store::count_feeds(pool).await.unwrap_or(0);
        Some((feeds_cap - existing).max(0))
    } else {
        None
    };
    let mut trimmed_over_global: usize = 0;

    let mut subs = Vec::with_capacity(feeds.len());
    let mut skipped_private: Vec<String> = Vec::new();
    // Imported into the PDS but not cached locally, so not pollable until the
    // next import touches them. Counted rather than only logged — see below.
    let mut uncached: usize = 0;
    // Entries this instance cannot store at all (an `at://` publication with
    // the flag off, an unsupported scheme). Counted, because the `continue`
    // below used to increment nothing while the privacy branch beside it
    // produced a label — so an OPML from a standard.site-enabled instance
    // imported "successfully" with entries missing and no reason given.
    let mut skipped_unsupported: usize = 0;
    for f in &feeds {
        // `xmlUrl` is whatever the uploaded file says, and nothing on this path
        // ever parsed it — the single-add path can't reach here because
        // `resolve_feed_url` must parse AND successfully fetch first. So
        // `javascript:alert(1)` and `file:///etc/passwd` were both accepted,
        // cached, and published as records to the user's PUBLIC repo. Note that
        // `classify_feed_privacy` does not catch these: both parse cleanly, and
        // it returns `Public` for anything unparseable by design.
        if !feed::is_storable_feed_url(&f.feed_url, state.config.standard_site) {
            info!(
                %did,
                "skipped an OPML entry whose xmlUrl is not a storable feed URL"
            );
            skipped_unsupported += 1;
            continue;
        }
        if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&f.feed_url) {
            info!(feed = %f.feed_url, %reason, %did, "skipped private/paid feed on OPML import (not stored)");
            // Report by title where we have one, else the (public-safe) host.
            let label = f
                .title
                .clone()
                .filter(|t| !t.trim().is_empty())
                .unwrap_or_else(|| private_feed_label(&f.feed_url));
            skipped_private.push(label);
            continue;
        }

        // Over-cap: stop importing once headroom is exhausted (count the rest so
        // we can tell the user how many were dropped).
        if let Some(h) = headroom.as_mut() {
            if *h <= 0 {
                trimmed_over_cap += 1;
                continue;
            }
        }

        // Global ceiling: a brand-new feed URL consumes global headroom. Once
        // it's exhausted, refuse to cache further NEW feeds (existing URLs are
        // free — they add no row). Checked before decrementing the per-DID
        // headroom so a dropped feed doesn't burn the caller's own quota.
        let is_new = match store::get_feed_by_url(pool, &f.feed_url).await {
            Ok(existing) => existing.is_none(),
            // On a lookup error, treat as existing (don't consume global
            // headroom) but still allow the upsert to proceed.
            Err(err) => {
                warn!(%err, feed = %f.feed_url, "get_feed_by_url failed during OPML global-cap check");
                false
            }
        };
        if is_new {
            if let Some(g) = global_headroom.as_mut() {
                if *g <= 0 {
                    trimmed_over_global += 1;
                    continue;
                }
                *g -= 1;
            }
        }

        // Passed both caps: consume the per-DID headroom now that the feed is
        // actually being imported.
        if let Some(h) = headroom.as_mut() {
            *h -= 1;
        }

        let mut sub = Subscription::new(f.feed_url.clone(), now.clone());
        sub.title = f.title.clone();
        sub.site_url = f.site_url.clone();
        sub.folder = f
            .folder
            .as_ref()
            .and_then(|name| folder_uris.get(name).cloned());
        subs.push(sub);
        // Same support ticket as the single-add path: no `feeds` row means the
        // poller never selects this subscription, so the import looks like it
        // worked and the feed silently never updates. Counted as well as logged,
        // because one line per feed in a 200-feed import is not something anyone
        // reads — the count goes to the reader.
        if let Err(err) = store::upsert_feed(
            pool,
            &store::NewFeed {
                url: f.feed_url.clone(),
                title: f.title.clone(),
                site_url: f.site_url.clone(),
                ..Default::default()
            },
        )
        .await
        {
            warn!(%err, %did, url = %f.feed_url, "OPML import could not cache a feed; \
                                                  it will not be polled");
            uncached += 1;
        }
    }

    // **A failed PDS write is not an import.**
    //
    // The subscriptions live in the reader's repo; a local `feeds` row is just a
    // poller hint. This used to `warn!` and then report "Imported N feeds"
    // regardless, so a total failure read as a total success — and the reader
    // would only discover otherwise on their next visit, with an empty sidebar.
    //
    // **And a part-landed write is not a failed one.** The batch goes out in
    // calls of at most 200 (#240: the reference PDS refuses more), sent in
    // order and stopped at the first failure, so what landed is a prefix of
    // `subs` and the error says how long. Saying "nothing was imported" after
    // the first 200 of 450 landed would send the reader to import the file
    // again, which adds those 200 a second time. Nothing local needs undoing
    // either way: the reader's `sub_ref` projection is rebuilt from the repo on
    // the next read, and a cached `feeds` row with no subscriber is the same
    // poller hint the total-failure path has always left behind.
    let landed = match state.repo().add_subscriptions_bulk(&did, &subs).await {
        Ok(rkeys) => {
            info!(%did, count = rkeys.len(), skipped = skipped_private.len(), "imported OPML subscriptions to PDS (batched)");
            rkeys.len()
        }
        Err(err) => {
            let landed = crate::atproto::ApplyWritesIncomplete::of(&err).map_or(0, |p| p.landed);
            warn!(%err, %did, landed, total = subs.len(), "OPML PDS batch write failed (feeds cached locally)");
            landed
        }
    };
    if landed == 0 && !subs.is_empty() {
        return Ok(Redirect::to(&format!(
            "/?flash={}",
            qenc(
                "Could not save those subscriptions to your PDS, so nothing was imported. \
                 Try again in a moment."
            )
        ))
        .into_response());
    }

    // Report the import count, plus any private/paid feeds skipped as unsupported.
    let mut flash = if landed < subs.len() {
        format!(
            "Imported {landed} of {} feeds: your PDS stopped accepting them part-way, so the \
             other {} may not have been saved. Importing the same file again would add the first \
             {landed} a second time",
            subs.len(),
            subs.len() - landed
        )
    } else {
        format!("Imported {} feeds", subs.len())
    };
    if uncached > 0 {
        flash.push_str(&format!(
            ". {uncached} of them could not be cached locally and may not update until the next import."
        ));
    }
    if trimmed_over_cap > 0 {
        flash.push_str(&format!(
            ". {trimmed_over_cap} feed(s) not imported: your subscription limit ({sub_cap}) was reached."
        ));
    }
    if trimmed_over_global > 0 {
        flash.push_str(&format!(
            ". {trimmed_over_global} feed(s) not imported: this instance is at its feed capacity right now."
        ));
    }
    if !skipped_private.is_empty() {
        flash.push_str(&format!(
            ". {} feed(s) skipped as private/paid: {} — not supported yet (public feeds only for now).",
            skipped_private.len(),
            skipped_private.join(", ")
        ));
    }
    if skipped_unsupported > 0 {
        // By count only — the URL is whatever the file said, and unlike the
        // private branch there is no public-safe label to give.
        flash.push_str(&format!(
            ". {skipped_unsupported} feed(s) skipped: not a kind of feed this instance can subscribe to."
        ));
    }
    Ok(Redirect::to(&format!("/?flash={}", qenc(&flash))).into_response())
}

/// A public-safe label for a skipped private feed when it has no title: just the
/// host, so we never echo the secret-bearing path/query back to the user.
fn private_feed_label(url: &str) -> String {
    url::Url::parse(url)
        .ok()
        .and_then(|u| u.host_str().map(str::to_string))
        .unwrap_or_else(|| "a private feed".to_string())
}

/// `GET /opml/export` — export the user's subscriptions + folders as OPML.
async fn export_opml(
    State(state): State<AppState>,
    headers: HeaderMap,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };

    // **An export must never be silently empty.** `unwrap_or_default` here turned
    // a failed read into a 200 carrying a zero-feed OPML file — the reader's
    // backup, blank, at exactly the moment they reached for it. That was survivable
    // while a truncated walk returned `Ok`; now that the walk refuses a short list,
    // this is the one caller that converts a refusal into data loss, and it is also
    // the recovery route the changelog points a locked-out reader at.
    let subs = match state.repo().list_subscriptions_sorted(&did).await {
        Ok(subs) => subs,
        Err(err) => {
            tracing::warn!(%err, did = %did, "refusing to export an OPML we could not read in full");
            return Ok(Redirect::to(&format!(
                "/manage?flash={}",
                qenc(EXPORT_INCOMPLETE_REFUSAL)
            ))
            .into_response());
        }
    };
    let folders = match state.repo().list_folders_sorted(&did).await {
        Ok(folders) => folders,
        Err(err) => {
            tracing::warn!(%err, did = %did, "refusing to export an OPML without its folders");
            return Ok(Redirect::to(&format!(
                "/manage?flash={}",
                qenc(EXPORT_INCOMPLETE_REFUSAL)
            ))
            .into_response());
        }
    };
    // The exporter matches a subscription's `folder` at-uri against the folder's
    // pair key; our folder pairs are keyed by rkey, so rebuild them as at-uris.
    let folder_pairs: Vec<(String, Folder)> = folders
        .into_iter()
        .map(|(rkey, f)| (folder_uri(&did, &rkey), f))
        .collect();

    let body = opml::to_opml(&subs, &folder_pairs);
    let mut resp = (StatusCode::OK, body).into_response();
    resp.headers_mut().insert(
        header::CONTENT_TYPE,
        "text/x-opml; charset=utf-8".parse().unwrap(),
    );
    resp.headers_mut().insert(
        header::CONTENT_DISPOSITION,
        "attachment; filename=\"featherreader-subscriptions.opml\""
            .parse()
            .unwrap(),
    );
    Ok(resp)
}

// ---------------------------------------------------------------------------
// Signed session cookie (HMAC-SHA256, dependency-free)
// ---------------------------------------------------------------------------

/// Set a `Set-Cookie` header on a response (append, so logout+redirect compose).
fn set_cookie(resp: &mut Response, cookie: &str) {
    if let Ok(value) = axum::http::HeaderValue::from_str(cookie) {
        resp.headers_mut()
            .append(axum::http::header::SET_COOKIE, value);
    }
}

/// Whether the request came from htmx (the `HX-Request` header).
fn is_htmx(headers: &HeaderMap) -> bool {
    headers
        .get("HX-Request")
        .is_some_and(|v| v.as_bytes().eq_ignore_ascii_case(b"true"))
}

/// Whether a mark-read / star request originated from the single-entry READER
/// (as opposed to the list view). The reader's forms tag themselves with
/// `X-FR-Reader: 1` via `hx-headers`; the list view's do not. This selects the
/// swap fragment: the reader gets an out-of-band action-bar update (its `<li>`
/// isn't in the DOM), the list gets the row (`entry_row.html`).
fn is_reader_request(headers: &HeaderMap) -> bool {
    headers
        .get("X-FR-Reader")
        .is_some_and(|v| v.as_bytes() == b"1")
}

/// A tiny, self-contained signed-cookie layer: HMAC-SHA256 over an opaque,
/// server-minted **session id** (never the DID — so the cookie can't be forged
/// from a resolved victim DID; forging it needs the HMAC secret *and* a live
/// server-side session id).
mod cookie {
    use super::{HeaderMap, SESSION_COOKIE};

    /// Sign a session id into a `Set-Cookie` header value: `fr_session=<sid>.<sig>`.
    pub fn sign_session(sid: &str, secret: &str) -> String {
        sign_value(SESSION_COOKIE, sid, secret, 2_592_000)
    }

    /// Verify the request's session cookie and return the session id it carries.
    pub fn verify_session(headers: &HeaderMap, secret: &str) -> Option<String> {
        verify_value(headers, SESSION_COOKIE, secret)
    }

    /// The HMAC message binding the cookie NAME to its value (`name || 0x00 ||
    /// value`), so a signature minted for one cookie can't verify under another —
    /// e.g. a value validly signed as `fr_invite` is not accepted as `fr_session`.
    /// The NUL separator can't appear in a cookie name, so the encoding is
    /// unambiguous.
    fn cookie_hmac_msg(name: &str, value: &str) -> Vec<u8> {
        let mut msg = Vec::with_capacity(name.len() + 1 + value.len());
        msg.extend_from_slice(name.as_bytes());
        msg.push(0);
        msg.extend_from_slice(value.as_bytes());
        msg
    }

    /// Sign an arbitrary string `value` into a `Set-Cookie` header for `name`,
    /// HMAC-SHA256 over `name || 0x00 || value`: `name=<b64url(value)>.<sig>`. The
    /// generic form behind both the session cookie and the short-lived invite
    /// cookie; domain-separating by name keeps a signature valid only for the
    /// cookie it was minted for.
    pub fn sign_value(name: &str, value: &str, secret: &str, max_age_secs: i64) -> String {
        let sig = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(name, value));
        let b64 = b64url_encode(value.as_bytes());
        format!(
            "{name}={b64}.{sig}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age={max_age_secs}"
        )
    }

    /// Verify + read a value out of the named signed cookie (`None` on absent /
    /// tampered / forged / cross-cookie). The generic form behind both readers.
    pub fn verify_value(headers: &HeaderMap, name: &str, secret: &str) -> Option<String> {
        let raw = cookie_value(headers, name)?;
        let (b64, sig) = raw.split_once('.')?;
        let bytes = b64url_decode(b64)?;
        let value = String::from_utf8(bytes).ok()?;
        let expected = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(name, &value));
        if constant_time_eq(expected.as_bytes(), sig.as_bytes()) {
            Some(value)
        } else {
            None
        }
    }

    /// Sign an arbitrary `value` into an opaque, URL-safe token string
    /// `b64url(value).<sig>` (HMAC-SHA256 over `label || 0x00 || value`). Unlike
    /// [`sign_value`] this is NOT a `Set-Cookie` header — it's a bare token for a
    /// URL query param (the bot's claim link). `label` domain-separates it from
    /// the cookies so a token can't be replayed as a cookie value.
    pub fn sign_token(label: &str, value: &str, secret: &str) -> String {
        let sig = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(label, value));
        let b64 = b64url_encode(value.as_bytes());
        format!("{b64}.{sig}")
    }

    /// Verify a token minted by [`sign_token`] and return the wrapped value
    /// (`None` on tamper / forge / malformed). Constant-time signature compare.
    pub fn verify_token(label: &str, token: &str, secret: &str) -> Option<String> {
        let (b64, sig) = token.split_once('.')?;
        let bytes = b64url_decode(b64)?;
        let value = String::from_utf8(bytes).ok()?;
        let expected = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(label, &value));
        if constant_time_eq(expected.as_bytes(), sig.as_bytes()) {
            Some(value)
        } else {
            None
        }
    }

    /// Pull one cookie value out of the `Cookie` request header.
    fn cookie_value(headers: &HeaderMap, name: &str) -> Option<String> {
        let header = headers.get(axum::http::header::COOKIE)?.to_str().ok()?;
        for part in header.split(';') {
            let part = part.trim();
            if let Some((k, v)) = part.split_once('=') {
                if k == name {
                    return Some(v.to_string());
                }
            }
        }
        None
    }

    /// Constant-time byte comparison (avoid signature-timing leaks). Public
    /// within the module so the bot-secret bearer check reuses the exact same
    /// comparator as the cookie/token HMAC checks (one implementation to audit).
    pub fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
        if a.len() != b.len() {
            return false;
        }
        let mut diff = 0u8;
        for (x, y) in a.iter().zip(b.iter()) {
            diff |= x ^ y;
        }
        diff == 0
    }

    // -- URL-safe base64 (no padding), std-only --------------------------------

    const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

    fn b64url_encode(input: &[u8]) -> String {
        let mut out = String::with_capacity(input.len().div_ceil(3) * 4);
        for chunk in input.chunks(3) {
            let b = [
                chunk[0],
                *chunk.get(1).unwrap_or(&0),
                *chunk.get(2).unwrap_or(&0),
            ];
            let n = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | (b[2] as u32);
            out.push(B64[((n >> 18) & 63) as usize] as char);
            out.push(B64[((n >> 12) & 63) as usize] as char);
            if chunk.len() > 1 {
                out.push(B64[((n >> 6) & 63) as usize] as char);
            }
            if chunk.len() > 2 {
                out.push(B64[(n & 63) as usize] as char);
            }
        }
        out
    }

    fn b64url_decode(input: &str) -> Option<Vec<u8>> {
        fn val(c: u8) -> Option<u32> {
            match c {
                b'A'..=b'Z' => Some((c - b'A') as u32),
                b'a'..=b'z' => Some((c - b'a' + 26) as u32),
                b'0'..=b'9' => Some((c - b'0' + 52) as u32),
                b'-' => Some(62),
                b'_' => Some(63),
                _ => None,
            }
        }
        let bytes = input.as_bytes();
        let mut out = Vec::with_capacity(input.len() / 4 * 3 + 2);
        for chunk in bytes.chunks(4) {
            let mut n = 0u32;
            let mut valid = 0;
            for (i, &c) in chunk.iter().enumerate() {
                n |= val(c)? << (18 - 6 * i);
                valid += 1;
            }
            out.push((n >> 16) as u8);
            if valid > 2 {
                out.push((n >> 8) as u8);
            }
            if valid > 3 {
                out.push(n as u8);
            }
        }
        Some(out)
    }

    // -- HMAC-SHA256, std-only -------------------------------------------------

    /// HMAC-SHA256(key, msg) as lowercase hex.
    fn hmac_sha256_hex(key: &[u8], msg: &[u8]) -> String {
        const BLOCK: usize = 64;
        let mut k = [0u8; BLOCK];
        if key.len() > BLOCK {
            let d = sha256(key);
            k[..32].copy_from_slice(&d);
        } else {
            k[..key.len()].copy_from_slice(key);
        }
        let mut ipad = [0x36u8; BLOCK];
        let mut opad = [0x5cu8; BLOCK];
        for i in 0..BLOCK {
            ipad[i] ^= k[i];
            opad[i] ^= k[i];
        }
        let mut inner = Vec::with_capacity(BLOCK + msg.len());
        inner.extend_from_slice(&ipad);
        inner.extend_from_slice(msg);
        let inner_hash = sha256(&inner);
        let mut outer = Vec::with_capacity(BLOCK + 32);
        outer.extend_from_slice(&opad);
        outer.extend_from_slice(&inner_hash);
        let mac = sha256(&outer);
        let mut hex = String::with_capacity(64);
        for b in mac {
            hex.push_str(&format!("{b:02x}"));
        }
        hex
    }

    /// SHA-256 (FIPS 180-4), std-only.
    fn sha256(data: &[u8]) -> [u8; 32] {
        const K: [u32; 64] = [
            0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
            0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
            0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
            0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
            0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
            0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
            0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
            0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
            0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
            0xc67178f2,
        ];
        let mut h: [u32; 8] = [
            0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
            0x5be0cd19,
        ];

        let bit_len = (data.len() as u64) * 8;
        let mut msg = data.to_vec();
        msg.push(0x80);
        while msg.len() % 64 != 56 {
            msg.push(0);
        }
        msg.extend_from_slice(&bit_len.to_be_bytes());

        for block in msg.chunks(64) {
            let mut w = [0u32; 64];
            for i in 0..16 {
                w[i] = u32::from_be_bytes([
                    block[i * 4],
                    block[i * 4 + 1],
                    block[i * 4 + 2],
                    block[i * 4 + 3],
                ]);
            }
            for i in 16..64 {
                let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
                let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
                w[i] = w[i - 16]
                    .wrapping_add(s0)
                    .wrapping_add(w[i - 7])
                    .wrapping_add(s1);
            }
            let mut a = h;
            for i in 0..64 {
                let s1 = a[4].rotate_right(6) ^ a[4].rotate_right(11) ^ a[4].rotate_right(25);
                let ch = (a[4] & a[5]) ^ ((!a[4]) & a[6]);
                let t1 = a[7]
                    .wrapping_add(s1)
                    .wrapping_add(ch)
                    .wrapping_add(K[i])
                    .wrapping_add(w[i]);
                let s0 = a[0].rotate_right(2) ^ a[0].rotate_right(13) ^ a[0].rotate_right(22);
                let maj = (a[0] & a[1]) ^ (a[0] & a[2]) ^ (a[1] & a[2]);
                let t2 = s0.wrapping_add(maj);
                a[7] = a[6];
                a[6] = a[5];
                a[5] = a[4];
                a[4] = a[3].wrapping_add(t1);
                a[3] = a[2];
                a[2] = a[1];
                a[1] = a[0];
                a[0] = t1.wrapping_add(t2);
            }
            for i in 0..8 {
                h[i] = h[i].wrapping_add(a[i]);
            }
        }

        let mut out = [0u8; 32];
        for (i, word) in h.iter().enumerate() {
            out[i * 4..i * 4 + 4].copy_from_slice(&word.to_be_bytes());
        }
        out
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        #[test]
        fn sha256_known_vector() {
            let d = sha256(b"abc");
            let hex: String = d.iter().map(|b| format!("{b:02x}")).collect();
            assert_eq!(
                hex,
                "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
            );
        }

        #[test]
        fn hmac_known_vector() {
            let mac = hmac_sha256_hex(b"Jefe", b"what do ya want for nothing?");
            assert_eq!(
                mac,
                "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
            );
        }

        #[test]
        fn sign_verify_round_trips() {
            let secret = "test-secret";
            let sid = "9f2c-opaque-session-id";
            let cookie = sign_session(sid, secret);
            let pair = cookie.split(';').next().unwrap().to_string();
            let mut headers = HeaderMap::new();
            headers.insert(axum::http::header::COOKIE, pair.parse().unwrap());
            assert_eq!(verify_session(&headers, secret).as_deref(), Some(sid));
            // Wrong secret → rejected (an attacker without the HMAC key can't forge).
            assert!(verify_session(&headers, "other-secret").is_none());
        }

        #[test]
        fn forged_and_tampered_cookies_are_rejected() {
            let secret = "test-secret";

            // 1. A fully forged cookie: attacker knows a victim's DID/sid but not
            //    the secret, so an arbitrary signature must not verify.
            let forged = format!(
                "{SESSION_COOKIE}={}.{}",
                b64url_encode(b"attacker-chosen-sid"),
                "deadbeef".repeat(8) // 64 hex chars, wrong sig
            );
            let mut headers = HeaderMap::new();
            headers.insert(axum::http::header::COOKIE, forged.parse().unwrap());
            assert!(verify_session(&headers, secret).is_none());

            // 2. A tampered cookie: take a VALID cookie and mutate the sid while
            //    keeping the original signature — must not verify.
            let cookie = sign_session("real-sid", secret);
            let pair = cookie.split(';').next().unwrap();
            let (_b64, sig) = pair.split_once('=').unwrap().1.split_once('.').unwrap();
            let tampered = format!(
                "{SESSION_COOKIE}={}.{}",
                b64url_encode(b"different-sid"),
                sig
            );
            let mut headers2 = HeaderMap::new();
            headers2.insert(axum::http::header::COOKIE, tampered.parse().unwrap());
            assert!(verify_session(&headers2, secret).is_none());
        }

        #[test]
        fn b64url_round_trips() {
            for s in ["did:plc:abc", "", "a", "ab", "abc", "abcd"] {
                let enc = b64url_encode(s.as_bytes());
                assert_eq!(b64url_decode(&enc).unwrap(), s.as_bytes());
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Small store helpers local to the web layer
// ---------------------------------------------------------------------------

/// Fetch a single cached entry by id — SCOPED to `did`'s subscriptions.
///
/// Returns `None` (→ 404 at the handler) if the entry does not exist OR if
/// `did` does not subscribe to its feed. This is the per-DID read gate for the
/// `GET /entries/:id` reader and the htmx row rebuild: the shared cache is
/// deduped by URL, but no DID can read another DID's cached article.
///
/// **The only `SELECT e.*` left, and deliberately so.** This is the one surface
/// that renders `content_html`, and it fetches exactly one row. The list views
/// go through [`store::list_entries`], which is both paged and body-free — see
/// [`store::EntryListRow`] for why they had to stop sharing this projection.
async fn get_entry_by_id(
    pool: &store::Pool,
    did: &str,
    id: i64,
) -> anyhow::Result<Option<store::Entry>> {
    let entry = sqlx::query_as::<_, store::Entry>(
        r#"
        SELECT e.* FROM entries e
        WHERE e.id = ?2
          AND EXISTS (
              SELECT 1 FROM sub_ref sr
              WHERE sr.did = ?1 AND sr.feed_id = e.feed_id
          )
        "#,
    )
    .bind(did)
    .bind(id)
    .fetch_optional(pool)
    .await?;
    Ok(entry)
}

/// Whether `entry_id` is marked read for `did` (absent state row = unread).
async fn entry_is_read(pool: &store::Pool, did: &str, entry_id: i64) -> anyhow::Result<bool> {
    let read: Option<bool> =
        sqlx::query_scalar("SELECT read FROM entry_state WHERE did = ?1 AND entry_id = ?2")
            .bind(did)
            .bind(entry_id)
            .fetch_optional(pool)
            .await?
            .flatten();
    Ok(read.unwrap_or(false))
}

/// Whether `entry_id` is starred for `did` (absent state row = not starred).
async fn entry_is_starred(pool: &store::Pool, did: &str, entry_id: i64) -> anyhow::Result<bool> {
    let starred: Option<bool> =
        sqlx::query_scalar("SELECT starred FROM entry_state WHERE did = ?1 AND entry_id = ?2")
            .bind(did)
            .bind(entry_id)
            .fetch_optional(pool)
            .await?
            .flatten();
    Ok(starred.unwrap_or(false))
}

/// Feed display title for one entry's feed id (via a single lookup).
async fn feed_title_by_entry(pool: &store::Pool, feed_id: i64) -> String {
    match sqlx::query_as::<_, store::Feed>("SELECT * FROM feeds WHERE id = ?1")
        .bind(feed_id)
        .fetch_optional(pool)
        .await
    {
        Ok(Some(f)) => display_title(f.title.as_deref(), &f.url),
        _ => String::new(),
    }
}

/// Rebuild an [`EntryRow`] for an htmx swap after a read/star toggle. `read` may
/// be forced (mark-read path) or looked up (`None` — star path).
async fn build_entry_row(
    pool: &store::Pool,
    did: &str,
    id: i64,
    read: Option<bool>,
) -> anyhow::Result<Option<EntryRow>> {
    let entry = match get_entry_by_id(pool, did, id).await? {
        Some(e) => e,
        None => return Ok(None),
    };
    let read = match read {
        Some(r) => r,
        None => entry_is_read(pool, did, id).await?,
    };
    let starred = entry_is_starred(pool, did, id).await?;
    Ok(Some(EntryRow {
        id: entry.id,
        title: entry
            .title
            .clone()
            .filter(|t| !t.trim().is_empty())
            .unwrap_or_else(|| "(untitled)".to_string()),
        feed_title: feed_title_by_entry(pool, entry.feed_id).await,
        published: display_date(entry.published.as_deref()),
        read,
        starred,
        link: SafeLink::entry(id, ""),
        cached: true,
        rkey: String::new(),
    }))
}

/// RFC3339 "now" (UTC) — shared by handlers that stamp/compare timestamps.
fn now_rfc3339() -> String {
    chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn qenc_encodes_reserved() {
        assert_eq!(qenc("a b"), "a%20b");
        assert_eq!(
            qenc("https://example.com/feed.xml"),
            "https%3A%2F%2Fexample.com%2Ffeed.xml"
        );
        assert_eq!(
            qenc("at://did:plc:x/c/r"),
            "at%3A%2F%2Fdid%3Aplc%3Ax%2Fc%2Fr"
        );
        // Unreserved chars pass through untouched.
        assert_eq!(qenc("A-Za-z0-9-_.~"), "A-Za-z0-9-_.~");
    }

    #[test]
    fn folder_uri_shape() {
        assert_eq!(
            folder_uri("did:plc:abc", "3kfolder"),
            "at://did:plc:abc/community.lexicon.rss.folder/3kfolder"
        );
    }

    // -- public-feeds-only: private/paid feeds are refused --------------------

    #[test]
    fn private_feeds_are_classified_private_across_providers() {
        // The add + OPML paths both gate on this classifier; assert it flags a
        // spread of paid providers (newsletters + private podcasts) and the
        // generic credential-in-URL shapes.
        for url in [
            "https://author.substack.com/feed/private/deadbeefcafe1234",
            "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4",
            "https://blog.ghost.io/rss/?uuid=1f2e3d4c-5b6a-7089-90ab-cdef01234567",
            "https://feeds.supportingcast.fm/show/abcdef0123456789abcdef01",
            "https://example.com/feed?token=Zm9vYmFyc2VjcmV0",
            "https://user:pass@example.com/feed",
        ] {
            assert!(
                feed::classify_feed_privacy(url).is_private(),
                "expected private: {url}"
            );
        }
    }

    #[test]
    fn public_feeds_stay_public() {
        for url in [
            "https://author.substack.com/feed",
            "https://wordpress.example.com/feed/",
            "https://example.com/rss.xml",
            "https://example.org/atom.xml",
            // YouTube channel/playlist RSS is fully public — must not false-block.
            "https://www.youtube.com/feeds/videos.xml?channel_id=UC-lHJZR3Gqxm24_Vd_AJ5Yw",
            "https://www.youtube.com/feeds/videos.xml?playlist_id=PLFgquLnL59alCl_2TQvOiD5Vgm1",
        ] {
            assert!(
                !feed::classify_feed_privacy(url).is_private(),
                "expected public: {url}"
            );
        }
    }

    #[test]
    fn private_feed_label_is_public_safe_host_only() {
        // The OPML skip report must never echo the secret path/query, only the host.
        let label =
            private_feed_label("https://author.substack.com/feed/private/deadbeefcafe1234token");
        assert_eq!(label, "author.substack.com");
        assert!(!label.contains("deadbeefcafe1234token"));
        assert!(!label.contains("/private/"));
        // An unparseable URL degrades to a generic label.
        assert_eq!(private_feed_label("not a url"), "a private feed");
    }

    #[test]
    fn refusal_message_promises_nothing_stored() {
        assert!(PRIVATE_FEED_REFUSAL.contains("not saved or sent anywhere"));
        assert!(PRIVATE_FEED_REFUSAL.contains("public feeds"));
    }

    #[test]
    fn scope_query_preserves_context() {
        let q = EntryQuery {
            feed: Some("https://example.com/feed.xml".to_string()),
            folder: None,
            view: Some("all".to_string()),
        };
        let s = scope_query(&q);
        assert!(s.contains("feed=https%3A%2F%2Fexample.com%2Ffeed.xml"));
        assert!(s.contains("view=all"));

        // Default view is omitted.
        let q2 = EntryQuery {
            feed: None,
            folder: None,
            view: Some("unread".to_string()),
        };
        assert_eq!(scope_query(&q2), "");
    }

    // -- closed-beta invite gate + rate-limit + cache-control ------------------

    use axum::body::Body;
    use axum::http::Request;
    use tower::ServiceExt; // for `oneshot`

    /// Build an [`AppState`] over a fresh in-memory DB, seeding the given admin
    /// DIDs (via ALLOWED_DIDS → ensure_seed) and a fixed cookie secret so tests
    /// can forge matching cookies.
    async fn test_state(allowed: &[&str]) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let dids: Vec<String> = allowed.iter().map(|s| s.to_string()).collect();
        store::ensure_seed(&db, &dids).await.unwrap();
        let config = Config {
            allowed_dids: dids,
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    /// A `Cookie` header carrying a valid signed session for `sid` (the sid is
    /// looked up in the registry, so create the session first).
    fn session_cookie(state: &AppState, did: &str, handle: Option<&str>) -> String {
        let sid = state.sessions.create(Session {
            did: did.to_string(),
            handle: handle.map(str::to_string),
        });
        let sc = cookie::sign_session(&sid, &state.config.cookie_secret);
        sc.split(';').next().unwrap().to_string()
    }

    /// The bucket map is bounded by COUNT, not only by idle time. An hour is a
    /// long time to accept distinct source IPs on two unauthenticated guarded
    /// routes.
    #[test]
    fn the_rate_limit_map_is_bounded() {
        let rl = RateLimiter::shared();
        let now = Instant::now();
        for i in 0..(MAX_RATE_BUCKETS + 2_000) {
            // Distinct IPv6 addresses, all "seen" at increasing times so the LRU
            // ordering below is well-defined.
            let ip: IpAddr = format!("2001:db8::{i:x}").parse().unwrap();
            rl.check_at(ip, now + Duration::from_millis(i as u64));
        }
        let len = rl.inner.lock().unwrap().buckets.len();
        assert!(
            len <= MAX_RATE_BUCKETS,
            "the rate-limit map grew to {len}, past its {MAX_RATE_BUCKETS} cap"
        );
    }

    /// Eviction must not hand a throttled attacker a fresh burst.
    ///
    /// The bound is LRU, so the one bucket an attacker can never evict is their
    /// own — it is the most recently touched thing in the map. If this inverted,
    /// the size cap would become a rate-limit bypass: spray addresses until the
    /// map overflows, then resume.
    #[test]
    fn flooding_the_map_does_not_reset_the_flooders_own_bucket() {
        let rl = RateLimiter::shared();
        let base = Instant::now();
        let attacker: IpAddr = "203.0.113.7".parse().unwrap();
        // Nanosecond steps: enough to keep the LRU ordering strictly increasing,
        // far too little for `RATE_REFILL_PER_SEC` to hand back a token. A
        // millisecond step made the whole flood take a second, and the refill —
        // working correctly — then looked exactly like an eviction bypass.
        let at = |n: u64| base + Duration::from_nanos(n);

        // Spend the burst. `RATE_BURST` allowed, then refused.
        for i in 0..(RATE_BURST as u64) {
            assert!(rl.check_at(attacker, at(i)));
        }
        assert!(
            !rl.check_at(attacker, at(RATE_BURST as u64)),
            "burst was not exhausted; the rest of this test proves nothing"
        );

        // Now overflow the map from other addresses, interleaving the attacker
        // so their bucket stays hot — the realistic shape of the attack.
        for i in 0..(MAX_RATE_BUCKETS + 2_000) {
            let t = at(100 + i as u64 * 2);
            let ip: IpAddr = format!("2001:db8:1::{i:x}").parse().unwrap();
            rl.check_at(ip, t);
            assert!(
                !rl.check_at(attacker, t),
                "the attacker got a token back after evictions at i={i}"
            );
        }
    }

    /// The idle sweep is amortised, not per-request. It used to be an O(n) scan
    /// of the whole map on every guarded request, on one shared core.
    #[test]
    fn the_idle_sweep_does_not_run_on_every_request() {
        let rl = RateLimiter::shared();
        let start = Instant::now();
        let a: IpAddr = "198.51.100.1".parse().unwrap();
        let b: IpAddr = "198.51.100.2".parse().unwrap();

        rl.check_at(a, start);
        // `b` arrives an hour later: `a` is now idle past `RATE_IDLE_EVICT`, but
        // the sweep interval has elapsed too, so this request does sweep it.
        rl.check_at(b, start + RATE_IDLE_EVICT + Duration::from_secs(1));
        assert!(
            !rl.inner.lock().unwrap().buckets.contains_key(&a),
            "an idle bucket survived a sweep that was due"
        );

        // A second request moments later must NOT re-sweep — `b` is still there,
        // and the recorded sweep time must not have moved.
        let before = rl.inner.lock().unwrap().last_sweep;
        rl.check_at(b, start + RATE_IDLE_EVICT + Duration::from_secs(2));
        assert_eq!(
            rl.inner.lock().unwrap().last_sweep,
            before,
            "the sweep ran again within the interval"
        );
    }

    #[test]
    fn rate_limited_paths_match_expected() {
        use axum::http::Method;
        assert!(is_rate_limited_path("/login", &Method::GET));
        assert!(is_rate_limited_path("/login", &Method::POST));
        assert!(is_rate_limited_path("/beta/redeem", &Method::POST));
        assert!(is_rate_limited_path("/subscriptions", &Method::POST));
        assert!(is_rate_limited_path("/opml", &Method::POST));
        assert!(is_rate_limited_path("/read-all", &Method::POST));
        assert!(is_rate_limited_path("/admin/invites", &Method::POST));
        assert!(is_rate_limited_path("/entries/42/read", &Method::POST));
        assert!(is_rate_limited_path("/entries/42/star", &Method::POST));
        // Read-only navigation is NOT limited.
        assert!(!is_rate_limited_path("/", &Method::GET));
        assert!(!is_rate_limited_path("/about", &Method::GET));
        assert!(!is_rate_limited_path("/entries/42", &Method::GET));
        assert!(!is_rate_limited_path("/login", &Method::HEAD));
    }

    #[test]
    fn rate_limiter_allows_burst_then_429s() {
        let rl = RateLimiter::shared();
        let ip: IpAddr = "203.0.113.7".parse().unwrap();
        // The full burst passes.
        for _ in 0..(RATE_BURST as usize) {
            assert!(rl.check(ip));
        }
        // The next one (no time elapsed → no refill) is rejected.
        assert!(!rl.check(ip));
        // A different IP has its own bucket.
        let ip2: IpAddr = "203.0.113.8".parse().unwrap();
        assert!(rl.check(ip2));
    }

    #[test]
    fn client_ip_ignores_spoofed_xff_without_trusted_header() {
        // With NO trusted header configured, a client-supplied X-Forwarded-For
        // must be ignored entirely — the limiter keys on the real socket peer,
        // so an attacker can't mint a fresh bucket per forged XFF value.
        let mut h = HeaderMap::new();
        h.insert("x-forwarded-for", "198.51.100.9, 10.0.0.1".parse().unwrap());
        let sock: SocketAddr = "203.0.113.55:1234".parse().unwrap();
        assert_eq!(
            client_ip(&h, Some(&sock), None),
            Some("203.0.113.55".parse().unwrap()),
            "spoofed XFF must not override the socket peer"
        );
    }

    #[test]
    fn client_ip_uses_trusted_header_last_hop() {
        // With a trusted proxy header configured, the client IP comes from THAT
        // header (the proxy overwrites any client copy). On a comma list we take
        // the RIGHT-most hop — the one the trusted proxy appended — so a
        // client-forged left-most value is ignored.
        let sock: SocketAddr = "10.0.0.1:1234".parse().unwrap();

        let mut h = HeaderMap::new();
        h.insert("fly-client-ip", "198.51.100.9".parse().unwrap());
        assert_eq!(
            client_ip(&h, Some(&sock), Some("fly-client-ip")),
            Some("198.51.100.9".parse().unwrap())
        );

        // Attacker prepends a forged hop; the trusted proxy appends the real one.
        let mut h2 = HeaderMap::new();
        h2.insert("x-forwarded-for", "1.2.3.4, 198.51.100.9".parse().unwrap());
        assert_eq!(
            client_ip(&h2, Some(&sock), Some("x-forwarded-for")),
            Some("198.51.100.9".parse().unwrap()),
            "must take the right-most (trusted) hop, not the forged left-most"
        );

        // Trusted header absent → fall back to the socket peer.
        let h3 = HeaderMap::new();
        assert_eq!(
            client_ip(&h3, Some(&sock), Some("fly-client-ip")),
            Some("10.0.0.1".parse().unwrap())
        );
    }

    #[test]
    fn invite_cookie_round_trips_and_rejects_tamper() {
        let secret = "test-cookie-secret-000";
        let sc = sign_invite("FEATHER-ABCDWXYZ", secret);
        let pair = sc.split(';').next().unwrap();
        let mut h = HeaderMap::new();
        h.insert(header::COOKIE, pair.parse().unwrap());
        assert_eq!(
            invite_cookie_code(&h, secret).as_deref(),
            Some("FEATHER-ABCDWXYZ")
        );
        // Wrong secret → rejected.
        assert!(invite_cookie_code(&h, "other").is_none());
    }

    #[tokio::test]
    async fn preflight_valid_expired_and_full() {
        let state = test_state(&["did:plc:admin"]).await;
        // A minted, active code preflights OK.
        let code = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        assert!(preflight_code(&state, &code).await.is_ok());

        // A code whose expiry is in the past preflights as Expired. (mint_code
        // clamps negative ttl to 0, so back-date the row directly for a
        // deterministic past expiry.)
        let expired = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        sqlx::query("UPDATE invite_codes SET expires_at = ?1 WHERE code = ?2")
            .bind(chrono::Utc::now().timestamp() - 3600)
            .bind(&expired)
            .execute(&state.db)
            .await
            .unwrap();
        assert_eq!(
            preflight_code(&state, &expired).await,
            Err(store::RedeemError::Expired)
        );

        // Unknown code → NotFound.
        assert_eq!(
            preflight_code(&state, "FEATHER-NOPENOPE").await,
            Err(store::RedeemError::NotFound)
        );

        // Fill to cap (cap=3; the admin seed already took 1 seat) then preflight
        // must report CapacityFull.
        store::grant_access(&state.db, "did:plc:b", None, "admin", None)
            .await
            .unwrap();
        store::grant_access(&state.db, "did:plc:c", None, "admin", None)
            .await
            .unwrap();
        assert_eq!(store::count_beta_access(&state.db).await.unwrap(), 3);
        assert_eq!(
            preflight_code(&state, &code).await,
            Err(store::RedeemError::CapacityFull)
        );
    }

    // -- Bot claim link + shared-secret mint ---------------------------------

    /// A test state with a configured bot secret (so `/bot/claims` is live).
    async fn bot_state(bot_secret: &str) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &["did:plc:admin".to_string()])
            .await
            .unwrap();
        let config = Config {
            allowed_dids: vec!["did:plc:admin".to_string()],
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            bot_secret: Some(bot_secret.to_string()),
            public_url: "https://feather-reader.com".to_string(),
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    #[test]
    fn claim_token_round_trips_and_rejects_tamper() {
        let secret = "test-cookie-secret-000";
        let token = sign_claim_token("FEATHER-ABCDWXYZ", secret);
        // No cookie framing — a bare URL-safe token.
        assert!(!token.contains(';'));
        assert_eq!(
            claim_token_code(&token, secret).as_deref(),
            Some("FEATHER-ABCDWXYZ")
        );
        // Wrong secret → rejected.
        assert!(claim_token_code(&token, "other").is_none());
        // Tampered token → rejected.
        let mut bad = token.clone();
        bad.push('x');
        assert!(claim_token_code(&bad, secret).is_none());
        // The token is NOT confidential: it is `b64url(code).<sig>`, so the code is
        // only base64-obscured (not verbatim, but TRIVIALLY decodable — anyone can
        // recover it WITHOUT the secret). The security is single-use + HMAC
        // integrity + rate-limit, not secrecy of the code. Assert the code half is
        // publicly decodable (a plain base64url decode, no secret involved).
        let (b64, _sig) = token.split_once('.').expect("token is b64.sig");
        assert_eq!(
            test_b64url_decode(b64).as_deref(),
            Some("FEATHER-ABCDWXYZ".as_bytes()),
            "the code half of the token is plain base64url, decodable by anyone"
        );
    }

    /// Minimal URL-safe base64 (no padding) decoder for the test above, proving the
    /// claim token's code half needs NO secret to recover (it is not confidential).
    fn test_b64url_decode(input: &str) -> Option<Vec<u8>> {
        fn val(c: u8) -> Option<u32> {
            match c {
                b'A'..=b'Z' => Some((c - b'A') as u32),
                b'a'..=b'z' => Some((c - b'a' + 26) as u32),
                b'0'..=b'9' => Some((c - b'0' + 52) as u32),
                b'-' => Some(62),
                b'_' => Some(63),
                _ => None,
            }
        }
        let mut out = Vec::with_capacity(input.len() / 4 * 3);
        for chunk in input.as_bytes().chunks(4) {
            let mut n = 0u32;
            let mut bits = 0;
            for &c in chunk {
                n = (n << 6) | val(c)?;
                bits += 6;
            }
            let bytes = bits / 8;
            n <<= 24 - bits;
            for i in 0..bytes {
                out.push((n >> (16 - i * 8)) as u8);
            }
        }
        Some(out)
    }

    #[tokio::test]
    async fn bot_mint_then_claim_grants_a_seat() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        // 1. Mint a claim via the shared-secret endpoint.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let json: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        let token = json["token"].as_str().unwrap().to_string();
        let url = json["url"].as_str().unwrap();
        assert!(url.starts_with("https://feather-reader.com/claim?t="));
        // The raw code is returned for the bot's records but not embedded in url.
        assert!(json["code"].as_str().unwrap().starts_with("FEATHER-"));
        assert!(!url.contains("FEATHER-"));

        // 2. Follow the claim link → reserves the invite cookie + redirects to /login.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/claim?t={}", qenc(&token)))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(resp.headers().get(header::LOCATION).unwrap(), "/login");
        let set_cookie = resp
            .headers()
            .get(header::SET_COOKIE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(set_cookie.starts_with(INVITE_COOKIE), "{set_cookie}");

        // 3. The reserved cookie carries the same code the token wrapped, and
        //    redeeming it (the callback's machinery) grants a seat.
        let code = claim_token_code(&token, &state.config.cookie_secret).unwrap();
        let out = store::redeem_code(
            &state.db,
            &code,
            "did:plc:follower",
            None,
            state.config.beta_cap,
        )
        .await
        .unwrap();
        assert_eq!(out, Ok(()));
        assert!(store::has_beta_access(&state.db, "did:plc:follower")
            .await
            .unwrap());
    }

    #[tokio::test]
    async fn claim_with_invalid_token_bounces() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri("/claim?t=not-a-real-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // Renders the invite page (200), NOT a redirect to /login.
        assert_eq!(resp.status(), StatusCode::OK);
    }

    #[tokio::test]
    async fn claim_with_used_token_is_refused() {
        let state = bot_state("bot-secret-abcdef").await;
        // Mint a code + wrap it, then redeem it out from under the token.
        let code = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        let token = sign_claim_token(&code, &state.config.cookie_secret);
        store::redeem_code(
            &state.db,
            &code,
            "did:plc:someone",
            None,
            state.config.beta_cap,
        )
        .await
        .unwrap()
        .unwrap();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/claim?t={}", qenc(&token)))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // A used code → the invite page (AlreadyRedeemed), not a fresh reservation.
        assert_eq!(resp.status(), StatusCode::OK);
        assert!(resp.headers().get(header::SET_COOKIE).is_none());
    }

    #[tokio::test]
    async fn bot_claims_rejects_bad_and_missing_secret() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        // Wrong secret.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "wrong")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
        // Missing secret.
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
    }

    #[tokio::test]
    async fn bot_claims_disabled_when_secret_unset() {
        // test_state configures NO bot secret → the endpoint is off (503).
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "anything")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
    }

    #[tokio::test]
    async fn bot_claims_refuses_at_capacity() {
        let state = bot_state("bot-secret-abcdef").await;
        // cap=3, admin seed took 1 seat. Grant 2 more to fill it.
        store::grant_access(&state.db, "did:plc:b", None, "admin", None)
            .await
            .unwrap();
        store::grant_access(&state.db, "did:plc:c", None, "admin", None)
            .await
            .unwrap();
        assert_eq!(store::count_beta_access(&state.db).await.unwrap(), 3);
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::CONFLICT);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        assert!(String::from_utf8_lossy(&bytes).contains("full"));
    }

    #[tokio::test]
    async fn bot_claims_counts_outstanding_codes_against_cap() {
        let state = bot_state("bot-secret-abcdef").await;
        // cap=3, admin seed = 1 seat. Two outstanding active codes = 3 committed.
        store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // 1 seat + 2 outstanding >= cap 3 → refused even though only 1 real seat used.
        assert_eq!(resp.status(), StatusCode::CONFLICT);
    }

    /// POST /bot/claims with a JSON body carrying the follower DID.
    async fn post_bot_claim_for(
        app: &axum::Router,
        secret: &str,
        did: &str,
    ) -> (StatusCode, serde_json::Value) {
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", secret)
                    .header("content-type", "application/json")
                    .body(Body::from(format!(
                        "{{\"did\":\"{did}\",\"handle\":\"who.test\"}}"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let json = if bytes.is_empty() {
            serde_json::Value::Null
        } else {
            serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null)
        };
        (status, json)
    }

    #[tokio::test]
    async fn bot_claims_returns_already_seated_for_a_member() {
        // A DID that already holds beta access must get `already_seated` with NO
        // code/url — the bot posts nothing. This is the server-side backstop that
        // survives a bot-host state loss (it would otherwise re-mint + re-post).
        let state = bot_state("bot-secret-abcdef").await;
        store::grant_access(&state.db, "did:plc:member", None, "admin", None)
            .await
            .unwrap();
        let app = router(state.clone());
        let (status, json) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:member").await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(json["status"], "already_seated");
        assert_eq!(json["code"], "");
        assert_eq!(json["url"], "");
        // No new invite code was minted for the seated DID.
        assert!(store::find_active_code_for_did(&state.db, "did:plc:member")
            .await
            .unwrap()
            .is_none());
    }

    #[tokio::test]
    async fn bot_claims_is_idempotent_per_did_returns_same_code() {
        // Two mint requests for the SAME follower DID must return the SAME code
        // (the app is authoritative), never a second one — so a bot-host state loss
        // re-requesting cannot double-mint or double-post.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        let (s1, j1) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower1").await;
        assert_eq!(s1, StatusCode::OK);
        assert_eq!(j1["status"], "minted");
        let code1 = j1["code"].as_str().unwrap().to_string();

        let (s2, j2) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower1").await;
        assert_eq!(s2, StatusCode::OK);
        assert_eq!(j2["status"], "existing");
        assert_eq!(j2["code"].as_str().unwrap(), code1, "same code returned");
        assert_eq!(j2["url"], j1["url"], "same url returned");

        // Exactly ONE active code exists for that DID.
        assert_eq!(store::count_active_codes(&state.db).await.unwrap(), 1);
    }

    #[tokio::test]
    async fn bot_claims_records_intended_did_at_mint() {
        // A fresh mint records the follower DID so the lookup finds it.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());
        let (status, json) =
            post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower2").await;
        assert_eq!(status, StatusCode::OK);
        let code = json["code"].as_str().unwrap();
        assert_eq!(
            store::find_active_code_for_did(&state.db, "did:plc:follower2")
                .await
                .unwrap()
                .as_deref(),
            Some(code)
        );
    }

    #[tokio::test]
    async fn bot_claims_concurrent_same_did_never_double_mints() {
        // S4: two concurrent /bot/claims for ONE follower DID must not both mint an
        // active code. The dedupe check (3b) and the mint are separate statements,
        // so a race can slip both past 3b's `Ok(None)`; the partial unique index
        // then makes the loser's INSERT conflict, and the handler recovers by
        // returning the winner's code (status `existing`) rather than 500-ing.
        // Result: exactly ONE active code, and BOTH callers get a usable code.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        let a = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:racer");
        let b = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:racer");
        let ((sa, ja), (sb, jb)) = tokio::join!(a, b);

        assert_eq!(sa, StatusCode::OK, "first response: {ja:?}");
        assert_eq!(sb, StatusCode::OK, "second response: {jb:?}");

        // Exactly one active code for the DID — the whole point of the fix.
        assert_eq!(
            store::count_active_codes(&state.db).await.unwrap(),
            1,
            "concurrent mints must not create two active codes"
        );

        // Both callers received the SAME (single) code, and neither got a 500.
        let ca = ja["code"].as_str().unwrap_or("");
        let cb = jb["code"].as_str().unwrap_or("");
        assert!(!ca.is_empty() && !cb.is_empty(), "both must return a code");
        assert_eq!(ca, cb, "both callers must get the one minted code");
        // One is `minted` (the winner), the other `minted` or `existing` depending
        // on interleaving — but never an error status.
        for st in [&ja["status"], &jb["status"]] {
            let s = st.as_str().unwrap_or("");
            assert!(s == "minted" || s == "existing", "unexpected status {s:?}");
        }
    }

    #[tokio::test]
    async fn bot_claims_rejects_malformed_json_body() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .header("content-type", "application/json")
                    .body(Body::from("{not json"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn favicon_ico_served_at_root() {
        // Browsers request bare /favicon.ico regardless of the <link rel="icon">
        // tags in <head>; the root route must serve the icon, not 404.
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .uri("/favicon.ico")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let ct = resp
            .headers()
            .get(header::CONTENT_TYPE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            ct.contains("icon") || ct.starts_with("image/"),
            "content-type = {ct}"
        );
    }

    #[tokio::test]
    async fn login_without_invite_redirects_to_beta_redeem() {
        // No allow-list seed, no invite cookie: starting OAuth must be refused.
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/login")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("handle=alice.bsky.social"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers().get(header::LOCATION).unwrap(),
            "/beta/redeem"
        );
    }

    #[tokio::test]
    async fn login_with_valid_invite_cookie_starts_oauth() {
        let state = test_state(&[]).await;
        let cookie = sign_invite("FEATHER-ABCDWXYZ", &state.config.cookie_secret);
        let cookie = cookie.split(';').next().unwrap().to_string();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/login")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .header(header::COOKIE, cookie)
                    .body(Body::from("handle=alice.bsky.social"))
                    .unwrap(),
            )
            .await
            .unwrap();
        // Redirects into the sidecar login (not to /beta/redeem).
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("/login"), "loc = {loc}");
        assert_ne!(loc, "/beta/redeem");
    }

    /// A resolver that always fails — proves the fast paths short-circuit BEFORE
    /// any network resolution and that a resolution failure fails closed.
    async fn resolver_never(_handle: String) -> Option<String> {
        None
    }

    /// A resolver that maps every handle to `did`.
    fn resolver_to(did: &'static str) -> impl FnOnce(String) -> std::future::Ready<Option<String>> {
        move |_handle| std::future::ready(Some(did.to_string()))
    }

    /// Path 3: a cookie-less visitor whose submitted handle resolves to a DID
    /// that already holds a seat (the seeded-admin first-login case) passes the
    /// gate — no session cookie, no invite code.
    #[tokio::test]
    async fn may_start_oauth_honors_seat_via_resolved_handle() {
        // The seeded admin holds a seat (via ALLOWED_DIDS → ensure_seed) but has
        // no cookie on a fresh deploy.
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            may_start_oauth_with(
                &state,
                &headers,
                "admin.example",
                resolver_to("did:plc:admin")
            )
            .await,
            "a handle resolving to a seated DID must pass the gate"
        );
    }

    /// Path 3, negative: a handle that resolves to a DID with NO seat is bounced
    /// — the anti-abuse intent is preserved (resolution succeeds, seat check
    /// fails).
    #[tokio::test]
    async fn may_start_oauth_bounces_non_member_handle() {
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            !may_start_oauth_with(
                &state,
                &headers,
                "rando.example",
                resolver_to("did:plc:rando")
            )
            .await,
            "a resolved DID with no seat must be bounced"
        );
    }

    /// Fail-closed: an unresolvable/malformed handle (resolver returns `None`)
    /// bounces gracefully — no panic, no handshake.
    #[tokio::test]
    async fn may_start_oauth_fails_closed_on_unresolvable_handle() {
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            !may_start_oauth_with(&state, &headers, "not a handle", resolver_never).await,
            "an unresolvable handle must fail closed"
        );
    }

    /// The session-cookie fast path admits a seated member WITHOUT calling the
    /// resolver (proven by injecting `resolver_never`, which would otherwise
    /// bounce).
    #[tokio::test]
    async fn may_start_oauth_session_cookie_shortcircuits_resolution() {
        let state = test_state(&[]).await;
        let did = "did:plc:member";
        store::grant_access(&state.db, did, Some("member.example"), "test", None)
            .await
            .unwrap();
        let cookie = session_cookie(&state, did, Some("member.example"));
        let mut headers = HeaderMap::new();
        headers.insert(header::COOKIE, cookie.parse().unwrap());
        assert!(
            may_start_oauth_with(&state, &headers, "member.example", resolver_never).await,
            "a seated session cookie must pass without resolution"
        );
    }

    /// The invite-cookie fast path admits WITHOUT calling the resolver.
    #[tokio::test]
    async fn may_start_oauth_invite_cookie_shortcircuits_resolution() {
        let state = test_state(&[]).await;
        let cookie = sign_invite("FEATHER-ABCDWXYZ", &state.config.cookie_secret);
        let cookie = cookie.split(';').next().unwrap().to_string();
        let mut headers = HeaderMap::new();
        headers.insert(header::COOKIE, cookie.parse().unwrap());
        assert!(
            may_start_oauth_with(&state, &headers, "someone.example", resolver_never).await,
            "a valid invite cookie must pass without resolution"
        );
    }

    #[tokio::test]
    async fn admin_mint_requires_admin_seed_did() {
        let state = test_state(&["did:plc:admin"]).await;
        // A non-admin (but beta'd) session is forbidden.
        store::grant_access(&state.db, "did:plc:rando", None, "test", None)
            .await
            .unwrap();
        let rando_cookie = session_cookie(&state, "did:plc:rando", None);
        // An admin session is allowed.
        let admin_cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        let forbidden = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites?n=2")
                    .header(header::COOKIE, rando_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(forbidden.status(), StatusCode::FORBIDDEN);

        let ok = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites?n=2")
                    .header(header::COOKIE, admin_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(ok.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(ok.into_body(), 64 * 1024)
            .await
            .unwrap();
        let body = String::from_utf8(bytes.to_vec()).unwrap();
        let minted: Vec<&str> = body.lines().filter(|l| !l.is_empty()).collect();
        assert_eq!(minted.len(), 2);
        assert!(minted.iter().all(|c| c.starts_with("FEATHER-")));
    }

    #[tokio::test]
    async fn admin_mint_unauthenticated_is_401() {
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
    }

    /// A state whose `/about` renders the adoption line, seeded with one
    /// observation.
    async fn adoption_state(repos: i64, truncated: bool) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::record_network_stat(
            &db,
            &store::NetworkStat {
                key: store::ADOPTION_STAT_KEY.to_string(),
                source: "https://relay1.us-west.bsky.network".to_string(),
                value: repos,
                truncated,
                observed_at: "2026-08-13T04:05:06Z".to_string(),
            },
        )
        .await
        .unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            show_adoption: true,
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    async fn about_body(state: AppState) -> String {
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/about")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 256 * 1024)
            .await
            .unwrap();
        String::from_utf8(bytes.to_vec()).unwrap()
    }

    /// Default config ⇒ the flag is off ⇒ no line, and no query is issued.
    #[tokio::test]
    async fn about_omits_adoption_line_by_default() {
        let state = test_state(&[]).await;
        assert!(!state.config.show_adoption);
        let body = about_body(state).await;
        assert!(
            !body.contains("atproto network"),
            "the adoption line must not render by default"
        );
    }

    #[tokio::test]
    async fn about_renders_adoption_line_when_enabled() {
        // **A distinctive count, and asserted IN ITS SENTENCE.**
        //
        // This used to seed 4 and assert `body.contains("4")`, which the
        // colophon's `width="44"` satisfies whatever the count is — so
        // hardcoding the rendered number passed. Both halves are needed: a
        // digit that does not occur incidentally, and the assertion tied to the
        // phrase it belongs to.
        let body = about_body(adoption_state(7_318, false).await).await;
        // The count and its phrase are on separate template lines, so compare
        // against a whitespace-collapsed copy rather than the raw HTML.
        let flat = body.split_whitespace().collect::<Vec<_>>().join(" ");
        assert!(
            flat.contains("7318 accounts on the atproto network hold"),
            "the count did not render in its own sentence: {flat}",
        );
        assert!(
            body.contains("accounts on the atproto network hold"),
            "{body}"
        );
        assert!(
            body.contains("2026-08-13"),
            "the observation date must render"
        );
        assert!(
            body.contains("lower bound"),
            "the non-archival caveat must ride along with the number"
        );
        assert!(
            !body.contains("At least"),
            "an untruncated count is exact-ish"
        );
    }

    /// A count of one must read as "1 account … holds", not "1 accounts … hold".
    #[tokio::test]
    async fn about_adoption_line_is_singular_at_one() {
        let body = about_body(adoption_state(1, false).await).await;
        assert!(
            body.contains("account on the atproto network holds"),
            "{body}"
        );
    }

    /// A truncated observation is a floor, and must say so.
    #[tokio::test]
    async fn about_adoption_line_says_at_least_when_truncated() {
        let body = about_body(adoption_state(25_000, true).await).await;
        assert!(body.contains("At least"), "{body}");
    }

    /// Flag on but no observation (or a zero) ⇒ 200, no line, no error.
    #[tokio::test]
    async fn about_omits_line_when_enabled_with_no_observation() {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            show_adoption: true,
            ..Config::default()
        };
        let body = about_body(AppState::new(config, db).unwrap()).await;
        assert!(!body.contains("atproto network"));
    }

    // ---- standard.site on the public pages and the subscribe form ----------
    //
    // `FEATHERREADER_STANDARD_SITE` gates what may be STORED (`add_subscription`
    // refuses every `at://` paste with it off), so a page that tells the reader
    // to paste a publication URI is advertising a form that will be refused
    // unless the flag is on. These pin both halves: with the flag on the pages
    // say how; with it off they do not.

    /// A state with the standard.site flag chosen, and `did` holding a seat so
    /// `/manage` renders for it.
    async fn standard_site_state(standard_site: bool, did: &str) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &[did.to_string()]).await.unwrap();
        let config = Config {
            allowed_dids: vec![did.to_string()],
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            standard_site,
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    /// `GET path` as `did`, asserted 200, body as a string.
    async fn signed_in_body(state: AppState, path: &str, did: &str) -> String {
        let cookie = session_cookie(&state, did, Some("reader.example"));
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri(path)
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "{path}");
        let bytes = axum::body::to_bytes(resp.into_body(), 512 * 1024)
            .await
            .unwrap();
        String::from_utf8(bytes.to_vec()).unwrap()
    }

    /// `GET path` signed out, asserted 200, body as a string.
    async fn public_body(state: AppState, path: &str) -> String {
        let resp = router(state)
            .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "{path}");
        let bytes = axum::body::to_bytes(resp.into_body(), 512 * 1024)
            .await
            .unwrap();
        String::from_utf8(bytes.to_vec()).unwrap()
    }

    /// The `<input … id="feed-url" …>` tag of the subscribe form, whole.
    fn feed_url_input(body: &str) -> &str {
        let start = body
            .find("id=\"feed-url\"")
            .and_then(|i| body[..i].rfind("<input"))
            .expect("the subscribe form's URL input renders");
        let end = body[start..].find('>').expect("the input tag closes") + start + 1;
        &body[start..end]
    }

    /// Flag on: the subscribe form says a publication URI is accepted, and shows
    /// both spellings the handler takes (DID and handle).
    #[tokio::test]
    async fn manage_hints_at_publications_when_the_flag_is_on() {
        let did = "did:plc:reader";
        let body = signed_in_body(standard_site_state(true, did).await, "/manage", did).await;
        assert!(
            body.contains("at://did:plc:…/site.standard.publication/…"),
            "the DID form must be shown: {body}"
        );
        assert!(
            body.contains("at://alice.example.com/site.standard.publication/…"),
            "the handle form must be shown: {body}"
        );
    }

    /// Flag on: the URL input must not be `type="url"`. A browser validates
    /// that type with the WHATWG URL parser, which REJECTS the DID form —
    /// `at://did:plc:…/…` fails as an invalid port, the same failure
    /// `url::Url::parse` has (see `feed::is_storable_feed_url`) — so the form
    /// would refuse to submit the very string the hint asks for.
    #[tokio::test]
    async fn manage_url_input_accepts_a_did_uri_when_the_flag_is_on() {
        let did = "did:plc:reader";
        let body = signed_in_body(standard_site_state(true, did).await, "/manage", did).await;
        let input = feed_url_input(&body);
        assert!(
            input.contains("type=\"text\""),
            "the input must be type=text so a DID-form at:// URI can be submitted: {input}"
        );
        assert!(
            input.contains("inputmode=\"url\""),
            "the URL keyboard is still wanted: {input}"
        );
    }

    /// Flag on, `type="text"` drops the browser's scheme check, so a pasted
    /// `example.com/blog` would reach the handler and come back as "Couldn't
    /// find a feed" — wrong, the site likely has one. A `pattern` keeps the
    /// browser asking for a scheme while still admitting `at://` (both cases:
    /// the handler canonicalises the scheme).
    #[tokio::test]
    async fn manage_url_input_still_requires_a_scheme_when_the_flag_is_on() {
        let did = "did:plc:reader";
        let body = signed_in_body(standard_site_state(true, did).await, "/manage", did).await;
        let input = feed_url_input(&body);
        assert!(
            input.contains(&format!("pattern=\"{FEED_URL_PATTERN}\"")),
            "the text input must keep a scheme check: {input}"
        );
    }

    /// Flag off: every `at://` paste is refused, so the form must not say
    /// publications are accepted — and the input keeps browser URL validation.
    #[tokio::test]
    async fn manage_does_not_advertise_publications_when_the_flag_is_off() {
        let did = "did:plc:reader";
        let state = standard_site_state(false, did).await;
        assert!(!state.config.standard_site);
        let page = signed_in_body(state, "/manage", did).await;
        // The `<head>` carries the site's link card, whose one-line description
        // names standard.site whatever the flag says — as the landing page does
        // with the flag off (a stored publication is polled regardless). What
        // must not advertise is the page: everything after `</head>`.
        let body = &page[page.find("</head>").expect("a <head>")..];
        assert!(
            !body.contains("site.standard.publication"),
            "a refused form must not be advertised: {body}"
        );
        // The shared footer links the `/standard-site` feature page on every
        // page, flag on or off — that page itself says the instance isn't
        // accepting new publication subscriptions — so the check is on the
        // page above the footer, where the form and its hints are.
        let above_footer = body
            .split("<footer")
            .next()
            .expect("split yields at least one piece");
        assert!(
            above_footer.contains("id=\"feed-url\""),
            "the form must be above the footer: {body}"
        );
        assert!(
            !above_footer.contains("standard.site"),
            "a refused form must not be advertised: {body}"
        );
        assert!(
            feed_url_input(body).contains("type=\"url\""),
            "with the flag off the input is unchanged"
        );
    }

    /// Flag on: the landing page says publications sit beside feeds AND how to
    /// subscribe to one.
    #[tokio::test]
    async fn landing_describes_publications_and_how_to_subscribe_when_on() {
        let body = public_body(standard_site_state(true, "did:plc:x").await, "/").await;
        assert!(body.contains("standard.site"), "{body}");
        assert!(
            body.contains("at://did:plc:…/site.standard.publication/…"),
            "the landing page must show the DID form: {body}"
        );
        assert!(
            body.contains("at://alice.example.com/site.standard.publication/…"),
            "the landing page must show the handle form: {body}"
        );
    }

    /// Flag off: the landing page still says what a publication is (a stored
    /// one is polled whatever the flag says), but shows no paste instructions
    /// and says new ones are not accepted here.
    #[tokio::test]
    async fn landing_does_not_tell_visitors_to_paste_a_publication_when_off() {
        let body = public_body(standard_site_state(false, "did:plc:x").await, "/").await;
        assert!(body.contains("standard.site"), "{body}");
        assert!(
            !body.contains("at://did:plc:…/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            !body.contains("at://alice.example.com/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            body.contains("isn't accepting new publication subscriptions"),
            "the page must say the form is closed here: {body}"
        );
    }

    /// Flag on: /about has a publications section with both spellings.
    #[tokio::test]
    async fn about_describes_publications_and_how_to_subscribe_when_on() {
        let body = public_body(standard_site_state(true, "did:plc:x").await, "/about").await;
        assert!(body.contains("site.standard.publication"), "{body}");
        assert!(body.contains("site.standard.document"), "{body}");
        assert!(
            body.contains("at://did:plc:…/site.standard.publication/…"),
            "{body}"
        );
        assert!(
            body.contains("at://alice.example.com/site.standard.publication/…"),
            "{body}"
        );
    }

    /// Flag off: /about keeps the description, drops the paste instructions.
    #[tokio::test]
    async fn about_does_not_tell_visitors_to_paste_a_publication_when_off() {
        let body = public_body(standard_site_state(false, "did:plc:x").await, "/about").await;
        assert!(body.contains("site.standard.publication"), "{body}");
        assert!(
            !body.contains("at://did:plc:…/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            !body.contains("at://alice.example.com/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            body.contains("isn't accepting new publication subscriptions"),
            "{body}"
        );
    }

    // ---- the standard.site feature page (`/standard-site`) -----------------
    //
    // A public page, like `/about`: what a publication is, what is shown from
    // it, how to subscribe (flag-conditional, as on the other public pages),
    // and the honest limits. It also carries the "latest releases" call-out.

    /// Signed out, with the default config, the page renders.
    #[tokio::test]
    async fn standard_site_page_renders_signed_out() {
        let body = public_body(test_state(&[]).await, "/standard-site").await;
        assert!(body.contains("site.standard.publication"), "{body}");
        assert!(body.contains("site.standard.document"), "{body}");
        assert!(
            body.contains("<title>standard.site — FeatherReader</title>"),
            "{body}"
        );
    }

    /// Flag on: the page says how to subscribe, in both spellings, and that a
    /// handle is resolved to its DID.
    #[tokio::test]
    async fn standard_site_page_tells_how_to_subscribe_when_on() {
        let body = public_body(
            standard_site_state(true, "did:plc:x").await,
            "/standard-site",
        )
        .await;
        assert!(
            body.contains("at://did:plc:…/site.standard.publication/…"),
            "the DID form must be shown: {body}"
        );
        assert!(
            body.contains("at://alice.example.com/site.standard.publication/…"),
            "the handle form must be shown: {body}"
        );
        assert!(
            body.contains("resolved to its DID"),
            "the handle resolution must be stated: {body}"
        );
        assert!(
            !body.contains("isn't accepting new publication subscriptions"),
            "{body}"
        );
    }

    /// Flag off: `add_subscription` refuses every `at://` paste, so the page
    /// must not tell visitors to paste one — it says new publication
    /// subscriptions are not accepted here, and that stored ones are still read.
    #[tokio::test]
    async fn standard_site_page_does_not_tell_visitors_to_paste_when_off() {
        let state = standard_site_state(false, "did:plc:x").await;
        assert!(!state.config.standard_site);
        let body = public_body(state, "/standard-site").await;
        assert!(body.contains("site.standard.publication"), "{body}");
        assert!(
            !body.contains("at://did:plc:…/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            !body.contains("at://alice.example.com/site.standard.publication/…"),
            "no paste instructions with the flag off: {body}"
        );
        assert!(
            body.contains("isn't accepting new publication subscriptions"),
            "the page must say the form is closed here: {body}"
        );
        assert!(
            body.contains("already follows are still read"),
            "stored publications are polled whatever the flag says: {body}"
        );
    }

    /// The releases call-out links each release's GitHub page and the
    /// changelog, on the feature page and on the landing page.
    #[tokio::test]
    async fn releases_callout_links_the_release_pages() {
        for path in ["/standard-site", "/"] {
            let body = public_body(test_state(&[]).await, path).await;
            for tag in ["v0.4.1", "v0.4.0"] {
                let href = format!(
                    "href=\"https://github.com/justin-stanley/feather-reader/releases/tag/{tag}\""
                );
                assert!(body.contains(&href), "{path} must link {tag}: {body}");
            }
            assert!(
                body.contains(
                    "https://github.com/justin-stanley/feather-reader/blob/main/CHANGELOG.md"
                ),
                "{path} must link the changelog: {body}"
            );
        }
    }

    /// The feature page is reachable from the landing page, from `/about`, and
    /// from the shared footer (`/privacy` renders nothing but prose and that
    /// footer, so it stands in for every page that includes it).
    #[tokio::test]
    async fn landing_about_and_footer_link_the_standard_site_page() {
        for path in ["/", "/about", "/privacy"] {
            let body = public_body(test_state(&[]).await, path).await;
            assert!(
                body.contains("href=\"/standard-site\""),
                "{path} must link the feature page: {body}"
            );
        }
    }

    /// `RELEASES` is the one place a release is described, so its shape is
    /// pinned: newest first, dates as the CHANGELOG headings spell them, and
    /// both derived links pointing where the template promises.
    #[test]
    fn releases_are_newest_first_and_link_the_tag_and_changelog() {
        assert!(!RELEASES.is_empty());
        let parse = |v: &str| -> Vec<u32> {
            v.split('.')
                .map(|p| p.parse::<u32>().expect("a numeric version part"))
                .collect()
        };
        for pair in RELEASES.windows(2) {
            assert!(
                parse(pair[0].version) > parse(pair[1].version),
                "{} must come before {}",
                pair[0].version,
                pair[1].version
            );
        }
        for r in RELEASES {
            assert_eq!(parse(r.version).len(), 3, "{}", r.version);
            assert!(
                chrono::NaiveDate::parse_from_str(r.date, "%Y-%m-%d").is_ok(),
                "{} is not YYYY-MM-DD",
                r.date
            );
            assert!(!r.summary.trim().is_empty());
            assert!(!r.summary.contains('<'), "the summary is plain text");
            assert_eq!(
                r.url(),
                format!(
                    "https://github.com/justin-stanley/feather-reader/releases/tag/v{}",
                    r.version
                )
            );
        }
        // The newest entry is this build's own version, so a release cannot
        // ship without adding itself to the call-out.
        let latest = &RELEASES[0];
        assert_eq!(latest.version, env!("CARGO_PKG_VERSION"));
        assert_eq!(
            latest.changelog_url(),
            "https://github.com/justin-stanley/feather-reader/blob/main/CHANGELOG.md#046--2026-10-06"
        );
    }

    /// Public and static like `/about`, so it is cacheable on the same terms.
    #[tokio::test]
    async fn standard_site_page_is_publicly_cacheable() {
        let resp = router(test_state(&[]).await)
            .oneshot(
                Request::builder()
                    .uri("/standard-site")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=300"
        );
    }

    #[tokio::test]
    async fn cache_control_public_on_about_no_store_on_authed() {
        let state = test_state(&["did:plc:admin"]).await;
        let admin_cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // /about → public, cacheable.
        let about = app
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/about")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            about.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=300"
        );
        // The security headers are still intact.
        // The VALUE, spelled out here rather than compared to the constant —
        // `== CONTENT_SECURITY_POLICY` passes with the constant gutted. This
        // used to assert only that the header existed, which a policy of
        // `default-src *` satisfies.
        assert_eq!(
            about.headers()["content-security-policy"],
            EXPECTED_CSP,
            "the CSP is not the policy the router promises"
        );
        assert_eq!(about.headers().get("x-frame-options").unwrap(), "DENY");

        // /privacy and /terms are static public pages → public, cacheable.
        for path in ["/privacy", "/terms"] {
            let resp = app
                .clone()
                .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            assert_eq!(
                resp.headers().get(header::CACHE_CONTROL).unwrap(),
                "public, max-age=300",
                "{path} should be publicly cacheable"
            );
            // Security headers apply to these pages too.
            assert_eq!(resp.headers()["content-security-policy"], EXPECTED_CSP);
            assert_eq!(resp.headers().get("x-frame-options").unwrap(), "DENY");
        }

        // The bare /login landing → public, cacheable.
        let login = app
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/login")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            login.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=300"
        );

        // An authenticated page → no-store.
        let home = app
            .oneshot(
                Request::builder()
                    .uri("/")
                    .header(header::COOKIE, admin_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            home.headers().get(header::CACHE_CONTROL).unwrap(),
            "no-store"
        );
    }

    // -- link cards (Open Graph) -----------------------------------------------
    //
    // Bluesky's card service fetches the HTML server-side, runs no JS, and
    // resolves nothing relative. Measured before these tags existed:
    // `cardyb.bsky.app/v1/extract?url=https://feather-reader.com/` returned
    // `{"title":"FeatherReader — read, quietly","description":"","image":""}`.

    /// Everything up to `</head>` — the only part a card fetcher reads.
    fn head(body: &str) -> &str {
        let end = body.find("</head>").expect("a <head>");
        &body[..end]
    }

    /// The `content` of the first `<meta …>` tag carrying `attr` (e.g.
    /// `property="og:title"`), or `None` when no tag carries it.
    fn meta(head: &str, attr: &str) -> Option<String> {
        let tag_start = head.find(attr)?;
        let rest = &head[tag_start..];
        let tag_end = rest.find('>')?;
        let tag = &rest[..tag_end];
        let content = tag.find("content=\"")? + "content=\"".len();
        let close = tag[content..].find('"')?;
        Some(tag[content..content + close].to_string())
    }

    /// A state whose public origin is production's. The card URLs must be
    /// absolute on THAT origin: a relative `/static/…` is what the card
    /// fetcher cannot use.
    async fn production_origin_state() -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &["did:plc:admin".to_string()])
            .await
            .unwrap();
        let config = Config {
            allowed_dids: vec!["did:plc:admin".to_string()],
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            public_url: "https://feather-reader.com".to_string(),
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    /// The landing page and /about each carry a complete card with absolute
    /// https URLs, and the two describe different things.
    #[tokio::test]
    async fn landing_and_about_render_open_graph_cards_with_absolute_urls() {
        let landing = public_body(production_origin_state().await, "/").await;
        let about = public_body(production_origin_state().await, "/about").await;
        let (lh, ah) = (head(&landing), head(&about));

        assert_eq!(
            meta(lh, "property=\"og:title\"").as_deref(),
            Some("FeatherReader — read, quietly"),
            "{lh}"
        );
        assert_eq!(
            meta(ah, "property=\"og:title\"").as_deref(),
            Some("About — FeatherReader"),
            "{ah}"
        );
        for (h, path) in [(lh, "/"), (ah, "/about")] {
            let url = format!("https://feather-reader.com{path}");
            assert_eq!(
                meta(h, "property=\"og:url\"").as_deref(),
                Some(url.as_str())
            );
            assert!(
                h.contains(&format!("<link rel=\"canonical\" href=\"{url}\"")),
                "{path} must carry a canonical link: {h}"
            );
            let image = meta(h, "property=\"og:image\"").unwrap_or_default();
            assert!(
                image.starts_with("https://feather-reader.com/static/"),
                "{path}: og:image must be absolute on the public origin, got {image:?}"
            );
            assert_eq!(
                meta(h, "name=\"twitter:card\"").as_deref(),
                Some("summary_large_image")
            );
            assert_eq!(meta(h, "property=\"og:type\"").as_deref(), Some("website"));
            assert_eq!(
                meta(h, "property=\"og:site_name\"").as_deref(),
                Some("FeatherReader")
            );
            let description = meta(h, "property=\"og:description\"").unwrap_or_default();
            assert!(!description.is_empty(), "{path}: og:description is empty");
            assert_eq!(
                meta(h, "name=\"description\"").as_deref(),
                Some(description.as_str()),
                "{path}: the meta description and og:description must agree"
            );
        }
        assert_ne!(
            meta(lh, "property=\"og:description\""),
            meta(ah, "property=\"og:description\""),
            "the landing page and /about must not share a description"
        );
    }

    /// The origin comes from `FEATHERREADER_PUBLIC_URL`, not a constant.
    #[tokio::test]
    async fn card_urls_follow_the_configured_public_url() {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &[]).await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            public_url: "https://reader.example.org".to_string(),
            ..Config::default()
        };
        let body = public_body(AppState::new(config, db).unwrap(), "/privacy").await;
        let h = head(&body);
        assert_eq!(
            meta(h, "property=\"og:url\"").as_deref(),
            Some("https://reader.example.org/privacy")
        );
        assert_eq!(
            meta(h, "property=\"og:image\"").as_deref(),
            Some("https://reader.example.org/static/social-card.png")
        );
    }

    /// Every signed-out page describes itself: no two share a description,
    /// and each `og:url` is its own path.
    #[tokio::test]
    async fn public_pages_each_carry_their_own_description() {
        let paths = [
            "/",
            "/about",
            "/privacy",
            "/terms",
            "/stats",
            "/standard-site",
            "/login",
            "/beta/redeem",
        ];
        let mut seen = std::collections::HashSet::new();
        for path in paths {
            let body = public_body(production_origin_state().await, path).await;
            let h = head(&body);
            let description = meta(h, "name=\"description\"").unwrap_or_default();
            assert!(!description.is_empty(), "{path} has no description: {h}");
            assert!(
                seen.insert(description.clone()),
                "{path} repeats another page's description: {description:?}"
            );
            assert_eq!(
                meta(h, "property=\"og:url\"").as_deref(),
                Some(format!("https://feather-reader.com{path}").as_str()),
                "{path}"
            );
            assert!(
                !h.contains("name=\"robots\""),
                "{path} is public and must not be noindex: {h}"
            );
        }
    }

    /// The share image is served from `/static` as a PNG of the dimensions the
    /// tags promise, well under the 1 MB card fetchers tolerate, and cacheable.
    #[tokio::test]
    async fn share_image_is_served_as_a_png_of_the_advertised_size() {
        let landing = public_body(production_origin_state().await, "/").await;
        let h = head(&landing);
        let image = meta(h, "property=\"og:image\"").unwrap();
        let path = image.strip_prefix("https://feather-reader.com").unwrap();
        let width: u32 = meta(h, "property=\"og:image:width\"")
            .unwrap()
            .parse()
            .unwrap();
        let height: u32 = meta(h, "property=\"og:image:height\"")
            .unwrap()
            .parse()
            .unwrap();
        assert_eq!((width, height), (1200, 630), "Bluesky renders ~1.91:1");
        assert_eq!(
            meta(h, "property=\"og:image:type\"").as_deref(),
            Some("image/png")
        );
        assert!(
            !meta(h, "property=\"og:image:alt\"")
                .unwrap_or_default()
                .is_empty(),
            "the image needs alt text"
        );

        let resp = router(production_origin_state().await)
            .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "{path}");
        assert_eq!(resp.headers()[header::CONTENT_TYPE], "image/png");
        assert_eq!(resp.headers()[header::CACHE_CONTROL], "public, max-age=300");
        let bytes = axum::body::to_bytes(resp.into_body(), 1024 * 1024)
            .await
            .expect("the image is under 1 MB");
        assert_eq!(&bytes[..8], b"\x89PNG\r\n\x1a\n", "not a PNG");
        // IHDR: width and height, big-endian, at offsets 16 and 20.
        let be = |at: usize| u32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
        assert_eq!(
            (be(16), be(20)),
            (width, height),
            "the PNG's own dimensions must match the tags"
        );
    }

    /// A page that renders a session's private view carries the site's generic
    /// card — nothing from the view reaches `<head>` — and is `noindex`.
    #[tokio::test]
    async fn private_pages_keep_user_data_out_of_the_card() {
        for path in ["/", "/manage"] {
            let state = production_origin_state().await;
            let body = signed_in_body(state, path, "did:plc:admin").await;
            let h = head(&body);
            assert!(
                h.contains("<meta name=\"robots\" content=\"noindex\""),
                "{path}: a private view must be noindex: {h}"
            );
            assert_eq!(
                meta(h, "property=\"og:title\"").as_deref(),
                Some("FeatherReader — read, quietly"),
                "{path}: the card of a private view is the site's generic one"
            );
            assert_eq!(
                meta(h, "property=\"og:url\"").as_deref(),
                Some("https://feather-reader.com/"),
                "{path}: og:url of a private view is the front door, not the private path"
            );
            for private in ["reader.example", "did:plc:admin"] {
                assert!(
                    !h.contains(private),
                    "{path}: {private:?} must not reach <head>: {h}"
                );
            }
        }
    }

    #[tokio::test]
    async fn beta_redeem_page_renders() {
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .uri("/beta/redeem")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 256 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(html.contains("Invite code"));
        assert!(html.contains("/beta/redeem"));
    }

    #[tokio::test]
    async fn rate_limit_returns_429_after_burst() {
        // Configure a trusted proxy header so the limiter keys on the forwarded
        // IP (the oneshot harness sets no ConnectInfo socket peer).
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &[]).await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            trusted_ip_header: Some("cf-connecting-ip".to_string()),
            ..Config::default()
        };
        let state = AppState::new(config, db).unwrap();
        let app = router(state);
        // Hammer POST /beta/redeem past the burst from a single (trusted) IP. The
        // handler itself returns 200 (re-render) on a bad code; the limiter is
        // what eventually yields 429.
        let mut saw_429 = false;
        for _ in 0..(RATE_BURST as usize + 5) {
            let resp = app
                .clone()
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/beta/redeem")
                        .header("content-type", "application/x-www-form-urlencoded")
                        .header("cf-connecting-ip", "203.0.113.200")
                        .body(Body::from("code=FEATHER-NOPENOPE"))
                        .unwrap(),
                )
                .await
                .unwrap();
            if resp.status() == StatusCode::TOO_MANY_REQUESTS {
                saw_429 = true;
                break;
            }
        }
        assert!(saw_429, "expected a 429 after exhausting the burst");
    }

    /// **A forged `X-Forwarded-For` does not key the limiter** — the property
    /// the middleware's comment cites this test as proof of.
    ///
    /// The previous version rotated the forged header and asserted that no
    /// request was EVER 429'd. Rotating addresses can never exhaust a per-IP
    /// burst, so that assertion held whether the header was trusted or
    /// ignored — it passed in the vulnerable configuration too. And with no
    /// socket peer the limiter fails open, so nothing could have been keyed on
    /// anything. Now one real peer sends `RATE_BURST + 5` requests, each with
    /// a DIFFERENT forged header, and the last must be 429: they all landed in
    /// the peer's bucket. A limiter keying on the header mints a fresh bucket
    /// per request and never trips — which is exactly what the mutation does.
    #[tokio::test]
    async fn a_forged_forwarded_for_header_does_not_key_the_limiter() {
        let state = test_state(&[]).await;
        assert!(
            state.config.trusted_ip_header.is_none(),
            "no proxy header is trusted here"
        );
        let app = router(state);
        let peer = std::net::SocketAddr::from(([203, 0, 113, 7], 40000));
        let mut saw_429 = false;
        for i in 0..(RATE_BURST as usize + 5) {
            let forged = format!("10.9.8.{}", i % 250);
            let resp = app
                .clone()
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/beta/redeem")
                        .header("content-type", "application/x-www-form-urlencoded")
                        .header("x-forwarded-for", forged)
                        .extension(axum::extract::ConnectInfo(peer))
                        .body(Body::from("code=FEATHER-NOPENOPE"))
                        .unwrap(),
                )
                .await
                .unwrap();
            if resp.status() == StatusCode::TOO_MANY_REQUESTS {
                saw_429 = true;
                break;
            }
        }
        assert!(
            saw_429,
            "rotating a forged X-Forwarded-For minted fresh buckets: the limiter is keyed on an attacker-chosen header"
        );
    }

    // -- OPML import body cap (DefaultBodyLimit → 413) -------------------------

    /// **A private feed is refused BEFORE it is fetched.** The add path's
    /// privacy gate had no test at all — `private_feeds_are_classified_private_
    /// across_providers` says "the add + OPML paths both gate on this
    /// classifier" and nothing checked either. The gate exists so a
    /// token-bearing URL never reaches the network; the assertion that
    /// matters is the server's hit count: zero.
    #[tokio::test]
    async fn subscribing_to_a_private_feed_never_reaches_the_network() {
        let did = "did:plc:privateadder";
        let state = test_state_with_caps(did, 0, 0).await;
        let (base, hits) = crate::net::tests::serve_body_counted(b"<rss/>".to_vec()).await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        crate::net::test_host_override(
            "private-add.test",
            std::net::SocketAddr::from(([127, 0, 0, 1], port)),
        );
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!(
                        "url=http%3A%2F%2Fprivate-add.test%3A{port}%2Ffeed%2Fprivate%2Fdeadbeefcafe1234"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("Private"), "not refused as private: {loc}");
        assert_eq!(
            hits.load(std::sync::atomic::Ordering::SeqCst),
            0,
            "the private feed was FETCHED before being refused"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// **OPML import skips a private feed without storing or publishing it.**
    /// The import path does not fetch, so "never fetched" is not the signal
    /// here; "never stored, never written to the PDS" is. The batch write's
    /// bytes are captured and must not carry the URL.
    #[tokio::test]
    async fn opml_import_skips_a_private_feed_without_storing_or_publishing_it() {
        let did = "did:plc:renamer4";
        let (sidecar, bodies) = spawn_logging_sidecar().await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let tokened = "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4";
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Public\" xmlUrl=\"https://public.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Paid\" xmlUrl=\"{tokened}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("skipped%20as%20private"),
            "not reported as skipped: {loc}"
        );
        assert!(store::get_feed_by_url(&state.db, tokened)
            .await
            .unwrap()
            .is_none());
        let sent = bodies.lock().unwrap().join("\n");
        assert!(
            sent.contains("public.example"),
            "the public feed was not written: {sent}"
        );
        assert!(
            !sent.contains("Zm9vYmFyc2VjcmV0dG9rZW4"),
            "the secret was PUBLISHED to the PDS: {sent}"
        );
    }

    /// **`GET /login?handle=` is gated like `POST /login`.** Only the POST was
    /// tested; the GET form starts the same handshake and had no test, so
    /// deleting its gate left the suite green.
    #[tokio::test]
    async fn get_login_without_a_seat_is_refused() {
        let state = test_state(&[]).await;
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri("/login?handle=alice.bsky.social")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers().get(header::LOCATION).unwrap(),
            "/beta/redeem"
        );
    }

    /// A sidecar fake that answers every request `ok` and records the PATH of
    /// each in arrival order, plus every body — for asserting what was sent,
    /// and in what order.
    async fn spawn_logging_sidecar() -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {
        use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let log = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let sink = log.clone();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut raw: Vec<u8> = Vec::new();
                let mut chunk = [0u8; 4096];
                let text = loop {
                    let Ok(n) = sock.read(&mut chunk).await else {
                        break String::new();
                    };
                    if n == 0 {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                    raw.extend_from_slice(&chunk[..n]);
                    let Some(split) = raw.windows(4).position(|w| w == b"\r\n\r\n") else {
                        continue;
                    };
                    let (head, body) = raw.split_at(split + 4);
                    let want = String::from_utf8_lossy(head).lines().find_map(|l| {
                        let (k, v) = l.split_once(':')?;
                        k.eq_ignore_ascii_case("content-length")
                            .then(|| v.trim().parse::<usize>().ok())?
                    });
                    if want.is_none_or(|w| body.len() >= w) {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                };
                let path = text
                    .lines()
                    .next()
                    .and_then(|l| l.split_whitespace().nth(1))
                    .unwrap_or("")
                    .to_string();
                let body_text = text
                    .split_once("\r\n\r\n")
                    .map(|(_, b)| b)
                    .unwrap_or("")
                    .to_string();
                sink.lock().unwrap().push(format!("{path} {body_text}"));
                let body = serde_json::json!({ "ok": true, "did": "did:plc:x", "revoked": true, "hadSession": true, "data": {"uri": "at://did:plc:x/c/r", "cid": "bafy"} }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        (format!("http://{addr}"), log)
    }

    /// **The sign-out flush settles a split flush's landed prefix too.** It is
    /// `readstate::flush_did` under a timeout, so it shares the fix — pinned
    /// here so a sign-out path that grew its own flush would not silently lose
    /// it. Call 1 of 2 lands, call 2's connection drops: the landed cursors are
    /// created and clean, the rest stay dirty to park until the next sign-in.
    #[tokio::test]
    async fn the_sign_out_flush_settles_what_a_split_flush_landed() {
        use crate::readstate::tests as rs;
        for backend in [
            crate::metrics::Backend::Sidecar,
            crate::metrics::Backend::Rust,
        ] {
            let fake = std::sync::Arc::new(std::sync::Mutex::new(rs::FakeRepo::default()));
            let state = rs::state_on(backend, &fake).await;
            for i in 0..250 {
                rs::mark_read(&state, i, "1").await;
            }
            fake.lock().unwrap().drop_call = Some(2);

            flush_before_revoke(&state, rs::DID).await;

            let order = rs::send_order(250);
            let (landed, rest) = order.split_at(crate::atproto::APPLY_WRITES_MAX_OPS);
            for &i in landed {
                let c = rs::cursor(&state, i).await;
                assert!(c.pds_created && !c.dirty, "{backend:?}: feed {i}");
            }
            for &i in rest {
                let c = rs::cursor(&state, i).await;
                assert!(c.dirty && !c.pds_created, "{backend:?}: feed {i}");
            }
            assert_eq!(fake.lock().unwrap().apply_calls, 2, "{backend:?}");
        }
    }

    /// **Sign-out flushes dirty read-state BEFORE it revokes — through the
    /// route.** The previous version of this test called
    /// `flush_before_revoke` and `revoke_everywhere` itself and asserted one
    /// flush attempt; its doc claimed deleting the call from the handler
    /// "drops that to zero", which was false — the handler was never run.
    /// Deleting the call left the suite green: #117 regressing in full, with
    /// the test named after it still passing. Now `POST /logout` is driven and
    /// the sidecar's log must show a repo write BEFORE the revoke.
    #[tokio::test]
    async fn signing_out_flushes_before_it_revokes_through_the_route() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let (sidecar, log) = spawn_logging_sidecar().await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        crate::store::upsert_cursor(
            &state.db,
            &crate::store::ReadCursor {
                did: did.to_string(),
                feed_url: "https://example.com/feed.xml".into(),
                read_through: None,
                read_ids: "[\"1\"]".into(),
                unread_ids: "[]".into(),
                dirty: true,
                pds_created: false,
                updated_at: "2026-09-13T21:22:40Z".into(),
            },
        )
        .await
        .unwrap();
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/logout")
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let entries = log.lock().unwrap().clone();
        let flush = entries
            .iter()
            .position(|e| e.starts_with("/internal/repo "));
        let revoke = entries
            .iter()
            .position(|e| e.starts_with("/internal/revoke "));
        assert!(revoke.is_some(), "sign-out did not revoke: {entries:?}");
        assert!(
            flush.is_some(),
            "sign-out did not attempt a flush before revoking: {entries:?}"
        );
        assert!(
            flush < revoke,
            "the flush arrived AFTER the revoke — no session left to send it with: {entries:?}"
        );
    }

    /// The policy, as a literal: the backstop the router calls "neutralises any
    /// XSS that slips past sanitization". `script-src 'self'` and no
    /// `'unsafe-inline'` on it are the two clauses that make it one.
    const EXPECTED_CSP: &str = "default-src 'self'; \
     script-src 'self'; \
     style-src 'self' 'unsafe-inline'; \
     img-src 'self' https: data:; \
     font-src 'self'; \
     connect-src 'self'; \
     form-action 'self'; \
     base-uri 'self'; \
     frame-ancestors 'none'; \
     object-src 'none'";

    /// Build a `multipart/form-data` body carrying a single `file` field whose
    /// contents are `payload`, returning `(content_type, body_bytes)`.
    fn opml_multipart(payload: &[u8]) -> (String, Vec<u8>) {
        let boundary = "----featherreadertestboundary";
        let mut body = Vec::new();
        body.extend_from_slice(format!("--{boundary}\r\n").as_bytes());
        body.extend_from_slice(
            b"Content-Disposition: form-data; name=\"file\"; filename=\"feeds.opml\"\r\n",
        );
        body.extend_from_slice(b"Content-Type: text/x-opml\r\n\r\n");
        body.extend_from_slice(payload);
        body.extend_from_slice(format!("\r\n--{boundary}--\r\n").as_bytes());
        (format!("multipart/form-data; boundary={boundary}"), body)
    }

    #[tokio::test]
    async fn opml_import_oversize_upload_returns_413() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // A payload comfortably above the route cap.
        let payload = vec![b'a'; OPML_BODY_LIMIT + 1024];
        let (content_type, body) = opml_multipart(&payload);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::PAYLOAD_TOO_LARGE,
            "an over-cap OPML upload must be rejected with 413, not collapsed to 500"
        );
    }

    /// **The route's own cap is what refuses this, not the framework's.**
    ///
    /// `OPML_BODY_LIMIT` used to equal axum's `DefaultBodyLimit` (2 MiB), so
    /// the route's layer was a no-op — deleting it left every test green, and
    /// `opml_import_oversize_upload_returns_413` was really testing axum. The
    /// limit is 1 MiB now, strictly tighter, and this uploads a payload that
    /// sits BETWEEN the two: over ours, under the framework's. Only the
    /// route's layer can refuse it — remove the layer and this payload is
    /// accepted, which is also what demonstrates the framework's default is
    /// the larger of the two.
    #[tokio::test]
    async fn opml_import_over_the_route_cap_is_refused_below_the_framework_default() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // Between the two ceilings: the framework would accept this.
        let payload = vec![b'a'; (OPML_BODY_LIMIT + AXUM_DEFAULT_BODY_LIMIT) / 2];
        let (content_type, body) = opml_multipart(&payload);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::PAYLOAD_TOO_LARGE,
            "a payload over the route's cap but under the framework's was accepted — \
             the route's own DefaultBodyLimit layer is not doing anything"
        );
    }

    #[tokio::test]
    async fn opml_import_under_limit_upload_is_accepted() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let db = state.db.clone();
        let app = router(state);

        // A small, valid OPML well under the cap: must be accepted (the handler
        // redirects to `/` or a flash), i.e. never 413.
        let opml = br#"<?xml version="1.0"?>
<opml version="2.0"><body>
  <outline text="Example" type="rss" xmlUrl="https://example.com/feed.xml"/>
</body></opml>"#;
        let (content_type, body) = opml_multipart(opml);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        // **Assert it was ACCEPTED, not merely that it was not a 413.**
        //
        // The old assertion was `assert_ne!(status, PAYLOAD_TOO_LARGE)`, which a
        // 500 satisfies — so making `import_opml` fail unconditionally left this
        // green. Three other OPML tests caught that mutation; the one whose name
        // promises to cover the under-cap case did not.
        assert_eq!(
            resp.status(),
            StatusCode::SEE_OTHER,
            "an under-cap OPML upload was not accepted (status {})",
            resp.status(),
        );
        // **303 alone is not acceptance.** `import_opml` redirects on several
        // FAILURES too — unparseable OPML, zero feeds found, every feed trimmed
        // by a cap — so an import that stored nothing satisfied the status check.
        let stored: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM feeds WHERE url = ?1")
            .bind("https://example.com/feed.xml")
            .fetch_one(&db)
            .await
            .unwrap();
        assert_eq!(stored, 1, "the upload was redirected but imported nothing");
        let location = resp
            .headers()
            .get(header::LOCATION)
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default()
            .to_string();
        assert!(
            !location.starts_with("/login"),
            "the import bounced to login instead of being accepted: {location}",
        );
    }

    #[tokio::test]
    async fn opml_import_logged_out_redirects_to_login() {
        // Logged-out callers are redirected before the body is consumed; assert
        // the auth short-circuit rather than a body-cap rejection.
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);

        let opml = b"<opml version=\"2.0\"><body></body></opml>";
        let (content_type, body) = opml_multipart(opml);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(resp.headers().get(header::LOCATION).unwrap(), "/login");
    }

    // -- delete-my-data (POST /account/delete) --------------------------------

    /// A one-shot mock sidecar: binds a loopback port, answers exactly one
    /// `POST /internal/revoke` with `{ok:true,…}`, and reports (via the returned
    /// channel) the DID it was asked to revoke. Enough to prove the delete
    /// handler triggers the sidecar revoke without pulling in an HTTP-mock crate.
    async fn spawn_revoke_sidecar() -> (String, tokio::sync::oneshot::Receiver<String>) {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let (tx, rx) = tokio::sync::oneshot::channel::<String>();
        tokio::spawn(async move {
            let (mut sock, _) = listener.accept().await.unwrap();
            let mut buf = vec![0u8; 4096];
            let n = sock.read(&mut buf).await.unwrap();
            let req = String::from_utf8_lossy(&buf[..n]).to_string();
            // Pull the DID out of the JSON body (last line of the request).
            let did = req
                .split("\r\n\r\n")
                .nth(1)
                .and_then(|body| {
                    let v: serde_json::Value = serde_json::from_str(body.trim()).ok()?;
                    v.get("did")?.as_str().map(str::to_string)
                })
                .unwrap_or_default();
            let is_revoke = req.starts_with("POST /internal/revoke");
            let body = serde_json::json!({
                "ok": true, "did": did, "revoked": true, "hadSession": true
            })
            .to_string();
            let resp = format!(
                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                body.len(),
                body
            );
            sock.write_all(resp.as_bytes()).await.unwrap();
            sock.flush().await.unwrap();
            let _ = tx.send(if is_revoke { did } else { String::new() });
        });
        (format!("http://{addr}"), rx)
    }

    /// Build an [`AppState`] whose sidecar points at `sidecar_url`.
    async fn test_state_with_sidecar(allowed: &[&str], sidecar_url: &str) -> AppState {
        let defaults = Config::default();
        test_state_with_sidecar_and(
            allowed,
            sidecar_url,
            defaults.standard_site,
            defaults.max_feeds_global,
        )
        .await
    }

    /// [`test_state_with_sidecar`] with the standard.site flag and the global
    /// feeds ceiling chosen — the two settings the at:// paths branch on.
    async fn test_state_with_sidecar_and(
        allowed: &[&str],
        sidecar_url: &str,
        standard_site: bool,
        max_feeds_global: i64,
    ) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let dids: Vec<String> = allowed.iter().map(|s| s.to_string()).collect();
        store::ensure_seed(&db, &dids).await.unwrap();
        let mut config = Config {
            allowed_dids: dids,
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            standard_site,
            max_feeds_global,
            ..Config::default()
        };
        config.sidecar.public_url = sidecar_url.to_string();
        config.sidecar.internal_url = sidecar_url.to_string();
        AppState::new(config, db).unwrap()
    }

    /// A confirmed `POST /account/delete` purges the caller's local rows, calls
    /// the sidecar revoke for that DID, and clears the session cookie.
    #[tokio::test]
    async fn account_delete_purges_rows_and_triggers_revoke() {
        let (sidecar_url, revoke_rx) = spawn_revoke_sidecar().await;
        let did = "did:plc:leaver";
        let state = test_state_with_sidecar(&[], &sidecar_url).await;

        // Seed the DID with local rows across the per-DID tables.
        store::grant_access(&state.db, did, Some("leaver.example"), "test", None)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[]).await.unwrap();
        store::mint_code(&state.db, did, 3600).await.unwrap();
        assert!(store::has_beta_access(&state.db, did).await.unwrap());

        let cookie = session_cookie(&state, did, Some("leaver.example"));
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/account/delete")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("confirm=DELETE"))
                    .unwrap(),
            )
            .await
            .unwrap();

        // Signed out: redirect to /login with the cookie cleared.
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert!(resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .starts_with("/login"));
        let set_cookie = resp
            .headers()
            .get(header::SET_COOKIE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(set_cookie.contains("Max-Age=0"), "cookie must be cleared");

        // The sidecar revoke was called for exactly this DID.
        //
        // BOUNDED. A bare `await` here meant a broken `revoke_everywhere` — one
        // that simply never called the sidecar — hung this test forever instead
        // of failing it: a wedged CI job rather than a red one, which is the
        // worse of the two signals because nobody reads it as a defect.
        let revoked_did = tokio::time::timeout(std::time::Duration::from_secs(10), revoke_rx)
            .await
            .expect("the sidecar revoke never fired; revoke_everywhere did not call it")
            .unwrap();
        assert_eq!(
            revoked_did, did,
            "sidecar revoke must fire for the caller DID"
        );

        // Local rows are gone.
        assert!(!store::has_beta_access(&state.db, did).await.unwrap());
        let codes: i64 =
            sqlx::query_scalar("SELECT COUNT(*) FROM invite_codes WHERE creator_did = ?1")
                .bind(did)
                .fetch_one(&state.db)
                .await
                .unwrap();
        assert_eq!(codes, 0);
    }

    /// An UN-confirmed `POST /account/delete` (wrong/blank `confirm`) deletes
    /// nothing and bounces back to /manage.
    #[tokio::test]
    async fn account_delete_without_confirm_is_a_noop() {
        let did = "did:plc:staying";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/account/delete")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("confirm=nope"))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert!(resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .starts_with("/manage"));
        // Nothing deleted.
        assert!(store::has_beta_access(&state.db, did).await.unwrap());
    }

    /// PDS-outage authorization: when the sidecar is unreachable (as it is in
    /// this harness — the default sidecar URL is not served), a DID must STILL
    /// be unable to read or mutate an entry in a feed it does not subscribe to.
    /// This guards the `resolve_subscriptions` fallback: it must fail CLOSED
    /// (serve only the DID's own `sub_ref`), never widen the caller's surface to
    /// every cached feed.
    #[tokio::test]
    async fn pds_outage_does_not_widen_cross_did_access() {
        let did_a = "did:plc:aaaa";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did_a, None, "test", None)
            .await
            .unwrap();

        // Shared cache: feed_a (A subscribes) + feed_b (A does NOT). An entry
        // lives in feed_b — the one A must never touch during the outage.
        let feed_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://a.example/feed.xml".to_string(),
                title: Some("A".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let feed_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://b.example/feed.xml".to_string(),
                title: Some("B".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed_b,
            &[store::NewEntry {
                guid: "b-1".to_string(),
                url: Some("https://b.example/1".to_string()),
                title: Some("B one".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                content_html: Some("<p>secret B body</p>".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        // A subscribes ONLY to feed_a.
        store::replace_sub_refs(&state.db, did_a, &[feed_a])
            .await
            .unwrap();
        // Read B's entry id via a transient sub_ref, then drop it so only the
        // shared cache holds B's entry (no DID subscribes to feed_b anymore).
        store::replace_sub_refs(&state.db, "did:plc:bbbb", &[feed_b])
            .await
            .unwrap();
        let b_entry_id = store::entries_for_feed(&state.db, "did:plc:bbbb", feed_b)
            .await
            .unwrap()[0]
            .id;
        store::replace_sub_refs(&state.db, "did:plc:bbbb", &[])
            .await
            .unwrap();

        let cookie = session_cookie(&state, did_a, None);
        let app = router(state.clone());

        // GET /entries/{b} as A → 404 even during the outage.
        let get_b = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/entries/{b_entry_id}"))
                    .header(header::COOKIE, cookie.clone())
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            get_b.status(),
            StatusCode::NOT_FOUND,
            "A must not read B's entry during a PDS outage"
        );

        // POST /entries/{b}/read as A → 404, and no entry_state row is written.
        let read_b = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{b_entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            read_b.status(),
            StatusCode::NOT_FOUND,
            "A must not mark B's entry read during a PDS outage"
        );

        // The fallback must NOT have widened A's sub_ref to feed_b.
        let a_feed_ids: Vec<i64> = sqlx::query_scalar("SELECT feed_id FROM sub_ref WHERE did = ?1")
            .bind(did_a)
            .fetch_all(&state.db)
            .await
            .unwrap();
        assert_eq!(
            a_feed_ids,
            vec![feed_a],
            "outage fallback must not add feeds A never subscribed to"
        );
        // And B's entry has zero read-state (A's attempt did not mutate).
        let es_count: i64 =
            sqlx::query_scalar("SELECT COUNT(*) FROM entry_state WHERE did = ?1 AND entry_id = ?2")
                .bind(did_a)
                .bind(b_entry_id)
                .fetch_one(&state.db)
                .await
                .unwrap();
        assert_eq!(es_count, 0, "no cross-DID mutation during the outage");
    }

    /// **A logout with nothing to revoke is a SUCCESS — on the arm that had
    /// nothing. The other arm is counted separately.**
    ///
    /// Logout is idempotent, so `NoSession` must record as ok; counting it as an
    /// error would make the metric noisy in exactly the case that is fine.
    ///
    /// But `revoke_everywhere` has TWO arms, and a review found that counting
    /// only the rust one let `oauth_revoke` report all-clear while every sidecar
    /// revocation failed. For anyone who logged in before the cutover the sidecar
    /// store is the only one holding tokens, so the rust arm correctly says
    /// NoSession and the metric said nothing was wrong. Both arms are now
    /// recorded, distinguished by the backend column — so this test pins the
    /// BACKEND as well as the outcome.
    #[tokio::test]
    async fn a_logout_with_no_session_counts_as_success() {
        let did = "did:plc:aaaa";
        let state = test_state(&[]).await;
        assert!(
            state.oauth.is_some(),
            "meaningless without an oauth runtime; the revoke arm would be skipped",
        );

        revoke_everywhere(&state, did).await;
        let rows = state.metrics.snapshot();
        let find = |b: crate::metrics::Backend| {
            rows.iter()
                .find(|r| r.op == "oauth_revoke" && r.backend == b)
                .unwrap_or_else(|| panic!("no oauth_revoke row for {b:?}"))
        };

        // Rust arm: nothing stored for this DID, so NoSession -> ok.
        let rust = find(crate::metrics::Backend::Rust);
        assert_eq!(
            rust.stats.err_count, 0,
            "NoSession was counted as a failure; logout is idempotent",
        );
        assert_eq!(rust.stats.ok_count, 1);

        // Sidecar arm: unreachable in a test, so it must be recorded as an
        // ERROR under its own backend — not silently dropped, and not folded
        // into the rust row.
        let sidecar = find(crate::metrics::Backend::Sidecar);
        assert_eq!(
            sidecar.stats.err_count, 1,
            "a failed sidecar revoke was not counted",
        );
    }

    /// **`Failed` must count as an error — the half the metric exists for.**
    ///
    /// A review found this unpinned: replacing the mapping with
    /// `let revoke_ok = true;` passed all 682 tests. The only revoke test
    /// asserted the `NoSession -> ok` half, so the branch that actually means
    /// "the PDS still holds tokens we asked it to drop" was untested.
    ///
    /// Driven through the same handler, with a session present but the PDS
    /// unreachable, so `sign_out_discovering` returns `Failed`.
    #[tokio::test]
    async fn a_failed_rust_revoke_counts_as_an_error() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let state = test_state(&[]).await;
        let runtime = state.oauth.as_deref().expect("oauth runtime");
        crate::oauth::store::put_session(
            &state.db,
            &runtime.codec,
            &crate::oauth::store::OAuthSession {
                sub: did.into(),
                issuer: "https://auth.invalid".into(),
                aud: "https://pds.invalid".into(),
                dpop_key_jwk: crate::oauth::keys::SigningKey::generate("session-dpop")
                    .to_jwk_json()
                    .unwrap(),
                access_token: "at".into(),
                refresh_token: "rt".into(),
                token_type: "DPoP".into(),
                granted_scope: "atproto".into(),
                expires_at: Some(crate::store::now_unix() + 3600),
            },
        )
        .await
        .unwrap();

        revoke_everywhere(&state, did).await;

        let rows = state.metrics.snapshot();
        let rust = rows
            .iter()
            .find(|r| r.op == "oauth_revoke" && r.backend == crate::metrics::Backend::Rust)
            .expect("no rust oauth_revoke row");
        assert_eq!(
            rust.stats.err_count, 1,
            "an unreachable PDS must count as a revocation failure",
        );
        assert_eq!(rust.stats.ok_count, 0);
    }

    /// **The `href` defence is now carried by the TYPE, not by remembering.**
    ///
    /// `EntryRow.link` used to be a `String`, and the guard was "call
    /// `net::safe_link` before assigning it". Deleting that call left all 679
    /// tests passing — a live XSS defence with nothing protecting it.
    ///
    /// `SafeLink` has no `From<String>` and no public member, so the only way to
    /// get foreign input into an `href` is `external`, which does the check
    /// itself. This test pins that constructor; the *wiring* is now pinned by
    /// the compiler, which is the part a test could never hold down.
    ///
    /// Note the empty-not-absent behaviour: a rejected URL yields an EMPTY link
    /// so the template renders the row WITHOUT an anchor. Dropping the row
    /// instead would make the record unremovable, because the un-save button
    /// lives on it.
    #[test]
    fn a_hostile_scheme_cannot_reach_an_href_through_safelink() {
        for hostile in [
            "javascript:alert(1)",
            "JavaScript:alert(1)",
            "  javascript:alert(1)",
            "data:text/html;base64,PHNjcmlwdD4=",
            "vbscript:msgbox(1)",
            "file:///etc/passwd",
            // Protocol-relative: inherits the page's scheme, so it is an
            // off-site link wearing a same-site costume. Carried over from the
            // test this one replaces, which was its only unique input.
            "//evil.example/path",
        ] {
            let link = SafeLink::external(hostile);
            assert!(
                link.is_empty(),
                "{hostile:?} produced a non-empty href: {link}",
            );
            assert!(
                !link.to_string().to_ascii_lowercase().contains("script"),
                "{hostile:?} leaked into the rendered link",
            );
        }

        // And the other direction: a check that rejects everything would satisfy
        // the loop above while breaking every real saved record.
        for good in ["https://example.com/a?b=c#d", "http://example.com/"] {
            let link = SafeLink::external(good);
            assert!(!link.is_empty(), "{good:?} was wrongly rejected");
            assert_eq!(link.to_string(), good);
        }
    }

    /// **The WIRING, not the helper — this is the one that catches the real
    /// mistake.**
    ///
    /// `a_hostile_scheme_cannot_reach_an_href_through_safelink` pins what
    /// `SafeLink::external` *does*. It cannot pin that the saved-record path
    /// *calls* it, and a review proved that gap was live twice over: swapping
    /// `external` for the app-path constructor, and constructing the tuple
    /// directly, both restored the whole `javascript:` hole with every test
    /// green. The type now blocks both — `entry` takes an `i64`, and the field
    /// lives in another module — but the wiring deserves a test of its own
    /// rather than resting on the shape of a signature.
    ///
    /// Renders the actual row through the actual handler, from a record whose
    /// URL is hostile.
    #[tokio::test]
    async fn a_saved_record_with_a_hostile_url_renders_no_anchor() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let sidecar = spawn_saved_sidecar("javascript:alert(1)", "Hostile record").await;
        let mut state = test_state_with_sidecar(&[did], &sidecar).await;
        std::sync::Arc::get_mut(&mut state.config).unwrap().dev_did = Some(did.to_string());

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/?view=starred")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Not in an href, and not as the title either — the title falls back to
        // the URL for links we DO render, so both paths must withhold it.
        assert!(
            !body.to_ascii_lowercase().contains("javascript:"),
            "the hostile scheme reached the rendered page",
        );
        // But the row must survive: the un-save button lives on it, so dropping
        // the row would make the record unremovable from here.
        assert!(
            body.contains("unusable link"),
            "the row was dropped instead of rendering without an anchor",
        );
    }

    /// **The reader view's two `href`s, through the actual handler.**
    ///
    /// The sibling above covers the LIST row. `entry.html` has its own pair of
    /// `href`s fed by `EntryTemplate.url`, and they were a raw `Option<String>`
    /// taken straight off the `entries.url` column — a remote feed's `<link>`.
    ///
    /// Ingest already scheme-checks that column (`feed.rs`'s `entry_link`), so
    /// this was never a live hole. But that guard is procedural and sits a long
    /// way from the `href`: it holds only as long as every future writer to
    /// `entries.url` remembers to go through `feed.rs`. This test does not
    /// depend on it — it writes the hostile URL into the column DIRECTLY, which
    /// is precisely the state the ingest check cannot speak for.
    ///
    /// **Both directions, deliberately.** A fix that renders no link at all
    /// satisfies every negative assertion here, and would break every real
    /// entry. The second half is what makes the first half mean something.
    #[tokio::test]
    async fn a_hostile_entry_url_renders_the_reader_without_an_original_link() {
        let did = "did:plc:readerhref";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://href.example/feed.xml".to_string(),
                title: Some("Href".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // Straight into the column, bypassing `feed.rs` — the whole point.
        store::insert_entries(
            &state.db,
            feed,
            &[
                store::NewEntry {
                    guid: "hostile-1".to_string(),
                    url: Some("javascript:alert(1)".to_string()),
                    title: Some("Hostile entry".to_string()),
                    published: Some("2026-07-11T00:00:00Z".to_string()),
                    ..Default::default()
                },
                store::NewEntry {
                    guid: "benign-1".to_string(),
                    url: Some("https://href.example/post".to_string()),
                    title: Some("Benign entry".to_string()),
                    published: Some("2026-07-10T00:00:00Z".to_string()),
                    ..Default::default()
                },
            ],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let rows = store::entries_for_feed(&state.db, did, feed).await.unwrap();
        let id_of = |guid: &str| {
            rows.iter()
                .find(|r| r.guid == guid)
                .unwrap_or_else(|| panic!("{guid} was not inserted"))
                .id
        };

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let render = |id: i64| {
            let app = app.clone();
            let cookie = cookie.clone();
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .method("GET")
                            .uri(format!("/entries/{id}"))
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                String::from_utf8(
                    axum::body::to_bytes(resp.into_body(), usize::MAX)
                        .await
                        .unwrap()
                        .to_vec(),
                )
                .unwrap()
            }
        };

        let hostile = render(id_of("hostile-1")).await;
        // The reader page for THIS entry actually rendered. Without this the
        // three negatives below are satisfied by an empty body.
        assert!(
            hostile.contains("Hostile entry"),
            "the reader did not render the entry: {hostile}",
        );
        assert!(
            !hostile.to_ascii_lowercase().contains("javascript:"),
            "the hostile scheme reached the reader page: {hostile}",
        );
        // Not merely escaped — the template took its no-link branch. Both
        // `href`s are gated on the same `Option`, so this covers the byline
        // link and the action-bar button together.
        assert!(
            !hostile.contains("actionbar-open"),
            "the action bar rendered an open-original link for a refused URL: {hostile}",
        );
        assert!(
            !hostile.contains("Original \u{2197}"),
            "the byline rendered an original link for a refused URL: {hostile}",
        );

        // The other direction: a legitimate entry still links out, so "render
        // nothing" cannot pass as a fix.
        let benign = render(id_of("benign-1")).await;
        assert!(
            benign.contains("Benign entry"),
            "the reader did not render the benign entry: {benign}",
        );
        // BOTH `href`s, counted. The negatives above fire on the action bar
        // first, so without this the byline needle `Original \u{2197}` is never
        // once observed failing — a misspelled needle would pass forever.
        assert_eq!(
            benign
                .matches(r#"href="https://href.example/post""#)
                .count(),
            2,
            "entry.html has two `href`s for the entry URL — the byline link and \
             the action-bar button — and this render produced a different \
             number: {benign}",
        );
        assert!(
            benign.contains("actionbar-open"),
            "a legitimate entry lost its open-original button: {benign}",
        );
        assert!(
            benign.contains("Original \u{2197}"),
            "a legitimate entry lost its byline link: {benign}",
        );
    }

    /// **The outage fallback must not widen what the caller can READ — and the
    /// sibling test above can only see what it WRITES.**
    ///
    /// `pds_outage_does_not_widen_cross_did_access` asserts on `sub_ref` rows and
    /// on `entry_state`: the fallback's side effects. But the fail-open it names
    /// returns **early**, before `sync_sub_refs` runs, so it touches neither. It
    /// leaks through the list it *hands back* — the sidebar and the reader render
    /// from that list, so a caller sees another DID's feeds while `sub_ref` stays
    /// perfectly honest and every existing assertion stays green.
    ///
    /// Measured, not assumed: replacing `feeds_for_did(pool, did)` with
    /// `due_feeds(pool, "9999-…", 10_000)` over the whole shared cache — the
    /// exact historical bug the fallback's comment describes — left **all 663
    /// tests passing**. Cross-tenant isolation is the one property this project
    /// cannot regress quietly, and nothing observed it.
    ///
    /// So this asserts on the RETURN VALUE, which is the thing that reaches the
    /// user, and it deliberately does not look at `sub_ref` at all — that half is
    /// already covered above.
    #[tokio::test]
    async fn the_outage_fallback_returns_only_the_callers_own_feeds() {
        let did_a = "did:plc:aaaa";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did_a, None, "test", None)
            .await
            .unwrap();

        let feed_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://a.example/feed.xml".to_string(),
                title: Some("A".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let _feed_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://b.example/feed.xml".to_string(),
                title: Some("B".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // A subscribes ONLY to feed_a. feed_b is in the shared cache and belongs
        // to nobody — exactly the row a whole-cache fallback would hand to A.
        store::replace_sub_refs(&state.db, did_a, &[feed_a])
            .await
            .unwrap();

        // No sidecar and no PDS are reachable from a test, so
        // `list_subscriptions_sorted` fails and this IS the outage path. Assert
        // that, rather than assuming it: if the repo ever starts succeeding here,
        // this test would silently stop exercising the fallback at all.
        assert!(
            state.repo().list_subscriptions_sorted(did_a).await.is_err(),
            "this test is only meaningful on the outage path; the repo answered",
        );

        let resolved = resolve_subscriptions(&state, did_a).await;

        let urls: Vec<&str> = resolved.iter().map(|r| r.sub.url.as_str()).collect();
        assert_eq!(
            urls,
            vec!["https://a.example/feed.xml"],
            "the outage fallback must return the caller's OWN subscriptions only; \
             any other feed here is cross-tenant read access granted by an outage",
        );
    }

    /// Build an [`AppState`] over a fresh in-memory DB with explicit feed caps,
    /// seeding `did` a beta seat + session-capable state.
    async fn test_state_with_caps(
        did: &str,
        max_subs_per_did: i64,
        max_feeds_global: i64,
    ) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 100,
            max_subs_per_did,
            max_feeds_global,
            ..Config::default()
        };
        store::grant_access(&db, did, None, "test", None)
            .await
            .unwrap();
        AppState::new(config, db).unwrap()
    }

    /// An OPML document with `n` distinct public feeds.
    fn opml_with_feeds(n: usize) -> String {
        let mut outlines = String::new();
        for i in 0..n {
            outlines.push_str(&format!(
                "<outline type=\"rss\" text=\"F{i}\" xmlUrl=\"https://f{i}.example/feed.xml\"/>\n"
            ));
        }
        format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n{outlines}</body></opml>"
        )
    }

    /// OPML bulk import must honour the GLOBAL feeds ceiling: importing more
    /// distinct new feeds than the shared cache can hold caches only up to the
    /// ceiling — the rest are trimmed. (Regression: the import loop previously
    /// bypassed `max_feeds_global` entirely.)
    #[tokio::test]
    async fn opml_import_enforces_global_feeds_ceiling() {
        let did = "did:plc:importer";
        // Cap the shared cache at 3 feeds; import 10 distinct new ones.
        let state = test_state_with_caps(did, 0, 3).await;
        let cookie = session_cookie(&state, did, None);
        let (ct, body) = opml_multipart(opml_with_feeds(10).as_bytes());
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let feeds = store::count_feeds(&state.db).await.unwrap();
        assert!(
            feeds <= 3,
            "OPML import blew past the global ceiling: {feeds} feeds cached with cap=3"
        );
    }

    /// POST an OPML of `n` feeds as `did` against a strict fake PDS behind the
    /// sidecar, and return the flash it redirected with plus the fake's log.
    async fn import_against_strict_pds(
        did: &str,
        n: usize,
        fail_call: Option<usize>,
    ) -> (String, crate::atproto::tests::ApplyWritesLog) {
        let (sidecar, log) = crate::atproto::tests::serve_apply_writes(fail_call).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let (ct, body) = opml_multipart(opml_with_feeds(n).as_bytes());
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp.headers()[header::LOCATION].to_str().unwrap();
        let flash = url::Url::parse(&format!("http://x{loc}"))
            .unwrap()
            .query_pairs()
            .find(|(k, _)| k == "flash")
            .map(|(_, v)| v.into_owned())
            .unwrap_or_default();
        (flash, log)
    }

    /// **An OPML import of more than 200 feeds succeeds** against a PDS that
    /// refuses more than 200 writes a call, as the reference PDS does. It used
    /// to go out as one `applyWrites` and fail outright, importing nothing.
    #[tokio::test]
    async fn opml_import_of_450_feeds_succeeds_against_a_pds_capping_at_200() {
        let (flash, log) = import_against_strict_pds("did:plc:bigimport", 450, None).await;
        assert_eq!(flash, "Imported 450 feeds", "{flash}");
        assert_eq!(crate::atproto::tests::call_sizes(&log), vec![200, 200, 50]);
    }

    /// **A part-landed import says so.** Chunk 2 of 3 fails: chunk 1's 200
    /// feeds are in the reader's repo, and "nothing was imported" — what the
    /// handler said for any failure — would be false.
    #[tokio::test]
    async fn opml_import_that_part_lands_reports_what_landed() {
        let (flash, log) = import_against_strict_pds("did:plc:partimport", 450, Some(2)).await;
        assert_eq!(crate::atproto::tests::call_sizes(&log), vec![200, 200]);
        assert!(
            flash.contains("200 of 450"),
            "the landed count is not reported: {flash}"
        );
        assert!(
            !flash.contains("nothing was imported"),
            "200 feeds landed and the reader was told none did: {flash}"
        );
    }

    /// A batch that failed on its first call still reports that nothing was
    /// imported — true, since nothing after a failed call is sent.
    #[tokio::test]
    async fn opml_import_that_fails_on_the_first_call_imports_nothing() {
        let (flash, log) = import_against_strict_pds("did:plc:noimport", 450, Some(1)).await;
        assert_eq!(crate::atproto::tests::call_sizes(&log), vec![200]);
        assert!(flash.contains("nothing was imported"), "{flash}");
    }

    /// **A malformed `at://` on the add path is "not a kind of feed we take",
    /// not "private/paid".** The first gate was the privacy classifier, whose
    /// at:// arm fails closed as `Private` for anything not a well-formed
    /// publication URI — so a typo (`did:plc:TOOSHORT`, a missing rkey) drew
    /// the private-feed flash and a "refused private/paid feed" log line. On
    /// main the same input reached `resolve_feed_url` and got "Couldn't find a
    /// feed". Storability is decided first for an at:// input, with its own
    /// message.
    #[tokio::test]
    async fn a_malformed_at_uri_on_the_add_path_is_refused_as_unsupported_not_private() {
        let did = "did:plc:typoist";
        let state = test_state_with_caps(did, 0, 0).await;
        let cookie = session_cookie(&state, did, None);
        for input in [
            "at%3A%2F%2Falice.example.com%2Fsite.standard.publication",
            "at%3A%2F%2Fdid%3Aplc%3ATOOSHORT%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
        ] {
            let resp = router(state.clone())
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/subscriptions")
                        .header(header::COOKIE, cookie.clone())
                        .header("content-type", "application/x-www-form-urlencoded")
                        .body(Body::from(format!("url={input}")))
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::SEE_OTHER);
            let loc = resp
                .headers()
                .get(header::LOCATION)
                .unwrap()
                .to_str()
                .unwrap();
            assert!(
                loc.contains("kind%20of%20feed"),
                "expected the unsupported-feed flash for {input}, got {loc}"
            );
            assert!(
                !loc.contains("Private"),
                "a storability refusal was reported as a privacy one for {input}: {loc}"
            );
        }
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// **An OPML entry this instance cannot store is counted and reported, not
    /// silently dropped.** The storability `continue` incremented nothing,
    /// while the privacy branch beside it produced a user-visible label — so
    /// an OPML exported from a standard.site-enabled instance imported
    /// "successfully" with entries missing and no reason given. The reader is
    /// told how many, and why.
    #[tokio::test]
    async fn opml_import_reports_entries_this_instance_cannot_store() {
        let did = "did:plc:renamer4";
        let (sidecar, _puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        assert!(!state.config.standard_site);
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Real\" xmlUrl=\"https://real.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Pub\" xmlUrl=\"{AT_URI_SUB}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Imported%201%20feed"),
            "unexpected flash: {loc}"
        );
        assert!(
            loc.contains("1%20feed%28s%29%20skipped") && loc.contains("can%20subscribe%20to"),
            "the dropped entry was not reported: {loc}"
        );
        // Reported by count only: the at-URI itself is not echoed back.
        assert!(
            !loc.contains("site.standard.publication"),
            "the URI was echoed: {loc}"
        );
    }

    /// OPML bulk import must honour the PER-DID subscription cap: a DID at its
    /// cap imports zero new feeds.
    #[tokio::test]
    async fn opml_import_enforces_per_did_cap() {
        let did = "did:plc:capped";
        // Per-DID cap 2, global unlimited. Pre-seed the DID at its cap.
        let state = test_state_with_caps(did, 2, 0).await;
        let existing_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have-a.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let existing_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have-b.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[existing_a, existing_b])
            .await
            .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();

        let cookie = session_cookie(&state, did, None);
        let (ct, body) = opml_multipart(opml_with_feeds(10).as_bytes());
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        // Headroom was 0 → no new feeds imported into the shared cache.
        let after = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(after, before, "over-cap DID imported new feeds anyway");
    }

    /// Single-add per-DID cap: a DID at its subscription cap is refused before
    /// any fetch, with the limit flash.
    #[tokio::test]
    async fn single_add_enforces_per_did_cap() {
        let did = "did:plc:subcapped";
        let state = test_state_with_caps(did, 1, 0).await;
        let f = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[f]).await.unwrap();
        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("url=https://another.example/feed.xml"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Subscription%20limit%20reached"),
            "expected sub-limit flash, got {loc}"
        );
    }

    /// `GET /` renders at most one page of rows and offers a way to the rest.
    ///
    /// The handler used to materialize EVERY unread entry — `SELECT e.*`, no
    /// `LIMIT`, article bodies included — and hand the lot to the template. With
    /// 250 entries that is the whole list in one response; with a real backlog on
    /// a 512 MB box it is the OOM the operator review flagged. Asserts the page
    /// is capped, the heading still reports the true total, and page 2 is
    /// reachable and disjoint.
    #[tokio::test]
    async fn the_reader_index_pages_instead_of_rendering_everything() {
        let did = "did:plc:pager";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://pager.example/feed.xml".to_string(),
                title: Some("Pager".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let total = 250_usize;
        let entries: Vec<store::NewEntry> = (0..total)
            .map(|i| store::NewEntry {
                guid: format!("p-{i:04}"),
                url: Some(format!("https://pager.example/{i}")),
                title: Some(format!("Article {i:04}")),
                published: Some(format!("2026-07-{:02}T00:00:00Z", (i % 28) + 1)),
                content_html: Some("x".repeat(4_000)),
                ..Default::default()
            })
            .collect();
        store::insert_entries(&state.db, feed, &entries, 0)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let get = |uri: &str| {
            let app = app.clone();
            let cookie = cookie.clone();
            let uri = uri.to_string();
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .uri(uri)
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                let bytes = axum::body::to_bytes(resp.into_body(), 8 * 1024 * 1024)
                    .await
                    .unwrap();
                String::from_utf8(bytes.to_vec()).unwrap()
            }
        };

        let page1 = get("/").await;
        // One `<li class="entry…>` per rendered row. Counting "/entries/" would
        // over-count: each row carries several (the link plus the read/star
        // forms).
        let rows1 = page1.matches("<li class=\"entry").count();
        assert!(
            rows1 <= ENTRIES_PER_PAGE as usize,
            "page 1 rendered {rows1} entry links; the list is unbounded"
        );
        assert!(
            rows1 > 0,
            "page 1 rendered nothing at all: the page bound swallowed the list"
        );
        // The count is the TRUE total, not the page size — otherwise paging
        // would quietly relabel a 250-entry backlog as a 100-entry one.
        assert!(
            page1.contains("250 entries"),
            "heading must report the full total, not the page"
        );
        assert!(
            page1.contains("page=2"),
            "no way to reach the rest of the list: {}",
            &page1[..page1.len().min(400)]
        );
        // The body never belongs in a list response.
        assert!(
            !page1.contains(&"x".repeat(4_000)),
            "the list response carried an article body"
        );

        let page2 = get("/?page=2").await;
        assert!(
            page2.matches("<li class=\"entry").count() > 0,
            "page 2 rendered no rows at all"
        );
        assert!(
            page2.contains("page=1") || page2.contains("Newer"),
            "page 2 offers no way back"
        );
        // Disjoint: an article on page 1 must not reappear on page 2.
        let first_title = (0..total)
            .map(|i| format!("Article {i:04}"))
            .find(|t| page1.contains(t))
            .expect("page 1 shows at least one titled article");
        assert!(
            !page2.contains(&first_title),
            "{first_title} appears on both pages"
        );

        // A page past the end must not be a dead end. The empty state renders
        // instead of the pager, so an out-of-range page would leave a reader
        // with no link back — reachable by typing a number, and reachable
        // WITHOUT typing anything by paging to the end and then marking entries
        // read, which shrinks the list under the URL already in the address bar.
        let past_end = get("/?page=999").await;
        assert!(
            past_end.matches("<li class=\"entry").count() > 0,
            "an out-of-range page rendered nothing and offered no way back"
        );
        assert!(
            past_end.contains("page=2"),
            "the clamped page offers no pager"
        );
    }

    /// Reader-view mark-read (a request tagged `X-FR-Reader: 1`) must return the
    /// out-of-band action-bar fragment with FRESHLY re-read state so a second
    /// keypress reverses the toggle: `hx-swap-oob="outerHTML"` is present, and
    /// the hidden `read` input + `aria-pressed` reflect the NEW state. The list
    /// view (no reader header) instead swaps the row. This guards the reader OOB
    /// toggle wiring, which had no test.
    #[tokio::test]
    async fn reader_mark_read_returns_oob_actionbar_with_flipped_state() {
        let did = "did:plc:reader";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://reader.example/feed.xml".to_string(),
                title: Some("Reader".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed,
            &[store::NewEntry {
                guid: "r-1".to_string(),
                url: Some("https://reader.example/1".to_string()),
                title: Some("Article".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                content_html: Some("<p>body</p>".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let entry_id = store::entries_for_feed(&state.db, did, feed).await.unwrap()[0].id;

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        // Reader-tagged mark-read → OOB action-bar fragment, entry now READ.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie.clone())
                    .header("HX-Request", "true")
                    .header("X-FR-Reader", "1")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(
            html.contains("hx-swap-oob=\"outerHTML\""),
            "reader response must be an OOB swap: {html}"
        );
        assert!(
            html.contains(r#"id="entry-actionbar""#),
            "reader response must be the action-bar fragment: {html}"
        );
        // Now READ: the read button reflects it (aria-pressed=true) and the
        // hidden value flips to `false` so the next tap marks it UNREAD.
        assert!(
            html.contains(r#"aria-pressed="true""#),
            "read button must show pressed after marking read: {html}"
        );
        assert!(
            html.contains(r#"name="read" value="false""#),
            "hidden read value must flip to false so a second tap reverses: {html}"
        );

        // A second reader mark-read (submitting the flipped `read=false`) marks
        // it UNREAD again — the toggle reverses.
        let resp2 = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("HX-Request", "true")
                    .header("X-FR-Reader", "1")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=false"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp2.status(), StatusCode::OK);
        let bytes2 = axum::body::to_bytes(resp2.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html2 = String::from_utf8(bytes2.to_vec()).unwrap();
        assert!(
            html2.contains(r#"aria-pressed="false""#),
            "read button must show un-pressed after reversing: {html2}"
        );
        assert!(
            html2.contains(r#"name="read" value="true""#),
            "hidden read value must flip back to true: {html2}"
        );
    }

    /// The LIST view (no `X-FR-Reader` header) swaps the row, not the OOB
    /// action-bar — the counterpart to the reader-OOB test above.
    #[tokio::test]
    async fn list_mark_read_returns_row_not_oob_actionbar() {
        let did = "did:plc:listv";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://list.example/feed.xml".to_string(),
                title: Some("List".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed,
            &[store::NewEntry {
                guid: "l-1".to_string(),
                url: Some("https://list.example/1".to_string()),
                title: Some("Article".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let entry_id = store::entries_for_feed(&state.db, did, feed).await.unwrap()[0].id;

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("HX-Request", "true")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(
            !html.contains("hx-swap-oob"),
            "list-view response must NOT be an OOB swap: {html}"
        );
        // **And it must actually BE the row.** The assertion above is satisfied
        // by an empty body, or by any response that simply omits the attribute —
        // so on its own it pins half a property and the name promises the other
        // half.
        assert!(
            html.contains(&format!("/entries/{entry_id}")),
            "the response is not the row for this entry: {html}",
        );
        assert!(
            html.contains("Article"),
            "the row rendered without its title: {html}",
        );
        // **The row comes back carrying read state. That is all this proves.**
        //
        // It does NOT prove the state was persisted: the handler renders
        // `Some(read)` from the form value, so making `mark_read` roll back
        // instead of commit fails 11 store tests and leaves this one green.
        //
        // It does not prove the OVERRIDE either, which an earlier version of
        // this comment claimed. Verified: changing the call site to
        // `build_entry_row(pool, &did, id, None)` — deleting the override
        // wholesale — keeps the whole suite green, because `mark_read` has
        // already persisted the same value two lines earlier, so reading it back
        // from the database produces an identical row.
        //
        // Distinguishing the two needs a case where the override and the stored
        // state DISAGREE, which this handler never produces: it writes the value
        // it then renders. Left as a known gap rather than described as covered.
        assert!(
            html.contains("is-read"),
            "the row came back without the read state it was just given: {html}",
        );
    }

    // -----------------------------------------------------------------------
    // Rename parity (POST /subscriptions/{rkey}/rename)
    // -----------------------------------------------------------------------

    /// **Autodiscovery cannot smuggle a non-http(s) URL into storage.**
    ///
    /// The add path gates the URL the user *typed*; the URL it *stores* is
    /// whatever `resolve_feed_url` returns, which for an HTML page is a
    /// publisher-controlled `<link rel="alternate">` href. Two layers stop
    /// that: `discover_feed` yields only http(s), and the add path re-checks
    /// storability on the resolved URL. This test pins the DISJUNCTION —
    /// each layer alone holds it, both removed fails it — driven through the
    /// real route against a real local server.
    ///
    /// **Why the fixture is `ftp://`, not `at://`.** This began as the
    /// at-URI bypass test from #164, and it was vacuous twice over. Handle
    /// form: once storage became DID-only the privacy classifier refused it
    /// at its own gate. DID form: `Url::parse` cannot read it (invalid port
    /// — the colons in the DID), so `discover_feed` drops it before either
    /// layer exists. An at:// link cannot come out of autodiscovery under
    /// ANY mutation of the layers, so no test through this route can pin
    /// them with one. `ftp://` reaches both. The at:// case is guaranteed by
    /// structure and pinned where it lives: `discover_skips_a_non_http_
    /// alternate` and the storability tests in `feed.rs`.
    #[tokio::test]
    async fn autodiscovery_cannot_smuggle_a_non_http_url_into_storage() {
        let did = "did:plc:autodiscovered";
        // Access granted, both caps disabled — the only gates left are the
        // two under test.
        let state = test_state_with_caps(did, 0, 0).await;

        let page = r#"<!doctype html><html><head><title>Blog</title>
            <link rel="alternate" type="application/rss+xml" href="ftp://files.example/feed.xml">
            </head><body>hi</body></html>"#;
        let base = crate::net::tests::serve_body(page.as_bytes().to_vec()).await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        crate::net::test_host_override(
            "autodiscover-ftp.test",
            std::net::SocketAddr::from(([127, 0, 0, 1], port)),
        );

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!(
                        "url=http://autodiscover-ftp.test:{port}/"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_ne!(loc, "/login", "the test never reached the add path");
        assert_ne!(loc, "/", "the subscribe succeeded");

        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            0,
            "a non-http(s) URL from autodiscovery was stored"
        );
        assert_eq!(
            store::count_subscriptions_for_did(&state.db, did)
                .await
                .unwrap(),
            0
        );
    }

    /// A rename that points at a BRAND-NEW feed URL while the shared cache is at
    /// its global ceiling must be refused (capacity flash) and must NOT insert a
    /// new `feeds` row — parity with add_subscription's global-cap guard, so a
    /// rename loop can't inflate the shared cache past the cap.
    #[tokio::test]
    async fn rename_to_new_url_refused_at_global_feeds_cap() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        // Global cap 1; pre-fill it with one feed so headroom is 0.
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://existing.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(before, 1);

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // A URL not in the cache → would be a NEW feeds row.
                    .body(Body::from(
                        "url=https://brand-new.example/feed.xml&title=Renamed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("feed%20capacity"),
            "expected the feed-capacity flash, got {loc}"
        );
        // No new feeds row was inserted, and nothing reached the PDS.
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), before);
        assert!(
            puts.lock().unwrap().is_empty(),
            "a refused repoint reached the PDS"
        );
    }

    /// A repoint to an EXISTING URL adds no row, so it is allowed even at the
    /// global cap (only new URLs are gated) — the other half of the guard.
    ///
    /// On the sidecar fake, so "allowed" means the put actually happened: the
    /// earlier harness had no sidecar, and this passed on a "could not reach
    /// your PDS" flash that merely was not the capacity one.
    #[tokio::test]
    async fn rename_to_existing_url_allowed_at_global_feeds_cap() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://existing.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https://existing.example/feed.xml&title=Retitled",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(loc, "/", "the repoint to a cached URL was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the repoint did not reach the PDS"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), before);
    }

    /// A rename with a blank URL writes nothing anywhere.
    #[tokio::test]
    async fn rename_with_blank_url_writes_nothing() {
        let did = "did:plc:renamer3";
        let state = test_state_with_caps(did, 0, 0).await;
        let before = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(before, 0);

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rkey123/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Whitespace-only URL trims to empty.
                    .body(Body::from("url=%20%20&title=Nope"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers()
                .get(header::LOCATION)
                .unwrap()
                .to_str()
                .unwrap(),
            "/",
        );
        // Nothing was cached.
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            0,
            "blank-URL rename wrote a junk feeds row"
        );
    }

    /// A sidecar mock that serves ONE existing subscription record and captures
    /// every `put` body a rename produces.
    ///
    /// **Reads to `content-length` rather than taking one `read`.** A single
    /// read gets whatever one segment carried; if the head and body land
    /// separately the capture holds no record and every field assertion below
    /// passes for the wrong reason. Each captured body must also mention the
    /// collection, so an empty capture fails loudly instead of quietly.
    async fn spawn_rename_sidecar(
        existing: serde_json::Value,
    ) -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {
        use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let puts = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let sink = puts.clone();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut raw: Vec<u8> = Vec::new();
                let mut chunk = [0u8; 4096];
                let body_text = loop {
                    let Ok(n) = sock.read(&mut chunk).await else {
                        break String::new();
                    };
                    if n == 0 {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                    raw.extend_from_slice(&chunk[..n]);
                    let Some(split) = raw.windows(4).position(|w| w == b"\r\n\r\n") else {
                        continue;
                    };
                    let (head, body) = raw.split_at(split + 4);
                    let want = String::from_utf8_lossy(head).lines().find_map(|l| {
                        let (k, v) = l.split_once(':')?;
                        k.eq_ignore_ascii_case("content-length")
                            .then(|| v.trim().parse::<usize>().ok())?
                    });
                    if want.is_none_or(|want| body.len() >= want) {
                        break String::from_utf8_lossy(body).to_string();
                    }
                };

                // `"action":"put"` is the rename write; anything else is the read.
                let is_put = body_text.contains("\"action\":\"put\"");
                let data = if is_put {
                    sink.lock().unwrap().push(body_text.clone());
                    serde_json::json!({
                        "uri": "at://did:plc:x/community.lexicon.rss.subscription/rk-keep",
                        "cid": "bafyreiafter"
                    })
                } else {
                    serde_json::json!({ "records": [existing.clone()] })
                };
                let body = serde_json::json!({ "ok": true, "data": data }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        (format!("http://{addr}"), puts)
    }

    /// The existing record a rename must not destroy.
    fn seeded_subscription() -> serde_json::Value {
        serde_json::json!({
            "uri": "at://did:plc:renamer4/community.lexicon.rss.subscription/rk-keep",
            "cid": "bafyreibefore",
            "value": {
                "$type": "community.lexicon.rss.subscription",
                "url": "https://example.com/feed.xml",
                "title": "Old title",
                "siteUrl": "https://example.com/blog",
                "fetchHint": "hourly",
                "private": false,
                "createdAt": "2024-03-01T00:00:00.000Z"
            }
        })
    }

    /// An existing standard.site subscription, as the 19 in production are:
    /// written before this reader refused the scheme, still in the repo.
    fn seeded_at_uri_subscription() -> serde_json::Value {
        seeded_subscription_with_url(AT_URI_SUB)
    }
    /// An existing subscription record at `rk-keep` with the given URL.
    fn seeded_subscription_with_url(url: &str) -> serde_json::Value {
        serde_json::json!({
            "uri": "at://did:plc:renamer5/community.lexicon.rss.subscription/rk-keep",
            "cid": "bafyreibefore",
            "value": {
                "$type": "community.lexicon.rss.subscription",
                "url": url,
                "title": "Old title",
                "private": false,
                "createdAt": "2024-03-01T00:00:00.000Z"
            }
        })
    }
    const AT_URI_SUB: &str =
        "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/site.standard.publication/3lab2c4d5e6f7g8h";
    const AT_URI_SUB_ENC: &str =
        "at%3A%2F%2Fdid%3Aplc%3Aohutz6x5acjmpuulp3x7wxxc%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h";

    /// **Retitling an existing `at://` subscription must work with the flag off.**
    ///
    /// The storability guard was placed before the repo lookup, so it refused
    /// any rename whose URL is an at-URI — including a pure title or folder
    /// change on a record that already exists. On main that rename succeeded;
    /// the 19 production records would have become un-editable. The flag gates
    /// what may be STORED in the cache, not whether a reader may edit their own
    /// record: the PDS write goes through, the cache row is simply not created.
    #[tokio::test]
    async fn retitling_an_existing_at_uri_subscription_survives_the_flag_being_off() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        assert!(
            !state.config.standard_site,
            "the flag must be off for this test"
        );
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=New+title")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(loc, "/", "the retitle was refused: {loc}");

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        assert_eq!(
            sent["record"]["title"], "New title",
            "the rename did not apply"
        );
        assert_eq!(
            sent["record"]["url"], AT_URI_SUB,
            "the rename changed the URL"
        );

        // The flag still means what it says for the CACHE: no at:// row.
        let cached: i64 = store::count_unpollable_feeds(&state.db).await.unwrap();
        assert_eq!(cached, 0, "a retitle stored an at:// row with the flag off");
    }

    /// **Repointing a subscription AT an `at://` URI is still refused with the
    /// flag off** — the half of the guard that has to survive the fix above.
    /// Nothing reaches the PDS and nothing reaches the cache.
    #[tokio::test]
    async fn repointing_a_subscription_at_an_at_uri_is_refused_with_the_flag_off() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=Moved")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("flash="), "the repoint was not refused: {loc}");
        assert!(
            !loc.contains("Private"),
            "a storability refusal was reported as a privacy one: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "the repoint reached the PDS"
        );
        let cached: i64 = store::count_unpollable_feeds(&state.db).await.unwrap();
        assert_eq!(cached, 0);
    }

    /// Posts a retitle of `rk-keep` with its URL unchanged; returns the
    /// redirect location.
    async fn retitle_unchanged(state: &AppState, did: &str, url_enc: &str) -> String {
        let cookie = session_cookie(state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={url_enc}&title=New+title")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        resp.headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .to_string()
    }

    /// **The privacy gate has the same ordering bug the storable gate had.**
    ///
    /// Another client can write a subscription whose URL is an at-URI that is
    /// not a well-formed publication URI at all — a feed generator, say. On
    /// main a retitle of it succeeded (the DID form fails `Url::parse`, which
    /// the classifier reads as `Public`). The narrowed at:// arm now fails
    /// closed as `Private` for it, and the gate ran before `url_changed` was
    /// known — so the record became un-editable, with a flash claiming it "was
    /// not saved or sent anywhere". Both gates now apply to a repoint only.
    #[tokio::test]
    async fn retitling_an_existing_at_uri_record_that_is_not_a_publication_survives() {
        let did = "did:plc:renamer5";
        let other = "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/app.bsky.feed.generator/whats-hot";
        let other_enc =
            "at%3A%2F%2Fdid%3Aplc%3Aohutz6x5acjmpuulp3x7wxxc%2Fapp.bsky.feed.generator%2Fwhats-hot";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(other)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let loc = retitle_unchanged(&state, did, other_enc).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).unwrap();
        assert_eq!(sent["record"]["title"], "New title");
        assert_eq!(sent["record"]["url"], other);
    }

    /// **A repoint to a secret-bearing URL is still refused** — the half of
    /// the privacy gate that has to survive moving it behind `url_changed`.
    /// Found by mutation: with the gate deleted outright, nothing failed.
    #[tokio::test]
    async fn repointing_a_subscription_at_a_private_feed_is_refused() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fpaid.example%2Ffeed.xml%3Ftoken%3DZm9vYmFyc2VjcmV0dG9rZW4&title=Moved",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Private"),
            "the private repoint was not refused: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "a secret-bearing URL reached the PDS"
        );
        // The repo's fixture token: opaque enough for the classifier, not a real
        // key shape (a Stripe-shaped fixture tripped the secret scanner — rightly).
        let leaked = "https://paid.example/feed.xml?token=Zm9vYmFyc2VjcmV0dG9rZW4";
        assert!(store::get_feed_by_url(&state.db, leaked)
            .await
            .unwrap()
            .is_none());
    }

    /// **A retitle of a never-cached at:// subscription is not "at feed
    /// capacity".** The global-ceiling check keyed on "URL not in the cache",
    /// and an at:// record is never cached with the flag off — so at capacity,
    /// a pure retitle was refused for a row the handler would not insert. The
    /// check now runs once `url_changed` is known and only for a repoint.
    #[tokio::test]
    async fn retitling_an_uncached_at_uri_subscription_is_not_refused_at_feed_capacity() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        // Ceiling 1, and one real feed already fills it.
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let loc = retitle_unchanged(&state, did, AT_URI_SUB_ENC).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the retitle did not reach the PDS"
        );
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            1,
            "a row was inserted"
        );
    }

    /// POST `/subscriptions` with `url`, returning the redirect target.
    async fn subscribe(state: &AppState, did: &str, url_enc: &str) -> String {
        let cookie = session_cookie(state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={url_enc}")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        resp.headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .to_string()
    }

    /// A `com.atproto.identity.resolveHandle` that answers `did` for anything.
    async fn serve_resolver(did: &str) -> String {
        let base = crate::net::tests::serve_body(
            serde_json::json!({ "did": did }).to_string().into_bytes(),
        )
        .await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        let host = format!("resolver-{port}.test");
        crate::net::test_host_override(&host, std::net::SocketAddr::from(([127, 0, 0, 1], port)));
        format!("http://{host}:{port}")
    }

    fn with_config(mut state: AppState, f: impl FnOnce(&mut Config)) -> AppState {
        let mut config = (*state.config).clone();
        f(&mut config);
        state.config = std::sync::Arc::new(config);
        state
    }

    /// **0.4.0 step 3: with the flag ON, a well-formed at:// paste is
    /// subscribed.** It was refused as unsupported while nothing could read a
    /// publication; the poller reads them now. Stored in DID form, as a
    /// `publication`, and written to the reader's PDS like any subscription.
    #[tokio::test]
    async fn a_well_formed_at_uri_paste_is_subscribed_with_the_flag_on() {
        let did = "did:plc:renamer5";
        let (sidecar, log) = spawn_logging_sidecar().await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.oauth.plc_directory = "http://plc.nowhere.invalid".into();
            },
        );
        let loc = subscribe(&state, did, AT_URI_SUB_ENC).await;
        assert_eq!(loc, "/", "the paste was refused: {loc}");
        let row = store::get_feed_by_url(&state.db, AT_URI_SUB)
            .await
            .unwrap()
            .expect("no feed row");
        assert_eq!(feed::FeedKind::of(&row.url), feed::FeedKind::Publication);
        let sent = log.lock().unwrap().join("\n");
        assert!(
            sent.contains(AT_URI_SUB),
            "the subscription was not written to the PDS: {sent}"
        );
    }

    /// **A0 through the form** — the 0.4.0 exit test, end to end: a reader
    /// pastes a publication, it is stored and written to their PDS, and the
    /// first poll — the one subscribing runs at once — stores its documents.
    #[tokio::test]
    async fn a0_subscribing_from_the_form_delivers_entries() {
        let did = "did:plc:renamer5";
        let author = "did:plc:ohutz6x5acjmpuulp3x7wxxc";
        let site = AT_URI_SUB;
        let (plc, _) = crate::standard_site::tests::serve_repo(
            author,
            vec![
                (
                    lexicon::nsid::STANDARD_PUBLICATION,
                    "3lab2c4d5e6f7g8h",
                    serde_json::json!({ "name": "A0 Journal", "url": "https://a0.example" }),
                ),
                (
                    lexicon::nsid::STANDARD_DOCUMENT,
                    "3l2a0frmaaa2a",
                    serde_json::json!({ "title": "From the form", "path": "/f",
                        "publishedAt": "2026-07-11T00:00:00Z", "site": site }),
                ),
            ],
        )
        .await;
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.oauth.plc_directory = plc;
            },
        );
        assert_eq!(subscribe(&state, did, AT_URI_SUB_ENC).await, "/");
        let row = store::get_feed_by_url(&state.db, site)
            .await
            .unwrap()
            .unwrap();
        let titles: Vec<String> = sqlx::query_scalar("SELECT title FROM entries WHERE feed_id = ?")
            .bind(row.id)
            .fetch_all(&state.db)
            .await
            .unwrap();
        assert_eq!(
            titles,
            vec!["From the form".to_string()],
            "the first poll stored nothing"
        );
        assert_eq!(row.title.as_deref(), Some("A0 Journal"));
    }

    /// A handle-form paste is resolved to the DID before it is stored: a
    /// handle is a mutable name, and `feeds.url` is keyed on identity.
    #[tokio::test]
    async fn a_handle_form_paste_is_stored_by_its_did() {
        let did = "did:plc:renamer5";
        let author = "did:plc:ohutz6x5acjmpuulp3x7wxxc";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let resolver = serve_resolver(author).await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.resolver_base = resolver;
                c.oauth.plc_directory = "http://plc.nowhere.invalid".into();
            },
        );
        let loc = subscribe(
            &state,
            did,
            "at%3A%2F%2Falice.example.com%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
        )
        .await;
        assert_eq!(loc, "/", "the paste was refused: {loc}");
        assert!(
            store::get_feed_by_url(&state.db, AT_URI_SUB)
                .await
                .unwrap()
                .is_some(),
            "not stored by its DID"
        );
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            1,
            "the handle form was stored too"
        );
    }

    /// A resolver answering `did` that counts how often it was asked.
    async fn serve_counting_resolver(
        did: &str,
    ) -> (String, std::sync::Arc<std::sync::atomic::AtomicUsize>) {
        let (base, hits) = crate::net::tests::serve_body_counted(
            serde_json::json!({ "did": did }).to_string().into_bytes(),
        )
        .await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        let host = format!("counting-resolver-{port}.test");
        crate::net::test_host_override(&host, std::net::SocketAddr::from(([127, 0, 0, 1], port)));
        (format!("http://{host}:{port}"), hits)
    }

    /// Review of #230: the per-DID cap is documented as checked "BEFORE any
    /// fetch/resolve so an over-cap account can't even trigger an outbound
    /// request" — a handle paste resolved the handle first.
    #[tokio::test]
    async fn an_over_cap_handle_paste_makes_no_outbound_request() {
        let did = "did:plc:renamer5";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let (resolver, hits) = serve_counting_resolver("did:plc:ohutz6x5acjmpuulp3x7wxxc").await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.resolver_base = resolver;
                c.max_subs_per_did = 1;
            },
        );
        let feed_id = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://already.example/feed.xml".into(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed_id])
            .await
            .unwrap();
        let loc = subscribe(
            &state,
            did,
            "at%3A%2F%2Falice.example.com%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
        )
        .await;
        assert!(
            loc.contains("Subscription%20limit"),
            "expected the cap flash: {loc}"
        );
        assert_eq!(
            hits.load(std::sync::atomic::Ordering::SeqCst),
            0,
            "an over-cap paste resolved a handle"
        );
    }

    /// Review of #230: an authority that is neither a valid DID nor a valid
    /// handle — `did:plc:TOOSHORT`, an uppercase DID — went to the resolver as
    /// a "handle". It is unsupported, and asks nobody anything.
    #[tokio::test]
    async fn a_malformed_did_paste_is_unsupported_with_the_flag_on() {
        let did = "did:plc:renamer5";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let (resolver, hits) = serve_counting_resolver("did:plc:ohutz6x5acjmpuulp3x7wxxc").await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.resolver_base = resolver;
            },
        );
        for authority in [
            "did%3Aplc%3ATOOSHORT",
            "did%3Aplc%3AOHUTZ6X5ACJMPUULP3X7WXXC",
            "bad%0Ahandle.example",
        ] {
            let loc = subscribe(
                &state,
                did,
                &format!("at%3A%2F%2F{authority}%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h"),
            )
            .await;
            assert!(
                loc.contains("kind%20of%20feed"),
                "{authority}: expected the unsupported flash: {loc}"
            );
        }
        assert_eq!(
            hits.load(std::sync::atomic::Ordering::SeqCst),
            0,
            "a malformed authority reached the resolver"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// A handle that does not resolve is refused, and nothing is stored.
    #[tokio::test]
    async fn an_unresolvable_handle_paste_is_refused() {
        let did = "did:plc:renamer5";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.resolver_base = "http://resolver.nowhere.invalid".into();
            },
        );
        let loc = subscribe(
            &state,
            did,
            "at%3A%2F%2Fnobody.example.com%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
        )
        .await;
        assert!(
            loc.contains("resolve%20the%20handle"),
            "expected the unresolvable-handle flash: {loc}"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// An at:// URI that is not a publication is refused, flag on or off.
    #[tokio::test]
    async fn a_non_publication_at_uri_paste_is_refused() {
        let did = "did:plc:renamer5";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 0).await;
        let loc = subscribe(
            &state,
            did,
            "at%3A%2F%2Fdid%3Aplc%3Aohutz6x5acjmpuulp3x7wxxc%2Fapp.bsky.feed.post%2F3lab2c4d5e6f7g8h",
        )
        .await;
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// A mixed-case scheme is canonicalised at input, not refused and not
    /// stored as a second spelling of the same publication.
    #[tokio::test]
    async fn a_mixed_case_at_scheme_paste_is_stored_canonically() {
        let did = "did:plc:renamer5";
        let (sidecar, _log) = spawn_logging_sidecar().await;
        let state = with_config(
            test_state_with_sidecar_and(&[did], &sidecar, true, 0).await,
            |c| {
                c.oauth.plc_directory = "http://plc.nowhere.invalid".into();
            },
        );
        let loc = subscribe(&state, did, &AT_URI_SUB_ENC.replacen("at", "At", 1)).await;
        assert_eq!(loc, "/", "the paste was refused: {loc}");
        assert!(store::get_feed_by_url(&state.db, AT_URI_SUB)
            .await
            .unwrap()
            .is_some());
    }

    /// **With the flag ON, an OPML at:// entry is stored.** The one storage
    /// path that is meant to work today, asserted with the flag actually on.
    #[tokio::test]
    async fn opml_import_stores_an_at_uri_entry_with_the_flag_on() {
        let did = "did:plc:renamer5";
        let (sidecar, _puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 0).await;
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Real\" xmlUrl=\"https://real.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Pub\" xmlUrl=\"{AT_URI_SUB}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Imported%202%20feeds"),
            "unexpected flash: {loc}"
        );
        assert!(
            !loc.contains("skipped"),
            "the at:// entry was skipped with the flag on: {loc}"
        );
        let stored = store::get_feed_by_url(&state.db, AT_URI_SUB).await.unwrap();
        assert!(
            stored.is_some(),
            "the at:// entry was not stored with the flag on"
        );
    }

    /// **A retitle must not cache a secret-bearing URL.** Moving the privacy
    /// gate behind `url_changed` was right for the PDS write — the record is
    /// the reader's — but the cache write was gated only on `storable`, which
    /// any http(s) URL is. So a retitle of a record another client wrote with
    /// a tokened feed URL inserted that URL into the shared `feeds` table,
    /// where the poller would fail it every cycle and print it on the admin
    /// page. main refused the whole rename; this keeps the record editable and
    /// the cache clean, as `resolve_subscriptions` already does for the same
    /// record.
    #[tokio::test]
    async fn retitling_a_secret_bearing_record_does_not_cache_its_url() {
        let did = "did:plc:renamer5";
        let tokened = "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4";
        let tokened_enc =
            "https%3A%2F%2Fwww.patreon.com%2Frss%2Fauthor%3Fauth%3DZm9vYmFyc2VjcmV0dG9rZW4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(tokened)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let loc = retitle_unchanged(&state, did, tokened_enc).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the retitle did not reach the PDS"
        );
        assert!(
            store::get_feed_by_url(&state.db, tokened)
                .await
                .unwrap()
                .is_none(),
            "a secret-bearing URL was written to the shared cache by a retitle"
        );
    }

    /// **On a repoint, storability is decided before privacy and capacity** —
    /// the same ordering the add path got. A malformed at:// target drew the
    /// private/paid flash, and at capacity a well-formed one drew "try again
    /// later" for a URL that can never be accepted with the flag off.
    #[tokio::test]
    async fn repointing_at_a_malformed_at_uri_is_refused_as_unsupported() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=at%3A%2F%2Fdid%3Aplc%3ATOOSHORT%2Fsite.standard.publication%2F3lab&title=Moved",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(
            !loc.contains("Private"),
            "a typo was reported as a paid feed: {loc}"
        );
        assert!(puts.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn repointing_at_an_at_uri_at_capacity_is_refused_as_unsupported_not_capacity() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=Moved")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(
            !loc.contains("capacity"),
            "an unacceptable URL was reported as a capacity problem: {loc}"
        );
        assert!(puts.lock().unwrap().is_empty());
    }

    /// **`url_changed` compares like for like.** The form value is trimmed;
    /// the record's URL was compared raw, so a record another client wrote
    /// with a trailing space read as a repoint on every retitle and re-armed
    /// every gate — including the one that made an at:// record un-editable.
    #[tokio::test]
    async fn retitling_a_record_whose_url_carries_whitespace_is_not_a_repoint() {
        let did = "did:plc:renamer5";
        let padded = format!("{AT_URI_SUB} ");
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(&padded)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        // The manage row posts the record's URL verbatim, padding included.
        let loc = retitle_unchanged(&state, did, &format!("{AT_URI_SUB_ENC}%20")).await;
        assert_eq!(
            loc, "/",
            "the retitle was treated as a repoint and refused: {loc}"
        );
        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1);
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).unwrap();
        assert_eq!(
            sent["record"]["url"], AT_URI_SUB,
            "the padding was not normalised away"
        );
    }

    /// **A retitle inserts no cache row.** The ceiling is checked on a repoint
    /// only, so the trailing upsert must not create a row for an unchanged URL
    /// that has none — with the flag on and the cache full, each retitle of a
    /// never-cached at:// record was a row past the cap. An existing row still
    /// gets its title kept in step.
    #[tokio::test]
    async fn retitling_an_uncached_record_at_capacity_inserts_no_row() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let loc = retitle_unchanged(&state, did, AT_URI_SUB_ENC).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(puts.lock().unwrap().len(), 1);
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            1,
            "a retitle inserted a cache row past the ceiling"
        );
    }

    /// **The add path's at:// pre-check is about the MESSAGE, so it is
    /// case-insensitive.** `Url::parse` folds the scheme, so `AT://…` skipped
    /// the pre-check and the classifier's at:// arm alike, parsed as `at`, and
    /// tripped the secret heuristic on the rkey — the private/paid flash the
    /// pre-check exists to avoid. Storage stays case-sensitive; this does not
    /// touch it.
    #[tokio::test]
    async fn an_uppercase_at_scheme_paste_is_refused_as_unsupported() {
        let did = "did:plc:typoist";
        let state = test_state_with_caps(did, 0, 0).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=AT%3A%2F%2Falice.example.com%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(!loc.contains("Private"), "reported as a paid feed: {loc}");
    }

    // -- #149: a rename that races another client's write -------------------

    /// One subscription record behind a fake repo that ENFORCES `swapRecord`
    /// the way the reference PDS does: a put naming a CID the record is no
    /// longer at is refused `400 InvalidSwap`; a put with no swap always lands.
    #[derive(Default)]
    struct SwapRepo {
        /// The record's current value.
        value: serde_json::Value,
        /// Bumped on every write, so each version has its own CID.
        version: u32,
        /// Every put request body received, in order, landed or not.
        puts: Vec<serde_json::Value>,
        /// Another client's write, landed the moment our FIRST put arrives —
        /// i.e. between our read and our write.
        concurrent: Option<serde_json::Value>,
        /// Refuse every put that carries a swap, whatever CID it names.
        refuse_every_swap: bool,
        /// Refuse every put with this (status, error) — a non-swap failure.
        fail_puts: Option<(u16, &'static str)>,
        /// The collection the record lives in; the subscription one when unset.
        collection: Option<&'static str>,
        /// The record is not in the repo: the listing comes back empty.
        missing: bool,
        /// Every listing fails `502`.
        fail_list: bool,
    }

    impl SwapRepo {
        fn cid(&self) -> String {
            format!("bafyreiversion{}", self.version)
        }

        fn nsid(&self) -> &'static str {
            self.collection
                .unwrap_or(crate::lexicon::nsid::SUBSCRIPTION)
        }

        fn page(&self) -> serde_json::Value {
            if self.missing {
                return serde_json::json!({ "records": [] });
            }
            serde_json::json!({ "records": [{
                "uri": format!("at://{RACE_DID}/{}/rk-keep", self.nsid()),
                "cid": self.cid(),
                "value": self.value,
            }] })
        }

        /// A put: `Ok(strong ref)` or `Err((status, error name))`.
        fn put(&mut self, body: &serde_json::Value) -> Result<serde_json::Value, (u16, String)> {
            self.puts.push(body.clone());
            if let Some(theirs) = self.concurrent.take() {
                self.value = theirs;
                self.version += 1;
            }
            if let Some((status, error)) = self.fail_puts {
                return Err((status, error.to_string()));
            }
            if let Some(swap) = body.get("swapRecord").and_then(|v| v.as_str()) {
                if self.refuse_every_swap || swap != self.cid() {
                    return Err((400, "InvalidSwap".to_string()));
                }
            }
            self.value = body["record"].clone();
            self.version += 1;
            Ok(serde_json::json!({
                "uri": format!("at://{RACE_DID}/{}/rk-keep", self.nsid()),
                "cid": self.cid(),
            }))
        }
    }

    const RACE_DID: &str = "did:plc:racer149";

    /// Serve `repo` as both a sidecar (`/internal/repo`) and a PDS (`/xrpc/*`),
    /// so one fixture drives either backend. Returns the sidecar base URL and
    /// the PDS audience a Rust-backend session should carry.
    async fn serve_swap_repo(repo: std::sync::Arc<std::sync::Mutex<SwapRepo>>) -> (String, String) {
        use axum::response::IntoResponse as _;
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let host = format!("pds-{}.race.test", addr.port());
        crate::net::test_host_override(&host, addr);
        let app = axum::Router::new().fallback(move |req: axum::extract::Request| {
            let repo = std::sync::Arc::clone(&repo);
            async move {
                let (parts, body) = req.into_parts();
                let raw = axum::body::to_bytes(body, usize::MAX).await.unwrap();
                let body: serde_json::Value =
                    serde_json::from_slice(&raw).unwrap_or(serde_json::Value::Null);
                let reply = |status: u16, body: serde_json::Value| {
                    (StatusCode::from_u16(status).unwrap(), axum::Json(body)).into_response()
                };
                let mut repo = repo.lock().unwrap();
                match (parts.uri.path(), body["action"].as_str()) {
                    ("/internal/repo", Some("list")) if repo.fail_list => reply(
                        502,
                        serde_json::json!({
                            "ok": false, "error": "UpstreamFailure", "message": "down", "status": 502,
                        }),
                    ),
                    ("/internal/repo", Some("list")) => {
                        reply(200, serde_json::json!({ "ok": true, "data": repo.page() }))
                    }
                    ("/internal/repo", Some("put")) => match repo.put(&body) {
                        Ok(data) => reply(200, serde_json::json!({ "ok": true, "data": data })),
                        Err((status, error)) => reply(
                            status,
                            serde_json::json!({
                                "ok": false, "error": error, "message": "refused", "status": status,
                            }),
                        ),
                    },
                    ("/xrpc/com.atproto.repo.listRecords", _) if repo.fail_list => reply(
                        502,
                        serde_json::json!({ "error": "UpstreamFailure", "message": "down" }),
                    ),
                    ("/xrpc/com.atproto.repo.listRecords", _) => reply(200, repo.page()),
                    ("/xrpc/com.atproto.repo.putRecord", _) => match repo.put(&body) {
                        Ok(data) => reply(200, data),
                        Err((status, error)) => reply(
                            status,
                            serde_json::json!({ "error": error, "message": "refused" }),
                        ),
                    },
                    other => panic!("unexpected request {other:?}"),
                }
            }
        });
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        (
            format!("http://{addr}"),
            format!("http://{host}:{}", addr.port()),
        )
    }

    /// An `AppState` on `backend`, pointed at `repo` — the sidecar through its
    /// internal URL, the Rust client through a live OAuth session whose `aud`
    /// is the fake.
    async fn race_state(
        backend: crate::metrics::Backend,
        repo: &std::sync::Arc<std::sync::Mutex<SwapRepo>>,
    ) -> AppState {
        let (sidecar, aud) = serve_swap_repo(std::sync::Arc::clone(repo)).await;
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &[RACE_DID.to_string()])
            .await
            .unwrap();
        let mut config = Config {
            allowed_dids: vec![RACE_DID.to_string()],
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            repo_backend: backend,
            oauth: crate::config::OauthConfig {
                // Per test, never the relative default — see `repo::tests`.
                key_path: std::env::temp_dir().join(format!(
                    "fr-race-oauth-key-{}-{:p}.json",
                    std::process::id(),
                    &db as *const _
                )),
                encryption_key: Some("a".repeat(43)),
                ..crate::config::OauthConfig::default()
            },
            ..Config::default()
        };
        config.sidecar.public_url = sidecar.clone();
        config.sidecar.internal_url = sidecar;
        let state = AppState::new(config, db).unwrap();
        if backend == crate::metrics::Backend::Rust {
            let runtime = state.oauth.as_deref().expect("oauth runtime");
            crate::oauth::store::put_session(
                &state.db,
                &runtime.codec,
                &crate::oauth::store::OAuthSession {
                    sub: RACE_DID.into(),
                    issuer: "https://auth.invalid".into(),
                    aud,
                    dpop_key_jwk: crate::oauth::keys::SigningKey::generate("session-dpop")
                        .to_jwk_json()
                        .unwrap(),
                    access_token: "at".into(),
                    refresh_token: "rt".into(),
                    token_type: "DPoP".into(),
                    granted_scope: "atproto".into(),
                    expires_at: Some(store::now_unix() + 3600),
                },
            )
            .await
            .unwrap();
        }
        state
    }

    /// The record before anyone touches it — the seeded one, as a value.
    fn race_seed() -> serde_json::Value {
        seeded_subscription()["value"].clone()
    }

    /// Post the manage row's rename (url unchanged, a new title and folder) and
    /// return the redirect location.
    async fn post_race_rename(state: &AppState) -> String {
        post_race_rename_body(
            state,
            "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&folder=Tech",
        )
        .await
    }

    /// Post `body` as the rename of `rk-keep`; returns the redirect location.
    async fn post_race_rename_body(state: &AppState, body: &str) -> String {
        let cookie = session_cookie(state, RACE_DID, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(body.to_string()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        resp.headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .to_string()
    }

    const RACE_BACKENDS: [crate::metrics::Backend; 2] = [
        crate::metrics::Backend::Sidecar,
        crate::metrics::Backend::Rust,
    ];

    /// **The key test of #149: a rename that loses a race keeps the other
    /// client's change AND lands its own.**
    ///
    /// The fake lands another client's edit (a new `siteUrl` and `fetchHint`)
    /// between the handler's read and its write. The write names the CID it
    /// read, so the PDS refuses it; the handler re-reads, re-applies the form's
    /// fields to the FRESH record, and writes again under the new CID.
    ///
    /// With `swapRecord` dropped anywhere on the way out, the first put lands
    /// unconditionally and the other client's edit is gone — which is what
    /// the final-record assertions catch. Run on both backends: production is
    /// on `rust`, and a backend whose put ignores the swap is the exact gap.
    #[tokio::test]
    async fn a_rename_that_loses_a_race_keeps_the_concurrent_edit_and_lands() {
        for backend in RACE_BACKENDS {
            let mut theirs = race_seed();
            theirs["siteUrl"] = serde_json::json!("https://elsewhere.example/blog");
            theirs["fetchHint"] = serde_json::json!("daily");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                concurrent: Some(theirs),
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename(&state).await;

            let repo = repo.lock().unwrap();
            assert_eq!(
                loc, "/",
                "{backend:?}: a rename that converged was not reported as done"
            );
            assert_eq!(
                repo.puts.len(),
                2,
                "{backend:?}: expected the refused put and one retry: {:?}",
                repo.puts
            );
            assert_eq!(
                repo.puts[0]["swapRecord"], "bafyreiversion0",
                "{backend:?}: the first put did not name the CID it read: {}",
                repo.puts[0]
            );
            assert_eq!(
                repo.puts[1]["swapRecord"], "bafyreiversion1",
                "{backend:?}: the retry did not name the RE-READ CID: {}",
                repo.puts[1]
            );
            let landed = &repo.value;
            // The reader's change landed...
            assert_eq!(landed["title"], "New title", "{backend:?}: {landed}");
            assert_eq!(landed["folder"], "Tech", "{backend:?}: {landed}");
            // ...on top of the other client's, not over it.
            assert_eq!(
                landed["siteUrl"], "https://elsewhere.example/blog",
                "{backend:?}: the concurrent edit was lost: {landed}"
            );
            assert_eq!(
                landed["fetchHint"], "daily",
                "{backend:?}: the concurrent edit was lost: {landed}"
            );
            // And #147's preservation still holds on the retried record.
            assert_eq!(
                landed["createdAt"], "2024-03-01T00:00:00.000Z",
                "{backend:?}: {landed}"
            );
        }
    }

    /// **A rename the PDS refuses on every attempt is reported as a conflict,
    /// never as done — and is not retried forever.** One retry, so at most two
    /// puts; then the reader is told the subscription changed elsewhere.
    #[tokio::test]
    async fn a_rename_refused_on_every_swap_reports_the_conflict() {
        for backend in RACE_BACKENDS {
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                refuse_every_swap: true,
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename(&state).await;

            let repo = repo.lock().unwrap();
            assert_ne!(loc, "/", "{backend:?}: a refused rename reported success");
            assert!(
                loc.contains("changed%20elsewhere"),
                "{backend:?}: expected the conflict flash, got {loc}"
            );
            assert!(
                (1..=2).contains(&repo.puts.len()),
                "{backend:?}: expected at most two put attempts, got {}",
                repo.puts.len()
            );
            assert_eq!(
                repo.value,
                race_seed(),
                "{backend:?}: the record changed though every put was refused"
            );
        }
    }

    /// **A put refused for any OTHER reason is not retried**, and keeps the
    /// message it had: a re-read cannot fix a rejected record or an outage,
    /// and calling it a conflict would send the reader looking for an edit
    /// nobody made.
    #[tokio::test]
    async fn a_rename_refused_for_another_reason_is_not_retried() {
        for backend in RACE_BACKENDS {
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                fail_puts: Some((400, "InvalidRequest")),
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename(&state).await;

            let repo = repo.lock().unwrap();
            assert_eq!(
                repo.puts.len(),
                1,
                "{backend:?}: a non-swap refusal was retried"
            );
            assert!(
                loc.contains("Could%20not%20save"),
                "{backend:?}: expected the save-failed flash, got {loc}"
            );
            assert!(
                !loc.contains("changed%20elsewhere"),
                "{backend:?}: a non-swap refusal was reported as a conflict: {loc}"
            );
        }
    }

    /// What the manage row posts for a reader who changed only the title: the
    /// url and folder as they were, plus the `seen_*` values the inputs were
    /// pre-filled with.
    const SEEN_SEED: &str = "seen_url=https%3A%2F%2Fexample.com%2Ffeed.xml\
                             &seen_title=Old+title&seen_folder=";

    /// **A retry merges; it does not replay the whole form.** Another client
    /// repoints the record (A -> B, with B's own siteUrl and fetchHint) while
    /// the reader only retitles it. The form still carries URL A — it is a
    /// hidden input — so replaying it on the fresh record "repointed" back to
    /// A, cleared the other client's siteUrl and fetchHint, and reported
    /// success. The reader changed the title and nothing else, so the title is
    /// all that may move. Run with and without the `seen_*` inputs: without
    /// them the base is the handler's first read.
    #[tokio::test]
    async fn a_retry_keeps_a_concurrent_repoint_the_reader_did_not_make() {
        for backend in RACE_BACKENDS {
            for with_seen in [true, false] {
                let mut theirs = race_seed();
                theirs["url"] = serde_json::json!("https://moved.example/feed.xml");
                theirs["siteUrl"] = serde_json::json!("https://moved.example/");
                theirs["fetchHint"] = serde_json::json!("daily");
                let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                    value: race_seed(),
                    concurrent: Some(theirs),
                    ..SwapRepo::default()
                }));
                let state = race_state(backend, &repo).await;
                let mut body =
                    "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title".to_string();
                if with_seen {
                    body.push_str(
                        "&seen_url=https%3A%2F%2Fexample.com%2Ffeed.xml&seen_title=Old+title",
                    );
                }

                let loc = post_race_rename_body(&state, &body).await;

                let repo = repo.lock().unwrap();
                let ctx = format!("{backend:?} seen={with_seen}");
                assert_eq!(loc, "/", "{ctx}: the rename did not land: {loc}");
                assert_eq!(repo.puts.len(), 2, "{ctx}: {:?}", repo.puts);
                let landed = &repo.value;
                assert_eq!(landed["title"], "New title", "{ctx}: {landed}");
                assert_eq!(
                    landed["url"], "https://moved.example/feed.xml",
                    "{ctx}: the retry repointed the record back to the stale URL: {landed}"
                );
                assert_eq!(
                    landed["siteUrl"], "https://moved.example/",
                    "{ctx}: {landed}"
                );
                assert_eq!(landed["fetchHint"], "daily", "{ctx}: {landed}");
            }
        }
    }

    /// The other client retitles; the reader only moves the folder. Their
    /// title is kept and the folder applied — the reader's stale copy of the
    /// title (posted because the input is always submitted) is not a change.
    #[tokio::test]
    async fn a_retry_keeps_a_concurrent_retitle_when_the_reader_only_moved_it() {
        for backend in RACE_BACKENDS {
            let mut theirs = race_seed();
            theirs["title"] = serde_json::json!("Their title");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                concurrent: Some(theirs),
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename_body(
                &state,
                &format!("url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Old+title&folder=Tech&{SEEN_SEED}"),
            )
            .await;

            let repo = repo.lock().unwrap();
            assert_eq!(loc, "/", "{backend:?}: {loc}");
            let landed = &repo.value;
            assert_eq!(
                landed["title"], "Their title",
                "{backend:?}: the reader's untouched title overwrote the other client's: {landed}"
            );
            assert_eq!(landed["folder"], "Tech", "{backend:?}: {landed}");
        }
    }

    /// **Both changed the same field: a conflict, and nothing is written.**
    /// Neither edit can be chosen for the reader, so they are told, and the
    /// other client's title stays.
    #[tokio::test]
    async fn both_retitling_is_a_conflict_that_writes_nothing() {
        for backend in RACE_BACKENDS {
            let mut theirs = race_seed();
            theirs["title"] = serde_json::json!("Their title");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                concurrent: Some(theirs.clone()),
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename_body(
                &state,
                &format!("url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&{SEEN_SEED}"),
            )
            .await;

            let repo = repo.lock().unwrap();
            assert!(
                loc.contains("changed%20elsewhere"),
                "{backend:?}: expected the conflict flash, got {loc}"
            );
            assert_eq!(
                repo.puts.len(),
                1,
                "{backend:?}: a conflicting retry was written: {:?}",
                repo.puts
            );
            assert_eq!(
                repo.value, theirs,
                "{backend:?}: their title was overwritten"
            );
        }
    }

    /// **The page-load window: an edit that landed BEFORE the handler's first
    /// read.** The manage page showed URL A; another client repointed to B
    /// before the reader pressed Save, so the first read already sees B and
    /// no swap fails. The `seen_url` the page was rendered with is what says
    /// the reader never touched the URL — without it, the stale hidden `url`
    /// reads as a repoint back to A.
    #[tokio::test]
    async fn a_repoint_before_the_first_read_is_kept_when_the_reader_only_retitled() {
        for backend in RACE_BACKENDS {
            let mut moved = race_seed();
            moved["url"] = serde_json::json!("https://moved.example/feed.xml");
            moved["siteUrl"] = serde_json::json!("https://moved.example/");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: moved,
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename_body(
                &state,
                &format!("url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&{SEEN_SEED}"),
            )
            .await;

            let repo = repo.lock().unwrap();
            assert_eq!(loc, "/", "{backend:?}: {loc}");
            assert_eq!(repo.puts.len(), 1, "{backend:?}");
            let landed = &repo.value;
            assert_eq!(
                landed["url"], "https://moved.example/feed.xml",
                "{backend:?}: the stale hidden url repointed the record: {landed}"
            );
            assert_eq!(landed["siteUrl"], "https://moved.example/", "{backend:?}");
            assert_eq!(landed["title"], "New title", "{backend:?}");
        }
    }

    /// **The cache follows the PDS, never leads it.** A rename that did not
    /// land — every swap refused, or the put failed for another reason — must
    /// leave the local `feeds` cache as it was: no row for a repoint's new URL
    /// (the poller would fetch a feed nobody subscribes to), and no new title
    /// on the existing row. One that landed updates it as before.
    #[tokio::test]
    async fn a_rename_that_did_not_land_leaves_the_cache_alone() {
        const NEW_URL: &str = "https://other.example/feed.xml";
        const OLD_URL: &str = "https://example.com/feed.xml";
        // (refuse every swap, fail every put, expect the write to land)
        for (refuse_every_swap, fail_puts, lands) in [
            (true, None, false),
            (false, Some((400, "InvalidRequest")), false),
            (false, Some((502, "UpstreamFailure")), false),
            (false, None, true),
        ] {
            for backend in RACE_BACKENDS {
                let ctx = format!("{backend:?} refuse={refuse_every_swap} fail={fail_puts:?}");
                for repoint in [false, true] {
                    let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                        value: race_seed(),
                        refuse_every_swap,
                        fail_puts,
                        ..SwapRepo::default()
                    }));
                    let state = race_state(backend, &repo).await;
                    store::upsert_feed(
                        &state.db,
                        &store::NewFeed {
                            url: OLD_URL.to_string(),
                            title: Some("Cached title".to_string()),
                            ..Default::default()
                        },
                    )
                    .await
                    .unwrap();
                    let url = if repoint { NEW_URL } else { OLD_URL };
                    let body = format!("url={}&title=New+title&{SEEN_SEED}", qenc(url));

                    let loc = post_race_rename_body(&state, &body).await;

                    let new_row = store::get_feed_by_url(&state.db, NEW_URL).await.unwrap();
                    let old_row = store::get_feed_by_url(&state.db, OLD_URL)
                        .await
                        .unwrap()
                        .expect("the old row");
                    let ctx = format!("{ctx} repoint={repoint} -> {loc}");
                    if lands {
                        assert_eq!(loc, "/", "{ctx}");
                        if repoint {
                            assert!(
                                new_row.is_some(),
                                "{ctx}: a landed repoint got no cache row"
                            );
                        } else {
                            assert_eq!(old_row.title.as_deref(), Some("New title"), "{ctx}");
                        }
                    } else {
                        assert_ne!(loc, "/", "{ctx}");
                        assert!(
                            new_row.is_none(),
                            "{ctx}: a repoint that did not land left a feeds row for its URL"
                        );
                        assert_eq!(
                            old_row.title.as_deref(),
                            Some("Cached title"),
                            "{ctx}: a rename that did not land changed the cached title"
                        );
                    }
                }
            }
        }
    }

    /// **A page with no folder dropdown does not un-folder.** The select (and
    /// its `seen_folder`) render only when the reader has folders the page
    /// could list — none, or a failed folder listing, and neither is posted.
    /// That is "the reader never saw a folder", not "the reader chose none":
    /// a retitle from such a page used to un-folder the subscription, and on
    /// a retry could report a conflict on a field the reader never saw.
    #[tokio::test]
    async fn a_rename_from_a_page_without_a_folder_select_keeps_the_folder() {
        for backend in RACE_BACKENDS {
            for raced in [false, true] {
                let mut seed = race_seed();
                seed["folder"] = serde_json::json!("at://did:plc:racer149/folder/kept");
                let concurrent = raced.then(|| {
                    let mut theirs = seed.clone();
                    theirs["folder"] = serde_json::json!("at://did:plc:racer149/folder/theirs");
                    theirs
                });
                let want_folder = concurrent
                    .as_ref()
                    .map_or(seed["folder"].clone(), |t| t["folder"].clone());
                let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                    value: seed,
                    concurrent,
                    ..SwapRepo::default()
                }));
                let state = race_state(backend, &repo).await;

                // Exactly what the manage row posts with no folder select.
                let loc = post_race_rename_body(
                    &state,
                    "url=https%3A%2F%2Fexample.com%2Ffeed.xml\
                     &seen_url=https%3A%2F%2Fexample.com%2Ffeed.xml\
                     &seen_title=Old+title&title=New+title",
                )
                .await;

                let repo = repo.lock().unwrap();
                let ctx = format!("{backend:?} raced={raced}");
                assert_eq!(loc, "/", "{ctx}: {loc}");
                assert_eq!(repo.value["title"], "New title", "{ctx}");
                assert_eq!(
                    repo.value["folder"], want_folder,
                    "{ctx}: a page that never showed a folder changed it: {}",
                    repo.value
                );
            }
        }
    }

    /// **A double-clicked Save is not a conflict.** Both POSTs read the same
    /// CID; the first lands; the second's swap fails, and its re-read finds
    /// the record already saying exactly what the reader asked for. That is
    /// success, with nothing left to write — not "nothing was renamed".
    #[tokio::test]
    async fn a_double_submitted_rename_reports_success_and_writes_once() {
        for backend in RACE_BACKENDS {
            // The first submission's write, landing between the second's read
            // and its put.
            let mut first = race_seed();
            first["title"] = serde_json::json!("New title");
            first["folder"] = serde_json::json!("Tech");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(SwapRepo {
                value: race_seed(),
                concurrent: Some(first.clone()),
                ..SwapRepo::default()
            }));
            let state = race_state(backend, &repo).await;

            let loc = post_race_rename_body(
                &state,
                &format!(
                    "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&folder=Tech&{SEEN_SEED}"
                ),
            )
            .await;

            let repo = repo.lock().unwrap();
            assert_eq!(
                loc, "/",
                "{backend:?}: a save that landed was reported as a conflict: {loc}"
            );
            assert_eq!(
                repo.puts.len(),
                1,
                "{backend:?}: only the refused put; the re-read has nothing left to write: {:?}",
                repo.puts
            );
            assert_eq!(repo.value, first, "{backend:?}");
        }
    }

    // -- #268: renaming a folder edits the record, it does not replace it ----

    /// A folder record as another `community.lexicon.rss` client might have
    /// left it: a sort position, an old `createdAt`, and a field this build
    /// does not know.
    fn folder_seed() -> serde_json::Value {
        serde_json::json!({
            "$type": crate::lexicon::nsid::FOLDER,
            "name": "Old name",
            "position": 3,
            "createdAt": "2024-01-01T00:00:00.000Z",
            "color": "#abc",
        })
    }

    /// A [`SwapRepo`] holding `value` as the folder `rk-keep`.
    fn folder_repo(value: serde_json::Value) -> SwapRepo {
        SwapRepo {
            value,
            collection: Some(crate::lexicon::nsid::FOLDER),
            ..SwapRepo::default()
        }
    }

    /// Post `body` as the rename of folder `rk-keep`; returns the redirect.
    async fn post_folder_rename(state: &AppState, body: &str) -> String {
        let cookie = session_cookie(state, RACE_DID, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/folders/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(body.to_string()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        resp.headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .to_string()
    }

    /// `value` with its name set to `name`.
    fn renamed(mut value: serde_json::Value, name: &str) -> serde_json::Value {
        value["name"] = serde_json::json!(name);
        value
    }

    /// **The key test of #268: a rename changes the name and nothing else.**
    /// The handler used to put `Folder::new(name, now)` over the record, which
    /// reset `position`, replaced `createdAt` with the rename time and dropped
    /// every field another client had added. The exact body put is asserted,
    /// so any field lost or invented on the way fails it — on both backends.
    #[tokio::test]
    async fn renaming_a_folder_changes_only_its_name() {
        for backend in RACE_BACKENDS {
            let repo = std::sync::Arc::new(std::sync::Mutex::new(folder_repo(folder_seed())));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name").await;

            let repo = repo.lock().unwrap();
            assert_eq!(
                loc, "/",
                "{backend:?}: a landed rename was not reported as done"
            );
            assert_eq!(repo.puts.len(), 1, "{backend:?}: {:?}", repo.puts);
            assert_eq!(
                repo.puts[0]["record"],
                renamed(folder_seed(), "New name"),
                "{backend:?}: the put did not keep the record whole: {}",
                repo.puts[0]
            );
            assert_eq!(
                repo.puts[0]["collection"],
                crate::lexicon::nsid::FOLDER,
                "{backend:?}"
            );
            assert_eq!(
                repo.puts[0]["swapRecord"], "bafyreiversion0",
                "{backend:?}: the put did not name the CID it read: {}",
                repo.puts[0]
            );
        }
    }

    /// **A rename that loses a race keeps the other client's change and
    /// lands.** Another client moves the folder (and adds a field) between the
    /// read and the write; the swap is refused, the handler re-reads and
    /// renames the FRESH record.
    #[tokio::test]
    async fn a_folder_rename_that_loses_a_race_keeps_the_concurrent_edit() {
        for backend in RACE_BACKENDS {
            for with_seen in [true, false] {
                let mut theirs = folder_seed();
                theirs["position"] = serde_json::json!(7);
                theirs["icon"] = serde_json::json!("star");
                let mut fake = folder_repo(folder_seed());
                fake.concurrent = Some(theirs.clone());
                let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
                let state = race_state(backend, &repo).await;

                let body = if with_seen {
                    "name=New+name&seen_name=Old+name"
                } else {
                    "name=New+name"
                };
                let loc = post_folder_rename(&state, body).await;

                let repo = repo.lock().unwrap();
                let ctx = format!("{backend:?} with_seen={with_seen}");
                assert_eq!(
                    loc, "/",
                    "{ctx}: a converged rename was not reported as done"
                );
                assert_eq!(repo.puts.len(), 2, "{ctx}: {:?}", repo.puts);
                assert_eq!(repo.puts[0]["swapRecord"], "bafyreiversion0", "{ctx}");
                assert_eq!(
                    repo.puts[1]["swapRecord"], "bafyreiversion1",
                    "{ctx}: the retry did not name the RE-READ CID"
                );
                assert_eq!(
                    repo.value,
                    renamed(theirs, "New name"),
                    "{ctx}: the concurrent edit was lost"
                );
            }
        }
    }

    /// **Both renaming the folder, differently, is a conflict that writes
    /// nothing** — the reader is told, and the other client's name stands.
    /// With and without `seen_name`: without it, the first read is the
    /// ancestor.
    #[tokio::test]
    async fn both_renaming_a_folder_differently_is_a_conflict() {
        for backend in RACE_BACKENDS {
            for body in ["name=New+name&seen_name=Old+name", "name=New+name"] {
                let theirs = renamed(folder_seed(), "Their name");
                let mut fake = folder_repo(folder_seed());
                fake.concurrent = Some(theirs.clone());
                let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
                let state = race_state(backend, &repo).await;

                let loc = post_folder_rename(&state, body).await;

                let repo = repo.lock().unwrap();
                assert!(
                    loc.contains("changed%20elsewhere"),
                    "{backend:?} {body}: expected the conflict flash, got {loc}"
                );
                assert_eq!(
                    repo.puts.len(),
                    1,
                    "{backend:?} {body}: only the refused put: {:?}",
                    repo.puts
                );
                assert_eq!(
                    repo.value, theirs,
                    "{backend:?} {body}: the other client's name was overwritten"
                );
            }
        }
    }

    /// **Both renaming it to the SAME name is agreement** — a double-submitted
    /// Save whose first request landed. Success, and no second write.
    #[tokio::test]
    async fn both_renaming_a_folder_the_same_is_success_without_a_write() {
        for backend in RACE_BACKENDS {
            let theirs = renamed(folder_seed(), "New name");
            let mut fake = folder_repo(folder_seed());
            fake.concurrent = Some(theirs.clone());
            let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name&seen_name=Old+name").await;

            let repo = repo.lock().unwrap();
            assert_eq!(
                loc, "/",
                "{backend:?}: agreement reported as a failure: {loc}"
            );
            assert_eq!(repo.puts.len(), 1, "{backend:?}: {:?}", repo.puts);
            assert_eq!(repo.value, theirs, "{backend:?}");
        }
    }

    /// **A folder that keeps moving is a conflict after one retry**, never
    /// reported as renamed and never retried forever.
    #[tokio::test]
    async fn a_folder_rename_refused_on_every_swap_reports_the_conflict() {
        for backend in RACE_BACKENDS {
            let mut fake = folder_repo(folder_seed());
            fake.refuse_every_swap = true;
            let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name").await;

            let repo = repo.lock().unwrap();
            assert!(
                loc.contains("changed%20elsewhere"),
                "{backend:?}: expected the conflict flash, got {loc}"
            );
            assert_eq!(repo.puts.len(), 2, "{backend:?}: one try and one retry");
            assert_eq!(repo.value, folder_seed(), "{backend:?}");
        }
    }

    /// **A failed rename tells the reader**, instead of redirecting as if it
    /// had worked — and a failure a re-read cannot fix is not retried.
    #[tokio::test]
    async fn a_failed_folder_rename_shows_an_error() {
        for backend in RACE_BACKENDS {
            let mut fake = folder_repo(folder_seed());
            fake.fail_puts = Some((502, "UpstreamFailure"));
            let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name").await;

            let repo = repo.lock().unwrap();
            assert_ne!(loc, "/", "{backend:?}: a failed rename reported success");
            assert!(
                loc.contains("Could%20not%20save"),
                "{backend:?}: expected the save-failed flash, got {loc}"
            );
            assert!(!loc.contains("changed%20elsewhere"), "{backend:?}: {loc}");
            assert_eq!(
                repo.puts.len(),
                1,
                "{backend:?}: a non-swap failure was retried"
            );
        }
    }

    /// **A folder deleted elsewhere is not recreated.** A put at a missing
    /// rkey creates the record, which a rename must not do.
    #[tokio::test]
    async fn renaming_a_folder_that_no_longer_exists_writes_nothing() {
        for backend in RACE_BACKENDS {
            let mut fake = folder_repo(folder_seed());
            fake.missing = true;
            let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name").await;

            let repo = repo.lock().unwrap();
            assert!(
                loc.contains("no%20longer%20exists"),
                "{backend:?}: expected the missing-folder flash, got {loc}"
            );
            assert!(repo.puts.is_empty(), "{backend:?}: {:?}", repo.puts);
        }
    }

    /// **A folder that cannot be read is not renamed** — rebuilding it from
    /// the form instead is the record loss this read exists to prevent.
    #[tokio::test]
    async fn a_folder_rename_whose_read_fails_writes_nothing() {
        for backend in RACE_BACKENDS {
            let mut fake = folder_repo(folder_seed());
            fake.fail_list = true;
            let repo = std::sync::Arc::new(std::sync::Mutex::new(fake));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name").await;

            let repo = repo.lock().unwrap();
            assert!(
                loc.contains("Could%20not%20reach"),
                "{backend:?}: expected the read-failed flash, got {loc}"
            );
            assert!(repo.puts.is_empty(), "{backend:?}: {:?}", repo.puts);
        }
    }

    /// **`seen_name` closes the page-load window.** Another client renamed the
    /// folder after the page was rendered but before the handler read it, so
    /// no swap fails; the form still says what the reader saw, and their
    /// different rename is a conflict rather than a silent overwrite.
    #[tokio::test]
    async fn a_rename_elsewhere_after_page_load_is_a_conflict_with_seen_name() {
        for backend in RACE_BACKENDS {
            let theirs = renamed(folder_seed(), "Their name");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(folder_repo(theirs.clone())));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=New+name&seen_name=Old+name").await;

            let repo = repo.lock().unwrap();
            assert!(
                loc.contains("changed%20elsewhere"),
                "{backend:?}: expected the conflict flash, got {loc}"
            );
            assert!(repo.puts.is_empty(), "{backend:?}: {:?}", repo.puts);
            assert_eq!(repo.value, theirs, "{backend:?}");
        }
    }

    /// A form whose name is the one it showed changes nothing: no write, and
    /// a rename another client made since stands.
    #[tokio::test]
    async fn an_unchanged_folder_name_writes_nothing() {
        for backend in RACE_BACKENDS {
            let theirs = renamed(folder_seed(), "Their name");
            let repo = std::sync::Arc::new(std::sync::Mutex::new(folder_repo(theirs.clone())));
            let state = race_state(backend, &repo).await;

            let loc = post_folder_rename(&state, "name=Old+name&seen_name=Old+name").await;

            let repo = repo.lock().unwrap();
            assert_eq!(loc, "/", "{backend:?}");
            assert!(repo.puts.is_empty(), "{backend:?}: {:?}", repo.puts);
            assert_eq!(repo.value, theirs, "{backend:?}");
        }
    }

    /// The folder merge, case by case (#268).
    #[test]
    fn merge_folder_rename_is_a_three_way_merge_on_the_name() {
        let base = Folder::new("Old", "2024-01-01T00:00:00.000Z");
        let with = |name: &str| {
            let mut f = base.clone();
            f.name = name.to_string();
            f.position = Some(3);
            f.extra
                .insert("color".to_string(), serde_json::json!("#abc"));
            f
        };
        // The reader left the name as shown: nothing to write.
        assert_eq!(
            merge_folder_rename("Old", Some("Old"), &base, with("Other")),
            Ok(FolderMerge::Unchanged)
        );
        // Only the reader changed it: the FRESH record, renamed.
        assert_eq!(
            merge_folder_rename("New", Some("Old"), &base, with("Old")),
            Ok(FolderMerge::Write(with("New")))
        );
        // Fresh already holds the reader's name: agreement.
        assert_eq!(
            merge_folder_rename("New", Some("Old"), &base, with("New")),
            Ok(FolderMerge::AlreadySaved)
        );
        // Both changed it, differently: a conflict.
        assert_eq!(
            merge_folder_rename("New", Some("Old"), &base, with("Other")),
            Err(RenameConflict("name"))
        );
        // Without seen_name the first read is the ancestor.
        assert_eq!(
            merge_folder_rename("New", None, &with("Other"), with("Other")),
            Ok(FolderMerge::Write(with("New")))
        );
        assert_eq!(
            merge_folder_rename("New", None, &base, with("Other")),
            Err(RenameConflict("name"))
        );
        // Padding is not a change.
        assert_eq!(
            merge_folder_rename(" Old ", Some("Old "), &base, with("Other")),
            Ok(FolderMerge::Unchanged)
        );
        assert_eq!(
            merge_folder_rename("New ", Some("Old"), &base, with(" Old ")),
            Ok(FolderMerge::Write(with("New")))
        );
    }

    /// Both sides changing a field to the SAME value is agreement, not a
    /// conflict — for every field the merge handles. Alongside a field still
    /// to apply, the write goes ahead with it; alone, there is nothing to
    /// write and the save is already done.
    #[test]
    fn the_same_change_on_both_sides_is_not_a_conflict() {
        let base = merge_base();
        let url = "https://a.example/feed.xml";
        let new_url = "https://c.example/feed.xml";

        // title: both "New".
        let mut fresh = base.clone();
        fresh.title = Some("New".to_string());
        let merged = merge_rename(&merge_form(url, "New", Some("at://f/old")), &base, fresh)
            .expect("same title is no conflict");
        assert!(merged.already_saved, "nothing left to write");

        // folder: both moved to the same folder, while the reader also retitles.
        let mut fresh = base.clone();
        fresh.folder = Some("at://f/new".to_string());
        let merged = merge_rename(&merge_form(url, "Mine", Some("at://f/new")), &base, fresh)
            .expect("same folder is no conflict");
        assert!(!merged.already_saved, "the title is still to write");
        assert_eq!(merged.sub.title.as_deref(), Some("Mine"));
        assert_eq!(merged.sub.folder.as_deref(), Some("at://f/new"));

        // url: both repointed to the same URL. Not a repoint by THIS write, so
        // the fresh record's siteUrl (which may be for the new feed) stays.
        let mut fresh = base.clone();
        fresh.url = new_url.to_string();
        fresh.site_url = Some("https://c.example/".to_string());
        let merged = merge_rename(
            &merge_form(new_url, "Old", Some("at://f/old")),
            &base,
            fresh,
        )
        .expect("same url is no conflict");
        assert!(merged.already_saved);
        assert!(!merged.repoint);
        assert_eq!(merged.sub.site_url.as_deref(), Some("https://c.example/"));

        // siteUrl: both set it the same.
        let mut fresh = base.clone();
        fresh.site_url = Some("https://same.example/".to_string());
        let mut form = merge_form(url, "Old", Some("at://f/old"));
        form.site_url = Some("https://same.example/".to_string());
        let merged = merge_rename(&form, &base, fresh).expect("same siteUrl is no conflict");
        assert!(merged.already_saved);

        // A form with no edits at all is NOT "already saved": it writes, as
        // it always has.
        let merged = merge_rename(
            &merge_form(url, "Old", Some("at://f/old")),
            &base,
            base.clone(),
        )
        .unwrap();
        assert!(!merged.already_saved);
    }

    fn merge_form(url: &str, title: &str, folder: Option<&str>) -> RenameSubForm {
        RenameSubForm {
            url: url.to_string(),
            title: Some(title.to_string()),
            site_url: None,
            folder: folder.map(str::to_string),
            seen_url: None,
            seen_title: None,
            seen_folder: None,
        }
    }

    fn merge_base() -> Subscription {
        let mut s = Subscription::new("https://a.example/feed.xml", "2024-03-01T00:00:00.000Z");
        s.title = Some("Old".to_string());
        s.folder = Some("at://f/old".to_string());
        s.site_url = Some("https://a.example/".to_string());
        s
    }

    /// The merge, field by field, for the branches the handler tests do not
    /// each reach: every field the reader changed that someone else also
    /// changed is a conflict; every field only one side changed merges.
    #[test]
    fn merge_rename_is_a_three_way_merge_per_field() {
        let base = merge_base();
        let url = "https://a.example/feed.xml";

        // Folder: both moved it -> conflict; only the reader -> applied.
        let mut theirs = base.clone();
        theirs.folder = Some("at://f/theirs".to_string());
        assert_eq!(
            merge_rename(
                &merge_form(url, "Old", Some("at://f/mine")),
                &base,
                theirs.clone()
            ),
            Err(RenameConflict("folder"))
        );
        let merged = merge_rename(
            &merge_form(url, "Old", Some("at://f/mine")),
            &base,
            base.clone(),
        )
        .unwrap();
        assert_eq!(merged.sub.folder.as_deref(), Some("at://f/mine"));
        assert!(!merged.repoint);
        // Only they moved it: theirs stands.
        let merged =
            merge_rename(&merge_form(url, "Old", Some("at://f/old")), &base, theirs).unwrap();
        assert_eq!(merged.sub.folder.as_deref(), Some("at://f/theirs"));

        // URL: both repointed -> conflict.
        let mut moved = base.clone();
        moved.url = "https://b.example/feed.xml".to_string();
        assert_eq!(
            merge_rename(
                &merge_form("https://c.example/feed.xml", "Old", Some("at://f/old")),
                &base,
                moved
            ),
            Err(RenameConflict("url"))
        );

        // siteUrl: a posted value both sides changed -> conflict.
        let mut resited = base.clone();
        resited.site_url = Some("https://theirs.example/".to_string());
        let mut form = merge_form(url, "Old", Some("at://f/old"));
        form.site_url = Some("https://mine.example/".to_string());
        assert_eq!(
            merge_rename(&form, &base, resited),
            Err(RenameConflict("siteUrl"))
        );

        // A reader's repoint drops the old feed's properties.
        let merged = merge_rename(
            &merge_form("https://c.example/feed.xml", "Old", Some("at://f/old")),
            &base,
            base.clone(),
        )
        .unwrap();
        assert!(merged.repoint);
        assert_eq!(merged.sub.url, "https://c.example/feed.xml");
        assert_eq!(merged.sub.site_url, None);

        // seen_* wins over base for "did the reader change it": the input was
        // pre-filled with a display title, and posting it back is no edit.
        let mut untitled = base.clone();
        untitled.title = None;
        let mut form = merge_form(url, "A display fallback", Some("at://f/old"));
        form.seen_title = Some("A display fallback".to_string());
        let merged = merge_rename(&form, &untitled, untitled.clone()).unwrap();
        assert_eq!(
            merged.sub.title, None,
            "an untouched display title was written"
        );
    }

    /// **A rename must not destroy the fields the form never carries.**
    ///
    /// `update_subscription` is a `putRecord` — the WHOLE record is replaced, per
    /// its own doc. The handler built a fresh `Subscription::new(url, now())`, so
    /// every field absent from `templates/manage_row.html` (which posts only
    /// `url`, `title`, `folder`) was written back as its default:
    ///
    /// | field | before | after |
    /// |---|---|---|
    /// | `siteUrl` | whatever the feed advertised | gone |
    /// | `fetchHint` | as set | gone |
    /// | `private` | as set | gone |
    /// | `createdAt` | original subscribe time | reset to now |
    ///
    /// `createdAt` is the worst of the four: it is the sort key for "when did I
    /// subscribe", it is unrecoverable once overwritten, and nothing in the UI
    /// tells the reader it moved.
    ///
    /// Asserted on the BYTES THE SIDECAR RECEIVES, not on a `Subscription` built
    /// in the test — the record only becomes wrong on the way out, so checking
    /// the value we passed in would pass just as happily with the fix removed.
    #[tokio::test]
    async fn renaming_preserves_the_fields_the_form_never_carries() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Exactly what the manage row posts: url, title, folder.
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&folder=Tech",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let body = &bodies[0];
        // Anchors the negative assertions: an empty capture would satisfy them.
        assert!(
            body.contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {body:?}"
        );

        let sent: serde_json::Value = serde_json::from_str(body).expect("put body is JSON");
        let record = &sent["record"];

        // What the form DID carry must be applied.
        assert_eq!(record["title"], "New title", "the rename did not apply");
        assert_eq!(record["folder"], "Tech", "the re-folder did not apply");

        // What the form did NOT carry must survive.
        assert_eq!(
            record["createdAt"], "2024-03-01T00:00:00.000Z",
            "the rename reset createdAt — the reader's subscribe time is gone \
             from their own repo, and nothing told them"
        );
        assert_eq!(
            record["siteUrl"], "https://example.com/blog",
            "the rename erased siteUrl"
        );
        assert_eq!(record["fetchHint"], "hourly", "the rename erased fetchHint");
        assert_eq!(record["private"], false, "the rename erased private");
    }

    /// **Repointing at a different feed drops that feed's properties, but not
    /// the subscription's.**
    ///
    /// `siteUrl` and `fetchHint` describe the feed the subscription points at,
    /// so carrying them onto a different URL would leave a site link for the old
    /// feed hanging off the new one. `createdAt` and `private` are properties of
    /// the SUBSCRIPTION and survive a repoint — the reader subscribed when they
    /// subscribed, whatever the URL was later corrected to.
    #[tokio::test]
    async fn repointing_a_feed_drops_the_old_feeds_properties_but_keeps_the_subscriptions() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // A DIFFERENT feed URL from the seeded record.
                    .body(Body::from(
                        "url=https%3A%2F%2Fother.example%2Ffeed.xml&title=Repointed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        assert!(
            bodies[0].contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {:?}",
            bodies[0]
        );
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        let record = &sent["record"];

        assert_eq!(record["url"], "https://other.example/feed.xml");
        // The old feed's properties are gone rather than misattributed.
        assert!(
            record.get("siteUrl").is_none() || record["siteUrl"].is_null(),
            "the old feed's site link followed the subscription to a new feed: {record}"
        );
        assert!(
            record.get("fetchHint").is_none() || record["fetchHint"].is_null(),
            "the old feed's fetch hint followed the subscription to a new feed: {record}"
        );
        // The subscription's own properties survive.
        assert_eq!(
            record["createdAt"], "2024-03-01T00:00:00.000Z",
            "a repoint is still not a new subscription; createdAt must not move"
        );
        assert_eq!(record["private"], false, "the repoint erased private");
    }

    /// **A rename against an rkey that is not in the repo writes NOTHING.**
    ///
    /// `update_subscription` is a `putRecord`, which CREATES the record when the
    /// rkey does not exist — with whatever `createdAt` we hand it. So without
    /// this refusal a rename against a stale or wrong rkey manufactures a
    /// subscription dated today, which is the bug this whole change exists to
    /// fix, arriving by a different door.
    ///
    /// The guard was untested when first written: removing it left all 733 tests
    /// green. An untested guard against the exact defect being fixed is how the
    /// two previous rounds of this problem got through.
    #[tokio::test]
    async fn renaming_an_unknown_rkey_writes_nothing() {
        let did = "did:plc:renamer4";
        // The sidecar serves exactly one record, at rkey `rk-keep`.
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    // ...and this is not it.
                    .uri("/subscriptions/rk-does-not-exist/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Ghost",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("flash="),
            "an unknown rkey redirected as though the rename had worked: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "a rename against an unknown rkey wrote a record — putRecord would \
             CREATE it, dated today: {:?}",
            puts.lock().unwrap()
        );
    }

    /// **A `site_url` the client actually sends is applied, not dropped.**
    ///
    /// `templates/manage_row.html` does not post this field, so it is tempting
    /// to read the arm that handles it as dead code. It is not:
    /// `RenameSubForm` carries `site_url`, so a hand-crafted POST reaches it
    /// today. Discarding the value instead of applying it left all 733 tests
    /// green.
    ///
    /// The value is scheme-checked on the way out by the repo-boundary vet, so
    /// this is a coverage gap rather than an exposure — but an untested path
    /// that writes a URL into the reader's PDS should not stay untested.
    #[tokio::test]
    async fn a_client_supplied_site_url_reaches_the_record() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Same feed URL, but carrying a site_url the manage row
                    // never sends.
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Kept\
                         &site_url=https%3A%2F%2Ftyped.example%2Fsite",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        assert!(
            bodies[0].contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {:?}",
            bodies[0]
        );
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        assert_eq!(
            sent["record"]["siteUrl"], "https://typed.example/site",
            "the client's siteUrl was dropped; the seeded record's survived instead"
        );
    }

    /// **A rename whose read fails writes NOTHING.**
    ///
    /// This is the property most easily lost when someone later touches this
    /// handler: falling back to `Subscription::new` on a read error looks like
    /// graceful degradation and is in fact the original bug, reinstated on
    /// exactly the path where it is hardest to notice. The reader must be told
    /// instead.
    #[tokio::test]
    async fn a_rename_whose_read_fails_writes_nothing() {
        let did = "did:plc:renamer5";
        // A port that accepts nothing: the read cannot succeed.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let dead = format!("http://{}", listener.local_addr().unwrap());
        drop(listener);

        let state = test_state_with_sidecar(&[did], &dead).await;
        let cookie = session_cookie(&state, did, None);
        let before = store::count_feeds(&state.db).await.unwrap();

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Doomed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("flash="),
            "a failed read redirected as though the rename had worked: {loc}"
        );
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            before,
            "a rename that could not read the record still wrote to the cache"
        );
    }

    /// Folder pre-selection regression: the manage rename row must mark the
    /// feed's CURRENT folder `<option>` as `selected`, so an untouched Save
    /// re-submits the current folder instead of silently un-foldering the feed.
    /// A loose (un-foldered) feed must mark "No folder" selected instead. Renders
    /// `ManageTemplate` directly so no PDS/sidecar round-trip is needed.
    #[test]
    fn manage_rename_row_preselects_current_folder() {
        let nav = Nav {
            handle: "@reader.example".to_string(),
            avatar: "RE".to_string(),
            view: "unread".to_string(),
            scope_qs: String::new(),
            folders: Vec::new(),
            loose_feeds: Vec::new(),
            manage_active: true,
        };
        let folder_options = vec![
            FolderOption {
                uri: "at://did:plc:x/app.folder/work".to_string(),
                name: "Work".to_string(),
            },
            FolderOption {
                uri: "at://did:plc:x/app.folder/fun".to_string(),
                name: "Fun".to_string(),
            },
        ];
        // A foldered feed (in "Work") and a loose feed (no folder), each with a
        // non-empty rkey so the rename form renders.
        let foldered = FeedView {
            rkey: "sub-foldered".to_string(),
            url: "https://work.example/feed.xml".to_string(),
            title: "Work Feed".to_string(),
            unread: 0,
            selected: false,
            folder: Some("at://did:plc:x/app.folder/work".to_string()),
        };
        let loose = FeedView {
            rkey: "sub-loose".to_string(),
            url: "https://loose.example/feed.xml".to_string(),
            title: "Loose Feed".to_string(),
            unread: 0,
            selected: false,
            folder: None,
        };
        let tmpl = ManageTemplate {
            card: Card::private(&Config::default()),
            version: VERSION,
            repo_url: REPO_URL,
            kofi_url: KOFI_URL,
            flash: String::new(),
            alert: String::new(),
            nav,
            folder_options,
            folders: vec![FolderView {
                rkey: "folder-work".to_string(),
                uri: "at://did:plc:x/app.folder/work".to_string(),
                name: "Work".to_string(),
                feeds: vec![foldered],
                selected: false,
            }],
            loose_feeds: vec![loose],
            standard_site: false,
        };
        let html = tmpl.render().unwrap();

        // The foldered feed's "Work" option is pre-selected.
        assert!(
            html.contains(
                r#"<option value="at://did:plc:x/app.folder/work" selected>Work</option>"#
            ),
            "foldered feed must pre-select its current folder: {html}"
        );
        // The loose feed's "No folder" option is pre-selected (appears for the
        // loose row, which has folder=None).
        assert!(
            html.contains(r#"<option value="" selected>No folder</option>"#),
            "loose feed must pre-select 'No folder': {html}"
        );

        // #149: the values each input was pre-filled with ride along, so the
        // handler can tell what the reader changed from what they merely saw.
        for want in [
            r#"<input type="hidden" name="seen_url" value="https://work.example/feed.xml" />"#,
            r#"<input type="hidden" name="seen_title" value="Work Feed" />"#,
            r#"<input type="hidden" name="seen_folder" value="at://did:plc:x/app.folder/work" />"#,
            r#"<input type="hidden" name="seen_folder" value="" />"#,
            // #268: the folder rename form says which name it showed.
            r#"<input type="hidden" name="seen_name" value="Work" />"#,
        ] {
            assert!(html.contains(want), "missing {want}: {html}");
        }
    }

    /// **The public stats page carries no user data.**
    ///
    /// It is reachable by anyone, so the thing worth pinning is what it does
    /// NOT say: nothing about how many people use the instance, nothing about
    /// which feeds fail, nothing about who reads what.
    #[tokio::test]
    async fn the_public_stats_page_exposes_no_user_data() {
        let state = test_state(&[]).await;
        store::ensure_seed(&state.db, &["did:plc:someone".to_string()])
            .await
            .unwrap();

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "stats must be public");

        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Structural checks, not word checks. The page's own prose says it
        // publishes no error rates, so searching for that PHRASE finds the
        // disclaimer rather than a leak — the first version of this test failed
        // on exactly that. What matters is whether identifiers or the
        // admin-only figures are present.
        assert!(
            !body.contains("did:"),
            "the public stats page leaked an identifier"
        );
        for admin_only in ["errp50ms", "p95ms", "live backend", "ok_count"] {
            assert!(
                !body.contains(admin_only),
                "the public page is showing the admin metrics column {admin_only:?}"
            );
        }
        // And it does render the aggregate it exists for.
        assert!(body.contains("Feeds tracked"));
        assert!(body.contains("Waiting to be polled"));
    }

    /// **The two states that stop feeds updating must be visible.**
    ///
    /// `overdue` and `polled_last_hour` move in BOTH and distinguish neither —
    /// and `overdue` moves the WRONG WAY for backoff, because backoff is applied
    /// by pushing `next_poll` forward, so a feed failing every fetch drops out of
    /// the backlog and makes the page read healthier. That inversion is what this
    /// test pins: a broken feed must raise a number, not lower one.
    #[tokio::test]
    async fn stats_distinguishes_backoff_from_a_watermark_pause() {
        let state = test_state(&[]).await;
        // Three feeds: one healthy, one flaky, one long dead.
        for (url, errors) in [
            ("https://ok.example/f.xml", 0),
            ("https://flaky.example/f.xml", 2),
            ("https://dead.example/f.xml", 9),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    // Pushed forward, exactly as backoff does — so none of these
                    // are counted as `overdue`.
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..errors {
                store::bump_feed_errors(
                    &state.db,
                    url,
                    feed::FailureKind::Fetch,
                    "connection refused",
                )
                .await
                .unwrap();
            }
        }

        let render_stats = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/stats")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap()
        };

        // **The fixture must actually be RUNNING, or this test measures nothing.**
        // `test_state` leaves `schedulers_enabled` false, and `fetching_state`
        // checks that BEFORE the watermark — so without these two lines every
        // render below reports "off" and the watermark can never surface. The
        // assertions still passed, for reasons unrelated to what they name: see
        // the two comments below.
        state.runtime_health.set_schedulers_enabled(true);
        state
            .runtime_health
            .poll_tick_completed(crate::store::now_unix());

        let body = render_stats(state.clone()).await;
        assert!(
            body.contains("Failing"),
            "backoff is still invisible on the public page"
        );
        // 2 failing, 1 of them badly (>= BADLY_BROKEN_ERRORS). Matched on the
        // value rather than on surrounding whitespace, so re-indenting the
        // template cannot break this.
        assert!(
            body.contains("2, 1 badly"),
            "expected '2, 1 badly' in the failing row; got:\n{}",
            body.split("Failing")
                .nth(1)
                .unwrap_or("")
                .chars()
                .take(300)
                .collect::<String>()
        );
        // Not paused, and the backlog is genuinely empty — which is exactly the
        // reading that used to be indistinguishable from healthy.
        //
        // **Asserted by EXCLUDING the other states, not by matching "running".**
        // The `off` row reads "the poller is not running on this instance", which
        // contains "running" — so the bare substring passed while the page was
        // reporting the exact opposite of what this line claims to check.
        assert!(
            !body.contains("the poller is not running")
                && !body.contains("the cache is at its size limit")
                && !body.contains("has not completed a round"),
            "expected the running state; the page reported a stopped one",
        );

        // Now trip the watermark. Nothing in the database changes; only the
        // recorded runtime state does — which is the whole reason it needed a
        // home outside the log stream.
        state.runtime_health.set_watermark(true);
        let paused = render_stats(state.clone()).await;
        // Matched on the paused row's OWN sentence. The bare word "paused" also
        // appeared in the page's explanatory prose, so this assertion passed
        // whether or not the row rendered — and trimming that prose is what
        // exposed it. This phrase exists only inside the `paused` branch.
        assert!(
            paused.contains("the cache is at its size limit"),
            "a watermark pause is still invisible on the public page"
        );

        // Still no identifiers: these are counts, not feeds.
        for leak in ["ok.example", "flaky.example", "dead.example", "did:"] {
            assert!(
                !paused.contains(leak),
                "the public page leaked {leak:?} while reporting failures"
            );
        }
    }

    /// **`/admin/metrics` is gated, and nothing checked that it was.**
    ///
    /// Deleting the `admin_seed_dids` check left the entire suite green. That
    /// was survivable while the page held only aggregate timings; it is not now,
    /// because this branch puts **per-feed URLs and remote error text** behind
    /// that gate. A guarantee nothing checks is a comment, and this one is now
    /// the only thing standing between a signed-in stranger and the operational
    /// picture the handler's own doc says is not public.
    ///
    /// All three doors: no session, a session that is not an admin, and the
    /// admin itself.
    #[tokio::test]
    async fn admin_metrics_is_refused_to_everyone_but_an_admin() {
        let admin = "did:plc:adminseed";
        // **Only the admin is in ALLOWED_DIDS**, because `admin_seed_dids()`
        // IS that list — deliberately, per its doc: "the same people I trust on
        // this instance". Production sets it to the bootstrap DID alone.
        //
        // A genuine non-admin is therefore someone holding a beta seat granted
        // by an invite, not by the allow-list. Seeding both would have made
        // both admins and quietly turned the 403 assertion below into a test of
        // nothing — which is exactly what the first draft of this did.
        let state = test_state(&[admin]).await;
        store::grant_access(&state.db, "did:plc:ordinaryuser", None, "invite", None)
            .await
            .unwrap();
        let url = "https://broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            url,
            feed::FailureKind::Fetch,
            "SENTINEL_ADMIN_ONLY",
        )
        .await
        .unwrap();

        let get = |state: AppState, cookie: Option<String>| async move {
            let mut req = Request::builder().uri("/admin/metrics");
            if let Some(c) = cookie {
                req = req.header(header::COOKIE, c);
            }
            let resp = router(state)
                .oneshot(req.body(Body::empty()).unwrap())
                .await
                .unwrap();
            let status = resp.status();
            let body = String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap();
            (status, body)
        };

        // No session at all.
        let (status, body) = get(state.clone(), None).await;
        assert_eq!(status, StatusCode::UNAUTHORIZED);
        assert!(
            !body.contains("SENTINEL_ADMIN_ONLY"),
            "leaked to anonymous: {body}"
        );

        // A real, signed-in user who is not an admin.
        let ordinary = session_cookie(&state, "did:plc:ordinaryuser", None);
        let (status, body) = get(state.clone(), Some(ordinary)).await;
        assert_eq!(
            status,
            StatusCode::FORBIDDEN,
            "a non-admin session was let in"
        );
        assert!(
            !body.contains("SENTINEL_ADMIN_ONLY") && !body.contains("broken.example"),
            "leaked to a non-admin: {body}",
        );

        // The admin does get it — otherwise the two refusals above are
        // satisfied by the endpoint being broken for everyone.
        let admin_cookie = session_cookie(&state, admin, None);
        let (status, body) = get(state, Some(admin_cookie)).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("SENTINEL_ADMIN_ONLY"),
            "admin cannot see it: {body}"
        );
    }

    /// **The cause a public count cannot carry belongs on the admin page.**
    ///
    /// The public histogram is four coarse buckets, and `fetch` is the coarsest:
    /// #159's own error — `guarded_get` bailing on a 304 — lands there beside
    /// DNS failure, timeout and SSRF refusal. So the histogram alone would NOT
    /// have separated "sixty dead publishers" from "one bug here", which is the
    /// case it was justified by.
    ///
    /// The answer is not a finer public vocabulary — `/stats` promises never
    /// which feed and never whose, and a bucket per error string would break
    /// that. It is to put the detail where per-feed data is already allowed.
    /// `/admin/metrics` is gated on `ALLOWED_DIDS` and already carries an
    /// operational picture.
    ///
    /// Asserts both halves: the detail IS on the admin page, and is NOT on the
    /// public one.
    #[tokio::test]
    async fn the_admin_page_names_failing_feeds_and_the_public_page_does_not() {
        let admin = "did:plc:adminseed";
        let state = test_state(&[admin]).await;
        let url = "https://broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            url,
            feed::FailureKind::Fetch,
            "SENTINEL_REDIRECT_NO_LOCATION",
        )
        .await
        .unwrap();

        let cookie = session_cookie(&state, admin, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/admin/metrics")
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let admin_body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        assert!(
            admin_body.contains("SENTINEL_REDIRECT_NO_LOCATION"),
            "the admin page does not carry the failure detail: {admin_body}",
        );
        assert!(
            admin_body.contains("broken.example"),
            "the admin page does not name the failing feed: {admin_body}",
        );

        // The public page still carries neither.
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let public = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        for secret in ["SENTINEL_REDIRECT_NO_LOCATION", "broken.example"] {
            assert!(
                !public.contains(secret),
                "{secret:?} reached the PUBLIC stats page: {public}",
            );
        }
    }

    /// **A direct poll must settle the error columns, like the scheduler does.**
    ///
    /// `add_subscription` polls through `feed::poll_feed` rather than the
    /// scheduler, and `poll_feed` writes validators and `last_polled` but never
    /// touches `consecutive_errors` — that is the scheduler's job, and this path
    /// is not the scheduler.
    ///
    /// So a feed that was failing, is re-subscribed, and polls SUCCESSFULLY kept
    /// its old count and its old cause: the public page went on reporting it
    /// under `Failing`, under `badly_broken`, and under a cause, for as long as
    /// the stale backoff horizon lasted — up to 24h — while the reader was
    /// demonstrably fetching it.
    #[tokio::test]
    async fn a_successful_direct_poll_clears_a_stale_failure() {
        let state = test_state(&[]).await;
        let url = "https://recovered.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(&state.db, url, feed::FailureKind::Fetch, "SENTINEL_OLD")
            .await
            .unwrap();
        // Park it on a stale backoff horizon, as a real failing feed would be.
        sqlx::query("UPDATE feeds SET next_poll = '2099-01-01T00:00:00Z' WHERE url = ?1")
            .bind(url)
            .execute(&state.db)
            .await
            .unwrap();

        // The publisher is fixed: a successful poll happens on this path.
        feed::settle_poll(
            &state.db,
            url,
            &feed::PollOutcome::NotModified,
            state.config.poll_interval,
        )
        .await;

        let row: (i64, Option<String>, Option<String>) = sqlx::query_as(
            "SELECT consecutive_errors, last_error_kind, next_poll FROM feeds WHERE url = ?1",
        )
        .bind(url)
        .fetch_one(&state.db)
        .await
        .unwrap();
        assert_eq!(row.0, 0, "a successful direct poll left the error streak");
        assert_eq!(row.1, None, "a successful direct poll left a stale cause");
        // **The half the first fix missed.** Clearing the count fixed the
        // REPORTING; the feed stayed parked until 2099. A working feed must be
        // rescheduled on its normal cadence, not left on the failure horizon.
        let next = row.2.expect("next_poll was cleared to NULL");
        // Not merely "moved off 2099" — rescheduled on the CADENCE, not a
        // backoff. A mutation that reschedules successes with backoff_for(1)
        // (5 min) also moves it off 2099, so the interval is asserted.
        let parsed = chrono::DateTime::parse_from_rfc3339(&next).unwrap();
        let delta = parsed
            .signed_duration_since(chrono::Utc::now())
            .num_seconds();
        let cadence = state.config.poll_interval.as_secs() as i64;
        assert!(
            (cadence - 60..=cadence + 60).contains(&delta),
            "expected rescheduling on the {cadence}s cadence, got {delta}s (next_poll={next})"
        );
    }

    /// The mirror case: a first poll that FAILS must be visible at all.
    ///
    /// `Ok(outcome) => info!(...)` discarded a `PollOutcome::Failed`, so a
    /// subscription whose very first fetch failed sat at `consecutive_errors = 0`
    /// with a NULL cause — invisible to the page built to count exactly that.
    #[tokio::test]
    async fn a_failing_direct_poll_is_recorded() {
        let state = test_state(&[]).await;
        let url = "https://born-broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();

        feed::settle_poll(
            &state.db,
            url,
            &feed::PollOutcome::Failed {
                backoff: std::time::Duration::from_secs(300),
                kind: feed::FailureKind::Parse,
                detail: "SENTINEL_BORN_BROKEN".to_string(),
            },
            state.config.poll_interval,
        )
        .await;

        let row: (i64, Option<String>, Option<String>) = sqlx::query_as(
            "SELECT consecutive_errors, last_error_kind, next_poll FROM feeds WHERE url = ?1",
        )
        .bind(url)
        .fetch_one(&state.db)
        .await
        .unwrap();
        assert_eq!(row.0, 1, "a failed first poll was not counted");
        assert_eq!(
            row.1.as_deref(),
            Some("parse"),
            "its cause was not recorded"
        );
        // And it is BACKED OFF on the schedule the scheduler would use — not
        // left with a NULL next_poll that `due_feeds` sorts first and re-polls
        // on the very next tick.
        let next = row.2.expect("a failed direct poll left next_poll NULL");
        let parsed = chrono::DateTime::parse_from_rfc3339(&next).unwrap();
        let delta = parsed
            .signed_duration_since(chrono::Utc::now())
            .num_seconds();
        assert!(
            (240..=360).contains(&delta),
            "expected ~300s backoff after one failure, got {delta}s (next_poll={next})"
        );
    }

    /// **The breakdown must sum to the Failing figure above it.**
    ///
    /// The histogram counts `last_error_kind IS NOT NULL`; `Failing` counts
    /// `consecutive_errors > 0`. On a migrated database every row that was
    /// already failing has a NULL kind — correctly, it was never recorded — so
    /// the two do not reconcile and the page shows "70 failing" beside "3
    /// fetch" with 67 silently unaccounted for. On deploy day the row vanishes
    /// entirely while the prose still promises a breakdown.
    ///
    /// An explicit `unknown` bucket is the honest shape: the page says how many
    /// it cannot explain rather than omitting them.
    #[tokio::test]
    async fn the_failure_breakdown_accounts_for_every_failing_feed() {
        let state = test_state(&[]).await;
        // Two legacy rows: failing, with no recorded cause.
        for url in [
            "https://legacy1.example/f.xml",
            "https://legacy2.example/f.xml",
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            sqlx::query("UPDATE feeds SET consecutive_errors = 4 WHERE url = ?1")
                .bind(url)
                .execute(&state.db)
                .await
                .unwrap();
        }
        // One row with a recorded cause.
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://known.example/f.xml".to_string(),
                next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            "https://known.example/f.xml",
            feed::FailureKind::Status,
            "SENTINEL",
        )
        .await
        .unwrap();

        let now = chrono::Utc::now();
        let health = store::poll_health(
            &state.db,
            &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        )
        .await
        .unwrap();
        let counted: i64 = health.failure_kinds.iter().map(|(_, n)| n).sum();
        assert_eq!(
            counted, health.in_backoff,
            "the breakdown ({counted}) does not account for all {} failing feeds: {:?}",
            health.in_backoff, health.failure_kinds,
        );
        assert!(
            health
                .failure_kinds
                .iter()
                .any(|(k, n)| k == "unknown" && *n == 2),
            "no unknown bucket for the legacy rows: {:?}",
            health.failure_kinds,
        );
    }

    /// **The breakdown is ordered by count, and the assertion can see it.**
    ///
    /// The first version of this asserted with three `contains` calls, which
    /// cannot observe order — deleting `ORDER BY` from the query passed.
    #[tokio::test]
    async fn the_failure_breakdown_is_ordered_by_count() {
        let state = test_state(&[]).await;
        for (url, kind, n) in [
            ("https://p1.example/f.xml", feed::FailureKind::Parse, 1),
            ("https://f1.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://f2.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://f3.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://s1.example/f.xml", feed::FailureKind::Status, 1),
            ("https://s2.example/f.xml", feed::FailureKind::Status, 1),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..n {
                store::bump_feed_errors(&state.db, url, kind, "d")
                    .await
                    .unwrap();
            }
        }
        let now = chrono::Utc::now();
        let health = store::poll_health(
            &state.db,
            &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        )
        .await
        .unwrap();
        let labels: Vec<&str> = health
            .failure_kinds
            .iter()
            .map(|(k, _)| k.as_str())
            .collect();
        assert_eq!(
            labels,
            ["fetch", "status", "parse"],
            "not ordered by count, descending: {:?}",
            health.failure_kinds,
        );
    }

    /// **Failing feeds are grouped by CAUSE, and still never named.**
    ///
    /// `badly_broken` could say that sixty feeds were failing and not whether
    /// that was sixty dead publishers or one bug here. It was the latter — #159,
    /// a `304 Not Modified` read as a malformed redirect — and the page could
    /// not say so, which is most of why it went unexamined.
    ///
    /// The second half of this test is the constraint that shapes the first:
    /// `/stats` is public and promises machines-not-people, *never which feed
    /// and never whose*. A histogram of causes keeps that promise; a list of
    /// failing URLs would break it, and is the obvious way to build this.
    #[tokio::test]
    async fn stats_groups_failures_by_cause_without_naming_any_feed() {
        let state = test_state(&[]).await;
        for (url, kind, detail, errors) in [
            // Detail strings are distinctive SENTINELS, not plausible English.
            // A first pass used "not a feed", which the page's own explanation
            // of the `parse` kind contains verbatim — the privacy assertion
            // fired on static copy rather than on a leak. A sentinel cannot
            // collide with prose.
            (
                "https://a.example/f.xml",
                feed::FailureKind::Fetch,
                "SENTINEL_CONNREFUSED",
                3,
            ),
            (
                "https://b.example/f.xml",
                feed::FailureKind::Fetch,
                "SENTINEL_DNSFAIL",
                2,
            ),
            (
                "https://c.example/f.xml",
                feed::FailureKind::Status,
                "SENTINEL_404",
                1,
            ),
            (
                "https://d.example/f.xml",
                feed::FailureKind::Parse,
                "SENTINEL_UNPARSEABLE",
                1,
            ),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..errors {
                store::bump_feed_errors(&state.db, url, kind, detail)
                    .await
                    .unwrap();
            }
        }

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Descending by count: two fetch, then one each, tie-broken by name.
        assert!(
            body.contains("2 fetch") && body.contains("1 status") && body.contains("1 parse"),
            "the cause histogram did not render: {body}",
        );

        // **The privacy half.** No feed URL, host, or error detail reaches the
        // public page — only counts by kind.
        for secret in [
            "a.example",
            "b.example",
            "c.example",
            "d.example",
            "SENTINEL_CONNREFUSED",
            "SENTINEL_DNSFAIL",
            "SENTINEL_404",
            "SENTINEL_UNPARSEABLE",
        ] {
            assert!(
                !body.contains(secret),
                "{secret:?} reached the PUBLIC stats page: {body}",
            );
        }
    }

    /// `/health` must prove the process can reach its database, and must report
    /// the loop state without letting it change the status code.
    #[tokio::test]
    async fn health_checks_the_database_and_reports_the_loops() {
        let state = test_state(&[]).await;
        let body_of = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/health")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            let status = resp.status();
            let body = String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap();
            (status, body)
        };

        // The boot stamp is what `main` sets; the router alone does not, so this
        // starts "unknown" and the uptime branch below drives it explicitly.
        state
            .runtime_health
            .set_started_at(chrono::Utc::now().timestamp());

        let (status, body) = body_of(state.clone()).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("db: ok"),
            "health did not probe the DB: {body}"
        );
        assert!(
            body.contains("uptime:"),
            "no uptime — the first thing anyone asks about a container that may \
             be restarting: {body}"
        );
        assert!(body.contains("poller:"), "no scheduler heartbeat: {body}");
        assert!(body.contains("polling-paused: no"), "{body}");
        assert!(body.contains("backend:"), "{body}");
        assert!(body.contains("oauth-runtime:"), "{body}");

        // A watermark pause is REPORTED but must not fail the check. A failed
        // check DEREGISTERS this machine from the proxy — and it is the only
        // machine — so it would turn "feeds are behind" into "the site is down"
        // for as long as the disk stays full.
        state.runtime_health.set_watermark(true);
        state.runtime_health.set_schedulers_enabled(true);
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::OK,
            "a watermark pause must not fail the liveness check: {body}"
        );
        assert!(body.contains("polling-paused: yes"), "{body}");
        // Schedulers on but no tick yet — and that must not read as "0s ago",
        // which is the healthiest possible answer to an unanswered question.
        assert!(
            body.contains("poller: not-yet-ticked"),
            "a never-ticked poller must say so: {body}"
        );

        // A stale heartbeat is likewise reported, not fatal.
        let stale_after = health_tick_stale_secs(configured_poll_tick());
        let long_ago = chrono::Utc::now().timestamp() - (stale_after + 60);
        state.runtime_health.poll_tick_completed(long_ago);
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::OK,
            "a stale poller must not 503: {body}"
        );
        assert!(body.contains("poller: stale"), "{body}");

        // **A poller that has never ticked stops being benign.**
        //
        // In a crash loop with 30 s+ boot cycles the poller never reaches its
        // first tick, so `not-yet-ticked` was reported forever and the heartbeat
        // could not detect the one failure mode the startup delays were added
        // for. It is read against uptime now.
        state.runtime_health.poll_tick_completed(0); // reset to "never"
        state
            .runtime_health
            .set_started_at(chrono::Utc::now().timestamp() - (HEALTH_FIRST_TICK_GRACE_SECS + 60));
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("poller: stale never-ticked"),
            "a poller that never ticked long after boot still reads as benign: {body}"
        );

        // A closed pool is a real outage: nothing can be served, and a restart is
        // the correct response. THIS is what the status code is for.
        state.db.close().await;
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::SERVICE_UNAVAILABLE,
            "an unreachable database must fail the check: {body}"
        );
        assert!(body.starts_with("FAIL"), "{body}");
        // Coarse, not the raw sqlx error: an unauthenticated caller learning
        // exactly which failure it hit is an attack-progress oracle, and this
        // endpoint is exempt from the origin lock.
        assert!(
            !body.contains("PoolClosed") && !body.contains("sqlx"),
            "health leaked the raw database error to an unauthenticated caller: {body}"
        );
    }

    /// The staleness threshold must track the configured tick.
    ///
    /// Hardcoded at 15 minutes, an operator who raised
    /// `FEATHERREADER_POLL_TICK_SECS` above 900 got a permanent `poller: stale`
    /// in the body the deployment docs tell them to alert on.
    #[test]
    fn the_stale_threshold_follows_the_poll_tick() {
        // A fast tick keeps the floor — five 60 s ticks is 5 minutes, and
        // alerting that early would fire on any brief hiccup.
        assert_eq!(
            health_tick_stale_secs(Duration::from_secs(60)),
            HEALTH_TICK_STALE_FLOOR_SECS
        );
        // A slow tick raises it, so a legitimately-configured loop is never
        // permanently "stale".
        let slow = Duration::from_secs(30 * 60);
        assert!(
            health_tick_stale_secs(slow) > slow.as_secs() as i64,
            "a 30-minute tick must not be stale after one interval"
        );
        assert_eq!(health_tick_stale_secs(slow), 30 * 60 * 5);
        // And it cannot overflow into nonsense on an absurd value.
        assert!(health_tick_stale_secs(Duration::from_secs(u64::MAX)) > 0);
    }

    /// `/stats` must distinguish "nothing is polling" from "polling is fine".
    ///
    /// `polling_paused` alone rendered "running" for three different states,
    /// including the two where nothing polls at all — on the page added to
    /// answer exactly that question.
    #[tokio::test]
    async fn stats_does_not_call_a_stopped_poller_running() {
        let state = test_state(&[]).await;
        let render = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/stats")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap()
        };

        // Schedulers never started: not "running".
        let body = render(state.clone()).await;
        assert!(
            body.contains("the poller is not running on this instance"),
            "a disabled poller renders as healthy"
        );

        // Started, but no tick has finished yet.
        state.runtime_health.set_schedulers_enabled(true);
        let body = render(state.clone()).await;
        assert!(
            body.contains("no poll has finished since this instance booted"),
            "a poller that has not ticked renders as healthy"
        );

        // Ticking: running.
        state
            .runtime_health
            .poll_tick_completed(chrono::Utc::now().timestamp());
        let body = render(state.clone()).await;
        assert!(
            body.contains("running"),
            "a healthy poller must read as running"
        );

        // Paused at the watermark still wins over "running".
        state.runtime_health.set_watermark(true);
        let body = render(state.clone()).await;
        assert!(
            body.contains("the cache is at its size limit"),
            "a watermark pause is hidden once the poller is ticking"
        );
    }

    /// **An UNMEASURED database must not fail the check.**
    ///
    /// `/health` is the one path exempt from the Cloudflare origin lock and
    /// absent from the rate limiter, and `DbProbeGuard` releases its claim on
    /// drop WITHOUT recording a verdict — so a cancelled request (a client
    /// disconnect is enough) leaves the verdict at "none", and a concurrent
    /// caller reads it. Treating that as a failure turned an unauthenticated
    /// request into a lever on the only signal the platform acts on. The
    /// previous version of this code had the opposite bug and reported `ok` for
    /// a database nothing had read; "unknown" is neither.
    #[tokio::test]
    async fn health_reports_an_unmeasured_database_without_failing() {
        use crate::runtime_health::DbProbe;
        let state = test_state(&[]).await;

        // Hold the probe claim, exactly as an in-flight request would, and never
        // record a verdict — the cancelled-request state.
        let held = state
            .runtime_health
            .begin_db_probe()
            .unwrap_or_else(|_| panic!("a fresh RuntimeHealth must grant the first claim"));

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        drop(held);

        assert_eq!(
            status,
            StatusCode::OK,
            "an unmeasured database failed the check, which an unauthenticated \
             caller can cause on demand: {body}"
        );
        assert!(
            body.contains("db: unknown"),
            "the unmeasured state must still be REPORTED: {body}"
        );
        assert!(!body.starts_with("FAIL"), "{body}");
        // **And it must not read as `ok` either.** `fly.toml` tells operators to
        // alert on the BODY for everything the status code ignores, so a first
        // line identical to the healthy one makes a monitor keying on `^ok` read
        // green in exactly the state this enum exists to surface.
        assert!(
            !body.starts_with("ok"),
            "the unmeasured state is indistinguishable from healthy to a \
             body-matching monitor: {body}"
        );
        assert!(body.starts_with("unknown"), "{body}");

        // **A BORROWED failure must 503 too.**
        //
        // This previously recorded `Failed` and then closed the pool — but
        // `record` consumes the guard and releases the claim, so the request won
        // it, ran a live probe against the closed pool, and failed on its own.
        // The 503 passed for the wrong reason and the borrow path — the whole
        // point of the three-state enum on the read side — had no coverage.
        //
        // Holding the claim forces the borrow, so the recorded verdict is what
        // gets reported.
        let held = state
            .runtime_health
            .begin_db_probe()
            .unwrap_or_else(|_| panic!("claim"));
        state
            .runtime_health
            .record_for_test(DbProbe::Failed("unavailable".to_string()));
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        drop(held);
        assert_eq!(
            status,
            StatusCode::SERVICE_UNAVAILABLE,
            "a BORROWED failure verdict must fail the check, not just a freshly \
             measured one: {body}"
        );
        assert!(body.starts_with("FAIL"), "{body}");

        state.db.close().await;
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::SERVICE_UNAVAILABLE,
            "a measured database failure must still fail the check"
        );
    }

    /// **A disconnected client must not be able to cancel the probe.**
    ///
    /// Axum drops the handler future when a caller goes away. With the probe
    /// inline that dropped it mid-flight and released the claim WITHOUT
    /// recording a verdict — which let an unauthenticated caller manufacture the
    /// no-verdict state on demand and freeze what every other caller, including
    /// Fly's own check, reads. The probe runs detached now, so the verdict is
    /// recorded whatever happens to the request that started it.
    #[tokio::test]
    async fn an_abandoned_request_still_records_its_probe() {
        use crate::runtime_health::DbProbe;
        let state = test_state(&[]).await;
        let rh = state.runtime_health.clone();

        // Drive /health and abandon it immediately — the disconnect case.
        let app = router(state.clone());
        let fut = app.oneshot(
            Request::builder()
                .uri("/health")
                .body(Body::empty())
                .unwrap(),
        );
        let handle = tokio::spawn(fut);
        handle.abort();
        let _ = handle.await;

        // The detached probe still completes and publishes a verdict, so the
        // claim is free and the next caller gets a MEASURED answer.
        for _ in 0..50 {
            if rh.begin_db_probe().is_ok() {
                break;
            }
            tokio::time::sleep(Duration::from_millis(20)).await;
        }
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        assert!(
            body.contains("db: ok"),
            "after an abandoned request the next caller still reads an \
             unmeasured database — the probe was cancelled with it: {body}"
        );
        // Sanity: the type still distinguishes the three states.
        assert_ne!(DbProbe::Unknown, DbProbe::Ok);
    }

    /// **The probe must read a real page.**
    ///
    /// `SELECT 1` compiles to `Init/Integer/ResultRow/Halt` — no `OpenRead`, so
    /// it never touches a b-tree and returns success against a corrupted
    /// database. Asserted by asking SQLite what the statement actually compiles
    /// to, so it survives someone "simplifying" the query later.
    #[tokio::test]
    async fn the_health_probe_opens_a_real_table() {
        use sqlx::Row;
        let state = test_state(&[]).await;
        // `EXPLAIN` lists the VM program; the `opcode` column is the second.
        let opcodes = |sql: &'static str| {
            let db = state.db.clone();
            async move {
                sqlx::query(sql)
                    .fetch_all(&db)
                    .await
                    .unwrap()
                    .into_iter()
                    .map(|r| r.get::<String, _>("opcode"))
                    .collect::<Vec<String>>()
            }
        };

        // The statement `health_db_probe` really runs — it is the sole path, so
        // there is no second string for the handler to use instead.
        let explain: &'static str =
            Box::leak(format!("EXPLAIN {HEALTH_DB_PROBE_SQL}").into_boxed_str());
        let probe = opcodes(explain).await;
        // And the probe itself works against a real schema.
        assert!(
            health_db_probe(&state.db).await.is_ok(),
            "the probe does not run against the real schema",
        );
        assert!(
            probe.iter().any(|op| op == "OpenRead"),
            "the health probe reads no page; it cannot detect a broken database: {probe:?}"
        );
        // And the bare form genuinely does not, which is the whole point.
        let bare = opcodes("EXPLAIN SELECT 1").await;
        assert!(
            !bare.iter().any(|op| op == "OpenRead"),
            "premise check failed: bare SELECT 1 now reads a page: {bare:?}"
        );
    }

    /// A fresh instance says "never", not "0" — which would read as "polled
    /// just now", the opposite of the truth.
    #[test]
    fn an_instance_that_has_never_polled_says_so() {
        assert_eq!(humanise_ago(None), "never");
        assert_eq!(humanise_ago(Some(0)), "0s ago");
        assert_eq!(humanise_ago(Some(59)), "59s ago");
        assert_eq!(humanise_ago(Some(60)), "1m ago");
        assert_eq!(humanise_ago(Some(3600)), "1h 0m ago");
        assert_eq!(humanise_ago(Some(11_460)), "3h 11m ago");
    }

    /// A sidecar mock that answers `/internal/repo` listRecords with one saved
    /// record, and anything else with an empty list. Serves repeatedly.
    async fn spawn_saved_sidecar(saved_url: &str, saved_title: &str) -> String {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let (url, title) = (saved_url.to_string(), saved_title.to_string());
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let Ok(n) = sock.read(&mut buf).await else {
                    continue;
                };
                let req = String::from_utf8_lossy(&buf[..n]).to_string();
                let wants_saved = req.contains("community.lexicon.rss.saved");
                let records = if wants_saved {
                    serde_json::json!([{
                        "uri": "at://did:plc:x/community.lexicon.rss.saved/rk1",
                        "cid": "bafy",
                        "value": {
                            "$type": "community.lexicon.rss.saved",
                            "url": url,
                            "title": title,
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else {
                    serde_json::json!([])
                };
                let body = serde_json::json!({
                    "ok": true, "data": { "records": records }
                })
                .to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(), body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    /// A sidecar mock serving `n` distinct saved records, none of them cached
    /// locally — the shape that exercises the uncached-row append.
    async fn spawn_saved_sidecar_many(n: usize, subscribed_feed: &str) -> String {
        let feed = subscribed_feed.to_string();
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let Ok(read) = sock.read(&mut buf).await else {
                    continue;
                };
                let req = String::from_utf8_lossy(&buf[..read]).to_string();
                let records = if req.contains("community.lexicon.rss.saved") {
                    serde_json::Value::Array(
                        (0..n)
                            .map(|i| {
                                serde_json::json!({
                                    "uri": format!("at://did:plc:x/community.lexicon.rss.saved/rk{i}"),
                                    "cid": "bafy",
                                    "value": {
                                        "$type": "community.lexicon.rss.saved",
                                        "url": format!("https://elsewhere.example/{i}"),
                                        "title": format!("Elsewhere {i}"),
                                        "createdAt": "2026-01-01T00:00:00Z"
                                    }
                                })
                            })
                            .collect(),
                    )
                } else if req.contains("community.lexicon.rss.subscription") {
                    // Without this the handler's `sync_sub_refs` would REPLACE
                    // sub_ref with an empty set on every render, and every
                    // sub_ref-scoped read — including the cached starred list
                    // this test is about — would come back empty.
                    serde_json::json!([{
                        "uri": "at://did:plc:x/community.lexicon.rss.subscription/sub1",
                        "cid": "bafy",
                        "value": {
                            "$type": "community.lexicon.rss.subscription",
                            "url": feed,
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else {
                    serde_json::json!([])
                };
                let body =
                    serde_json::json!({ "ok": true, "data": { "records": records } }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(), body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    /// **The pager must not advertise a page the clamp cannot reach.**
    ///
    /// The page clamp is computed from the CACHED total; the uncached PDS rows
    /// are appended to the last page rather than paged. Inflating `total` with
    /// them made `page_count` and the "Older →" link point one page past the end:
    /// requesting it clamped straight back, re-rendered the same last page, and
    /// still offered the link. An infinite "next" that never advances.
    #[tokio::test]
    async fn the_starred_pager_does_not_advertise_an_unreachable_page() {
        let did = "did:plc:pagerloop";
        let sidecar = spawn_saved_sidecar_many(80, "https://loop.example/feed.xml").await;
        let state = test_state_with_sidecar(&[], &sidecar).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://loop.example/feed.xml".to_string(),
                title: Some("Loop".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // 250 cached starred entries: the last page holds 50, so 50 + 80 > 100
        // and the old arithmetic reported a fourth page.
        let entries: Vec<store::NewEntry> = (0..250)
            .map(|i| store::NewEntry {
                guid: format!("s-{i:04}"),
                url: Some(format!("https://loop.example/{i}")),
                title: Some(format!("Starred {i:04}")),
                published: Some(format!("2026-06-{:02}T00:00:00Z", (i % 28) + 1)),
                ..Default::default()
            })
            .collect();
        store::insert_entries(&state.db, feed, &entries, 0)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        for row in store::list_entries(&state.db, did, store::ListView::All, None, 1_000, 0)
            .await
            .unwrap()
        {
            store::mark_starred(&state.db, did, row.id, true)
                .await
                .unwrap();
        }

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let get = |uri: &str| {
            let (app, cookie, uri) = (app.clone(), cookie.clone(), uri.to_string());
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .uri(uri)
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                String::from_utf8(
                    axum::body::to_bytes(resp.into_body(), 16 * 1024 * 1024)
                        .await
                        .unwrap()
                        .to_vec(),
                )
                .unwrap()
            }
        };

        // 250 cached + 80 uncached = 330 rows over 4 pages. The pager and the
        // clamp must agree on that, and EVERY page it offers must have content —
        // the original bug advertised a fourth page that clamped back to the
        // third and re-rendered it, still offering the link.
        let p3 = get("/?view=starred&page=3").await;
        assert!(
            p3.contains("Page 3 of 4"),
            "the pager and the clamp disagree on the total: {}",
            p3.split("pager-pos")
                .nth(1)
                .unwrap_or("")
                .chars()
                .take(120)
                .collect::<String>()
        );
        // Page 3 is the boundary: the last 50 cached rows, then the first 50
        // uncached ones.
        assert!(
            p3.contains("Elsewhere 0"),
            "page 3 should start the uncached run"
        );
        assert_eq!(
            p3.matches("<li class=\"entry").count(),
            ENTRIES_PER_PAGE as usize,
            "the boundary page is not full"
        );

        // **The heading, which the previous round broke by deleting this.**
        //
        // `total` includes the uncached records, so the parenthetical is a
        // SUBSET of it, not an addition — "330 entries (80 saved elsewhere)".
        // The version that said "plus N" double counted once `total` started
        // including them, and N had become page-local in the same commit while
        // the template stayed put. It shipped because this assertion was deleted
        // rather than updated.
        {
            let body = &p3;
            assert!(
                body.contains("330 entries"),
                "the heading must count the whole sequence: {}",
                body.split("content-count")
                    .nth(1)
                    .unwrap_or("")
                    .chars()
                    .take(120)
                    .collect::<String>()
            );
            assert!(
                body.contains("(80 saved elsewhere)"),
                "the heading must say how many of the total the cache cannot show, \
                 as a whole-list figure and not a per-page one: {}",
                body.split("content-count")
                    .nth(1)
                    .unwrap_or("")
                    .chars()
                    .take(120)
                    .collect::<String>()
            );
            assert!(
                !body.contains("plus 50") && !body.contains("plus 80"),
                "the heading is adding the uncached rows to a total that already \
                 includes them"
            );
        }

        let p4 = get("/?view=starred&page=4").await;
        assert!(
            p4.contains("Page 4 of 4"),
            "page 4 was advertised but clamps somewhere else — the unreachable-page bug"
        );
        assert_eq!(
            p4.matches("<li class=\"entry").count(),
            30,
            "page 4 should hold the remaining 30 uncached records"
        );
        assert!(
            p4.contains("Elsewhere 79"),
            "the LAST saved record is unreachable — it can only be removed from here"
        );

        // No uncached record appears on two pages.
        assert!(
            !p4.contains("Elsewhere 0"),
            "an uncached record was rendered on more than one page"
        );
        // Page 1 is all cached — and still reports the same whole-list heading,
        // because the parenthetical describes the LIST, not the page.
        let first = get("/?view=starred").await;
        assert!(
            first.contains("330 entries") && first.contains("(80 saved elsewhere)"),
            "the heading changed between pages; it describes the list, not the page"
        );
        assert!(
            !first.contains("Elsewhere "),
            "uncached saved records leaked onto the first page"
        );
    }

    /// **A saved record whose article is not cached here is still shown.**
    ///
    /// The starred view is built from local `entries`, so before this a record
    /// starred in ANOTHER atproto reader — the portability the shared lexicon
    /// exists for — was simply invisible. It now renders from the PDS record,
    /// visually distinct, linking straight out.
    #[tokio::test]
    async fn a_saved_record_with_no_cached_entry_is_shown_as_a_link() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let sidecar =
            spawn_saved_sidecar("https://elsewhere.example/article", "Starred elsewhere").await;
        let mut state = test_state_with_sidecar(&[did], &sidecar).await;
        std::sync::Arc::get_mut(&mut state.config).unwrap().dev_did = Some(did.to_string());

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/?view=starred")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        assert!(
            body.contains("Starred elsewhere"),
            "the saved record was not rendered at all"
        );
        assert!(
            body.contains("entry-uncached"),
            "it was not marked as uncached, so it looks like a normal entry"
        );
        assert!(
            body.contains("https://elsewhere.example/article"),
            "the row must link straight to the article"
        );
        assert!(
            !body.contains("/entries/0/"),
            "an uncached row must not offer entry actions against a nonexistent id"
        );
    }

    /// **A PDS `createdAt` must not be able to panic the starred view.**
    ///
    /// `display_date` byte-sliced `p[..10]`. Every prior caller passed a
    /// timestamp the feed parser produced; the saved-record path passes a bare
    /// string off a PDS record, written by whatever client the reader used. A
    /// multi-byte value panicked the handler, and with no catch-panic layer the
    /// view stayed down until the record was removed — from that same view.
    #[test]
    fn a_multibyte_timestamp_does_not_panic_the_date_formatter() {
        for hostile in [
            "日本語日本語日本",
            "é",
            "",
            "2026",
            "🙂🙂🙂🙂🙂🙂🙂🙂🙂🙂🙂",
        ] {
            let out = display_date(Some(hostile));
            assert!(out.chars().count() <= 10, "{hostile:?} -> {out:?}");
        }
        assert_eq!(display_date(Some("2026-01-01T00:00:00Z")), "2026-01-01");
        assert_eq!(display_date(None), "");
    }

    /// Unsaving makes a DPoP-signed PDS round-trip, which is the stated reason
    /// its neighbours are limited. It was added as a route and not added here.
    #[test]
    fn the_unsave_route_is_rate_limited() {
        use axum::http::Method;
        assert!(is_rate_limited_path("/saved/3abc/delete", &Method::POST));
        // And the neighbours still are.
        assert!(is_rate_limited_path("/entries/1/star", &Method::POST));
    }

    /// **The probe detects a broken database — asserted through `/health`
    /// itself, not through a string.**
    ///
    /// A named constant did not bind the handler: it stayed free to call
    /// `query_scalar` with a different literal, so degrading the real probe to
    /// `SELECT 1` shipped green twice over. This drops the table the probe reads
    /// and asserts the endpoint stops saying `ok` — behaviour no substituted SQL
    /// can fake, because `SELECT 1` still succeeds against a wrecked schema.
    #[tokio::test]
    async fn health_reports_a_broken_database() {
        let state = test_state(&[]).await;
        // Sanity: healthy first, so the assertion below is about the damage.
        assert!(
            health_db_probe(&state.db).await.is_ok(),
            "the fixture was not healthy to begin with",
        );

        sqlx::query("DROP TABLE feeds")
            .execute(&state.db)
            .await
            .unwrap();

        assert!(
            health_db_probe(&state.db).await.is_err(),
            "the probe reported success against a database missing the table it \
             claims to read; `SELECT 1` would do exactly this",
        );

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        // The documented contract: the FIRST token is the state.
        assert!(
            body.starts_with("FAIL"),
            "/health did not report FAIL for a broken database: {body}",
        );
        assert!(
            !body.contains("db: ok"),
            "/health still called the database ok: {body}",
        );
    }

    /// A sidecar mock for the OPML export: serves one subscription and one
    /// folder, except for the collection named in `fail_on`, which answers
    /// `500` — the shape a refused (short or unreadable) walk takes at this
    /// boundary.
    async fn spawn_export_sidecar(fail_on: Option<&'static str>) -> String {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let Ok(n) = sock.read(&mut buf).await else {
                    continue;
                };
                let req = String::from_utf8_lossy(&buf[..n]).to_string();
                let wants = |c: &str| req.contains(c);
                if fail_on.is_some_and(wants) {
                    let body = r#"{"ok":false,"error":"ShortList"}"#;
                    let resp = format!(
                        "HTTP/1.1 500 Internal Server Error\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                        body.len(),
                        body
                    );
                    let _ = sock.write_all(resp.as_bytes()).await;
                    let _ = sock.flush().await;
                    continue;
                }
                let records = if wants(crate::lexicon::nsid::SUBSCRIPTION) {
                    serde_json::json!([{
                        "uri": "at://did:plc:exporter/community.lexicon.rss.subscription/sub1",
                        "cid": "bafy",
                        "value": {
                            "$type": crate::lexicon::nsid::SUBSCRIPTION,
                            "url": "https://kept.example/feed.xml",
                            "title": "Kept",
                            // Inside the folder, so the healthy export has to
                            // carry BOTH walks' results: an exporter that lost
                            // the folder list would flatten this outline out of
                            // its group with nothing else changing.
                            "folder": "at://did:plc:exporter/community.lexicon.rss.folder/fold1",
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else if wants(crate::lexicon::nsid::FOLDER) {
                    serde_json::json!([{
                        "uri": "at://did:plc:exporter/community.lexicon.rss.folder/fold1",
                        "cid": "bafy",
                        "value": {
                            "$type": crate::lexicon::nsid::FOLDER,
                            "name": "Kept folder",
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else {
                    serde_json::json!([])
                };
                let body =
                    serde_json::json!({ "ok": true, "data": { "records": records } }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    /// A sidecar whose every `listRecords` page carries one good record and
    /// one with no `uri` — the #177 shape — for any collection.
    async fn spawn_malformed_sidecar() -> String {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let _ = sock.read(&mut buf).await;
                let body = serde_json::json!({ "ok": true, "data": { "records": [
                    { "uri": "at://did:plc:alerted/c/3labGOOD", "cid": "bafy", "value": {} },
                    { "cid": "bafy", "value": {} },
                ]}})
                .to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    async fn page_body(state: AppState, did: &str, uri: &str) -> (StatusCode, String) {
        let cookie = session_cookie(&state, did, None);
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri(uri)
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        (status, String::from_utf8_lossy(&body).to_string())
    }

    /// **0.4.0 step 4: a publication document with neither summary field
    /// renders as a title, a date and a link** — 8% of measured documents
    /// (37 of 449) carry neither `description` nor `textContent`. That is what
    /// an RSS reader shows for a title-only feed, not an error, in the list and
    /// on the article page alike.
    #[tokio::test]
    async fn a_publication_entry_with_no_summary_renders_title_date_and_link() {
        let did = "did:plc:displayer";
        let state = test_state(&[did]).await;
        let url = "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/site.standard.publication/3lab";
        let feed_id = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.into(),
                title: Some("Quiet Journal".into()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed_id])
            .await
            .unwrap();
        store::insert_entries(
            &state.db,
            feed_id,
            &[store::NewEntry {
                guid: "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/site.standard.document/3l2nosumaaa2a"
                    .into(),
                url: Some("https://quiet.example/no-summary".into()),
                title: Some("A title-only article".into()),
                published: Some("2026-07-11T00:00:00Z".into()),
                content_html: None,
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        let (status, list) = page_body(state.clone(), did, "/?view=all").await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            list.contains("A title-only article"),
            "the entry is missing from the list"
        );

        let id: i64 = sqlx::query_scalar("SELECT id FROM entries WHERE feed_id = ?")
            .bind(feed_id)
            .fetch_one(&state.db)
            .await
            .unwrap();
        let (status, page) = page_body(state, did, &format!("/entries/{id}")).await;
        assert_eq!(
            status,
            StatusCode::OK,
            "the article page failed for an entry with no body"
        );
        assert!(page.contains("A title-only article"));
        assert!(
            page.contains("https://quiet.example/no-summary"),
            "no link to the original"
        );
        assert!(
            page.contains(r#"<time datetime=""#),
            "no date on the article page"
        );
    }

    /// **#177: a malformed record in the reader's own repo is refused, and the
    /// reader is told.** Refusing keeps `replace_sub_refs` from dropping the
    /// subscription that record was; telling them keeps the stale list from
    /// looking like the real one. Both the reading page and the manage page.
    #[tokio::test]
    async fn a_malformed_subscription_record_raises_an_alert() {
        let did = "did:plc:alerted";
        for page in ["/", "/manage"] {
            let sidecar = spawn_malformed_sidecar().await;
            let state = test_state_with_sidecar(&[did], &sidecar).await;
            let (status, body) = page_body(state, did, page).await;
            assert_eq!(status, StatusCode::OK, "{page} did not render");
            assert!(
                body.contains(r#"role="alert""#) && body.contains("could not be read"),
                "{page} rendered no alert for a refused subscription list"
            );
            assert!(
                body.contains("1 record(s) in your subscription list"),
                "{page} gave the generic alert, not the malformed-record one"
            );
        }
    }

    /// The control: a healthy listing raises no alert.
    #[tokio::test]
    async fn a_healthy_subscription_listing_raises_no_alert() {
        let did = "did:plc:exporter";
        let sidecar = spawn_export_sidecar(None).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let (status, body) = page_body(state, did, "/").await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            !body.contains("could not be read"),
            "a healthy listing raised an alert"
        );
    }

    /// `GET /opml/export` against the mock, returning `(status, headers, body)`.
    async fn export_opml_response(
        fail_on: Option<&'static str>,
    ) -> (StatusCode, HeaderMap, String) {
        let did = "did:plc:exporter";
        let sidecar = spawn_export_sidecar(fail_on).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/opml/export")
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let headers = resp.headers().clone();
        let body = String::from_utf8_lossy(
            &axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap(),
        )
        .to_string();
        (status, headers, body)
    }

    /// **An empty export is worse than no export, and this is the caller that
    /// used to produce one.**
    ///
    /// `export_opml` read both walks through `unwrap_or_default()`. Now that a
    /// truncated walk refuses instead of returning a short list, that turned the
    /// refusal into `200 OK` carrying a zero-feed
    /// `featherreader-subscriptions.opml` — a blank backup handed over at exactly
    /// the moment a locked-out reader reached for one, and the changelog points
    /// them at this route as the recovery path.
    ///
    /// Asserts the three things a reader can actually observe: no success status,
    /// no download offered, and no OPML document in the body.
    #[tokio::test]
    async fn an_export_that_cannot_read_the_subscriptions_serves_no_opml() {
        let (status, headers, body) =
            export_opml_response(Some(crate::lexicon::nsid::SUBSCRIPTION)).await;

        assert_ne!(
            status,
            StatusCode::OK,
            "a failed subscription walk answered 200: {body}",
        );
        assert!(
            !headers.contains_key(header::CONTENT_DISPOSITION),
            "a failed subscription walk still offered a download: {headers:?}",
        );
        assert!(
            !body.contains("<opml"),
            "a failed subscription walk still served an OPML document: {body}",
        );
    }

    /// The folders half of the same hole. The two walks are separate calls, and
    /// fixing only the first leaves an export that silently loses every folder —
    /// a flat list that reimports as one, with no sign anything was lost.
    #[tokio::test]
    async fn an_export_that_cannot_read_the_folders_serves_no_opml() {
        let (status, headers, body) =
            export_opml_response(Some(crate::lexicon::nsid::FOLDER)).await;

        assert_ne!(
            status,
            StatusCode::OK,
            "a failed folder walk answered 200: {body}",
        );
        assert!(
            !headers.contains_key(header::CONTENT_DISPOSITION),
            "a failed folder walk still offered a download: {headers:?}",
        );
        assert!(
            !body.contains("<opml"),
            "a failed folder walk still served an OPML document: {body}",
        );
    }

    /// The other direction, without which "refuse everything" would pass both
    /// tests above: a healthy read still serves the file, with the feed in it.
    #[tokio::test]
    async fn a_healthy_export_serves_the_subscriptions_as_a_download() {
        let (status, headers, body) = export_opml_response(None).await;

        assert_eq!(
            status,
            StatusCode::OK,
            "a healthy export did not answer 200"
        );
        assert_eq!(
            headers
                .get(header::CONTENT_DISPOSITION)
                .and_then(|v| v.to_str().ok()),
            Some("attachment; filename=\"featherreader-subscriptions.opml\""),
            "a healthy export did not offer the download",
        );
        assert!(
            body.contains("https://kept.example/feed.xml"),
            "the exported OPML lost the subscription: {body}",
        );
        assert!(
            body.contains("Kept folder"),
            "the exported OPML lost the folder: {body}",
        );
    }
}