forge_connectors/

slack.rs

//! The Slack Web API client: one uniform POST per method, form params,
//! Bearer token, and the envelope rules that turn a logical failure into
//! an error.
//!
//! Slack answers `{"ok": false, "error": "..."}` with HTTP 200 for a
//! logical failure, so a 200 is not success. Only a 429 arrives as a
//! status, and it carries `Retry-After`.

use std::collections::{HashMap, HashSet};
use std::hash::BuildHasher;
use std::sync::Arc;
use std::time::Duration;

use tokio::sync::oneshot;

use forge_primitives::slack::{
    SlackBookmark, SlackConversation, SlackFile, SlackFollowedThread, SlackMessage, SlackPin,
    SlackSearchMatch, SlackSubscription, SlackSubscriptionTarget, SlackThreadOwner, SlackUser,
    SlackWatchMode,
};
use serde::Deserialize;
use serde::de::DeserializeOwned;

/// What the pump needs from the workspace. The connector holds no state
/// of its own, so the subscription set, the watermarks and the liveness
/// flag all live behind this.
pub trait SlackHost: Send + Sync {
    /// A ready API for this workspace, or an error when the workspace is
    /// not configured. The host builds it, so the token stays with the
    /// workspace and the connector never asks for the credential itself.
    /// The trait object is what the pump drives, so a test host can hand
    /// back a double instead of a live client.
    fn client(&self, workspace: &str, timeout: Duration) -> Result<Arc<dyn SlackApi>, String>;

    /// The authenticated user's id for a workspace, resolved at boot.
    /// Needed to recognise `<@U...>` mentions.
    fn user_id(&self, workspace: &str) -> Option<String>;

    /// The display name this workspace has already resolved for a user id,
    /// or `None` when it has not. A `users.info` lookup is a call, so the
    /// host keeps what it has learned rather than the sweep re-asking for
    /// every message from a known author.
    fn user_name(&self, workspace: &str, user: &str) -> Option<String>;

    /// Record a user's display name, so the next message from them is free.
    fn set_user_name(&self, workspace: &str, user: &str, name: &str);

    /// The subscriptions scoped to one workspace.
    fn subscriptions(&self, workspace: &str) -> Vec<SlackSubscription>;

    /// The last timestamp delivered for a conversation, or `None` when it
    /// has never been swept. An error means the cursor could not be read:
    /// the caller skips the conversation rather than sweeping it from the
    /// beginning, which would deliver its whole history as new.
    fn watermark(&self, workspace: &str, conversation: &str) -> Result<Option<String>, String>;

    /// Record the last timestamp delivered. A `ts` is a string with a
    /// microsecond fraction; never round-trip it through a number.
    fn set_watermark(&self, workspace: &str, conversation: &str, ts: &str);

    /// The threads tracked for a conversation, each with the owners still
    /// subscribed to it. The host prunes while listing: an owner whose
    /// subscription is gone is dropped from the record, a row's last owner
    /// deletion removes the row, and a row idle past the host's drop age
    /// never comes back.
    fn followed_threads(&self, workspace: &str, conversation: &str) -> Vec<SlackFollowedThread>;

    /// How far a thread's replies have been read: normally the newest reply
    /// seen, and nothing at all before the first walk. An error means the
    /// cursor could not be read: the caller skips the thread this tick
    /// rather than walking it from the parent.
    fn thread_watermark(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
    ) -> Result<Option<String>, String>;

    /// Advance a thread's reply cursor. It is compared as a string, and the
    /// per-tick read sends one microsecond below it as the walk's `oldest` -
    /// see `just_below` - so a reply at the cursor is re-read for an edit.
    fn set_thread_watermark(&self, workspace: &str, conversation: &str, parent_ts: &str, ts: &str);

    /// Record that the user is in a thread, so later walks read past the
    /// cursor instead of reading the thread whole to find out again.
    fn mark_thread_participating(&self, workspace: &str, conversation: &str, parent_ts: &str);

    /// When this thread was last read whole, if it ever was. **The attempt
    /// is stamped whether or not the read lands**, so a thread that errors or
    /// is past the page cap backs off instead of retrying every tick.
    fn thread_full_read_at(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
    ) -> Option<std::time::Instant>;

    /// Record a whole-thread read attempt at `at`.
    fn mark_thread_full_read(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
        at: std::time::Instant,
    );

    /// Whether this thread's next walk is its first since the row was
    /// created. **Peek, not take**: a throttled or failed first walk must
    /// keep the mark, or the replay guard is lost for the row's life. A first
    /// walk filters by `ts` alone: its seed is `latest_reply`, which an edit
    /// does not move, so an edit-aware filter would hand over corrections the
    /// previous row already had.
    fn thread_first_walk(&self, workspace: &str, conversation: &str, parent_ts: &str) -> bool;

    /// Clear the first-walk mark, once that walk has actually read the thread.
    fn clear_thread_first_walk(&self, workspace: &str, conversation: &str, parent_ts: &str);

    /// The newest edit stamp a whole read has already judged. A whole read
    /// tests `edited` against this, never against the reply cursor: the cheap
    /// tick moves the cursor to the newest reply, and an edit below it would
    /// otherwise be behind the cursor forever. **Durable with the thread
    /// row**, not process state: a restart that lost it would judge every
    /// edited reply against nothing and re-offer corrections already
    /// delivered.
    fn thread_edit_watermark(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
    ) -> Option<String>;

    /// Advance a thread's edit watermark to `ts`.
    fn set_thread_edit_watermark(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
        ts: &str,
    );

    /// Whether this is the first time an author lookup has failed for this
    /// user. The lookup is retried either way; this only decides whether the
    /// failure is worth a line a reader sees, since a persistent one - a
    /// token missing `users:read`, a network that is down - would otherwise
    /// report itself for every author on every tick.
    fn first_author_failure(&self, workspace: &str, user: &str) -> bool;

    /// The same once-per-user line for a held draft's tag lookup. Kept apart
    /// from [`Self::first_author_failure`] so a draft's miss does not spend
    /// the line the sweep relies on, and the sweep's does not hide the draft's.
    fn first_draft_user_failure(&self, workspace: &str, user: &str) -> bool;

    /// Track a thread, owned by the matching subscription. A new row's cursor
    /// starts at `since`, which the caller picks to be recent enough to
    /// survive the idle window and below everything still worth delivering.
    /// Tracking again by another owner adds that owner and keeps the cursor.
    fn follow_thread(
        &self,
        workspace: &str,
        conversation: &str,
        parent_ts: &str,
        owner: SlackThreadOwner,
        since: &str,
    );

    /// Liveness for the Inspector's status line.
    fn set_connected(&self, workspace: &str, connected: bool);

    /// Fill in a conversation's display name on any subscription that has
    /// none, so the Inspector can render the name rather than the raw id.
    /// Only unnamed records are touched: a conversation renamed since it
    /// was subscribed keeps the stored name.
    fn name_conversation(&self, workspace: &str, conversation: &str, name: &str);

    /// Hand one conversation's matched messages to its subscriber's
    /// session, as the one block they will be read as. Returns whether
    /// delivery succeeded: a `false` means the caller did not advance the
    /// conversation cursor past this batch, so the next sweep re-delivers
    /// it instead of losing it.
    fn deliver(&self, subscription: &SlackSubscription, messages: &[SlackMessage]) -> bool;

    /// Called after a mention is delivered, so the conversation it came
    /// from is watched too and the agent can reply into it rather than
    /// only seeing the ping. Returns whether a record was added: the host
    /// does nothing when that owner already covers the conversation.
    fn auto_subscribe(&self, workspace: &str, message: &SlackMessage) -> bool;

    /// Whether forge posted this message itself, read from the outbound
    /// ledger by its ts. This is what the sweep refuses: forge posts as
    /// the user, so the author says nothing about who wrote the words.
    fn own_post(&self, workspace: &str, conversation: &str, ts: &str) -> bool;

    /// How long the oldest live post call in `conversation` has been in
    /// flight, or `None` when none is. A message can reach history before
    /// the post call returns and its ts is ledgered, so the sweep skips
    /// the conversation for the tick instead of delivering its own post.
    /// A mark older than [`REQUEST_TIMEOUT`] is the host's to expire,
    /// never something to obey.
    fn post_in_flight(&self, workspace: &str, conversation: &str) -> Option<Duration>;
}

/// The Web API calls this connector makes, behind a trait so a sweep or
/// an outbound call can be driven from a test double instead of a live
/// workspace.
///
/// Public because forge-workspace holds one and cannot store a trait it
/// cannot name, the same reason [`SlackHost`] is public. It abstracts
/// this one connector's own surface; it is not a trait shared between
/// connectors.
#[async_trait::async_trait]
pub trait SlackApi: Send + Sync {
    /// Who the token belongs to; the boot probe's only call.
    async fn auth_test(&self) -> Result<AuthTest, SlackError>;
    async fn list_conversations(&self) -> Result<Vec<SlackConversation>, SlackError>;
    async fn history(
        &self,
        channel: &str,
        oldest: Option<&str>,
        newest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError>;
    async fn replies(
        &self,
        channel: &str,
        ts: &str,
        oldest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError>;
    /// Post one message, as a root or into an existing thread. Returns the
    /// posted message's `ts`, the handle a reply, an edit, a delete and a
    /// reaction all take, and the channel it landed in - a request can
    /// address a user id or a channel name instead of the conversation id.
    async fn post_message(
        &self,
        channel: &str,
        text: &str,
        thread_ts: Option<&str>,
    ) -> Result<PostedMessage, SlackError>;
    /// Replace the text of one of the authenticated user's own messages.
    async fn update_message(&self, channel: &str, ts: &str, text: &str) -> Result<(), SlackError>;
    /// Delete one of the authenticated user's own messages.
    async fn delete_message(&self, channel: &str, ts: &str) -> Result<(), SlackError>;
    /// Add or remove one reaction on a message.
    async fn set_reaction(
        &self,
        channel: &str,
        ts: &str,
        name: &str,
        add: bool,
    ) -> Result<(), SlackError>;
    /// GET an absolute URL with the bearer attached, for a private file.
    async fn get_bytes(&self, url: &str) -> Result<Vec<u8>, SlackError>;
    /// POST raw bytes to an absolute pre-signed URL, with no bearer.
    async fn post_bytes(&self, url: &str, body: Vec<u8>) -> Result<(), SlackError>;
    /// `files.info` for one file id.
    async fn file_info(&self, id: &str) -> Result<SlackFile, SlackError>;
    /// `files.getUploadURLExternal`: the pre-signed URL to POST the bytes
    /// to, plus the file id the completion call needs.
    async fn get_upload_url(
        &self,
        name: &str,
        length: usize,
    ) -> Result<(String, String), SlackError>;
    /// `files.completeUploadExternal`, which can be called once only.
    /// Returns the files it reports: when Slack fills their `shares`, that
    /// already names the message the upload was posted as.
    async fn complete_upload(
        &self,
        file_id: &str,
        channel: &str,
        thread_ts: Option<&str>,
    ) -> Result<Vec<SlackFile>, SlackError>;
    /// `search.messages`, always timestamp-ordered. The cursor follows a
    /// previous page when one sweep has more hits than one page holds.
    async fn search_messages(
        &self,
        query: &str,
        count: u32,
        cursor: Option<&str>,
    ) -> Result<SearchPage, SlackError>;
    /// `users.info` for one user id.
    async fn user_info(&self, user: &str) -> Result<SlackUser, SlackError>;
    /// Every member in the workspace. Deactivated members are included so
    /// the caller decides what a row means.
    async fn list_users(&self) -> Result<Vec<SlackUser>, SlackError>;
    /// `pins.list` for one conversation.
    async fn pins(&self, channel: &str) -> Result<Vec<SlackPin>, SlackError>;
    /// `bookmarks.list` for one conversation.
    async fn bookmarks(&self, channel: &str) -> Result<Vec<SlackBookmark>, SlackError>;
}

#[async_trait::async_trait]
impl SlackApi for SlackClient {
    async fn auth_test(&self) -> Result<AuthTest, SlackError> {
        SlackClient::auth_test(self).await
    }

    async fn list_conversations(&self) -> Result<Vec<SlackConversation>, SlackError> {
        SlackClient::list_conversations(self).await
    }

    async fn history(
        &self,
        channel: &str,
        oldest: Option<&str>,
        newest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError> {
        SlackClient::history(self, channel, oldest, newest, limit, cursor).await
    }

    async fn replies(
        &self,
        channel: &str,
        ts: &str,
        oldest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError> {
        SlackClient::replies(self, channel, ts, oldest, limit, cursor).await
    }

    async fn post_message(
        &self,
        channel: &str,
        text: &str,
        thread_ts: Option<&str>,
    ) -> Result<PostedMessage, SlackError> {
        SlackClient::post_message(self, channel, text, thread_ts).await
    }

    async fn update_message(&self, channel: &str, ts: &str, text: &str) -> Result<(), SlackError> {
        SlackClient::update_message(self, channel, ts, text).await
    }

    async fn delete_message(&self, channel: &str, ts: &str) -> Result<(), SlackError> {
        SlackClient::delete_message(self, channel, ts).await
    }

    async fn set_reaction(
        &self,
        channel: &str,
        ts: &str,
        name: &str,
        add: bool,
    ) -> Result<(), SlackError> {
        SlackClient::set_reaction(self, channel, ts, name, add).await
    }

    async fn get_bytes(&self, url: &str) -> Result<Vec<u8>, SlackError> {
        SlackClient::get_bytes(self, url).await
    }

    async fn post_bytes(&self, url: &str, body: Vec<u8>) -> Result<(), SlackError> {
        SlackClient::post_bytes(self, url, body).await
    }

    async fn file_info(&self, id: &str) -> Result<SlackFile, SlackError> {
        SlackClient::file_info(self, id).await
    }

    async fn get_upload_url(
        &self,
        name: &str,
        length: usize,
    ) -> Result<(String, String), SlackError> {
        SlackClient::get_upload_url(self, name, length).await
    }

    async fn complete_upload(
        &self,
        file_id: &str,
        channel: &str,
        thread_ts: Option<&str>,
    ) -> Result<Vec<SlackFile>, SlackError> {
        SlackClient::complete_upload(self, file_id, channel, thread_ts).await
    }

    async fn search_messages(
        &self,
        query: &str,
        count: u32,
        cursor: Option<&str>,
    ) -> Result<SearchPage, SlackError> {
        SlackClient::search_messages(self, query, count, cursor).await
    }

    async fn user_info(&self, user: &str) -> Result<SlackUser, SlackError> {
        SlackClient::user_info(self, user).await
    }

    async fn list_users(&self) -> Result<Vec<SlackUser>, SlackError> {
        SlackClient::list_users(self).await
    }

    async fn pins(&self, channel: &str) -> Result<Vec<SlackPin>, SlackError> {
        SlackClient::pins(self, channel).await
    }

    async fn bookmarks(&self, channel: &str) -> Result<Vec<SlackBookmark>, SlackError> {
        SlackClient::bookmarks(self, channel).await
    }
}

/// The largest text `chat.postMessage` carries without truncating. The
/// probe measured a silent cut at 4000 with `ok: true`, so a longer draft
/// is split and posted in sequence rather than quietly halved.
pub const POST_LIMIT: usize = 4000;

/// Budget per part once a draft is split, leaving room for the `[i/n] `
/// prefix each part carries.
const POST_PART_BUDGET: usize = 3800;

/// Split `text` into parts each under [`POST_LIMIT`], numbered so a
/// reader can see the order. Text at or under the limit is one part.
pub fn split_for_post(text: &str) -> Vec<String> {
    if text.chars().count() <= POST_LIMIT {
        return vec![text.to_owned()];
    }
    let chars: Vec<char> = text.chars().collect();
    let total = chars.len().div_ceil(POST_PART_BUDGET);
    chars
        .chunks(POST_PART_BUDGET)
        .enumerate()
        .map(|(index, chunk)| {
            format!("[{}/{}] {}", index + 1, total, chunk.iter().collect::<String>())
        })
        .collect()
}

/// Whether `text` carries a mention of `user_id`.
pub fn mentions(text: &str, user_id: &str) -> bool {
    text.contains(&format!("<@{user_id}>"))
}

/// Every user id a message's text tags, once each, in order of appearance.
/// Slack writes a mention as `<@U...>`, optionally carrying a display label
/// after a `|`; a channel reference and a link start with a different sigil
/// and are not people.
pub fn mention_ids(text: &str) -> Vec<String> {
    let mut ids: Vec<String> = Vec::new();
    let mut rest = text;
    while let Some(start) = rest.find("<@") {
        let after = &rest[start + 2..];
        let Some(end) = after.find('>') else { break };
        let id = after[..end].split('|').next().unwrap_or_default();
        if is_user_id(id) && !ids.iter().any(|seen| seen == id) {
            ids.push(id.to_owned());
        }
        rest = &after[end + 1..];
    }
    ids
}

/// Whether a token is a Slack user id rather than some other `<@...>` text.
fn is_user_id(id: &str) -> bool {
    id.chars().next().is_some_and(|first| first.is_ascii_alphabetic())
        && id.chars().all(|ch| ch.is_ascii_alphanumeric())
}

/// The prose a message reads as when a card quotes it: Slack's mrkdwn is
/// flattened - a mention is `@name` from `names` (the bare id when it
/// cannot be named), a link its label or address, and `*text*` its text.
/// A token this does not understand is left exactly as written. Flattening
/// stops once `limit` non-space characters have been emitted, which is
/// enough for the excerpt bound; a single long token still scans the text
/// after the bound.
pub fn flatten_mrkdwn<S: BuildHasher>(
    text: &str,
    names: &HashMap<String, String, S>,
    limit: usize,
) -> String {
    let chars: Vec<char> = text.chars().collect();
    let mut out = String::with_capacity(text.len().min(limit.saturating_mul(2)));
    let mut non_space = 0usize;
    let mut index = 0;
    while index < chars.len() && non_space <= limit {
        match chars[index] {
            // Only a recognised token is markup; a literal `<` in the text
            // is not a bracket that runs to the next `>` somewhere later.
            '<' => {
                let token = chars[index + 1..]
                    .iter()
                    .position(|&ch| ch == '>')
                    .map(|offset| index + 1 + offset)
                    .filter(|end| is_markup_token(&chars[index + 1..*end]));
                if let Some(end) = token {
                    let inner: String = chars[index + 1..end].iter().collect();
                    let flat = flatten_token(&inner, names);
                    non_space += flat.chars().filter(|ch| !ch.is_whitespace()).count();
                    out.push_str(&flat);
                    index = end + 1;
                } else {
                    out.push('<');
                    non_space += 1;
                    index += 1;
                }
            }
            // A `*` pair is bold only where Slack would read it as bold; a
            // glob such as `src/*.rs` keeps both stars.
            '*' if opens_bold(&chars, index) => {
                if let Some(close) = first_bold_closer(&chars, index) {
                    let inner: String = chars[index + 1..close].iter().collect();
                    let flat = flatten_mrkdwn(&inner, names, limit);
                    non_space += flat.chars().filter(|ch| !ch.is_whitespace()).count();
                    out.push_str(&flat);
                    index = close + 1;
                } else {
                    out.push('*');
                    non_space += 1;
                    index += 1;
                }
            }
            ch => {
                if !ch.is_whitespace() {
                    non_space += 1;
                }
                out.push(ch);
                index += 1;
            }
        }
    }
    out
}

/// A `*` opens a bold span only at a word boundary, with text after it and
/// no doubled marker either side - the `**` of a literal and the `*` of a
/// glob are literals rather than openers. The rule mirrors `strip_emphasis`
/// in `forge-server`'s `envelope.rs`; a change there should move here.
fn opens_bold(chars: &[char], at: usize) -> bool {
    let before = at.checked_sub(1).and_then(|p| chars.get(p));
    let after = chars.get(at + 1).copied();
    before.is_none_or(|p| !p.is_alphanumeric() && *p != '*')
        && after.is_some_and(|n| !n.is_whitespace() && n != '*')
}

/// The first `*` after `open` able to close a span opened there: non-space
/// before it, no word character after it, and no ability to open a span of
/// its own - otherwise the two stars of a pair of globs would close a span
/// between them.
fn first_bold_closer(chars: &[char], open: usize) -> Option<usize> {
    ((open + 1)..chars.len()).find(|&j| {
        chars[j] == '*'
            && chars.get(j - 1).is_some_and(|p| !p.is_whitespace())
            && chars.get(j + 1).is_none_or(|n| !n.is_alphanumeric())
            && !opens_bold(chars, j)
    })
}

/// Whether `<token>` is one of Slack's markup tokens rather than text that
/// happens to sit between two brackets.
fn is_markup_token(token: &[char]) -> bool {
    match token.first().copied() {
        Some('@' | '#' | '!') => true,
        Some('h') => {
            token.starts_with(&['h', 't', 't', 'p', 's', ':', '/', '/'])
                || token.starts_with(&['h', 't', 't', 'p', ':', '/', '/'])
        }
        Some('m') => token.starts_with(&['m', 'a', 'i', 'l', 't', 'o', ':']),
        _ => false,
    }
}

/// One `<...>` token flattened. A mention takes its name from `names`, a
/// link its label or address; a channel reference, a broadcast and any
/// token this does not recognise keep their own text.
fn flatten_token<S: BuildHasher>(inner: &str, names: &HashMap<String, String, S>) -> String {
    if let Some(rest) = inner.strip_prefix('@') {
        let id = rest.split('|').next().unwrap_or_default();
        if is_user_id(id) {
            return names.get(id).map_or_else(|| id.to_owned(), |name| format!("@{name}"));
        }
        return format!("<{inner}>");
    }
    if inner.starts_with('#') || inner.starts_with('!') {
        return format!("<{inner}>");
    }
    match inner.split_once('|') {
        Some((_, label)) if !label.is_empty() => label.to_owned(),
        Some((address, _)) => address.to_owned(),
        None => inner.to_owned(),
    }
}

/// One flattened line of a message's text, for a card that quotes it: the
/// whitespace collapses, and a line past `limit` characters stops at the
/// last space before the bound where there is one, marked with an ellipsis.
pub fn one_line_excerpt(text: &str, limit: usize) -> String {
    let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
    if flat.chars().count() <= limit {
        return flat;
    }
    let prefix: String = flat.chars().take(limit).collect();
    let kept = prefix.rfind(' ').map_or(prefix.as_str(), |at| &prefix[..at]);
    format!("{}...", kept.trim_end())
}

/// Every message a file was shared as, as `(conversation, ts)`. The
/// conversation is the share's own - the channel Slack posted into, which
/// need not be the string the upload was addressed with. Both the upload's
/// answer and `files.info` carry these when Slack fills them.
pub fn shared_messages(file: &SlackFile) -> Vec<(String, String)> {
    file.shares
        .public
        .iter()
        .chain(file.shares.private.iter())
        .flat_map(|(conversation, shares)| {
            shares.iter().map(move |share| (conversation.clone(), share.ts.clone()))
        })
        .collect()
}

/// Whether one subscription wants this message. forge posts as the user, so
/// a message is refused by identity - its ts in the outbound ledger - and
/// never by author: refusing every message the user wrote drops what Ved
/// types himself, and a thread he is in then reads one-sided.
fn matches(
    subscription: &SlackSubscription,
    conversation: &SlackConversation,
    text: &str,
    ts: &str,
    user_id: &str,
    own_post: &dyn Fn(&str) -> bool,
) -> bool {
    if own_post(ts) {
        return false;
    }
    match &subscription.target {
        SlackSubscriptionTarget::DirectMessages => conversation.is_im || conversation.is_mpim,
        SlackSubscriptionTarget::Conversation { id, mode, .. } => {
            id == &conversation.id
                && match mode {
                    SlackWatchMode::All => true,
                    SlackWatchMode::MentionsOnly => mentions(text, user_id),
                }
        }
        // Swept by search, never by conversation.
        SlackSubscriptionTarget::Mentions => false,
    }
}

/// Whether any of `subscriptions` wants this message.
pub fn wants(
    subscriptions: &[SlackSubscription],
    conversation: &SlackConversation,
    text: &str,
    ts: &str,
    user_id: &str,
    own_post: &dyn Fn(&str) -> bool,
) -> bool {
    subscriptions.iter().any(|s| matches(s, conversation, text, ts, user_id, own_post))
}

/// Whether any subscription names this conversation, ignoring the mode and
/// the author. Decides which conversations a sweep fetches history for: a
/// mentions-only subscription still has to look, or it would never see a
/// mention arrive.
fn targets(subscriptions: &[SlackSubscription], conversation: &SlackConversation) -> bool {
    subscriptions.iter().any(|subscription| covers(subscription, conversation))
}

/// Whether one subscription watches this conversation at all, whatever its
/// mode and whoever wrote the message.
fn covers(subscription: &SlackSubscription, conversation: &SlackConversation) -> bool {
    match &subscription.target {
        SlackSubscriptionTarget::DirectMessages => conversation.is_im || conversation.is_mpim,
        SlackSubscriptionTarget::Conversation { id, .. } => id == &conversation.id,
        // Swept by search, never by conversation.
        SlackSubscriptionTarget::Mentions => false,
    }
}

/// Whether this subscription wants a thread's replies. Watching a
/// conversation is not the same as wanting everything in it: a
/// `mentions`-mode subscription asked to be told when it is named, and it is
/// told through the match, so it owns no thread - or every thread the sweep
/// anchors would deliver every reply to a session that asked for mentions.
/// A `Mentions` target is swept by search and owns no conversation at all.
fn owns_threads(subscription: &SlackSubscription, conversation: &SlackConversation) -> bool {
    covers(subscription, conversation)
        && !matches!(
            &subscription.target,
            SlackSubscriptionTarget::Conversation { mode: SlackWatchMode::MentionsOnly, .. }
        )
}

/// The thread a delivered message anchors: its own thread when it is a
/// reply, the thread it starts when it is a parent that already has
/// replies, and nothing for a plain top-level message - or every message
/// would grow the tracked set.
fn followed_parent_of(message: &SlackHistoryMessage) -> Option<String> {
    message.thread_ts.clone().or_else(|| is_thread_parent(message).then(|| message.ts.clone()))
}

/// Whether a message is a thread's parent, which is what decides whose
/// replies the sweep fetches. Slack sends a parent with `thread_ts` equal
/// to its own `ts`; `thread_ts` being present therefore says nothing about
/// whether a message is a reply, and a parent is instead the message that
/// reports replies and is its own thread root.
fn is_thread_parent(message: &SlackHistoryMessage) -> bool {
    message.reply_count > 0 && message.thread_ts.as_deref() == Some(message.ts.as_str())
}

/// Whether a thread is one the user is in, read from its replies: his own
/// message, or one that names him.
///
/// He replies from the Slack app rather than through forge, so this is
/// detected from the wire rather than remembered from forge's own record.
/// A mention counts, because being named in a thread is the other half of
/// the spec's rule.
fn participating(replies: &[SlackHistoryMessage], user_id: &str) -> bool {
    replies
        .iter()
        .any(|reply| reply.user.as_deref() == Some(user_id) || mentions(&reply.text, user_id))
}

/// The workspace's own identity, read from `auth.test` at most once a sweep.
struct OwnIdentity<'a> {
    /// The token's own user id, the one `auth.test` reports.
    id: &'a str,
    /// The name that id goes by; `asked` separates "not asked" from
    /// "asked, no name".
    name: Option<String>,
    asked: bool,
}

impl OwnIdentity<'_> {
    /// The name the token's own user goes by, asked of `auth.test` once a
    /// sweep. A failed call reads as no name; a throttle belongs to the
    /// sweep.
    async fn resolve_name(
        &mut self,
        api: &dyn SlackApi,
        workspace: &str,
    ) -> Result<Option<&str>, SlackError> {
        if !self.asked {
            match api.auth_test().await {
                Ok(auth) => self.name = Some(auth.user).filter(|name| !name.is_empty()),
                Err(error @ SlackError::RateLimited { .. }) => return Err(error),
                Err(error) => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        event_name = "slack_auth_test_failed",
                        workspace,
                        %error,
                        "auth.test failed; the author falls back to the name on the message, the app's on an app-authored post",
                    );
                }
            }
            self.asked = true;
        }
        Ok(self.name.as_deref())
    }
}

/// The name to show for a message's author, asked once per user per
/// conversation, or `None` when no name is known - the block drops the
/// clause rather than printing a raw id.
///
/// The conversation owns the memo so the same author costs one lookup however
/// many messages he sent; the host owns the longer memory, because a name is
/// worth keeping across sweeps. What the host keeps is only what Slack
/// settled: that a user has no name, or none worth showing. A lookup that
/// failed for any other reason - a dead socket, a 5xx, a throttled call -
/// says nothing about the user, so it is not remembered and the next message
/// asks again.
async fn author_of(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
    message: &SlackHistoryMessage,
    names: &mut HashMap<String, Option<String>>,
    own: &mut OwnIdentity<'_>,
) -> Result<Option<String>, SlackError> {
    let Some(user) = message.user.as_deref() else { return Ok(None) };
    if let Some(known) = names.get(user) {
        return Ok(known.clone());
    }
    let name = resolve_author(host, api, workspace, message, own).await?;
    names.insert(user.to_owned(), name.clone());
    Ok(name)
}

/// The name the token's own user goes by. A failed `auth.test` falls back to
/// the name the host already learned; `None` only when neither is known, and
/// the caller then uses whatever the wire offered.
///
/// Kept on the host as well as in `own`, because the host outlives a
/// sweep: a later `auth.test` that fails must not resurrect an app name
/// the host remembered.
async fn own_name(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
    own: &mut OwnIdentity<'_>,
) -> Result<Option<String>, SlackError> {
    let id = own.id;
    if let Some(name) = own.resolve_name(api, workspace).await? {
        host.set_user_name(workspace, id, name);
        return Ok(Some(name.to_owned()));
    }
    Ok(host.user_name(workspace, own.id).filter(|name| !name.is_empty()))
}

/// Resolves one author outright, without the per-conversation memo
/// [`author_of`] keeps.
async fn resolve_author(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
    message: &SlackHistoryMessage,
    own: &mut OwnIdentity<'_>,
) -> Result<Option<String>, SlackError> {
    let Some(user) = message.user.as_deref() else { return Ok(None) };
    // A message the user posts through the Slack app carries the app's
    // `bot_profile`; his own id is recognised before that name is read.
    if user == own.id
        && let Some(name) = own_name(host, api, workspace, own).await?
    {
        return Ok(Some(name));
    }
    if let Some(known) = host.user_name(workspace, user) {
        // An empty name is what a settled refusal leaves behind.
        return Ok((!known.is_empty()).then_some(known));
    }
    // A bot names itself in the payload, but an empty name there is no name:
    // it falls through to the lookup rather than being kept as one.
    let inline = message.bot_name.as_deref().filter(|name| !name.is_empty()).map(str::to_owned);
    let name = match inline {
        Some(name) => Some(name),
        None => match api.user_info(user).await {
            Ok(found) => Some(found.name).filter(|name| !name.is_empty()),
            // A rate limit belongs to the sweep: the pump has to back off
            // the way it does for every other call.
            Err(error @ SlackError::RateLimited { .. }) => return Err(error),
            // Slack says there is no such user, which is settled: asking
            // again would spend a call on every message from them forever.
            Err(SlackError::Api { error, .. }) if error == "user_not_found" => {
                tracing::debug!(
                    target: "forge_connectors::slack",
                    workspace,
                    user,
                    error = %error,
                    "slack knows no user by this id; the message carries no name",
                );
                None
            }
            // Anything else is forge's own call failing, and the reader
            // sees it as a message with no author at all - so it is
            // reported where the default log shows it, and nothing about
            // the user is remembered. Once per author: a failure that
            // persists would otherwise say so for every author on every
            // tick, and the retry is what recovers it, not the line.
            Err(error) => {
                if host.first_author_failure(workspace, user) {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        workspace,
                        user,
                        %error,
                        "resolving a slack author failed; the message carries no name this time",
                    );
                } else {
                    tracing::debug!(
                        target: "forge_connectors::slack",
                        workspace,
                        user,
                        %error,
                        "resolving a slack author failed again",
                    );
                }
                return Ok(None);
            }
        },
    };
    host.set_user_name(workspace, user, name.as_deref().unwrap_or_default());
    Ok(name)
}

/// The display name for a user id, from the host's cache or a `users.info`
/// lookup that is then remembered. `None` when the id cannot be named - the
/// caller draws the id rather than a guess. A failure that is not settled is
/// not remembered, so a later ask tries again.
pub async fn user_display_name(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
    user: &str,
) -> Option<String> {
    if let Some(known) = host.user_name(workspace, user) {
        return (!known.is_empty()).then_some(known);
    }
    match api.user_info(user).await {
        Ok(found) => {
            let name = Some(found.name).filter(|name| !name.is_empty());
            host.set_user_name(workspace, user, name.as_deref().unwrap_or_default());
            name
        }
        // Slack says there is no such user, which is settled: remember the
        // miss so every later draft does not spend a call on it.
        Err(SlackError::Api { error, .. }) if error == "user_not_found" => {
            host.set_user_name(workspace, user, "");
            None
        }
        Err(error) => {
            if host.first_draft_user_failure(workspace, user) {
                tracing::warn!(
                    target: "forge_connectors::slack",
                    event_name = "slack_draft_user_unreadable",
                    workspace,
                    user,
                    %error,
                    "resolving a slack user for a held draft failed; the card draws the id",
                );
            } else {
                tracing::debug!(
                    target: "forge_connectors::slack",
                    event_name = "slack_draft_user_unreadable",
                    workspace,
                    user,
                    %error,
                    "resolving a slack user for a held draft failed again",
                );
            }
            None
        }
    }
}

const API_ROOT: &str = "https://slack.com/api";

/// Used when the response carries no `Retry-After`.
pub(crate) const RETRY_FALLBACK: Duration = Duration::from_secs(5);
/// Floor for a `Retry-After` that asks for no wait at all. `Retry-After: 0`
/// is legal, and retrying at once is the opposite of what it asked.
pub(crate) const RETRY_FLOOR: Duration = Duration::from_secs(1);
/// Ceiling for a hostile or broken `Retry-After`.
pub(crate) const RETRY_CAP: Duration = Duration::from_secs(60);

/// What to wait after a 429. Slack sends whole seconds.
pub(crate) fn retry_delay(retry_after_secs: Option<u64>) -> Duration {
    match retry_after_secs {
        None => RETRY_FALLBACK,
        Some(secs) => Duration::from_secs(secs).clamp(RETRY_FLOOR, RETRY_CAP),
    }
}

/// Slack's whole-second `Retry-After`, when the response carries one.
fn retry_after_of(response: &reqwest::Response) -> Option<u64> {
    response
        .headers()
        .get(reqwest::header::RETRY_AFTER)
        .and_then(|value| value.to_str().ok())
        .and_then(|value| value.parse::<u64>().ok())
}

/// Bounded so a gateway's error page cannot flood the log or the tool output.
const BODY_PREFIX_LEN: usize = 200;

fn body_prefix(body: &str) -> String {
    body.chars().take(BODY_PREFIX_LEN).collect()
}

/// A non-success status other than 429. The body may be an HTML error
/// page, which the envelope decoder would report as a JSON parse failure
/// - the status is what the operator needs, so name it and bound the body.
fn status_failure(method: &str, status: reqwest::StatusCode, body: &str) -> SlackError {
    SlackError::Transport {
        method: method.to_owned(),
        detail: format!("HTTP {status}: {}", body_prefix(body)),
    }
}

/// `application/x-www-form-urlencoded` body for one call.
fn encode_form(params: &[(&str, String)]) -> String {
    let mut serializer = form_urlencoded::Serializer::new(String::new());
    for (key, value) in params {
        serializer.append_pair(key, value);
    }
    serializer.finish()
}

/// `Debug` is hand-written because the token must never be printed.
pub struct SlackClient {
    http: reqwest::Client,
    token: String,
}

impl std::fmt::Debug for SlackClient {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SlackClient").finish_non_exhaustive()
    }
}

#[derive(Debug, Clone)]
pub enum SlackError {
    /// Slack answered `ok: false`. `needed` names the scope when it is a scope failure.
    Api { method: String, error: String, needed: Option<String> },
    /// The transport failed, or the body was not the envelope we expect.
    Transport { method: String, detail: String },
    /// HTTP 429. Slack's Web API surfaces these as a status, not an `ok: false`.
    RateLimited { method: String, retry_after: Duration },
    /// A walk hit its page cap. The pages collected are the oldest the walk
    /// saw, not the whole thread, so it is a refusal rather than a success:
    /// advancing a cursor over a partial read would hide every reply past
    /// the cap for good.
    Truncated { method: String, pages: usize },
}

impl std::fmt::Display for SlackError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Api { method, error, needed } => {
                write!(f, "slack {method} failed: {error}")?;
                if let Some(needed) = needed {
                    write!(f, " (needs {needed})")?;
                }
                Ok(())
            }
            Self::Transport { method, detail } => write!(f, "slack {method} transport: {detail}"),
            Self::RateLimited { method, retry_after } => {
                write!(f, "slack {method} rate limited, retry in {}s", retry_after.as_secs())
            }
            Self::Truncated { method, pages } => {
                write!(
                    f,
                    "slack {method} exceeded {pages} pages; the walk is longer than forge reads"
                )
            }
        }
    }
}

impl std::error::Error for SlackError {}

/// Slack wraps every payload in `ok`, and reports logical failures with HTTP 200.
#[derive(Deserialize)]
struct Envelope<T> {
    ok: bool,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    needed: Option<String>,
    #[serde(flatten)]
    value: T,
}

/// Split out of `call` so the envelope rules are testable without HTTP.
pub(crate) fn decode_envelope<T: DeserializeOwned>(
    method: &str,
    body: &str,
) -> Result<T, SlackError> {
    let envelope: Envelope<T> = serde_json::from_str(body).map_err(|detail| {
        SlackError::Transport { method: method.to_owned(), detail: detail.to_string() }
    })?;
    if !envelope.ok {
        return Err(SlackError::Api {
            method: method.to_owned(),
            error: envelope.error.unwrap_or_else(|| "unknown".to_owned()),
            needed: envelope.needed,
        });
    }
    Ok(envelope.value)
}

/// Messages fetched per `conversations.history` call.
const SWEEP_LIMIT: u32 = 200;

/// A cursor Slack hands back unchanged must not spin the history walk
/// forever, the same guard the conversation walk carries.
const MAX_HISTORY_PAGES: usize = 200;

/// A cursor Slack hands back unchanged must not spin the reply walk
/// forever, the same guard the conversation walk carries.
const MAX_REPLY_PAGES: usize = 200;

/// How often a participating thread is read whole. The per-tick walk is
/// cheap - it re-reads from the newest reply - so this is the only pass that
/// finds a correction to a reply below that one, and reading every long
/// thread whole on every tick would spend the sweep's rate budget.
const FULL_THREAD_READ_INTERVAL: Duration = Duration::from_secs(600);

/// Whole-thread reads one conversation may spend per sweep. Each pages
/// through its thread, so the budget keeps one long thread from using calls
/// the rest of the sweep needs.
const MAX_FULL_THREAD_READS_PER_SWEEP: usize = 2;

/// How long one Web API call gets. The pump waits this long, and every
/// Web API request carries it, so a post that stalls cannot pin its
/// in-flight mark past it. File bodies are not Web API calls and keep
/// their own transfer behaviour.
pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);

/// What one sweep did.
#[derive(Debug, Default)]
pub(crate) struct SweepOutcome {
    /// Blocks handed over: one per conversation per subscription that had
    /// news, and one per mention hit.
    pub delivered: usize,
    /// Set when a call was throttled, so the caller backs off rather than
    /// hammering. A 429 is a report, not an error.
    pub rate_limited: Option<Duration>,
    /// A conversation is gone from Slack's side: the pump folds this into
    /// the glyph write, because the sweep returning `Ok` must not read as
    /// a connected row over a conversation that can never deliver again.
    pub conversation_gone: bool,
}

/// The exclusive read position just below `ts`.
///
/// A thread's cursor is exclusive, so seeding one from a reply would skip
/// that reply - the reply is usually the news that brought the thread in.
/// Seeding it from the parent instead would skip nothing, but a parent can
/// be weeks old, and the idle window reads the cursor: the thread would be
/// dropped before its first walk. One microsecond below the newest reply is
/// both recent and below everything still worth delivering.
fn just_below(ts: &str) -> String {
    let (seconds, micros) = ts.split_once('.').unwrap_or((ts, "0"));
    let seconds: u64 = seconds.parse().unwrap_or(0);
    let micros: u64 = micros.parse().unwrap_or(0);
    // Borrowing from the seconds on a zero fraction, because the cursor is
    // compared as a string: `150.000000` sorts AFTER `150.0`, the same
    // instant written shorter.
    if micros == 0 {
        format!("{}.{:06}", seconds.saturating_sub(1), 999_999)
    } else {
        format!("{seconds}.{:06}", micros - 1)
    }
}

/// Whether `ts` is strictly after `watermark`. Timestamps are compared as
/// the strings Slack sent: they carry a microsecond fraction, and parsing
/// one to a number loses it and silently moves the cursor.
fn is_newer(ts: &str, watermark: Option<&str>) -> bool {
    match watermark {
        None => true,
        Some(watermark) => ts > watermark,
    }
}

/// Whether a message carries news the cursor has not passed: the message
/// is newer than the cursor, or it was edited after the cursor. An edit
/// keeps the message's own `ts`, so the ts test alone drops every
/// correction.
fn is_news(message: &SlackHistoryMessage, cursor: Option<&str>) -> bool {
    is_newer(&message.ts, cursor)
        || message.edited.as_deref().is_some_and(|edited| is_newer(edited, cursor))
}

/// The newest cursor value a message owns: its `ts`, or the later ts of
/// its newest edit. A cursor advanced over a handed edit has to clear the
/// edit too, or the next sweep re-offers the message forever and, once
/// the delivery memory lapses, redispatches it.
fn newest_stamp(message: &SlackHistoryMessage) -> &str {
    match message.edited.as_deref() {
        Some(edited) if is_newer(edited, Some(message.ts.as_str())) => edited,
        _ => message.ts.as_str(),
    }
}

#[cfg(test)]
mod is_newer_tests {
    use super::is_newer;

    /// Slack ts strings share the fixed-width seconds prefix, so string
    /// order matches time order only while that holds. The disagreeing
    /// pair pins the comparison as string order: numerically 1700000000.1
    /// equals 1700000000.10, and a numeric compare would call the newer
    /// cursor "not newer" and silently skip real messages.
    #[test]
    fn string_order_survives_trailing_zeros_a_numeric_compare_does_not() {
        assert!(
            is_newer("1700000000.000100", Some("1700000000.0001")),
            "string order, not numeric - these are equal as f64",
        );
        assert!(!is_newer("1700000000.0001", Some("1700000000.000100")));
    }
}

/// Every history message after each page boundary, following the cursor.
/// One page is `SWEEP_LIMIT` messages, and a sweep that read only the first
/// would advance the watermark past everything it never fetched, losing
/// those messages silently.
async fn fetch_history(
    api: &dyn SlackApi,
    workspace: &str,
    channel: &str,
    oldest: Option<&str>,
) -> Result<Vec<SlackHistoryMessage>, SlackError> {
    let mut out = Vec::new();
    let mut cursor: Option<String> = None;
    let mut pages = 0;
    loop {
        let page = api.history(channel, oldest, None, SWEEP_LIMIT, cursor.as_deref()).await?;
        out.extend(page.messages);
        pages += 1;
        match page.next_cursor {
            Some(next) if pages < MAX_HISTORY_PAGES => cursor = Some(next),
            Some(_) => {
                tracing::warn!(
                    target: "forge_connectors::slack",
                    event_name = "slack_history_page_cap",
                    workspace,
                    channel,
                    pages,
                    "conversations.history exceeded the page cap; the channel is longer than \
                     forge reads, so the walk is not treated as complete",
                );
                return Err(SlackError::Truncated {
                    method: "conversations.history".to_owned(),
                    pages,
                });
            }
            None => return Ok(out),
        }
    }
}

/// The conversation's newest page, and only that page. Not [`fetch_history`]:
/// walking back from a cursor would page through the channel's whole past,
/// and this is a window over what is recent rather than a read position.
///
/// A thread's parent stays inside it, which is the only way the sweep can see
/// that a thread has moved - `conversations.history` never returns a reply,
/// and a parent the cursor has moved past is otherwise invisible for good.
async fn fetch_recent(
    api: &dyn SlackApi,
    channel: &str,
) -> Result<Vec<SlackHistoryMessage>, SlackError> {
    Ok(api.history(channel, None, None, SWEEP_LIMIT, None).await?.messages)
}

/// Every reply in a thread, following the cursor. Dedupe is the caller's:
/// Slack repeats the parent on every page, so the caller takes the newest by
/// comparing `ts` rather than by taking the last one it read.
async fn fetch_replies(
    api: &dyn SlackApi,
    workspace: &str,
    channel: &str,
    ts: &str,
    oldest: Option<&str>,
) -> Result<Vec<SlackHistoryMessage>, SlackError> {
    let mut out = Vec::new();
    let mut cursor: Option<String> = None;
    let mut pages = 0;
    loop {
        let page = api.replies(channel, ts, oldest, SWEEP_LIMIT, cursor.as_deref()).await?;
        out.extend(page.messages);
        pages += 1;
        match page.next_cursor {
            Some(next) if pages < MAX_REPLY_PAGES => cursor = Some(next),
            Some(_) => {
                tracing::warn!(
                    target: "forge_connectors::slack",
                    event_name = "slack_thread_page_cap",
                    workspace,
                    channel,
                    parent = %ts,
                    pages,
                    "conversations.replies exceeded the page cap; the thread is longer than \
                     forge reads, so the walk is not treated as complete",
                );
                return Err(SlackError::Truncated {
                    method: "conversations.replies".to_owned(),
                    pages,
                });
            }
            None => return Ok(out),
        }
    }
}

/// Every reply in a thread, the parent first, for a caller reading the thread
/// rather than advancing a cursor. Slack repeats the parent at the top of
/// every page, so the result is deduped by `ts`; the first occurrence wins,
/// which keeps the parent where the contract puts it. `limit` bounds the rows
/// returned, and the walk stops as soon as it has them.
pub async fn read_thread(
    api: &dyn SlackApi,
    channel: &str,
    ts: &str,
    limit: u32,
) -> Result<Vec<SlackHistoryMessage>, SlackError> {
    if limit == 0 {
        return Ok(Vec::new());
    }
    let mut out: Vec<SlackHistoryMessage> = Vec::new();
    let mut seen: HashSet<String> = HashSet::new();
    let mut cursor: Option<String> = None;
    let mut pages = 0;
    loop {
        let page = api.replies(channel, ts, None, limit, cursor.as_deref()).await?;
        for message in page.messages {
            if seen.insert(message.ts.clone()) {
                out.push(message);
                if out.len() >= limit as usize {
                    return Ok(out);
                }
            }
        }
        pages += 1;
        match page.next_cursor {
            Some(next) if pages < MAX_REPLY_PAGES => cursor = Some(next),
            Some(_) => {
                tracing::warn!(
                    target: "forge_connectors::slack",
                    event_name = "slack_thread_read_page_cap",
                    channel,
                    parent = %ts,
                    pages,
                    "conversations.replies exceeded the page cap; the read is not complete",
                );
                return Err(SlackError::Truncated {
                    method: "conversations.replies".to_owned(),
                    pages,
                });
            }
            None => return Ok(out),
        }
    }
}

/// The parent message of the thread `ts` starts, which is the message a
/// draft's card names. An error is the caller's to draw around: the card
/// names the thread "a thread" rather than inventing a name.
pub async fn thread_parent(
    api: &dyn SlackApi,
    channel: &str,
    ts: &str,
) -> Result<Option<SlackHistoryMessage>, SlackError> {
    let page = api.replies(channel, ts, None, 1, None).await?;
    Ok(page.messages.into_iter().next())
}

/// Which conversations one pass reads. The DM class covers every DM rather
/// than a list, so it costs one history read per DM however many
/// subscriptions exist - which is why it is swept on its own clock, and why
/// a pass reads only what it is for.
#[derive(Clone, Copy)]
pub(crate) enum SweepScope {
    /// The conversations a subscription names, and the mention-pulled ones.
    Conversations,
    /// The conversations only the DM class covers. A DM a subscription also
    /// names is read on the conversation clock rather than twice.
    DirectMessages,
}

/// Whether this pass is for this conversation. `targets` has already said the
/// conversation is watched by someone; this narrows that to the clock the
/// sweep is running on.
fn in_scope(
    subscriptions: &[SlackSubscription],
    conversation: &SlackConversation,
    scope: SweepScope,
) -> bool {
    let named = subscriptions.iter().any(|subscription| {
        matches!(
            &subscription.target,
            SlackSubscriptionTarget::Conversation { id, .. } if id == &conversation.id
        )
    });
    match scope {
        SweepScope::Conversations => named,
        SweepScope::DirectMessages => {
            (conversation.is_im || conversation.is_mpim)
                && !named
                && subscriptions
                    .iter()
                    .any(|s| matches!(s.target, SlackSubscriptionTarget::DirectMessages))
        }
    }
}

/// Both passes in one call, the way the pump runs them within a DM interval.
/// The tests drive this, so a test asserts what a sweep does without naming a
/// clock.
#[cfg(test)]
pub(crate) async fn sweep(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
) -> Result<SweepOutcome, SlackError> {
    let conversations = sweep_scope(host, api, workspace, SweepScope::Conversations).await?;
    let dms = sweep_scope(host, api, workspace, SweepScope::DirectMessages).await?;
    Ok(SweepOutcome {
        delivered: conversations.delivered + dms.delivered,
        rate_limited: conversations.rate_limited.or(dms.rate_limited),
        conversation_gone: conversations.conversation_gone || dms.conversation_gone,
    })
}

/// One pass over the conversations in `scope`: fetch what is newer than each
/// conversation's watermark, follow the threads of the parents that report
/// replies, and hand every survivor to the host.
pub(crate) async fn sweep_scope(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
    scope: SweepScope,
) -> Result<SweepOutcome, SlackError> {
    let subscriptions = host.subscriptions(workspace);
    if subscriptions.is_empty() {
        return Ok(SweepOutcome { delivered: 0, ..Default::default() });
    }
    let user_id = host.user_id(workspace).unwrap_or_default();
    if user_id.is_empty() {
        // A mentions-only subscription matches on the id, and the thread
        // walk reads participation from it; sweeping without either would
        // miss every own-engagement signal. Fail quiet-but-visible rather
        // than sweep half-blind; the host retries the id in the
        // background.
        tracing::warn!(
            target: "forge_connectors::slack",
            workspace,
            "slack user id unresolved; the sweep is skipped this tick",
        );
        return Ok(SweepOutcome { delivered: 0, ..Default::default() });
    }

    let mut conversations = match api.list_conversations().await {
        Ok(conversations) => conversations,
        Err(SlackError::RateLimited { retry_after, .. }) => {
            return Ok(SweepOutcome {
                delivered: 0,
                rate_limited: Some(retry_after),
                ..Default::default()
            });
        }
        Err(error) => return Err(error),
    };
    // A subscription can name a conversation the token's user never joined:
    // a mention pulled us into a public channel, and users.conversations is
    // membership-scoped. Those arrive from the subscription set itself, or
    // the headline mention case dies after its first delivery.
    for subscription in &subscriptions {
        if let SlackSubscriptionTarget::Conversation { id, .. } = &subscription.target
            && !conversations.iter().any(|conversation| &conversation.id == id)
        {
            conversations.push(SlackConversation {
                id: id.clone(),
                name: None,
                is_channel: false,
                is_private: false,
                is_im: false,
                is_mpim: false,
                is_archived: false,
                user: None,
                purpose: None,
                topic: None,
            });
        }
    }
    // The synthetic entries above carry no name, so they are skipped
    // without a case of their own.
    for subscription in &subscriptions {
        if let SlackSubscriptionTarget::Conversation { id, name: None, .. } = &subscription.target
            && let Some(name) = conversations
                .iter()
                .find(|conversation| &conversation.id == id)
                .and_then(|conversation| conversation.name.as_deref())
            && !name.is_empty()
            && name != id
        {
            host.name_conversation(workspace, id, name);
        }
    }

    let mut delivered = 0;
    // A throttled thread arms the pump's backoff without ending the sweep;
    // every other step's early return carries its own.
    let mut rate_limited: Option<Duration> = None;
    let mut conversation_gone = false;
    let mut own = OwnIdentity { id: &user_id, name: None, asked: false };
    for conversation in &conversations {
        if !targets(&subscriptions, conversation) || !in_scope(&subscriptions, conversation, scope)
        {
            continue;
        }
        // A message can reach history before the post call returns and its
        // ts is ledgered. Skipping the conversation for this tick, and not
        // moving its cursor, is what keeps that window from delivering a
        // self-post. Marks are keyed by the conversation a post resolved
        // to, so the id answers first; the name and the DM partner cover a
        // post whose listing failed and fell back to the request address.
        let in_flight = host.post_in_flight(workspace, &conversation.id).or_else(|| {
            conversation.name.as_deref().and_then(|name| host.post_in_flight(workspace, name))
        });
        let in_flight = in_flight.or_else(|| {
            conversation.user.as_deref().and_then(|user| host.post_in_flight(workspace, user))
        });
        if let Some(age) = in_flight {
            tracing::debug!(
                target: "forge_connectors::slack",
                event_name = "slack_post_in_flight",
                workspace,
                conversation = %conversation.id,
                age_ms = age.as_millis(),
                "a post is in flight; skipping this conversation this tick",
            );
            continue;
        }
        let watermark = match host.watermark(workspace, &conversation.id) {
            Ok(watermark) => watermark,
            Err(error) => {
                // "Could not read the cursor" is not "never swept": sweeping
                // from the beginning would deliver the channel's whole
                // history as new. Skip it for this tick.
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace,
                    conversation = %conversation.id,
                    %error,
                    "reading the slack watermark failed; skipping the conversation this tick",
                );
                continue;
            }
        };

        let window = match fetch_recent(api, &conversation.id).await {
            Ok(window) => window,
            Err(SlackError::RateLimited { retry_after, .. }) => {
                return Ok(SweepOutcome {
                    delivered,
                    rate_limited: Some(retry_after),
                    ..Default::default()
                });
            }
            // One conversation's failure is not the workspace's: the
            // sweep continues with the conversations after it. The cursor
            // stays where it was, so nothing is skipped.
            Err(error) => {
                let gone = matches!(&error, SlackError::Api { error: api_error, .. }
                    if api_error == "channel_not_found" || api_error == "invalid_channel_id");
                // A DM id a user token can never read - Slackbot's
                // conversation answers channel_not_found forever - is a
                // Slack quirk, not a dead channel, so it earns no glyph.
                if gone && (conversation.is_im || conversation.is_mpim) {
                    tracing::info!(
                        target: "forge_connectors::slack",
                        workspace,
                        conversation = %conversation.id,
                        %error,
                        "slack withholds this DM's history from user tokens; skipping it every tick",
                    );
                    continue;
                }
                // A conversation deleted on Slack's side is permanent. The
                // flag rides the outcome: the pump owns the glyph, and a
                // write here would be clobbered by its Ok arm.
                if gone {
                    conversation_gone = true;
                }
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace,
                    conversation = %conversation.id,
                    %error,
                    "reading a conversation's history failed; skipping it this tick",
                );
                continue;
            }
        };

        // The DM class covers conversations that cannot be pre-seeded per
        // id, so first sight baselines instead of replaying: the newest
        // message the window holds becomes the cursor and the back catalogue
        // is not new. Read before the walk below, which would otherwise page
        // a DM's whole history to find the same ts. Logged, because the same
        // shape hides a named conversation whose subscribe-time cursor write
        // failed - a swallowed backlog. That is still the right direction:
        // refusing to sweep would deliver nothing forever, and replaying the
        // backlog would spam every session watching it.
        if watermark.is_none() {
            if let Some(newest) = window.iter().map(|message| message.ts.as_str()).max() {
                tracing::info!(
                    target: "forge_connectors::slack",
                    workspace,
                    conversation = %conversation.id,
                    cursor = %newest,
                    "no cursor for this conversation; baselining at the newest message seen",
                );
                host.set_watermark(workspace, &conversation.id, newest);
            }
            continue;
        }

        // The window reaches back past the cursor on the common tick, so it
        // IS everything new. When it does not - more arrived between two
        // sweeps than one page holds - the rest is behind it, and only the
        // cursor walk reaches that. That walk starts at the cursor and ends
        // on the very page the window just returned, so the overlap is
        // deliberate: the window is a view, not a read position.
        let reaches_back =
            window.last().is_some_and(|oldest| !is_newer(&oldest.ts, watermark.as_deref()));
        let history = if reaches_back {
            window.clone()
        } else {
            match fetch_history(api, workspace, &conversation.id, watermark.as_deref()).await {
                Ok(history) => history,
                Err(SlackError::RateLimited { retry_after, .. }) => {
                    return Ok(SweepOutcome {
                        delivered,
                        rate_limited: Some(retry_after),
                        ..Default::default()
                    });
                }
                Err(error) => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        workspace,
                        conversation = %conversation.id,
                        %error,
                        "reading a conversation's history failed; skipping it this tick",
                    );
                    continue;
                }
            }
        };
        // What the window says about each parent's thread. A parent missing
        // from it has aged out, and only the thread's own walk reaches it.
        let latest_replies: HashMap<&str, &str> = window
            .iter()
            .filter_map(|message| Some((message.ts.as_str(), message.latest_reply.as_deref()?)))
            .collect();

        // A thread is tracked as soon as the window shows it has replies,
        // whoever wrote the parent. Anchoring on delivery alone would miss
        // every thread that had none when its parent went past: the parent is
        // read once, and the reply that arrives minutes later never brings it
        // back. Whether the user is IN the thread is a separate question,
        // asked of the replies the walk fetches.
        for message in window.iter().filter(|message| is_thread_parent(message)) {
            let anchor = match message.latest_reply.as_deref() {
                Some(latest) => just_below(latest),
                None => message.ts.clone(),
            };
            // A new thread's seed never falls below the conversation cursor:
            // its newest reply can predate a new subscription. The walk filters
            // by ts alone, so a correction to a reply already behind that
            // cursor is not re-offered on the first follow.
            let since = match watermark.as_deref() {
                Some(cursor) if is_newer(cursor, Some(anchor.as_str())) => cursor.to_owned(),
                _ => anchor,
            };
            for subscription in
                subscriptions.iter().filter(|subscription| owns_threads(subscription, conversation))
            {
                host.follow_thread(
                    workspace,
                    &conversation.id,
                    &message.ts,
                    SlackThreadOwner {
                        project: subscription.project.clone(),
                        team_role: subscription.team_role.clone(),
                    },
                    &since,
                );
            }
        }

        let mut seen: HashSet<String> = HashSet::new();
        let mut batch: Vec<SlackHistoryMessage> = history
            .into_iter()
            .filter(|message| {
                is_news(message, watermark.as_deref()) && seen.insert(message.ts.clone())
            })
            .collect();

        // Thread replies never appear in `conversations.history`, so a
        // parent that reports replies is the only way to reach them.
        let parents: Vec<String> = batch
            .iter()
            .filter(|message| is_thread_parent(message))
            .map(|m| m.ts.clone())
            .collect();
        for parent in parents {
            let replies = match fetch_replies(api, workspace, &conversation.id, &parent, None).await
            {
                Ok(replies) => replies,
                Err(SlackError::RateLimited { retry_after, .. }) => {
                    return Ok(SweepOutcome {
                        delivered,
                        rate_limited: Some(retry_after),
                        ..Default::default()
                    });
                }
                // One conversation's failure is not the workspace's: the
                // sweep continues with the conversations after it.
                Err(error) => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        workspace,
                        conversation = %conversation.id,
                        parent = %parent,
                        %error,
                        "reading a thread's replies failed; skipping them this tick",
                    );
                    continue;
                }
            };
            // The same rule the walk applies: a thread the user is not in is
            // not his to read, however recently its parent landed.
            if !participating(&replies, &user_id) {
                continue;
            }
            for reply in replies {
                if is_news(&reply, watermark.as_deref()) && seen.insert(reply.ts.clone()) {
                    batch.push(reply);
                }
            }
        }

        // What each author in this conversation is called, the walk's
        // replies included; the map is per conversation.
        let mut names: HashMap<String, Option<String>> = HashMap::new();
        for message in &batch {
            match author_of(host, api, workspace, message, &mut names, &mut own).await {
                Ok(_) => {}
                Err(SlackError::RateLimited { retry_after, .. }) => {
                    return Ok(SweepOutcome {
                        delivered,
                        rate_limited: Some(retry_after),
                        ..Default::default()
                    });
                }
                Err(error) => return Err(error),
            }
        }

        let label =
            conversation.name.clone().or_else(|| conversation.user.clone()).unwrap_or_default();
        // The ledger is per conversation, so one read per message serves
        // every subscription watching it.
        let own_posts: HashSet<&str> = batch
            .iter()
            .map(|message| message.ts.as_str())
            .filter(|ts| host.own_post(workspace, &conversation.id, ts))
            .collect();
        let own_post = |ts: &str| own_posts.contains(ts);
        // One block per subscription that wants this conversation's news:
        // a lead and a worker watching one channel are two destinations,
        // and one shared block would starve whichever sorted second. No
        // subscription wants anything here means nothing is delivered at
        // all - never an empty block.
        let mut all_handed = true;
        // The thread watermark has to clear edits this batch hands over, or
        // the thread walk's next whole read offers the same correction again.
        let mut handed_edits: HashMap<String, String> = HashMap::new();
        for subscription in &subscriptions {
            let wanted: Vec<&SlackHistoryMessage> = batch
                .iter()
                .filter(|message| {
                    matches(
                        subscription,
                        conversation,
                        &message.text,
                        &message.ts,
                        &user_id,
                        &own_post,
                    )
                })
                .collect();
            if wanted.is_empty() {
                continue;
            }
            let messages: Vec<SlackMessage> = wanted
                .iter()
                .map(|message| SlackMessage {
                    workspace: workspace.to_owned(),
                    conversation: conversation.id.clone(),
                    conversation_label: label.clone(),
                    ts: message.ts.clone(),
                    thread_ts: message.thread_ts.clone(),
                    user: message.user.clone(),
                    author: message
                        .user
                        .as_deref()
                        .and_then(|user| names.get(user).cloned().flatten()),
                    text: message.text.clone(),
                    parent_user_id: message.parent_user_id.clone(),
                    latest_reply: message.latest_reply.clone(),
                    edited: message.edited.clone(),
                    files: message.files.clone(),
                })
                .collect();
            if !host.deliver(subscription, &messages) {
                all_handed = false;
                continue;
            }
            delivered += 1;
            for message in wanted {
                if let Some(parent_ts) = followed_parent_of(message)
                    && message.ts != parent_ts
                    && let Some(edited) = message.edited.as_deref()
                {
                    let stamp = handed_edits.entry(parent_ts.clone()).or_default();
                    if edited > stamp.as_str() {
                        edited.clone_into(stamp);
                    }
                }
                if let Some(parent_ts) = followed_parent_of(message) {
                    host.follow_thread(
                        workspace,
                        &conversation.id,
                        &parent_ts,
                        SlackThreadOwner {
                            project: subscription.project.clone(),
                            team_role: subscription.team_role.clone(),
                        },
                        &message.ts,
                    );
                }
            }
        }

        // Advanced last, and only over a batch that was handed off whole:
        // a cursor advanced past an undelivered message loses it, and the
        // wire's newest-first pages mean any advance jumps over everything
        // at and below the failure. Dedupe absorbs the re-delivery.
        if all_handed {
            for (parent_ts, edited) in handed_edits {
                let current = host.thread_edit_watermark(workspace, &conversation.id, &parent_ts);
                if current.as_deref().is_none_or(|mark| is_newer(&edited, Some(mark))) {
                    host.set_thread_edit_watermark(
                        workspace,
                        &conversation.id,
                        &parent_ts,
                        &edited,
                    );
                }
            }
            if let Some(newest) = batch.iter().map(newest_stamp).max() {
                host.set_watermark(workspace, &conversation.id, newest);
            }
        }

        // Threads followed from earlier deliveries. Replies never appear
        // in history and the parent ages past the conversation watermark,
        // so each tracked thread is walked on its own cursor.
        let mut full_reads = 0usize;
        for thread in host.followed_threads(workspace, &conversation.id) {
            let cursor = match host.thread_watermark(workspace, &conversation.id, &thread.parent_ts)
            {
                Ok(cursor) => cursor,
                Err(error) => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        workspace,
                        conversation = %conversation.id,
                        parent = %thread.parent_ts,
                        %error,
                        "reading a thread cursor failed; skipping the thread this tick",
                    );
                    continue;
                }
            };
            // A parent the window still shows says whether the thread moved
            // at all, and one that did not costs no call. A parent the window
            // has lost has to be fetched to find out - which is the one call
            // per sweep the aged-out case has always cost.
            let first_walk = host.thread_first_walk(workspace, &conversation.id, &thread.parent_ts);
            let now = std::time::Instant::now();
            // A first walk refused by the page cap keeps its mark, and the
            // attempt stamp is what stops it walking the whole thread again
            // next tick: without this gate a 200-page thread is re-walked
            // every tick and never leaves.
            if first_walk
                && host
                    .thread_full_read_at(workspace, &conversation.id, &thread.parent_ts)
                    .is_some_and(|at| at + FULL_THREAD_READ_INTERVAL > now)
            {
                continue;
            }
            if !thread.participating
                && !first_walk
                && let Some(latest) = latest_replies.get(thread.parent_ts.as_str())
                && cursor.as_deref().is_some_and(|cursor| *latest <= cursor)
            {
                continue;
            }
            // **Cheap every tick, whole on a slower clock.** A correction
            // keeps its reply's `ts`, so only a whole read finds one below
            // the newest reply; reading every long thread whole every tick
            // would spend the sweep's rate budget, so the whole pass runs
            // once per `FULL_THREAD_READ_INTERVAL` and at most
            // `MAX_FULL_THREAD_READS_PER_SWEEP` times a sweep. Whether the
            // user is in a thread is read off the replies, so a first walk
            // and a thread he is not in still read whole.
            let full_due = thread.participating
                && !first_walk
                && full_reads < MAX_FULL_THREAD_READS_PER_SWEEP
                && host
                    .thread_full_read_at(workspace, &conversation.id, &thread.parent_ts)
                    .is_none_or(|at| at + FULL_THREAD_READ_INTERVAL <= now);
            if full_due {
                full_reads += 1;
            }
            if full_due || first_walk {
                // A first walk is a whole read too, so the interval starts
                // there. The attempt is stamped before the call: an error or
                // a page cap must back off too, or a thread past the cap
                // walks its 200 pages on every tick. A failed delivery still
                // holds the cursor, and the cheap tick re-offers what it did
                // not hand over.
                host.mark_thread_full_read(workspace, &conversation.id, &thread.parent_ts, now);
            }
            let read_from: Option<String> = if full_due || first_walk || !thread.participating {
                None
            } else {
                cursor.as_deref().map(just_below)
            };
            let replies = match fetch_replies(
                api,
                workspace,
                &conversation.id,
                &thread.parent_ts,
                read_from.as_deref(),
            )
            .await
            {
                Ok(replies) => replies,
                // One thread must not spend the whole sweep: a throttle arms
                // the pump's backoff and the walk moves on. The largest wait
                // wins, so the pump backs off for the longest ask.
                Err(SlackError::RateLimited { retry_after, .. }) => {
                    rate_limited =
                        Some(rate_limited.map_or(retry_after, |held| held.max(retry_after)));
                    continue;
                }
                // One thread's failure is not the workspace's: the walk
                // continues with the threads after it, and the cursor stays
                // where it was. A thread past the page cap refuses too, so a
                // partial read cannot advance the cursor.
                Err(error) => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        event_name = "slack_thread_walk_failed",
                        workspace,
                        conversation = %conversation.id,
                        parent = %thread.parent_ts,
                        %error,
                        "walking a followed thread failed; skipping it this tick",
                    );
                    continue;
                }
            };
            if first_walk {
                host.clear_thread_first_walk(workspace, &conversation.id, &thread.parent_ts);
            }
            let participated = thread.participating || participating(&replies, &user_id);
            if participated && !thread.participating {
                host.mark_thread_participating(workspace, &conversation.id, &thread.parent_ts);
            }
            // **An edit is judged against the edit watermark, never the reply
            // cursor.** The cheap tick moves the cursor to the newest reply,
            // so an edit below it would sit behind the cursor forever. A
            // first walk filters by `ts` alone: its seed is `latest_reply`,
            // which an edit does not move, so an edit-aware filter would hand
            // over corrections the previous row already had.
            let edit_mark =
                host.thread_edit_watermark(workspace, &conversation.id, &thread.parent_ts);
            let news = |reply: &SlackHistoryMessage| {
                if first_walk {
                    is_newer(&reply.ts, cursor.as_deref())
                } else if full_due {
                    is_newer(&reply.ts, cursor.as_deref())
                        || reply.edited.as_deref().is_some_and(|edited| {
                            edit_mark.as_deref().is_none_or(|mark| is_newer(edited, Some(mark)))
                        })
                } else {
                    is_news(reply, cursor.as_deref())
                }
            };
            // Everything this walk saw, whether or not it went anywhere: his
            // own reply is never delivered, and a thread he is not in is not
            // read again until it moves. Advancing over what was read is what
            // lets the window's `latest_reply` say a thread has not moved and
            // cost no call at all - held back only by a failed hand-off.
            let newest_seen: Option<String> = replies
                .iter()
                .filter(|reply| reply.ts != thread.parent_ts && news(reply))
                .map(|reply| newest_stamp(reply).to_owned())
                .max();
            // **The cursor never moves back.** A whole read can see only
            // replies at and below a cursor the cheap tick already advanced,
            // and an edit handed over there carries an older stamp.
            let next_cursor = match (cursor.clone(), newest_seen) {
                (Some(current), Some(newest)) if newest > current => Some(newest),
                (None, Some(newest)) => Some(newest),
                _ => None,
            };
            if !participated {
                if let Some(newest) = next_cursor {
                    host.set_thread_watermark(
                        workspace,
                        &conversation.id,
                        &thread.parent_ts,
                        &newest,
                    );
                }
                continue;
            }
            // What this thread has to say this tick, in the order the wire
            // sent it, so an owner is handed one block rather than one per
            // reply - the shape the conversation batch delivers.
            let mut deliverable: Vec<(&SlackHistoryMessage, Option<String>)> = Vec::new();
            let mut thread_throttled = false;
            for reply in &replies {
                // Slack repeats the parent on every page of the walk.
                if reply.ts == thread.parent_ts || !news(reply) || !seen.insert(reply.ts.clone()) {
                    continue;
                }
                // Replies never appear in history, so this walk is the one
                // path that sees the agent's own answers to the threads it
                // anchors - and they must not come back, or an agent
                // answering the echo answers itself. Identity, not author:
                // Ved's own replies in the thread are his to see.
                if host.own_post(workspace, &conversation.id, &reply.ts) {
                    continue;
                }
                // Resolved the same way the conversation batch's are: a
                // reply usually comes from someone who posted nothing in
                // the channel this tick, so the map may not hold him yet.
                match author_of(host, api, workspace, reply, &mut names, &mut own).await {
                    Ok(author) => deliverable.push((reply, author)),
                    Err(SlackError::RateLimited { retry_after, .. }) => {
                        rate_limited =
                            Some(rate_limited.map_or(retry_after, |held| held.max(retry_after)));
                        thread_throttled = true;
                        break;
                    }
                    Err(error) => return Err(error),
                }
            }
            if thread_throttled {
                continue;
            }
            let mut walk_failed = false;
            for owner in &thread.owners {
                let messages: Vec<SlackMessage> = deliverable
                    .iter()
                    .map(|(reply, author)| SlackMessage {
                        workspace: workspace.to_owned(),
                        conversation: conversation.id.clone(),
                        conversation_label: label.clone(),
                        ts: reply.ts.clone(),
                        thread_ts: Some(thread.parent_ts.clone()),
                        user: reply.user.clone(),
                        author: author.clone(),
                        text: reply.text.clone(),
                        parent_user_id: reply.parent_user_id.clone(),
                        latest_reply: reply.latest_reply.clone(),
                        edited: reply.edited.clone(),
                        files: reply.files.clone(),
                    })
                    .collect();
                if messages.is_empty() {
                    break;
                }
                // Delivery routes by the owner fields alone, so any
                // subscription of the same owner carries the block.
                let Some(subscription) = subscriptions.iter().find(|subscription| {
                    subscription.project == owner.project
                        && subscription.team_role == owner.team_role
                }) else {
                    walk_failed = true;
                    continue;
                };
                if host.deliver(subscription, &messages) {
                    delivered += 1;
                } else {
                    // Whatever came back may hold replies newer than the
                    // block, so any advance would jump ABOVE the replies that
                    // did not reach every owner and never fetch them again.
                    // The cursor holds at its previous value; dedupe absorbs
                    // the re-delivery.
                    walk_failed = true;
                }
            }
            if !walk_failed {
                // **The edit watermark moves over what was handed over, and
                // only after it was.** Every branch delivers edits - the
                // first walk, the cheap tick and the whole read - so every
                // branch has to clear them, or the next whole read offers the
                // same correction again once the delivery memory has lapsed.
                // A failed hand-off leaves it alone, so the correction is
                // still news when the cursor cannot reach it.
                let delivered_edit =
                    deliverable.iter().filter_map(|(reply, _)| reply.edited.as_deref()).max();
                if let Some(edited) = delivered_edit
                    && edit_mark.as_deref().is_none_or(|mark| is_newer(edited, Some(mark)))
                {
                    host.set_thread_edit_watermark(
                        workspace,
                        &conversation.id,
                        &thread.parent_ts,
                        edited,
                    );
                }
                if let Some(newest) = next_cursor {
                    host.set_thread_watermark(
                        workspace,
                        &conversation.id,
                        &thread.parent_ts,
                        &newest,
                    );
                }
            }
        }
    }

    Ok(SweepOutcome { delivered, rate_limited, conversation_gone })
}

/// The watermark key for a workspace's whole mention stream. One cursor,
/// not one per conversation: both sides share this constant so a typo
/// cannot silently reset it and re-deliver everything.
pub const MENTION_CURSOR: &str = "__mentions__";

/// Mentions fetched per search. The workspace's newest, since the query is
/// timestamp-sorted.
const MENTION_SEARCH_COUNT: u32 = 20;

/// A cursor Slack hands back unchanged must not spin the mention walk
/// forever, the same guard the other walks carry.
const MAX_SEARCH_PAGES: usize = 200;

/// Sweep the workspace's mention stream. Returns at once when no
/// `Mentions` target exists, so a workspace with only conversation
/// subscriptions never spends a search call on every tick.
pub(crate) async fn sweep_mentions(
    host: &dyn SlackHost,
    api: &dyn SlackApi,
    workspace: &str,
) -> Result<SweepOutcome, SlackError> {
    let subscriptions = host.subscriptions(workspace);
    // Every Mentions target gets the hit: a lead and a worker each asking
    // to be told are two owners, and find-first would starve whichever
    // sorted second. Same-owner re-delivery is absorbed by the
    // destination dedupe.
    let mention_subscriptions: Vec<&SlackSubscription> = subscriptions
        .iter()
        .filter(|s| matches!(s.target, SlackSubscriptionTarget::Mentions))
        .collect();
    if mention_subscriptions.is_empty() {
        return Ok(SweepOutcome { delivered: 0, ..Default::default() });
    }
    // The query is the authenticated user's own mention token, so without
    // their id there is nothing to search for. Fail quiet-but-visible
    // rather than sweeping half-blind.
    let Some(user_id) = host.user_id(workspace).filter(|id| !id.is_empty()) else {
        tracing::warn!(
            target: "forge_connectors::slack",
            workspace,
            "slack user id unresolved; the mention sweep is skipped this tick",
        );
        return Ok(SweepOutcome { delivered: 0, ..Default::default() });
    };

    let mut own = OwnIdentity { id: &user_id, name: None, asked: false };

    let watermark = match host.watermark(workspace, MENTION_CURSOR) {
        Ok(watermark) => watermark,
        Err(error) => {
            tracing::warn!(
                target: "forge_connectors::slack",
                workspace,
                %error,
                "reading the mention cursor failed; skipping the mention sweep this tick",
            );
            return Ok(SweepOutcome { delivered: 0, ..Default::default() });
        }
    };
    let query = format!("<@{user_id}>");

    // Follow the search cursor while the page comes back full: a page
    // holds the NEWEST hits, so advancing the cursor past a full page
    // would silently discard everything older on it. Catch-up costs extra
    // calls only while a backlog exists, which is exactly when it matters.
    let mut delivered = 0;
    let mut newest: Option<String> = None;
    let mut cursor: Option<String> = None;
    let mut pages = 0;
    loop {
        let page = match api.search_messages(&query, MENTION_SEARCH_COUNT, cursor.as_deref()).await
        {
            Ok(page) => page,
            Err(SlackError::RateLimited { retry_after, .. }) => {
                // The cursor stays where it was: advancing it here would
                // drop the older undelivered pages behind it. Re-delivery
                // is the cheap failure.
                return Ok(SweepOutcome {
                    delivered,
                    rate_limited: Some(retry_after),
                    ..Default::default()
                });
            }
            Err(error) => return Err(error),
        };
        pages += 1;

        for hit in &page.matches {
            // The cursor test first: a stale hit costs no ledger read.
            if !is_newer(&hit.ts, watermark.as_deref()) {
                continue;
            }
            // A post in flight in this conversation can already be in the
            // index with its ts not yet ledgered: the same window the
            // conversation sweep skips. Hits arrive newest-first, so a
            // newer hit already delivered this sweep would move the cursor
            // above this one and lose it for good - hold the cursor where
            // it was, the way a failed delivery does, and let the next
            // tick re-offer the newer hits (the destination's own memory
            // absorbs them). The check is by id and by the name the search
            // hit carries, for a stamp keyed under an unresolved address.
            let in_flight = host.post_in_flight(workspace, &hit.conversation_id).or_else(|| {
                hit.conversation_name
                    .as_deref()
                    .and_then(|name| host.post_in_flight(workspace, name))
            });
            if let Some(age) = in_flight {
                tracing::debug!(
                    target: "forge_connectors::slack",
                    event_name = "slack_post_in_flight",
                    workspace,
                    conversation = %hit.conversation_id,
                    age_ms = age.as_millis(),
                    "a post is in flight in this conversation; holding the mention cursor",
                );
                return Ok(SweepOutcome { delivered, ..Default::default() });
            }
            // The query is the literal mention token, so it matches the
            // agent's own posts that quote one. The ledger is what refuses
            // those; a message Ved wrote himself mentioning himself is his
            // own conversation and is delivered.
            if host.own_post(workspace, &hit.conversation_id, &hit.ts) {
                continue;
            }
            // A search hit sends the handle alongside the id, so the
            // mention path needs no lookup at all - except for the user's
            // own posts, where that handle can be the Slack app's name.
            let author = if hit.user.as_deref() == Some(own.id) {
                match own_name(host, api, workspace, &mut own).await {
                    Ok(name) => {
                        name.or_else(|| hit.username.clone().filter(|name| !name.is_empty()))
                    }
                    Err(SlackError::RateLimited { retry_after, .. }) => {
                        return Ok(SweepOutcome {
                            delivered,
                            rate_limited: Some(retry_after),
                            ..Default::default()
                        });
                    }
                    Err(error) => return Err(error),
                }
            } else {
                hit.username.clone().filter(|name| !name.is_empty())
            };
            let message = SlackMessage {
                workspace: workspace.to_owned(),
                conversation: hit.conversation_id.clone(),
                conversation_label: hit
                    .conversation_name
                    .clone()
                    .unwrap_or_else(|| hit.conversation_id.clone()),
                ts: hit.ts.clone(),
                thread_ts: hit.thread_ts.clone(),
                user: hit.user.clone(),
                author,
                text: hit.text.clone(),
                // A search hit carries neither: only a conversation read
                // reports the reply markers.
                parent_user_id: None,
                latest_reply: None,
                edited: None,
                files: hit.files.clone(),
            };
            let mut all_handed = true;
            for subscription in &mention_subscriptions {
                if !host.deliver(subscription, std::slice::from_ref(&message)) {
                    all_handed = false;
                }
            }
            if !all_handed {
                // Hits arrive newest-first, so a failed delivery means
                // everything behind it is undelivered too: hold the
                // cursor where it was, skip the auto-subscribe, and let
                // the next tick retry the whole window.
                return Ok(SweepOutcome { delivered, ..Default::default() });
            }
            // Ved's ask: a mention pulls the agent into the conversation, so
            // the reply back and forth does not need another subscription.
            host.auto_subscribe(workspace, &message);
            // A mention inside a thread anchors that thread the same way,
            // once per owner that received it: the back and forth
            // continues under the parent, not the channel.
            for subscription in &mention_subscriptions {
                if let Some(parent_ts) = hit.thread_ts.clone() {
                    host.follow_thread(
                        workspace,
                        &hit.conversation_id,
                        &parent_ts,
                        SlackThreadOwner {
                            project: subscription.project.clone(),
                            team_role: subscription.team_role.clone(),
                        },
                        &hit.ts,
                    );
                }
            }
            delivered += 1;
            if newest.as_deref().is_none_or(|current| hit.ts.as_str() > current) {
                newest = Some(hit.ts.clone());
            }
        }

        match page.next_cursor {
            Some(next) if pages < MAX_SEARCH_PAGES => cursor = Some(next),
            Some(_) => {
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace,
                    pages,
                    "search.messages kept handing back a cursor; stopping the mention walk",
                );
                break;
            }
            None => break,
        }
    }

    if let Some(newest) = newest {
        host.set_watermark(workspace, MENTION_CURSOR, &newest);
    }

    Ok(SweepOutcome { delivered, ..Default::default() })
}

/// The wait before the next sweep: never shorter than the configured
/// interval, and at least the clamped Retry-After when one was reported.
pub(crate) fn next_interval(configured: Duration, rate_limited: Option<Duration>) -> Duration {
    rate_limited.map_or(configured, |delay| configured.max(delay.min(RETRY_CAP)))
}

/// Reports throttling once per episode: warn on entry, debug inside it,
/// info when the first clean pass ends it.
#[derive(Default)]
struct ThrottleEpisode {
    active: bool,
}

impl ThrottleEpisode {
    fn note_pass(
        &mut self,
        workspace: &str,
        sweep: &'static str,
        configured: Duration,
        rate_limited: Option<Duration>,
    ) {
        match (rate_limited, self.active) {
            (Some(delay), false) => {
                self.active = true;
                tracing::warn!(
                    target: "forge_connectors::slack::throttle",
                    workspace = %workspace,
                    sweep = %sweep,
                    event_name = "slack_sweep_throttled",
                    retry_after_secs = delay.as_secs(),
                    configured_secs = configured.as_secs(),
                    "slack throttled the sweep",
                );
            }
            (Some(delay), true) => {
                tracing::debug!(
                    target: "forge_connectors::slack::throttle",
                    workspace = %workspace,
                    sweep = %sweep,
                    event_name = "slack_sweep_throttled",
                    retry_after_secs = delay.as_secs(),
                    configured_secs = configured.as_secs(),
                    "slack sweep still throttled",
                );
            }
            (None, true) => {
                self.active = false;
                tracing::info!(
                    target: "forge_connectors::slack::throttle",
                    workspace = %workspace,
                    sweep = %sweep,
                    event_name = "slack_sweep_recovered",
                    "slack sweep recovered from throttling",
                );
            }
            (None, false) => {}
        }
    }
}

/// The pump's throttle reporter, for another crate's log-filter test.
#[cfg(feature = "testing")]
pub mod testing {
    use super::ThrottleEpisode;
    use std::time::Duration;

    /// Reports two throttled passes, so the second is the demoted per-pass
    /// record under the pump's own target and event name.
    pub fn emit_a_repeated_throttle_pass() {
        let mut episode = ThrottleEpisode::default();
        let throttled = Some(Duration::from_secs(7));
        let configured = Duration::from_secs(30);
        episode.note_pass("acme", "conversation", configured, throttled);
        episode.note_pass("acme", "conversation", configured, throttled);
    }
}

/// Sweep one workspace forever, until `shutdown` fires. The first sweep is
/// delayed by the interval so a boot with many workspaces does not burst.
pub async fn run_workspace_pump(
    host: Arc<dyn SlackHost>,
    workspace: String,
    poll_seconds: u64,
    dm_poll_seconds: u64,
    mut shutdown: oneshot::Receiver<()>,
) {
    let interval = Duration::from_secs(poll_seconds);
    let dm_interval = Duration::from_secs(dm_poll_seconds);
    let Ok(client) = host.client(&workspace, REQUEST_TIMEOUT) else {
        tracing::warn!(
            target: "forge_connectors::slack",
            workspace = %workspace,
            "no client for this workspace; its pump stays down",
        );
        return;
    };

    // The DM class runs on its own task, not on this loop's tick: one pass is
    // a sequential call per DM, so on a large inbox it would otherwise hold
    // the conversation targets and the mention stream for the whole walk.
    let (dm_shutdown_tx, dm_shutdown_rx) = oneshot::channel();
    let dm_pump = tokio::spawn(run_dm_pump(
        Arc::clone(&host),
        Arc::clone(&client),
        workspace.clone(),
        dm_interval,
        dm_shutdown_rx,
    ));

    let mut throttle = ThrottleEpisode::default();
    let mut mention_throttle = ThrottleEpisode::default();
    let mut wait = interval;
    loop {
        tokio::select! {
            _ = &mut shutdown => break,
            () = tokio::time::sleep(wait) => {}
        }
        wait = interval;
        match sweep_scope(host.as_ref(), client.as_ref(), &workspace, SweepScope::Conversations)
            .await
        {
            Ok(outcome) => {
                // A dead conversation rides the outcome so the Ok arm
                // writes the glyph down; an unconditional write here
                // would flip it back up in the same tick.
                host.set_connected(&workspace, !outcome.conversation_gone);
                tracing::debug!(
                    target: "forge_connectors::slack",
                    workspace = %workspace,
                    delivered = outcome.delivered,
                    "slack sweep finished",
                );
                // A throttled sweep otherwise reads as messages arriving
                // late from a connected row.
                throttle.note_pass(&workspace, "conversation", interval, outcome.rate_limited);
                wait = next_interval(interval, outcome.rate_limited);
            }
            Err(error) => {
                host.set_connected(&workspace, false);
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace = %workspace,
                    %error,
                    "slack sweep failed",
                );
            }
        }
        // The mention stream is one search per workspace, not one call per
        // conversation, so it costs the same whether one channel is watched
        // or fifty. It returns at once when nothing subscribes to mentions.
        match sweep_mentions(host.as_ref(), client.as_ref(), &workspace).await {
            Ok(outcome) => {
                // Its own episode: a mention search throttled on its own
                // would otherwise extend the wait with nothing said.
                mention_throttle.note_pass(&workspace, "mentions", interval, outcome.rate_limited);
                if let Some(delay) = outcome.rate_limited {
                    // The conversation sweep may already have asked for a
                    // longer wait; the longer backoff wins.
                    wait = wait.max(next_interval(interval, Some(delay)));
                }
            }
            Err(error) => {
                // The conversation sweep alone decides the glyph, so a
                // mention stream failing every tick (a token without
                // search scope, say) would read connected forever. When
                // anyone subscribes to mentions, a failing mention sweep
                // is exactly the condition the row is for.
                if host
                    .subscriptions(&workspace)
                    .iter()
                    .any(|sub| matches!(sub.target, SlackSubscriptionTarget::Mentions))
                {
                    host.set_connected(&workspace, false);
                }
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace = %workspace,
                    %error,
                    "slack mention sweep failed",
                );
            }
        }
    }
    // Dropping the sender is what stops the DM task: it selects on that
    // receiver, so the pump's own exit reaches both.
    drop(dm_shutdown_tx);
    let _ = dm_pump.await;
    host.set_connected(&workspace, false);
}

/// Sweep the DM class on its own task and its own clock, until `shutdown`
/// fires. The first pass runs at once - a restart has a gap to catch up on -
/// and every one after it waits the interval.
async fn run_dm_pump(
    host: Arc<dyn SlackHost>,
    client: Arc<dyn SlackApi>,
    workspace: String,
    interval: Duration,
    mut shutdown: oneshot::Receiver<()>,
) {
    let mut throttle = ThrottleEpisode::default();
    let mut wait = Duration::ZERO;
    loop {
        tokio::select! {
            _ = &mut shutdown => break,
            () = tokio::time::sleep(wait) => {}
        }
        match sweep_scope(host.as_ref(), client.as_ref(), &workspace, SweepScope::DirectMessages)
            .await
        {
            Ok(outcome) => {
                tracing::debug!(
                    target: "forge_connectors::slack",
                    workspace = %workspace,
                    delivered = outcome.delivered,
                    "slack DM sweep finished",
                );
                throttle.note_pass(&workspace, "dm", interval, outcome.rate_limited);
                wait = next_interval(interval, outcome.rate_limited);
            }
            Err(error) => {
                // The glyph goes down but never up from here: the
                // conversation pass owns raising it, and a DM-only row is not
                // its to declare healthy.
                host.set_connected(&workspace, false);
                tracing::warn!(
                    target: "forge_connectors::slack",
                    workspace = %workspace,
                    %error,
                    "slack DM sweep failed",
                );
                wait = interval;
            }
        }
    }
}

/// What `chat.postMessage` answers with. `channel` is the conversation the
/// message actually landed in: a request addressed by a user id or a
/// channel name does not spell the id the sweep reads it under.
#[derive(Debug, Clone, Deserialize)]
pub struct PostedMessage {
    #[serde(default)]
    pub channel: Option<String>,
    pub ts: String,
}

/// `auth.test` - who the token belongs to.
#[derive(Debug, Clone, Deserialize)]
pub struct AuthTest {
    pub team: String,
    pub user: String,
    pub team_id: String,
    pub user_id: String,
    pub url: String,
}

/// `types` must be passed explicitly or Slack returns public channels
/// only, and `limit` must be passed or the call gets a stricter cap.
const CONVERSATION_TYPES: &str = "public_channel,private_channel,im,mpim";

/// A cursor Slack hands back unchanged must not spin the walk forever:
/// at 200 per page this is far past any real workspace, and the failure
/// mode is an endless request loop against a rate-limited API.
const MAX_CONVERSATION_PAGES: usize = 200;

/// One page of `users.conversations` as Slack sends it.
#[derive(Debug, Deserialize)]
struct RawConversationsPage {
    channels: Vec<SlackConversation>,
    #[serde(default)]
    response_metadata: Metadata,
}

#[derive(Debug, Default, Deserialize)]
struct Metadata {
    #[serde(default)]
    next_cursor: String,
}

/// One page with the cursor normalised: Slack sends an empty string on
/// the last page, which would otherwise read as a cursor to page from.
#[derive(Debug)]
struct ConversationsPage {
    conversations: Vec<SlackConversation>,
    next_cursor: Option<String>,
}

/// Split out of the async path so the paging rules are testable without HTTP.
fn decode_conversations_page(body: &str) -> Result<ConversationsPage, SlackError> {
    let raw: RawConversationsPage = decode_envelope("users.conversations", body)?;
    Ok(page_from_raw(raw))
}

fn page_from_raw(raw: RawConversationsPage) -> ConversationsPage {
    let cursor = (!raw.response_metadata.next_cursor.is_empty())
        .then_some(raw.response_metadata.next_cursor);
    ConversationsPage { conversations: raw.channels, next_cursor: cursor }
}

/// One message off `conversations.history` or `conversations.replies`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackHistoryMessage {
    pub ts: String,
    pub user: Option<String>,
    pub text: String,
    /// `None` on a message with no thread at all. Equal to `ts` on a
    /// thread's parent, and the parent's `ts` on a reply.
    pub thread_ts: Option<String>,
    /// Non-zero on a parent whose thread has replies.
    pub reply_count: u32,
    /// A bot's own display name, which rides the message: free where a
    /// human's id has to be looked up.
    pub bot_name: Option<String>,
    /// Set on a reply, carrying the parent's author, and absent on a
    /// parent. This, not `thread_ts`, is what marks a reply: a parent
    /// carries `thread_ts` too.
    pub parent_user_id: Option<String>,
    /// A parent's newest reply `ts`. Absent on a message with no replies.
    pub latest_reply: Option<String>,
    /// The `ts` of the message's newest edit, absent on one never edited.
    /// This is the whole of what an edit looks like on this read path:
    /// `conversations.history` sends the message it always was, with the
    /// new text and this object. `message_changed` and `message_deleted`
    /// are Events API shapes the sweep never sees, and a deleted message
    /// is simply absent from history - so deletion has no frame here to
    /// decide on. An edit to a message the cursor has passed is reached by
    /// the thread's periodic whole read, which judges it against the edit
    /// watermark rather than the cursor.
    pub edited: Option<String>,
    /// Files shared on the message, ids and all.
    pub files: Vec<SlackFile>,
}

/// One page of a conversation's messages. Both `conversations.history` and
/// `conversations.replies` answer with this shape.
#[derive(Debug)]
pub struct MessagePage {
    pub messages: Vec<SlackHistoryMessage>,
    pub next_cursor: Option<String>,
}

#[derive(Debug, Deserialize)]
struct RawMessagePage {
    #[serde(default)]
    messages: Vec<RawWireMessage>,
    #[serde(default)]
    response_metadata: Metadata,
}

#[derive(Debug, Deserialize)]
struct RawWireMessage {
    ts: String,
    #[serde(default)]
    user: Option<String>,
    #[serde(default)]
    text: String,
    #[serde(default)]
    thread_ts: Option<String>,
    #[serde(default)]
    reply_count: u32,
    #[serde(default)]
    bot_profile: Option<BotProfile>,
    #[serde(default)]
    parent_user_id: Option<String>,
    #[serde(default)]
    latest_reply: Option<String>,
    #[serde(default)]
    edited: Option<RawEdited>,
    #[serde(default)]
    files: Vec<SlackFile>,
}

/// The wire's `edited` object. Only the edit's own `ts` is decision-bearing:
/// whose edit it was changes nothing the sweep decides.
#[derive(Debug, Deserialize)]
struct RawEdited {
    #[serde(default)]
    ts: Option<String>,
}

/// A bot message's own profile. `name` is the app's name, which is the
/// only display name a bot message carries.
#[derive(Debug, Deserialize)]
struct BotProfile {
    #[serde(default)]
    name: Option<String>,
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_message_page(method: &str, body: &str) -> Result<MessagePage, SlackError> {
    let raw: RawMessagePage = decode_envelope(method, body)?;
    let cursor = (!raw.response_metadata.next_cursor.is_empty())
        .then_some(raw.response_metadata.next_cursor);
    let messages = raw
        .messages
        .into_iter()
        .map(|message| SlackHistoryMessage {
            ts: message.ts,
            user: message.user,
            text: message.text,
            thread_ts: message.thread_ts,
            reply_count: message.reply_count,
            bot_name: message.bot_profile.and_then(|profile| profile.name),
            parent_user_id: message.parent_user_id,
            latest_reply: message.latest_reply,
            edited: message.edited.and_then(|edited| edited.ts),
            files: message.files,
        })
        .collect();
    Ok(MessagePage { messages, next_cursor: cursor })
}

/// The params `conversations.history` is called with. Slack calls the newest
/// bound `latest`, and both bounds are exclusive.
fn history_params(
    channel: &str,
    oldest: Option<&str>,
    newest: Option<&str>,
    limit: u32,
    cursor: Option<&str>,
) -> Vec<(&'static str, String)> {
    let mut params = vec![("channel", channel.to_owned()), ("limit", limit.to_string())];
    if let Some(oldest) = oldest {
        params.push(("oldest", oldest.to_owned()));
    }
    if let Some(newest) = newest {
        params.push(("latest", newest.to_owned()));
    }
    if let Some(cursor) = cursor {
        params.push(("cursor", cursor.to_owned()));
    }
    params
}

/// Slack's page ceiling for `users.list`.
const USER_PAGE_LIMIT: u32 = 200;

/// A cursor Slack hands back unchanged must not spin the user walk forever:
/// at 200 per page this is far past any real workspace, and the failure mode
/// is an endless request loop against a rate-limited API.
const MAX_USER_PAGES: usize = 100;

/// One page of `users.list`, with Slack's empty last-page cursor normalised
/// the way the conversations page is.
#[derive(Debug)]
struct UsersPage {
    members: Vec<SlackUser>,
    next_cursor: Option<String>,
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_users_page(body: &str) -> Result<UsersPage, SlackError> {
    #[derive(Deserialize)]
    struct RawUsersPage {
        #[serde(default)]
        members: Vec<SlackUser>,
        #[serde(default)]
        response_metadata: Metadata,
    }
    let raw: RawUsersPage = decode_envelope("users.list", body)?;
    let cursor = (!raw.response_metadata.next_cursor.is_empty())
        .then_some(raw.response_metadata.next_cursor);
    Ok(UsersPage { members: raw.members, next_cursor: cursor })
}

/// One page of `users.list`. The walk is split from the HTTP client so its
/// page cap is reachable from a double that never stops handing back a
/// cursor.
#[async_trait::async_trait]
trait UsersPages: Send + Sync {
    async fn users_page(&self, cursor: Option<&str>) -> Result<UsersPage, SlackError>;
}

#[async_trait::async_trait]
impl UsersPages for SlackClient {
    async fn users_page(&self, cursor: Option<&str>) -> Result<UsersPage, SlackError> {
        let mut params = vec![("limit", USER_PAGE_LIMIT.to_string())];
        if let Some(cursor) = cursor {
            params.push(("cursor", cursor.to_owned()));
        }
        let body = self.call_text("users.list", &params).await?;
        decode_users_page(&body)
    }
}

/// Every member in the workspace, following the cursor. A cursor that never
/// ends returns what was read, the way the history and reply walks do,
/// rather than failing the whole lookup.
async fn walk_users(pages: &dyn UsersPages) -> Result<Vec<SlackUser>, SlackError> {
    let mut out = Vec::new();
    let mut cursor: Option<String> = None;
    for _ in 0..MAX_USER_PAGES {
        let page = pages.users_page(cursor.as_deref()).await?;
        out.extend(page.members);
        match page.next_cursor {
            Some(next) => cursor = Some(next),
            None => return Ok(out),
        }
    }
    tracing::warn!(
        target: "forge_connectors::slack",
        pages = MAX_USER_PAGES,
        users = out.len(),
        "users.list kept handing back a cursor; stopping the walk",
    );
    Ok(out)
}

/// The API's ceiling for one search page.
const SEARCH_COUNT_CAP: u32 = 100;

/// The params `search.messages` is always called with. `sort=timestamp`
/// because the default is relevance, which during the probe ranked a
/// 22-hour-old match above a 2.6-hour-old one.
fn search_params(query: &str, count: u32) -> Vec<(&'static str, String)> {
    vec![
        ("query", query.to_owned()),
        ("sort", "timestamp".to_owned()),
        ("count", count.min(SEARCH_COUNT_CAP).to_string()),
    ]
}

/// One page of `search.messages`, newest first.
#[derive(Debug, Default)]
pub struct SearchPage {
    pub matches: Vec<SlackSearchMatch>,
    pub next_cursor: Option<String>,
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_search(body: &str) -> Result<SearchPage, SlackError> {
    #[derive(Default, Deserialize)]
    struct SearchMessages {
        #[serde(default)]
        matches: Vec<RawMatch>,
        #[serde(default)]
        next_cursor: String,
    }
    #[derive(Default, Deserialize)]
    struct SearchPayload {
        #[serde(default)]
        messages: SearchMessages,
    }
    #[derive(Deserialize)]
    struct RawMatch {
        ts: String,
        #[serde(default)]
        text: String,
        channel: RawChannel,
        #[serde(default)]
        username: Option<String>,
        /// The author's id, which the delivered block carries - `username`
        /// is only a handle.
        #[serde(default)]
        user: Option<String>,
        #[serde(default)]
        thread_ts: Option<String>,
        #[serde(default)]
        files: Vec<SlackFile>,
    }
    #[derive(Deserialize)]
    struct RawChannel {
        id: String,
        #[serde(default)]
        name: Option<String>,
    }

    let payload: SearchPayload = decode_envelope("search.messages", body)?;
    let next_cursor =
        (!payload.messages.next_cursor.is_empty()).then_some(payload.messages.next_cursor);
    let matches = payload
        .messages
        .matches
        .into_iter()
        .map(|hit| SlackSearchMatch {
            ts: hit.ts,
            text: hit.text,
            conversation_id: hit.channel.id,
            conversation_name: hit.channel.name,
            username: hit.username,
            user: hit.user,
            thread_ts: hit.thread_ts,
            files: hit.files,
        })
        .collect();
    Ok(SearchPage { matches, next_cursor })
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_user(body: &str) -> Result<SlackUser, SlackError> {
    #[derive(Deserialize)]
    struct Wrapper {
        user: SlackUser,
    }
    let wrapper: Wrapper = decode_envelope("users.info", body)?;
    Ok(wrapper.user)
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_file(body: &str) -> Result<SlackFile, SlackError> {
    #[derive(Deserialize)]
    struct Wrapper {
        file: SlackFile,
    }
    let wrapper: Wrapper = decode_envelope("files.info", body)?;
    Ok(wrapper.file)
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_pins(body: &str) -> Result<Vec<SlackPin>, SlackError> {
    #[derive(Deserialize)]
    struct Wrapper {
        #[serde(default)]
        items: Vec<SlackPin>,
    }
    let wrapper: Wrapper = decode_envelope("pins.list", body)?;
    Ok(wrapper.items)
}

/// Split out of the async path so the decode is testable without HTTP.
fn decode_bookmarks(body: &str) -> Result<Vec<SlackBookmark>, SlackError> {
    #[derive(Deserialize)]
    struct Wrapper {
        #[serde(default)]
        bookmarks: Vec<SlackBookmark>,
    }
    let wrapper: Wrapper = decode_envelope("bookmarks.list", body)?;
    Ok(wrapper.bookmarks)
}

impl SlackClient {
    pub fn new(http: reqwest::Client, token: String) -> Self {
        Self { http, token }
    }

    /// POST one Web API method. Slack is uniform here, so one helper
    /// covers every call the connector makes.
    pub async fn call<T: DeserializeOwned>(
        &self,
        method: &str,
        params: &[(&str, String)],
    ) -> Result<T, SlackError> {
        let body = self.call_text(method, params).await?;
        decode_envelope(method, &body)
    }

    /// POST one Web API method and hand back the body undecoded, for the
    /// callers whose decode needs the raw text rather than one envelope.
    async fn call_text(
        &self,
        method: &str,
        params: &[(&str, String)],
    ) -> Result<String, SlackError> {
        let url = format!("{API_ROOT}/{method}");
        let response = self
            .http
            .post(&url)
            .bearer_auth(&self.token)
            .header(reqwest::header::CONTENT_TYPE, "application/x-www-form-urlencoded")
            .body(encode_form(params))
            // Per request, not on the client: a file body's transfer is
            // not a Web API call and keeps its own behaviour.
            .timeout(REQUEST_TIMEOUT)
            .send()
            .await
            .map_err(|err| SlackError::Transport {
                method: method.to_owned(),
                detail: err.to_string(),
            })?;

        let status = response.status();
        if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
            return Err(SlackError::RateLimited {
                method: method.to_owned(),
                retry_after: retry_delay(retry_after_of(&response)),
            });
        }

        let body = response.text().await.map_err(|err| SlackError::Transport {
            method: method.to_owned(),
            detail: err.to_string(),
        })?;
        if !status.is_success() {
            return Err(status_failure(method, status, &body));
        }
        Ok(body)
    }

    /// Who this token belongs to. The first thing to prove on a new workspace.
    pub async fn auth_test(&self) -> Result<AuthTest, SlackError> {
        self.call("auth.test", &[]).await
    }

    /// One page of a conversation's history. Each bound is omitted entirely
    /// when absent: Slack treats an empty `oldest` differently from an
    /// absent one.
    pub async fn history(
        &self,
        channel: &str,
        oldest: Option<&str>,
        newest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError> {
        let params = history_params(channel, oldest, newest, limit, cursor);
        let body = self.call_text("conversations.history", &params).await?;
        decode_message_page("conversations.history", &body)
    }

    /// One page of a thread's replies. Slack repeats the parent on every
    /// page, so the caller dedupes by `ts`.
    pub async fn replies(
        &self,
        channel: &str,
        ts: &str,
        oldest: Option<&str>,
        limit: u32,
        cursor: Option<&str>,
    ) -> Result<MessagePage, SlackError> {
        let mut params = vec![
            ("channel", channel.to_owned()),
            ("ts", ts.to_owned()),
            ("limit", limit.to_string()),
        ];
        if let Some(oldest) = oldest {
            params.push(("oldest", oldest.to_owned()));
        }
        if let Some(cursor) = cursor {
            params.push(("cursor", cursor.to_owned()));
        }
        let body = self.call_text("conversations.replies", &params).await?;
        decode_message_page("conversations.replies", &body)
    }

    /// Post one message, as a root or into an existing thread. Returns the
    /// posted message's `ts`.
    pub async fn post_message(
        &self,
        channel: &str,
        text: &str,
        thread_ts: Option<&str>,
    ) -> Result<PostedMessage, SlackError> {
        let mut params = vec![("channel", channel.to_owned()), ("text", text.to_owned())];
        if let Some(thread_ts) = thread_ts {
            params.push(("thread_ts", thread_ts.to_owned()));
        }
        self.call("chat.postMessage", &params).await
    }

    /// Replace the text of one of the user's own messages. Slack drops
    /// existing blocks when `text` is sent without them, which is what
    /// this connector wants: one text body, no stale block.
    pub async fn update_message(
        &self,
        channel: &str,
        ts: &str,
        text: &str,
    ) -> Result<(), SlackError> {
        let params =
            vec![("channel", channel.to_owned()), ("ts", ts.to_owned()), ("text", text.to_owned())];
        let _: serde_json::Value = self.call("chat.update", &params).await?;
        Ok(())
    }

    /// Delete one of the user's own messages.
    pub async fn delete_message(&self, channel: &str, ts: &str) -> Result<(), SlackError> {
        let params = vec![("channel", channel.to_owned()), ("ts", ts.to_owned())];
        let _: serde_json::Value = self.call("chat.delete", &params).await?;
        Ok(())
    }

    /// Add or remove one reaction. `reactions.remove` requires being the
    /// original reaction's author.
    pub async fn set_reaction(
        &self,
        channel: &str,
        ts: &str,
        name: &str,
        add: bool,
    ) -> Result<(), SlackError> {
        let method = if add { "reactions.add" } else { "reactions.remove" };
        let params = vec![
            ("channel", channel.to_owned()),
            ("timestamp", ts.to_owned()),
            ("name", name.to_owned()),
        ];
        let _: serde_json::Value = self.call(method, &params).await?;
        Ok(())
    }

    /// GET an absolute URL with the bearer attached. Slack's private file
    /// URLs answer 403 without it, and byte-identically with it.
    pub async fn get_bytes(&self, url: &str) -> Result<Vec<u8>, SlackError> {
        let response = self.http.get(url).bearer_auth(&self.token).send().await.map_err(|err| {
            SlackError::Transport { method: "download".to_owned(), detail: err.to_string() }
        })?;
        if response.status() == reqwest::StatusCode::TOO_MANY_REQUESTS {
            return Err(SlackError::RateLimited {
                method: "download".to_owned(),
                retry_after: retry_delay(retry_after_of(&response)),
            });
        }
        let status = response.status();
        let bytes = response.bytes().await.map_err(|err| SlackError::Transport {
            method: "download".to_owned(),
            detail: err.to_string(),
        })?;
        if !status.is_success() {
            // A non-success body is an error page, never a file: treating
            // it as bytes would write an HTML 403 to disk as the file.
            return Err(SlackError::Transport {
                method: "download".to_owned(),
                detail: format!("HTTP {status}"),
            });
        }
        Ok(bytes.to_vec())
    }

    /// POST raw bytes to an absolute URL. Deliberately no bearer: the
    /// upload URL is pre-signed, and it is not the Web API host.
    pub async fn post_bytes(&self, url: &str, body: Vec<u8>) -> Result<(), SlackError> {
        let response = self.http.post(url).body(body).send().await.map_err(|err| {
            SlackError::Transport { method: "upload".to_owned(), detail: err.to_string() }
        })?;
        let status = response.status();
        if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
            return Err(SlackError::RateLimited {
                method: "upload".to_owned(),
                retry_after: retry_delay(retry_after_of(&response)),
            });
        }
        if !status.is_success() {
            return Err(SlackError::Transport {
                method: "upload".to_owned(),
                detail: format!("HTTP {status}"),
            });
        }
        Ok(())
    }

    /// `files.info` for one file id.
    pub async fn file_info(&self, id: &str) -> Result<SlackFile, SlackError> {
        let params = vec![("file", id.to_owned())];
        let body = self.call_text("files.info", &params).await?;
        decode_file(&body)
    }

    /// `files.getUploadURLExternal`: the pre-signed URL to POST the bytes
    /// to, plus the file id the completion call needs.
    pub async fn get_upload_url(
        &self,
        name: &str,
        length: usize,
    ) -> Result<(String, String), SlackError> {
        #[derive(Deserialize)]
        struct UploadTarget {
            upload_url: String,
            file_id: String,
        }
        let params = vec![("filename", name.to_owned()), ("length", length.to_string())];
        let target: UploadTarget = self.call("files.getUploadURLExternal", &params).await?;
        Ok((target.upload_url, target.file_id))
    }

    /// `files.completeUploadExternal`. It can be called once only, and the
    /// file is discarded if it never is.
    pub async fn complete_upload(
        &self,
        file_id: &str,
        channel: &str,
        thread_ts: Option<&str>,
    ) -> Result<Vec<SlackFile>, SlackError> {
        #[derive(Deserialize)]
        struct Uploaded {
            #[serde(default)]
            files: Vec<SlackFile>,
        }
        let files = serde_json::json!([{ "id": file_id }]).to_string();
        let mut params = vec![("files", files), ("channel_id", channel.to_owned())];
        if let Some(thread_ts) = thread_ts {
            params.push(("thread_ts", thread_ts.to_owned()));
        }
        let uploaded: Uploaded = self.call("files.completeUploadExternal", &params).await?;
        Ok(uploaded.files)
    }

    /// `search.messages`. Matches text; it cannot find every message that
    /// mentions a user, which is what the mention subscription is for.
    pub async fn search_messages(
        &self,
        query: &str,
        count: u32,
        cursor: Option<&str>,
    ) -> Result<SearchPage, SlackError> {
        let mut params = search_params(query, count);
        if let Some(cursor) = cursor {
            params.push(("cursor", cursor.to_owned()));
        }
        let body = self.call_text("search.messages", &params).await?;
        decode_search(&body)
    }

    /// `users.info` for one user id.
    pub async fn user_info(&self, user: &str) -> Result<SlackUser, SlackError> {
        let params = vec![("user", user.to_owned())];
        let body = self.call_text("users.info", &params).await?;
        decode_user(&body)
    }

    /// Every member in the workspace, following the cursor. Slack has no
    /// server-side name search, so a resolver reads the directory and
    /// matches locally.
    pub async fn list_users(&self) -> Result<Vec<SlackUser>, SlackError> {
        walk_users(self).await
    }

    /// `pins.list` for one conversation.
    pub async fn pins(&self, channel: &str) -> Result<Vec<SlackPin>, SlackError> {
        let params = vec![("channel", channel.to_owned())];
        let body = self.call_text("pins.list", &params).await?;
        decode_pins(&body)
    }

    /// `bookmarks.list` for one conversation. The param is `channel_id`
    /// here against `channel` on pins.list.
    pub async fn bookmarks(&self, channel: &str) -> Result<Vec<SlackBookmark>, SlackError> {
        let params = vec![("channel_id", channel.to_owned())];
        let body = self.call_text("bookmarks.list", &params).await?;
        decode_bookmarks(&body)
    }

    /// Every conversation the token's user is a member of, paging to the end.
    pub async fn list_conversations(&self) -> Result<Vec<SlackConversation>, SlackError> {
        let mut out = Vec::new();
        let mut cursor: Option<String> = None;
        let mut pages = 0;
        loop {
            let mut params =
                vec![("types", CONVERSATION_TYPES.to_owned()), ("limit", "200".to_owned())];
            if let Some(cursor) = &cursor {
                params.push(("cursor", cursor.clone()));
            }
            let body = self.call_text("users.conversations", &params).await?;
            let page = decode_conversations_page(&body)?;
            out.extend(page.conversations);
            pages += 1;
            match page.next_cursor {
                Some(_) if pages >= MAX_CONVERSATION_PAGES => {
                    tracing::warn!(
                        target: "forge_connectors::slack",
                        pages,
                        conversations = out.len(),
                        "users.conversations kept handing back a cursor; stopping the walk",
                    );
                    return Ok(out);
                }
                Some(next) => cursor = Some(next),
                None => return Ok(out),
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use forge_primitives::slack::{SlackFileShares, SlackThreadRecord};
    use std::collections::HashMap;

    /// Pinned against literals, not against `RETRY_FALLBACK` / `RETRY_CAP`:
    /// asserting the output equals the constant the function itself applies
    /// holds for any value, so it cannot catch a changed cap.
    #[test]
    fn retry_delay_honours_the_header_and_floors_absurd_values() {
        assert_eq!(retry_delay(Some(7)), Duration::from_secs(7), "an honest header is honoured");
        assert_eq!(retry_delay(None), Duration::from_secs(5), "a missing header falls back");
        // A hostile or broken header must not park the pump for an hour.
        assert_eq!(
            retry_delay(Some(100_000)),
            Duration::from_secs(60),
            "an absurd header is capped"
        );
        // `Retry-After: 0` is legal, and retrying immediately is the one
        // thing the header asked us not to do.
        assert_eq!(retry_delay(Some(0)), Duration::from_secs(1), "a zero header still waits");
    }

    #[test]
    fn a_gateway_failure_reports_the_status_and_a_bounded_body_prefix() {
        let mut body = "bad gateway from the edge".to_owned();
        body.push_str(&"x".repeat(1000));
        let err = status_failure("users.conversations", reqwest::StatusCode::BAD_GATEWAY, &body);
        match err {
            SlackError::Transport { method, detail } => {
                assert!(detail.contains("502"), "the status is named, got: {detail}");
                assert!(detail.contains("bad gateway"), "the body prefix is carried: {detail}");
                assert!(detail.len() < 300, "the body is bounded, got {} chars", detail.len());
                assert_eq!(method, "users.conversations");
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn an_ok_false_envelope_is_an_api_error_not_a_decode_error() {
        let body = r#"{"ok":false,"error":"missing_scope","needed":"search:read.public"}"#;
        let err = decode_envelope::<serde_json::Value>("conversations.history", body)
            .expect_err("ok:false must be an error");
        match err {
            SlackError::Api { method, error, needed } => {
                assert_eq!(method, "conversations.history");
                assert_eq!(error, "missing_scope");
                assert_eq!(needed.as_deref(), Some("search:read.public"));
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    /// `auth.test` is where forge learns the token's own user id. The id,
    /// not the handle: the mention sweep queries it and the thread walk
    /// reads participation from it, so a handle-only probe would silently
    /// stop both.
    #[test]
    fn auth_test_yields_the_tokens_own_user_id() {
        let body = r#"{"ok":true,"team":"acme","user":"ved","team_id":"T1","user_id":"U123","url":"https://x.slack.com/"}"#;
        let auth: AuthTest = decode_envelope("auth.test", body).expect("decodes");
        assert_eq!(auth.user_id, "U123", "the id is what the filters compare");
    }

    #[test]
    fn an_ok_true_envelope_decodes_its_payload() {
        let body = r#"{"ok":true,"team":"Trust Machines","user":"ved","team_id":"T1","user_id":"U1","url":"https://x.slack.com/"}"#;
        let got: AuthTest = decode_envelope("auth.test", body).expect("decodes");
        assert_eq!(got.team_id, "T1", "the flattened payload carries team_id");
        assert_eq!(got.user, "ved", "the flattened payload carries user");
    }

    #[test]
    fn list_conversations_decodes_mixed_types_and_keeps_the_cursor() {
        let body = r#"{
          "ok": true,
          "channels": [
            {"id":"C1","name":"general","is_channel":true},
            {"id":"D1","is_im":true,"user":"U9"},
            {"id":"G1","name":"secret","is_private":true}
          ],
          "response_metadata": {"next_cursor": "abc123"}
        }"#;
        let page = decode_conversations_page(body).expect("decodes");
        assert_eq!(page.conversations.len(), 3, "every channel in the page is kept");
        assert_eq!(page.conversations[1].user.as_deref(), Some("U9"), "a DM keeps its partner");
        assert_eq!(page.next_cursor.as_deref(), Some("abc123"), "a non-empty cursor pages on");

        let empty = decode_conversations_page(
            r#"{"ok":true,"channels":[],"response_metadata":{"next_cursor":""}}"#,
        )
        .expect("an empty cursor means the last page");
        assert_eq!(empty.next_cursor, None, "an empty cursor ends the walk");
    }

    #[test]
    fn purpose_and_topic_decode_and_a_dm_omits_them() {
        let page = decode_conversations_page(
            r#"{"ok":true,"channels":[{"id":"C1","name":"general","is_channel":true,
                "purpose":{"value":"Deploy chatter","creator":"U1","last_set":1700000000},
                "topic":{"value":"release coordination"}}]}"#,
        )
        .expect("decodes");
        let channel = &page.conversations[0];
        assert_eq!(
            channel.purpose.as_ref().expect("a channel carries its purpose").value,
            "Deploy chatter",
        );
        assert_eq!(
            channel.topic.as_ref().expect("a channel carries its topic").value,
            "release coordination",
            "only the value is read; the metadata stays behind",
        );

        let dm = decode_conversations_page(r#"{"ok":true,"channels":[{"id":"D1","is_im":true}]}"#)
            .expect("decodes");
        assert!(
            dm.conversations[0].purpose.is_none() && dm.conversations[0].topic.is_none(),
            "a DM carries neither object",
        );
    }

    #[test]
    fn pins_list_decodes_the_pinned_rows() {
        let body = r#"{"ok":true,"items":[
            {"type":"message","created":1700000000,"created_by":"U1",
             "message":{"type":"message","ts":"1700000000.000100","user":"U2",
                        "text":"the pinned text"}}]}"#;
        let pins = decode_pins(body).expect("decodes");
        assert_eq!(pins.len(), 1, "one row per pinned message");
        let message = pins[0].message.as_ref().expect("a pin carries its message");
        assert_eq!(message.ts, "1700000000.000100", "the ts survives verbatim");
        assert_eq!(message.text, "the pinned text");
        assert_eq!(message.user.as_deref(), Some("U2"));
        assert_eq!(pins[0].created_by.as_deref(), Some("U1"), "who pinned it comes along");
    }

    #[test]
    fn bookmarks_list_decodes_the_saved_links() {
        let body = r#"{"ok":true,"bookmarks":[
            {"id":"Bk1","type":"link","channel_id":"C1","title":"Runbook",
             "link":"https://example.com","date_created":1700000000}]}"#;
        let bookmarks = decode_bookmarks(body).expect("decodes");
        assert_eq!(bookmarks.len(), 1);
        assert_eq!(bookmarks[0].id, "Bk1");
        assert_eq!(bookmarks[0].title.as_deref(), Some("Runbook"));
        assert_eq!(bookmarks[0].link.as_deref(), Some("https://example.com"));
    }

    /// The input class a message body actually contains, and the class a
    /// hand-rolled encoder silently splits a parameter on.
    #[test]
    fn encode_form_escapes_what_a_message_body_carries() {
        let encoded = encode_form(&[("text", "a&b=c+d\ncafé".to_owned())]);
        assert_eq!(encoded, "text=a%26b%3Dc%2Bd%0Acaf%C3%A9");
        assert_eq!(
            encode_form(&[("text", "two words".to_owned())]),
            "text=two+words",
            "a space is a form `+`, not %20"
        );
    }

    #[test]
    fn encode_form_keeps_an_empty_value_and_emits_nothing_for_no_params() {
        assert_eq!(encode_form(&[]), "", "no params is an empty body");
        assert_eq!(
            encode_form(&[("cursor", String::new())]),
            "cursor=",
            "an empty value still emits its name"
        );
    }

    fn sub_for(target: SlackSubscriptionTarget) -> SlackSubscription {
        SlackSubscription {
            id: uuid::Uuid::new_v4(),
            workspace: "acme".to_owned(),
            project: "forge".to_owned(),
            team_role: None,
            target,
            created_at: std::time::SystemTime::UNIX_EPOCH,
        }
    }

    fn conversation_channel(id: &str, name: &str) -> SlackConversation {
        SlackConversation {
            id: id.to_owned(),
            name: Some(name.to_owned()),
            is_channel: true,
            is_private: false,
            is_im: false,
            is_mpim: false,
            is_archived: false,
            user: None,
            purpose: None,
            topic: None,
        }
    }

    fn conversation_im(id: &str, user: &str) -> SlackConversation {
        SlackConversation {
            id: id.to_owned(),
            name: None,
            is_channel: false,
            is_private: false,
            is_im: true,
            is_mpim: false,
            is_archived: false,
            user: Some(user.to_owned()),
            purpose: None,
            topic: None,
        }
    }

    #[test]
    fn a_mention_is_the_literal_token_and_nothing_looser() {
        assert!(mentions("hey <@U123> look", "U123"));
        assert!(!mentions("hey U123 look", "U123"), "a bare id is not a mention");
        assert!(!mentions("hey <@U1234> look", "U123"), "a longer id must not match");
        assert!(mentions("<@U123>", "U123"), "a mention with no surrounding text still counts");
    }

    /// A message forge did not post: nothing in the outbound ledger.
    fn not_ours(_ts: &str) -> bool {
        false
    }

    /// A message forge posted: every ts is in the outbound ledger.
    fn ours(_ts: &str) -> bool {
        true
    }

    #[test]
    fn a_dm_subscription_wants_every_dm() {
        let subs = vec![sub_for(SlackSubscriptionTarget::DirectMessages)];
        let dm = conversation_im("D1", "U9");
        assert!(wants(&subs, &dm, "anything", "100.1", "U1", &not_ours));
    }

    #[test]
    fn a_mentions_only_channel_filters_on_the_token() {
        let subs = vec![sub_for(SlackSubscriptionTarget::Conversation {
            id: "C1".to_owned(),
            name: None,
            mode: SlackWatchMode::MentionsOnly,
        })];
        let channel = conversation_channel("C1", "general");
        assert!(!wants(&subs, &channel, "no mention here", "100.1", "U1", &not_ours));
        assert!(wants(&subs, &channel, "ping <@U1>", "100.1", "U1", &not_ours));
    }

    /// forge posts as the user, so refusing by author refuses the messages
    /// he types himself - the bug this test reproduces. Only a ts in the
    /// outbound ledger is forge's own post.
    #[test]
    fn a_self_authored_message_with_an_unledgered_ts_is_delivered() {
        let subs = vec![sub_for(SlackSubscriptionTarget::Conversation {
            id: "C1".to_owned(),
            name: None,
            mode: SlackWatchMode::All,
        })];
        let channel = conversation_channel("C1", "general");
        assert!(
            wants(&subs, &channel, "what I typed", "1700000000.000100", "U1", &not_ours),
            "a thread Ved talks in must not read one-sided",
        );
    }

    /// The agent must never answer itself: forge's own post carries the ts
    /// it recorded at send time, so the ledger is what refuses it.
    #[test]
    fn a_ledgered_ts_is_refused_however_it_is_authored() {
        let subs = vec![sub_for(SlackSubscriptionTarget::Conversation {
            id: "C1".to_owned(),
            name: None,
            mode: SlackWatchMode::All,
        })];
        let channel = conversation_channel("C1", "general");
        assert!(
            !wants(&subs, &channel, "the agent's own words", "1700000000.000100", "U1", &ours),
            "a post forge made comes back to it unless the ledger refuses it",
        );
    }

    /// A mention target sweeps by search rather than by conversation, so
    /// the per-conversation path must never claim it - claiming it would
    /// deliver the same mention twice.
    #[test]
    fn a_mention_target_is_not_a_conversation_target() {
        let subs = vec![sub_for(SlackSubscriptionTarget::Mentions)];
        let channel = conversation_channel("C1", "general");
        assert!(!wants(&subs, &channel, "no mention here", "100.1", "U1", &not_ours));
        assert!(!wants(&subs, &channel, "a mention <@U1>", "100.1", "U1", &not_ours));
    }

    #[test]
    fn an_unsubscribed_conversation_is_never_wanted() {
        let subs = vec![sub_for(SlackSubscriptionTarget::Conversation {
            id: "C1".to_owned(),
            name: None,
            mode: SlackWatchMode::All,
        })];
        assert!(!wants(
            &subs,
            &conversation_channel("C2", "other"),
            "hi",
            "100.1",
            "U1",
            &not_ours
        ));
    }

    #[test]
    fn a_history_page_decodes_its_messages_and_the_cursor() {
        let body = r#"{
          "ok": true,
          "messages": [
            {"ts":"100.000001","user":"U9","text":"hello","thread_ts":"100.000001","reply_count":3},
            {"ts":"200.000002","user":"U8","text":"plain"}
          ],
          "response_metadata": {"next_cursor": "cur1"}
        }"#;
        let page = decode_message_page("conversations.history", body).expect("decodes");
        assert_eq!(page.messages.len(), 2, "every message in the page is kept");
        assert_eq!(page.messages[0].ts, "100.000001", "the ts survives as the string Slack sent");
        assert_eq!(page.messages[0].reply_count, 3, "the reply count drives thread following");
        assert_eq!(page.messages[0].thread_ts.as_deref(), Some("100.000001"));
        assert_eq!(page.messages[1].thread_ts, None, "a top-level message has no thread");
        assert_eq!(page.next_cursor.as_deref(), Some("cur1"));

        let last = decode_message_page(
            "conversations.history",
            r#"{"ok":true,"messages":[],"response_metadata":{"next_cursor":""}}"#,
        )
        .expect("an empty cursor means the last page");
        assert_eq!(last.next_cursor, None);
    }

    /// An edit arrives as the message it always was, with the new text and
    /// an `edited` object (Slack's message shape; `message_changed` is an
    /// Events API subtype this sweep never sees). The decode must keep the
    /// edit's own ts, or nothing downstream can tell a corrected message
    /// apart from its original.
    #[test]
    fn an_edited_message_decodes_the_edit_ts() {
        let body = r#"{
          "ok": true,
          "messages": [
            {"ts":"100.000001","user":"U9","text":"the correction",
             "edited":{"user":"U9","ts":"1790186900.123456"}},
            {"ts":"90.000001","user":"U9","text":"untouched"}
          ]
        }"#;
        let page = decode_message_page("conversations.history", body).expect("decodes");
        assert_eq!(
            page.messages[0].edited.as_deref(),
            Some("1790186900.123456"),
            "the edit's own ts is what says the text changed after sending",
        );
        assert_eq!(page.messages[1].edited, None, "an untouched message carries no edit");
    }

    /// `search.messages` carries the author's id beside the handle, and the
    /// mention sweep tells his own post from the app's name by that id. A
    /// decode that dropped it would silently put `Forge` back on his words.
    #[test]
    fn search_decodes_the_user_id_beside_the_username() {
        let body = r#"{
          "ok": true,
          "messages": {
            "matches": [
              {"ts":"200.1","text":"ping <@U1>","channel":{"id":"C1","name":"general"},
               "username":"Forge","user":"U1"}
            ],
            "next_cursor": ""
          }
        }"#;
        let page = decode_search(body).expect("decodes");
        let hit = &page.matches[0];
        assert_eq!(hit.user.as_deref(), Some("U1"), "the id is what the own-id rule reads");
        assert_eq!(hit.username.as_deref(), Some("Forge"), "and the app's handle rides along");
    }

    /// Slack calls the newest bound `latest`, and a bound that was not asked
    /// for must be absent rather than empty.
    #[test]
    fn history_params_carry_each_bound_only_when_it_is_asked_for() {
        let bounded = history_params("C1", Some("100.0"), Some("200.0"), 50, Some("cur"));
        assert_eq!(
            bounded,
            vec![
                ("channel", "C1".to_owned()),
                ("limit", "50".to_owned()),
                ("oldest", "100.0".to_owned()),
                ("latest", "200.0".to_owned()),
                ("cursor", "cur".to_owned()),
            ],
            "the newest bound travels as `latest`",
        );

        let bare = history_params("C1", None, None, 50, None);
        assert!(
            !bare.iter().any(|(key, _)| *key == "oldest" || *key == "latest"),
            "an absent bound is omitted entirely: {bare:?}",
        );
    }

    /// The draft's tag list is the user ids its text mentions, once each and
    /// in order; a channel reference or a link is not a person.
    #[test]
    fn the_ids_a_draft_tags_are_its_user_mentions_once_each() {
        assert_eq!(
            mention_ids("thanks <@U2>, <@U3|carol> and <@U2> again"),
            vec!["U2", "U3"],
            "a labelled mention is its id, and a repeated tag is one person",
        );
        assert!(
            mention_ids("<#C1> <https://example.com|the doc> <@> <@123>").is_empty(),
            "a channel, a link, an empty mention and a non-user token tag nobody",
        );
    }

    /// A quoted parent reads as prose: a mention is the name the tag lookup
    /// resolved (its id when it could not), a link its label or address, and
    /// bold loses its stars. Literal asterisks stay literal.
    #[test]
    fn a_quoted_excerpt_flattens_its_slack_markup() {
        let names = HashMap::from([("U2".to_owned(), "bob".to_owned())]);
        assert_eq!(
            flatten_mrkdwn("<@U2> and <@U2|carol> and <@U9>", &names, 80),
            "@bob and @bob and U9",
            "a named mention draws its name; an unnamed one keeps its id",
        );
        assert_eq!(
            flatten_mrkdwn(
                "<https://example.com/docs|the docs> and <https://example.com>",
                &names,
                80,
            ),
            "the docs and https://example.com",
            "a titled link draws its label, and a bare link its address",
        );
        assert_eq!(
            flatten_mrkdwn("<https://example.com|>", &names, 80),
            "https://example.com",
            "an empty label draws the address",
        );
        assert_eq!(
            flatten_mrkdwn("*<https://example.com|the docs>* and *green*", &names, 80),
            "the docs and green",
            "a link inside bold flattens too, and bold loses its stars",
        );
        assert_eq!(
            flatten_mrkdwn("src/*.rs and tests/*.rs", &names, 80),
            "src/*.rs and tests/*.rs",
            "a glob keeps its stars rather than reading as bold",
        );
        assert_eq!(
            flatten_mrkdwn("2 * 3 * 4 and **bold**", &names, 80),
            "2 * 3 * 4 and **bold**",
            "a spaced star and a doubled marker are literals, not bold",
        );
        assert_eq!(
            flatten_mrkdwn("a < b, and <#C1|general> with <!here>", &names, 80),
            "a < b, and <#C1|general> with <!here>",
            "a channel reference, a broadcast and a literal bracket keep their own text",
        );
        assert_eq!(
            flatten_mrkdwn("<!here|*x*>", &names, 80),
            "<!here|*x*>",
            "a labelled broadcast is left whole, markup and all",
        );
        assert_eq!(
            flatten_mrkdwn("<@|broken> and <@123>", &names, 80),
            "<@|broken> and <@123>",
            "an unrecognised mention keeps its brackets",
        );
    }

    /// The bound counts characters on the flattened text, so a long parent is
    /// cut as prose at a word boundary and never mid-glyph.
    #[test]
    fn an_excerpt_is_bounded_after_flattening() {
        let names = HashMap::from([("U2".to_owned(), "bob".to_owned())]);
        let parent = "*<https://example.com|the staging deploy>* is <@U2> and every check is \
                      green while the p99 is still high and the canary holds at one percent";
        let flat = flatten_mrkdwn(parent, &names, 80);
        let excerpt = one_line_excerpt(&flat, 80);
        assert!(excerpt.ends_with("..."), "the line is cut: {excerpt:?}");
        assert!(excerpt.chars().count() <= 83, "the bound holds after flattening: {excerpt:?}");
        assert!(
            !excerpt.contains('<') && !excerpt.contains('*'),
            "no markup survives the flattening: {excerpt:?}",
        );
        let kept = excerpt.strip_suffix("...").expect("the mark is there");
        assert!(
            flat.starts_with(kept) && !kept.ends_with(' '),
            "the cut is the flattened opening at a word boundary: {excerpt:?}",
        );

        // Glyphs count as characters, not bytes: a multibyte run is cut at
        // the same place a Latin one would be.
        let multibyte = format!("*{}*", "ééé ".repeat(30).trim_end());
        let flat = flatten_mrkdwn(&multibyte, &names, 80);
        let excerpt = one_line_excerpt(&flat, 80);
        assert!(excerpt.ends_with("..."), "the glyph run is cut: {excerpt:?}");
        assert!(
            excerpt.chars().count() <= 83,
            "the char bound holds on multibyte text: {excerpt:?}"
        );
        let kept = excerpt.strip_suffix("...").expect("the mark is there");
        assert!(
            flat.starts_with(kept) && !kept.ends_with(' '),
            "the cut lands on a word boundary in multibyte text: {excerpt:?}",
        );
        assert!(
            kept.chars().count() >= 76,
            "the cut keeps the character budget rather than a byte count: {excerpt:?}",
        );
        assert!(!excerpt.contains('*'), "the bold markers are gone: {excerpt:?}");
    }

    /// The early stop counts characters, not bytes: a multibyte span inside
    /// the budget still lets the prose after it through.
    #[test]
    fn the_early_stop_counts_characters_not_bytes() {
        let names: HashMap<String, String> = HashMap::new();
        let bold = format!("*{}* and more words", "é".repeat(50));
        assert!(
            flatten_mrkdwn(&bold, &names, 80).ends_with(" and more words"),
            "a multibyte bold span that fits the budget does not end the walk",
        );
        let link = format!("<https://example.com|{}> and more words", "é".repeat(50));
        assert!(
            flatten_mrkdwn(&link, &names, 80).ends_with(" and more words"),
            "a multibyte link label that fits the budget does not end the walk",
        );
    }

    /// The card gets one line: the parent's whitespace collapses, and a long
    /// parent stops at a word rather than mid-word.
    #[test]
    fn an_excerpt_is_one_line_cut_at_a_word_boundary() {
        assert_eq!(one_line_excerpt("the deploy\n is   green", 80), "the deploy is green");
        let long = "the canary is holding at 1% and every check is green but the p99 is still high";
        let cut = one_line_excerpt(long, 40);
        assert!(cut.ends_with("..."), "the cut is marked: {cut:?}");
        assert!(cut.chars().count() <= 43, "the cut keeps the bound: {cut:?}");
        let kept = cut.strip_suffix("...").expect("the mark is there");
        assert!(!kept.ends_with(' '), "no trailing space before the mark: {cut:?}");
        assert!(long.starts_with(kept), "the excerpt is the parent's opening words: {cut:?}");
        assert_eq!(
            one_line_excerpt("abcdefghij", 4),
            "abcd...",
            "a word with no boundary is cut at the bound",
        );
        assert_eq!(
            one_line_excerpt("one two three four five six", 20),
            "one two three four...",
            "the cut lands on the word boundary inside the bound",
        );
    }

    /// The first message `conversations.replies` returns for a thread's ts is
    /// the parent, which is what a draft's card names.
    #[tokio::test]
    async fn a_thread_parent_is_the_first_message_of_the_replies_read() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        fake.seed_replies(
            "C1",
            "100.0",
            vec![
                history_message("100.0", "U2", "the parent"),
                history_message("200.0", "U3", "a reply"),
            ],
        );
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;

        let parent = thread_parent(api.as_ref(), "C1", "100.0")
            .await
            .expect("the read lands")
            .expect("the thread has a parent");
        assert_eq!(parent.ts, "100.0", "the parent is the message the thread starts at");
        assert_eq!(parent.text, "the parent");
        assert_eq!(parent.user.as_deref(), Some("U2"), "the author id rides the parent");
        assert_eq!(
            *fake.replies_limits.lock().expect("lock"),
            vec![1],
            "the card needs the parent alone, so the read asks for one message",
        );
    }

    /// A failed thread read is surfaced rather than turned into a blank
    /// thread: the card names it "a thread", never an invented name.
    #[tokio::test]
    async fn a_thread_parent_read_that_fails_is_not_a_guess() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        fake.rate_limit_replies_at(0);
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;
        assert!(
            thread_parent(api.as_ref(), "C1", "100.0").await.is_err(),
            "the caller decides what a failed read draws; the connector does not guess",
        );
    }

    /// A name the host already resolved costs no call.
    #[tokio::test]
    async fn a_cached_user_name_answers_without_a_lookup() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        fake.set_user_name("acme", "U2", "bob");
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;

        let name = user_display_name(fake.as_ref(), api.as_ref(), "acme", "U2").await;
        assert_eq!(name.as_deref(), Some("bob"));
        assert_eq!(*fake.user_info_calls.lock().expect("lock"), 0, "the cache is the point");
        assert_eq!(
            *fake.cache_workspaces.lock().expect("lock"),
            vec!["acme".to_owned(), "acme".to_owned()],
            "the seeding write and the read both name the draft's workspace",
        );
    }

    /// A miss asks once, hands the name back, and remembers it.
    #[tokio::test]
    async fn a_user_lookup_names_the_person_and_is_remembered() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        fake.seed_user_name("U2", "bob");
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;

        assert_eq!(
            user_display_name(fake.as_ref(), api.as_ref(), "acme", "U2").await.as_deref(),
            Some("bob"),
        );
        assert_eq!(
            user_display_name(fake.as_ref(), api.as_ref(), "acme", "U2").await.as_deref(),
            Some("bob"),
        );
        assert_eq!(*fake.user_info_calls.lock().expect("lock"), 1, "a resolved name is cached");
    }

    /// A failed lookup leaves the person unnamed and remembers nothing: the
    /// card draws the id, and the next draft asks again rather than pinning
    /// the miss forever.
    #[tokio::test]
    async fn a_failed_user_lookup_is_none_and_remembers_nothing() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        fake.fail_user_info_transiently();
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;

        assert_eq!(user_display_name(fake.as_ref(), api.as_ref(), "acme", "U2").await, None);
        assert!(
            fake.resolved_names().is_empty(),
            "a failure is not a name to remember: {:?}",
            fake.resolved_names(),
        );
    }

    /// Slack answering `user_not_found` is settled: the miss is remembered as
    /// no name, so a second draft does not spend another call on it.
    #[tokio::test]
    async fn a_settled_miss_is_remembered_as_no_name() {
        let fake = Arc::new(FakeHost::default());
        FakeHost::set_api_self(&fake);
        let api = Arc::clone(&fake) as Arc<dyn SlackApi>;

        assert_eq!(user_display_name(fake.as_ref(), api.as_ref(), "acme", "U404").await, None);
        assert_eq!(user_display_name(fake.as_ref(), api.as_ref(), "acme", "U404").await, None);
        assert_eq!(*fake.user_info_calls.lock().expect("lock"), 1, "a settled miss costs one call");
        assert_eq!(
            fake.resolved_names().get("U404").map(String::as_str),
            Some(""),
            "the empty name is the record that the miss is settled",
        );
    }

    /// The decoder keeps the repeat: Slack returns the parent on every page
    /// of `conversations.replies`, and deduping is the sweep's job.
    #[test]
    fn a_replies_page_keeps_the_repeated_parent_for_the_caller_to_dedupe() {
        let body = r#"{
          "ok": true,
          "messages": [
            {"ts":"100.0","user":"U9","text":"root"},
            {"ts":"200.1","user":"U8","text":"reply one"},
            {"ts":"100.0","user":"U9","text":"root"},
            {"ts":"300.2","user":"U8","text":"reply two"}
          ]
        }"#;
        let page = decode_message_page("conversations.replies", body).expect("decodes");
        assert_eq!(page.messages.len(), 4, "the decoder does not dedupe");
        assert_eq!(
            page.messages.iter().filter(|m| m.ts == "100.0").count(),
            2,
            "the parent arrives twice and the caller is the one that folds it",
        );
    }

    /// Measured against live Slack 2026-09-23 and captured in the two
    /// fixtures: a parent carries `thread_ts` equal to its own `ts`,
    /// `reply_count > 0` and `latest_reply`; a reply carries
    /// `parent_user_id` and a `thread_ts` that differs from its `ts`. So a
    /// present `thread_ts` does NOT mean "this is a reply".
    #[test]
    fn a_parent_carries_its_latest_reply_and_a_reply_does_not() {
        let page = decode_message_page(
            "conversations.history",
            include_str!("../fixtures/slack_parent.json"),
        )
        .expect("the captured parent decodes");
        let parent = &page.messages[0];
        assert_eq!(
            parent.latest_reply.as_deref(),
            Some("1790186555.957249"),
            "a parent names its newest reply",
        );
        assert_eq!(parent.parent_user_id, None, "a parent carries no parent_user_id");
        assert_eq!(
            parent.thread_ts.as_deref(),
            Some(parent.ts.as_str()),
            "a real parent's thread_ts is its own ts, never None",
        );
        assert_eq!(parent.reply_count, 2, "and it reports how many replies it has");

        let replies = decode_message_page(
            "conversations.replies",
            include_str!("../fixtures/slack_reply.json"),
        )
        .expect("the captured thread decodes");
        let reply = &replies.messages[1];
        assert!(reply.parent_user_id.is_some(), "parent_user_id is what marks a reply");
        assert_eq!(reply.latest_reply, None, "a reply names no newest reply");
        assert_ne!(
            reply.thread_ts.as_deref(),
            Some(reply.ts.as_str()),
            "a reply's thread_ts is the parent's, not its own",
        );
    }

    /// Drives both ports from seeded responses, so a sweep runs with no
    /// workspace and no network. One type implements both traits because
    /// the sweep's two arguments are the same double in every test.
    #[derive(Default)]
    struct FakeHost {
        subscriptions: std::sync::Mutex<Vec<SlackSubscription>>,
        user_id_slot: std::sync::Mutex<Option<String>>,
        /// The fake's own API trait object, set post-construction so the
        /// pump's `client()` drives the seeded double instead of a live
        /// client.
        api_self: std::sync::Mutex<Option<Arc<dyn SlackApi>>>,
        rate_limited: Option<Duration>,
        conversations: std::sync::Mutex<Vec<SlackConversation>>,
        history: std::sync::Mutex<HashMap<String, Vec<Vec<SlackHistoryMessage>>>>,
        /// Seeded failures: channel -> the error history returns.
        history_errors: std::sync::Mutex<HashMap<String, SlackError>>,
        /// Per channel, the next this many `conversations.history` calls
        /// answer 429 with a 1 s Retry-After. Keyed per channel so each
        /// pump's episode does not depend on how the two interleave.
        history_rate_limited_calls: std::sync::Mutex<HashMap<String, usize>>,
        /// The next this many `search.messages` calls answer 429 with a 1 s
        /// Retry-After, so the mention sweep's episode is driven too.
        search_rate_limited_calls: std::sync::Mutex<usize>,
        /// Display names the fake's `users.info` answers with, and how many
        /// times it was asked - a lookup is a call.
        user_names: std::sync::Mutex<HashMap<String, String>>,
        user_info_calls: std::sync::Mutex<usize>,
        /// How many `auth.test` calls the sweep made, so a test can assert
        /// the identity is asked once rather than once per message.
        auth_test_calls: std::sync::Mutex<usize>,
        /// Set to make `auth.test` fail with a transient error, the shape a
        /// later sweep sees when the call blips.
        auth_test_transient: std::sync::Mutex<bool>,
        /// Set to make `auth.test` answer 429 instead.
        auth_test_rate_limited: std::sync::Mutex<Option<Duration>>,
        /// Set to make `users.info` answer 429 instead.
        user_info_rate_limited: std::sync::Mutex<Option<Duration>>,
        /// Set to make `users.info` fail with a transient error instead of
        /// settling anything about the user.
        user_info_transient: std::sync::Mutex<bool>,
        /// How many `conversations.replies` calls were made, so a test can
        /// assert a thread that has not moved costs none.
        replies_calls: std::sync::Mutex<usize>,
        /// The 0-based `conversations.replies` call that answers 429.
        replies_rate_limit_at: std::sync::Mutex<Option<usize>>,
        /// The `limit` each `conversations.replies` call carried.
        replies_limits: std::sync::Mutex<Vec<u32>>,
        /// The workspace every user-name cache call carried, so a test can
        /// prove the cache is keyed per workspace.
        cache_workspaces: std::sync::Mutex<Vec<String>>,
        /// How many `conversations.history` calls were made, so a test can
        /// assert which clock read a conversation and how often.
        history_calls: std::sync::Mutex<usize>,
        /// What the host has already resolved, the cache the port keeps.
        resolved_names: std::sync::Mutex<HashMap<String, String>>,
        /// Authors whose failed lookup has already been reported.
        reported_failures: std::sync::Mutex<HashSet<String>>,
        replies: std::sync::Mutex<HashMap<String, Vec<Vec<SlackHistoryMessage>>>>,
        watermarks: std::sync::Mutex<HashMap<String, String>>,
        connected: std::sync::Mutex<Option<bool>>,
        delivered: std::sync::Mutex<Vec<SlackMessage>>,
        /// The owner of each successful delivery, index-aligned with
        /// `delivered`.
        delivered_owners: std::sync::Mutex<Vec<SlackThreadOwner>>,
        /// Each batch handed over, in delivery order, so a test can see how
        /// the sweep grouped a conversation's news.
        batches: std::sync::Mutex<Vec<Vec<SlackMessage>>>,
        search: std::sync::Mutex<Vec<Vec<SlackSearchMatch>>>,
        search_calls: std::sync::Mutex<usize>,
        auto_subscribed: std::sync::Mutex<Vec<String>>,
        deliver_failures: std::sync::Mutex<std::collections::HashSet<usize>>,
        deliver_attempts: std::sync::Mutex<usize>,
        /// Followed threads keyed `workspace/conversation/parent`.
        threads: std::sync::Mutex<HashMap<String, SlackThreadRecord>>,
        /// Whole-read stamps, first-walk marks and edit watermarks, keyed the
        /// same way.
        thread_full_reads: std::sync::Mutex<HashMap<String, std::time::Instant>>,
        thread_first_walks: std::sync::Mutex<HashSet<String>>,
        thread_edit_watermarks: std::sync::Mutex<HashMap<String, String>>,
        /// The `oldest` each `conversations.replies` call carried, so a test
        /// can tell a whole read from the cheap tick.
        replies_oldest: std::sync::Mutex<Vec<Option<String>>>,
        /// The outbound ledger, keyed `workspace/conversation/ts`.
        own_posts: std::sync::Mutex<HashSet<String>>,
        /// Conversations with a post in flight, keyed
        /// `workspace/address`.
        inflight: std::sync::Mutex<HashSet<String>>,
    }

    fn conversation_for(id: &str) -> SlackConversation {
        let is_im = id.starts_with('D');
        SlackConversation {
            id: id.to_owned(),
            name: (!is_im).then(|| id.to_lowercase()),
            is_channel: !is_im,
            is_private: false,
            is_im,
            is_mpim: false,
            is_archived: false,
            user: is_im.then(|| "U9".to_owned()),
            purpose: None,
            topic: None,
        }
    }

    impl FakeHost {
        fn with_subscriptions(subscriptions: Vec<SlackSubscription>) -> Self {
            Self {
                subscriptions: std::sync::Mutex::new(subscriptions),
                user_id_slot: std::sync::Mutex::new(Some("U1".to_owned())),
                ..Self::default()
            }
        }

        /// Expose the fake's own API impl for the pump's `client()`. Must
        /// be called on the Arc before a pump test runs.
        fn set_api_self(me: &Arc<Self>) {
            *me.api_self.lock().expect("lock") = Some(Arc::clone(me) as Arc<dyn SlackApi>);
        }

        fn seed_history(&self, channel: &str, messages: Vec<SlackHistoryMessage>) {
            self.seed_history_pages(channel, vec![messages]);
        }

        /// Seed history WITHOUT registering the conversation in the
        /// membership list, the shape of a channel the token's user is
        /// not a member of.
        fn seed_history_unlisted(&self, channel: &str, messages: Vec<SlackHistoryMessage>) {
            self.history.lock().expect("lock").insert(channel.to_owned(), vec![messages]);
        }

        /// Seed several pages. The fake serves them in order, handing back
        /// the next index as the cursor, so a paging walk is exercised.
        fn seed_history_pages(&self, channel: &str, pages: Vec<Vec<SlackHistoryMessage>>) {
            {
                let mut conversations = self.conversations.lock().expect("lock");
                if !conversations.iter().any(|c| c.id == channel) {
                    conversations.push(conversation_for(channel));
                }
            }
            self.history.lock().expect("lock").insert(channel.to_owned(), pages);
        }

        fn seed_replies(&self, channel: &str, parent: &str, messages: Vec<SlackHistoryMessage>) {
            self.seed_replies_pages(channel, parent, vec![messages]);
        }

        /// Seed several reply pages. The fake serves them in order,
        /// handing back the next index as the cursor, and repeats the parent
        /// on each the way Slack does.
        fn seed_replies_pages(
            &self,
            channel: &str,
            parent: &str,
            pages: Vec<Vec<SlackHistoryMessage>>,
        ) {
            self.replies.lock().expect("lock").insert(format!("{channel}/{parent}"), pages);
        }

        /// Make history for `channel` fail with a seeded error.
        fn fail_history_with(&self, channel: &str, error: SlackError) {
            self.history_errors.lock().expect("lock").insert(channel.to_owned(), error);
        }

        /// Resolve the user id late, or leave it unresolved with `None` -
        /// the shape of a boot whose auth probe has not come back yet.
        fn set_user_id(&self, id: Option<String>) {
            *self.user_id_slot.lock().expect("lock") = id;
        }

        fn fail_with_rate_limit(&mut self, retry_after: Duration) {
            self.rate_limited = Some(retry_after);
        }

        /// Throttle the channel's next `calls` history reads, then answer
        /// normally.
        fn rate_limit_history_calls(&self, channel: &str, calls: usize) {
            self.history_rate_limited_calls.lock().expect("lock").insert(channel.to_owned(), calls);
        }

        /// Throttle the next `calls` mention searches, then answer normally.
        fn rate_limit_search_calls(&self, calls: usize) {
            *self.search_rate_limited_calls.lock().expect("lock") = calls;
        }

        /// Make the nth (0-based) `conversations.replies` call answer 429.
        fn rate_limit_replies_at(&self, call: usize) {
            *self.replies_rate_limit_at.lock().expect("lock") = Some(call);
        }

        fn delivered(&self) -> Vec<SlackMessage> {
            self.delivered.lock().expect("lock").clone()
        }

        fn batches(&self) -> Vec<Vec<SlackMessage>> {
            self.batches.lock().expect("lock").clone()
        }

        fn seed_user_name(&self, user: &str, name: &str) {
            self.user_names.lock().expect("lock").insert(user.to_owned(), name.to_owned());
        }

        /// Put a message in the outbound ledger: forge posted it.
        fn record_own_post(&self, workspace: &str, conversation: &str, ts: &str) {
            self.own_posts.lock().expect("lock").insert(format!("{workspace}/{conversation}/{ts}"));
        }

        /// Mark a post in flight, addressed as a post addresses it.
        fn set_post_in_flight(&self, workspace: &str, address: &str, in_flight: bool) {
            let key = format!("{workspace}/{address}");
            let mut marks = self.inflight.lock().expect("lock");
            if in_flight {
                marks.insert(key);
            } else {
                marks.remove(&key);
            }
        }

        fn rate_limit_user_info(&self, retry_after: Duration) {
            *self.user_info_rate_limited.lock().expect("lock") = Some(retry_after);
        }

        fn fail_user_info_transiently(&self) {
            *self.user_info_transient.lock().expect("lock") = true;
        }

        fn resolved_names(&self) -> HashMap<String, String> {
            self.resolved_names.lock().expect("lock").clone()
        }

        fn replies_calls(&self) -> usize {
            *self.replies_calls.lock().expect("lock")
        }

        /// The `oldest` each `conversations.replies` call carried, in call
        /// order: `None` is a whole read, `Some` the cheap tick.
        fn replies_oldest(&self) -> Vec<Option<String>> {
            self.replies_oldest.lock().expect("lock").clone()
        }

        /// Make a thread's last whole read look `age` old, so the next sweep
        /// is due for one.
        fn age_thread_full_read(
            &self,
            workspace: &str,
            conversation: &str,
            parent: &str,
            age: Duration,
        ) {
            let at =
                std::time::Instant::now().checked_sub(age).expect("the test clock is past the age");
            self.thread_full_reads
                .lock()
                .expect("lock")
                .insert(format!("{workspace}/{conversation}/{parent}"), at);
        }

        /// Drop every process-lifetime clock and keep every durable record:
        /// the state a restarted process starts from.
        fn restart(&self) {
            self.thread_full_reads.lock().expect("lock").clear();
            self.thread_first_walks.lock().expect("lock").clear();
            self.thread_edit_watermarks.lock().expect("lock").clear();
        }

        fn history_calls(&self) -> usize {
            *self.history_calls.lock().expect("lock")
        }

        fn user_info_calls(&self) -> usize {
            *self.user_info_calls.lock().expect("lock")
        }

        fn auth_test_calls(&self) -> usize {
            *self.auth_test_calls.lock().expect("lock")
        }

        fn fail_auth_test_transiently(&self) {
            *self.auth_test_transient.lock().expect("lock") = true;
        }

        fn rate_limit_auth_test(&self, retry_after: Duration) {
            *self.auth_test_rate_limited.lock().expect("lock") = Some(retry_after);
        }

        fn connected(&self) -> Option<bool> {
            *self.connected.lock().expect("lock")
        }

        fn seed_search(&self, matches: Vec<SlackSearchMatch>) {
            self.seed_search_pages(vec![matches]);
        }

        /// Seed several pages. The fake serves them in order, handing back
        /// the next index as the cursor, so a paging walk is exercised.
        fn seed_search_pages(&self, pages: Vec<Vec<SlackSearchMatch>>) {
            *self.search.lock().expect("lock") = pages;
        }

        /// How many times `method` was called, for the tests that assert a
        /// sweep did or did not spend a call.
        fn count_for(&self, method: &str) -> usize {
            match method {
                "search.messages" => *self.search_calls.lock().expect("lock"),
                other => panic!("the fake does not count {other}"),
            }
        }

        fn auto_subscribed(&self) -> Vec<String> {
            self.auto_subscribed.lock().expect("lock").clone()
        }

        /// Make the Nth delivery attempt fail, so a test can assert how
        /// the sweep treats a partial failure.
        fn fail_delivery_at(&self, index: usize) {
            self.deliver_failures.lock().expect("lock").insert(index);
        }

        fn delivered_owners(&self) -> Vec<SlackThreadOwner> {
            self.delivered_owners.lock().expect("lock").clone()
        }

        fn thread_cursor(
            &self,
            workspace: &str,
            conversation: &str,
            parent: &str,
        ) -> Option<String> {
            self.threads
                .lock()
                .expect("lock")
                .get(&format!("{workspace}/{conversation}/{parent}"))
                .map(|record| record.cursor.clone())
        }
    }

    impl SlackHost for FakeHost {
        fn client(
            &self,
            _workspace: &str,
            _timeout: Duration,
        ) -> Result<Arc<dyn SlackApi>, String> {
            let exposed = self.api_self.lock().expect("lock").clone();
            exposed.ok_or("the fake exposes no API; call set_api_self first".to_owned())
        }

        fn user_id(&self, _workspace: &str) -> Option<String> {
            self.user_id_slot.lock().expect("lock").clone()
        }

        fn user_name(&self, workspace: &str, user: &str) -> Option<String> {
            self.cache_workspaces.lock().expect("lock").push(workspace.to_owned());
            self.resolved_names.lock().expect("lock").get(user).cloned()
        }

        fn set_user_name(&self, workspace: &str, user: &str, name: &str) {
            self.cache_workspaces.lock().expect("lock").push(workspace.to_owned());
            self.resolved_names.lock().expect("lock").insert(user.to_owned(), name.to_owned());
        }

        fn first_author_failure(&self, _workspace: &str, user: &str) -> bool {
            self.reported_failures.lock().expect("lock").insert(user.to_owned())
        }

        fn first_draft_user_failure(&self, _workspace: &str, user: &str) -> bool {
            self.reported_failures.lock().expect("lock").insert(user.to_owned())
        }

        fn subscriptions(&self, _workspace: &str) -> Vec<SlackSubscription> {
            self.subscriptions.lock().expect("lock").clone()
        }

        fn watermark(&self, workspace: &str, conversation: &str) -> Result<Option<String>, String> {
            Ok(self
                .watermarks
                .lock()
                .expect("lock")
                .get(&format!("{workspace}/{conversation}"))
                .cloned())
        }

        fn set_watermark(&self, workspace: &str, conversation: &str, ts: &str) {
            self.watermarks
                .lock()
                .expect("lock")
                .insert(format!("{workspace}/{conversation}"), ts.to_owned());
        }

        fn set_connected(&self, _workspace: &str, connected: bool) {
            *self.connected.lock().expect("lock") = Some(connected);
        }

        /// Deliberately without the sweep's unnamed-only guard: the double
        /// records what it is told, so a test asserting the guard is
        /// testing the sweep's filter rather than the fake's copy of it.
        fn name_conversation(&self, workspace: &str, conversation: &str, name: &str) {
            for sub in self.subscriptions.lock().expect("lock").iter_mut() {
                if sub.workspace != workspace {
                    continue;
                }
                if let SlackSubscriptionTarget::Conversation { id, name: stored, .. } =
                    &mut sub.target
                    && id.as_str() == conversation
                {
                    *stored = Some(name.to_owned());
                }
            }
        }

        fn deliver(&self, subscription: &SlackSubscription, messages: &[SlackMessage]) -> bool {
            // One attempt per batch, not per message: the whole slice lands
            // or none of it does, which is what `fail_delivery_at` indexes.
            let attempt = {
                let mut attempts = self.deliver_attempts.lock().expect("lock");
                *attempts += 1;
                *attempts - 1
            };
            if self.deliver_failures.lock().expect("lock").contains(&attempt) {
                return false;
            }
            let owner = SlackThreadOwner {
                project: subscription.project.clone(),
                team_role: subscription.team_role.clone(),
            };
            self.batches.lock().expect("lock").push(messages.to_vec());
            for message in messages {
                self.delivered.lock().expect("lock").push(message.clone());
                self.delivered_owners.lock().expect("lock").push(owner.clone());
            }
            true
        }

        fn followed_threads(
            &self,
            workspace: &str,
            conversation: &str,
        ) -> Vec<SlackFollowedThread> {
            let prefix = format!("{workspace}/{conversation}/");
            self.threads
                .lock()
                .expect("lock")
                .iter()
                .filter(|(key, _)| key.starts_with(&prefix))
                .map(|(key, record)| SlackFollowedThread {
                    parent_ts: key
                        .rsplit('/')
                        .next()
                        .expect("the parent is the last part")
                        .to_owned(),
                    owners: record.owners.clone(),
                    participating: record.participating,
                })
                .collect()
        }

        fn thread_watermark(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
        ) -> Result<Option<String>, String> {
            Ok(self
                .threads
                .lock()
                .expect("lock")
                .get(&format!("{workspace}/{conversation}/{parent_ts}"))
                .map(|record| record.cursor.clone()))
        }

        fn set_thread_watermark(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
            ts: &str,
        ) {
            let mut threads = self.threads.lock().expect("lock");
            let record = threads
                .entry(format!("{workspace}/{conversation}/{parent_ts}"))
                .or_insert_with(|| SlackThreadRecord {
                    cursor: String::new(),
                    edit_watermark: None,
                    owners: Vec::new(),
                    participating: false,
                });
            record.cursor = ts.to_owned();
        }

        fn mark_thread_participating(&self, workspace: &str, conversation: &str, parent_ts: &str) {
            let mut threads = self.threads.lock().expect("lock");
            if let Some(record) =
                threads.get_mut(&format!("{workspace}/{conversation}/{parent_ts}"))
            {
                record.participating = true;
            }
        }

        fn thread_full_read_at(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
        ) -> Option<std::time::Instant> {
            self.thread_full_reads
                .lock()
                .expect("lock")
                .get(&format!("{workspace}/{conversation}/{parent_ts}"))
                .copied()
        }

        fn mark_thread_full_read(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
            at: std::time::Instant,
        ) {
            self.thread_full_reads
                .lock()
                .expect("lock")
                .insert(format!("{workspace}/{conversation}/{parent_ts}"), at);
        }

        fn thread_first_walk(&self, workspace: &str, conversation: &str, parent_ts: &str) -> bool {
            self.thread_first_walks
                .lock()
                .expect("lock")
                .contains(&format!("{workspace}/{conversation}/{parent_ts}"))
        }

        fn clear_thread_first_walk(&self, workspace: &str, conversation: &str, parent_ts: &str) {
            self.thread_first_walks
                .lock()
                .expect("lock")
                .remove(&format!("{workspace}/{conversation}/{parent_ts}"));
        }

        fn thread_edit_watermark(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
        ) -> Option<String> {
            let key = format!("{workspace}/{conversation}/{parent_ts}");
            if let Some(mark) = self.thread_edit_watermarks.lock().expect("lock").get(&key).cloned()
            {
                return Some(mark);
            }
            // The row is where a real host keeps it, so a restart reads it
            // back instead of judging the whole thread from the beginning.
            // A row with no stamp is approximated by its cursor, the same
            // fallback the real host applies.
            self.threads.lock().expect("lock").get(&key).and_then(|record| {
                record.edit_watermark.clone().or_else(|| Some(record.cursor.clone()))
            })
        }

        fn set_thread_edit_watermark(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
            ts: &str,
        ) {
            let key = format!("{workspace}/{conversation}/{parent_ts}");
            self.thread_edit_watermarks.lock().expect("lock").insert(key.clone(), ts.to_owned());
            if let Some(record) = self.threads.lock().expect("lock").get_mut(&key) {
                record.edit_watermark = Some(ts.to_owned());
            }
        }

        fn follow_thread(
            &self,
            workspace: &str,
            conversation: &str,
            parent_ts: &str,
            owner: SlackThreadOwner,
            since: &str,
        ) {
            let key = format!("{workspace}/{conversation}/{parent_ts}");
            let created = {
                let mut threads = self.threads.lock().expect("lock");
                let entry = threads.entry(key.clone());
                let created = matches!(&entry, std::collections::hash_map::Entry::Vacant(_));
                let record = entry.or_insert_with(|| {
                    // The real host starts a new thread at the caller's
                    // since, so the first replies walk reaches everything
                    // after the message that anchored it.
                    SlackThreadRecord {
                        cursor: since.to_owned(),
                        edit_watermark: Some(since.to_owned()),
                        owners: Vec::new(),
                        participating: false,
                    }
                });
                if !record.owners.contains(&owner) {
                    record.owners.push(owner);
                }
                created
            };
            if created {
                self.thread_first_walks.lock().expect("lock").insert(key.clone());
                self.thread_edit_watermarks.lock().expect("lock").insert(key, since.to_owned());
            }
        }

        fn auto_subscribe(&self, workspace: &str, message: &SlackMessage) -> bool {
            let already =
                self.subscriptions.lock().expect("lock").iter().any(|sub| match &sub.target {
                    SlackSubscriptionTarget::Conversation { id, .. } => id == &message.conversation,
                    SlackSubscriptionTarget::DirectMessages | SlackSubscriptionTarget::Mentions => {
                        false
                    }
                });
            if already {
                return false;
            }
            // Mirrors the real host: the new subscription's cursor starts
            // at the mention, so the channel's past is not swept.
            self.watermarks
                .lock()
                .expect("lock")
                .insert(format!("{}/{}", workspace, message.conversation), message.ts.clone());
            self.subscriptions.lock().expect("lock").push(SlackSubscription {
                id: uuid::Uuid::new_v4(),
                workspace: workspace.to_owned(),
                project: "forge".to_owned(),
                team_role: None,
                target: SlackSubscriptionTarget::Conversation {
                    id: message.conversation.clone(),
                    name: None,
                    mode: SlackWatchMode::All,
                },
                created_at: std::time::SystemTime::UNIX_EPOCH,
            });
            self.auto_subscribed.lock().expect("lock").push(message.conversation.clone());
            true
        }

        fn own_post(&self, workspace: &str, conversation: &str, ts: &str) -> bool {
            self.own_posts
                .lock()
                .expect("lock")
                .contains(&format!("{workspace}/{conversation}/{ts}"))
        }

        fn post_in_flight(&self, workspace: &str, conversation: &str) -> Option<Duration> {
            self.inflight
                .lock()
                .expect("lock")
                .contains(&format!("{workspace}/{conversation}"))
                .then(Duration::default)
        }
    }

    #[async_trait::async_trait]
    impl SlackApi for FakeHost {
        async fn auth_test(&self) -> Result<AuthTest, SlackError> {
            *self.auth_test_calls.lock().expect("lock") += 1;
            if let Some(retry_after) = *self.auth_test_rate_limited.lock().expect("lock") {
                return Err(SlackError::RateLimited {
                    method: "auth.test".to_owned(),
                    retry_after,
                });
            }
            if *self.auth_test_transient.lock().expect("lock") {
                return Err(SlackError::Transport {
                    method: "auth.test".to_owned(),
                    detail: "the socket is down".to_owned(),
                });
            }
            Ok(AuthTest {
                team: "Test".to_owned(),
                user: "tester".to_owned(),
                team_id: "T1".to_owned(),
                user_id: self.user_id_slot.lock().expect("lock").clone().unwrap_or_default(),
                url: "https://test.slack.com/".to_owned(),
            })
        }

        async fn list_conversations(&self) -> Result<Vec<SlackConversation>, SlackError> {
            if let Some(retry_after) = self.rate_limited {
                return Err(SlackError::RateLimited {
                    method: "users.conversations".to_owned(),
                    retry_after,
                });
            }
            Ok(self.conversations.lock().expect("lock").clone())
        }

        async fn history(
            &self,
            channel: &str,
            oldest: Option<&str>,
            _newest: Option<&str>,
            _limit: u32,
            cursor: Option<&str>,
        ) -> Result<MessagePage, SlackError> {
            *self.history_calls.lock().expect("lock") += 1;
            {
                let mut calls = self.history_rate_limited_calls.lock().expect("lock");
                if let Some(left) = calls.get_mut(channel)
                    && *left > 0
                {
                    *left -= 1;
                    return Err(SlackError::RateLimited {
                        method: "conversations.history".to_owned(),
                        retry_after: Duration::from_secs(1),
                    });
                }
            }
            if let Some(retry_after) = self.rate_limited {
                return Err(SlackError::RateLimited {
                    method: "conversations.history".to_owned(),
                    retry_after,
                });
            }
            if let Some(error) = self.history_errors.lock().expect("lock").get(channel) {
                return Err(error.clone());
            }
            let pages = self.history.lock().expect("lock");
            let Some(seeded) = pages.get(channel) else {
                return Ok(MessagePage { messages: Vec::new(), next_cursor: None });
            };
            let index = cursor.and_then(|cursor| cursor.parse::<usize>().ok()).unwrap_or(0);
            // `oldest` is honoured, the way Slack honours it, so that the
            // window read and the cursor read are distinguishable: a fake
            // that ignored it would let the window read be swapped for the
            // cursor read with every test still green.
            let messages = seeded.get(index).cloned().unwrap_or_default();
            let messages = match oldest {
                Some(oldest) => {
                    messages.into_iter().filter(|message| message.ts.as_str() > oldest).collect()
                }
                None => messages,
            };
            Ok(MessagePage {
                messages,
                next_cursor: (index + 1 < seeded.len()).then(|| (index + 1).to_string()),
            })
        }

        async fn replies(
            &self,
            channel: &str,
            ts: &str,
            oldest: Option<&str>,
            limit: u32,
            cursor: Option<&str>,
        ) -> Result<MessagePage, SlackError> {
            self.replies_limits.lock().expect("lock").push(limit);
            let call = {
                let mut calls = self.replies_calls.lock().expect("lock");
                let call = *calls;
                *calls += 1;
                call
            };
            if *self.replies_rate_limit_at.lock().expect("lock") == Some(call) {
                return Err(SlackError::RateLimited {
                    method: "conversations.replies".to_owned(),
                    retry_after: Duration::from_secs(5),
                });
            }
            self.replies_oldest.lock().expect("lock").push(oldest.map(str::to_owned));
            let pages = self.replies.lock().expect("lock");
            let Some(seeded) = pages.get(&format!("{channel}/{ts}")) else {
                return Ok(MessagePage { messages: Vec::new(), next_cursor: None });
            };
            let index = cursor.and_then(|cursor| cursor.parse::<usize>().ok()).unwrap_or(0);
            // `oldest` is honoured, so a test that asserts the walk reads a
            // thread's WHOLE reply set is pinning the argument it passes -
            // a fake that ignored it would keep passing either way.
            let messages = seeded.get(index).cloned().unwrap_or_default();
            let messages = match oldest {
                Some(oldest) => {
                    messages.into_iter().filter(|message| message.ts.as_str() > oldest).collect()
                }
                None => messages,
            };
            Ok(MessagePage {
                messages,
                next_cursor: (index + 1 < seeded.len()).then(|| (index + 1).to_string()),
            })
        }

        async fn post_message(
            &self,
            _channel: &str,
            _text: &str,
            _thread_ts: Option<&str>,
        ) -> Result<PostedMessage, SlackError> {
            Ok(PostedMessage { channel: None, ts: "1.0".to_owned() })
        }

        async fn update_message(
            &self,
            _channel: &str,
            _ts: &str,
            _text: &str,
        ) -> Result<(), SlackError> {
            Ok(())
        }

        async fn delete_message(&self, _channel: &str, _ts: &str) -> Result<(), SlackError> {
            Ok(())
        }

        async fn set_reaction(
            &self,
            _channel: &str,
            _ts: &str,
            _name: &str,
            _add: bool,
        ) -> Result<(), SlackError> {
            Ok(())
        }

        async fn get_bytes(&self, _url: &str) -> Result<Vec<u8>, SlackError> {
            Ok(Vec::new())
        }

        async fn post_bytes(&self, _url: &str, _body: Vec<u8>) -> Result<(), SlackError> {
            Ok(())
        }

        async fn file_info(&self, _id: &str) -> Result<SlackFile, SlackError> {
            Ok(SlackFile {
                id: String::new(),
                name: String::new(),
                url_private: String::new(),
                shares: SlackFileShares::default(),
            })
        }

        async fn get_upload_url(
            &self,
            _name: &str,
            _length: usize,
        ) -> Result<(String, String), SlackError> {
            Ok((String::new(), String::new()))
        }

        async fn complete_upload(
            &self,
            _file_id: &str,
            _channel: &str,
            _thread_ts: Option<&str>,
        ) -> Result<Vec<SlackFile>, SlackError> {
            Ok(Vec::new())
        }

        async fn search_messages(
            &self,
            query: &str,
            _count: u32,
            cursor: Option<&str>,
        ) -> Result<SearchPage, SlackError> {
            *self.search_calls.lock().expect("lock") += 1;
            {
                let mut calls = self.search_rate_limited_calls.lock().expect("lock");
                if *calls > 0 {
                    *calls -= 1;
                    return Err(SlackError::RateLimited {
                        method: "search.messages".to_owned(),
                        retry_after: Duration::from_secs(1),
                    });
                }
            }
            let seeded = self.search.lock().expect("lock");
            let index = cursor.and_then(|cursor| cursor.parse::<usize>().ok()).unwrap_or(0);
            let _ = query;
            let page = seeded.get(index).cloned().unwrap_or_default();
            Ok(SearchPage {
                matches: page,
                next_cursor: (index + 1 < seeded.len()).then(|| (index + 1).to_string()),
            })
        }

        async fn user_info(&self, user: &str) -> Result<SlackUser, SlackError> {
            *self.user_info_calls.lock().expect("lock") += 1;
            if let Some(retry_after) = *self.user_info_rate_limited.lock().expect("lock") {
                return Err(SlackError::RateLimited {
                    method: "users.info".to_owned(),
                    retry_after,
                });
            }
            if *self.user_info_transient.lock().expect("lock") {
                return Err(SlackError::Transport {
                    method: "users.info".to_owned(),
                    detail: "connection reset".to_owned(),
                });
            }
            let name = self.user_names.lock().expect("lock").get(user).cloned();
            let Some(name) = name else {
                return Err(SlackError::Api {
                    method: "users.info".to_owned(),
                    error: "user_not_found".to_owned(),
                    needed: None,
                });
            };
            Ok(SlackUser {
                id: user.to_owned(),
                name,
                real_name: None,
                tz: None,
                deleted: false,
                profile: None,
            })
        }

        async fn list_users(&self) -> Result<Vec<SlackUser>, SlackError> {
            Ok(Vec::new())
        }

        async fn pins(&self, _channel: &str) -> Result<Vec<SlackPin>, SlackError> {
            Ok(Vec::new())
        }

        async fn bookmarks(&self, _channel: &str) -> Result<Vec<SlackBookmark>, SlackError> {
            Ok(Vec::new())
        }
    }

    #[test]
    fn a_search_always_asks_for_timestamp_order() {
        // The default is relevance, which ranked a 22-hour-old match above
        // a 2.6-hour-old one during the probe.
        let params = search_params("granite", 20);
        assert_eq!(
            params.iter().find(|(key, _)| *key == "sort").map(|(_, value)| value.as_str()),
            Some("timestamp"),
        );
    }

    /// A file-share mention carries its files in the hit: the ids are
    /// what slack__attachment fetches with, so delivery loses nothing on
    /// a no-text file share.
    #[test]
    fn a_search_hit_carries_its_files() {
        let body = r#"{"ok":true,"messages":{"matches":[
            {"ts":"100.1","text":"","channel":{"id":"C1"},"user":"U9",
             "files":[{"id":"F1","name":"notes.txt","url_private":"https://files/x"}]}]}}"#;
        let page = decode_search(body).expect("decodes");
        assert_eq!(page.matches.len(), 1);
        assert_eq!(page.matches[0].files.len(), 1, "the file rides on the hit");
        assert_eq!(page.matches[0].files[0].id, "F1");
    }

    #[test]
    fn a_search_decodes_matches_and_their_channel_names() {
        let body = r#"{"ok":true,"messages":{"total":2,"matches":[
            {"ts":"100.1","text":"hello","channel":{"id":"C1","name":"general"},"username":"ved"},
            {"ts":"200.2","text":"world","channel":{"id":"D1","is_im":true},"username":"other"}]}}"#;
        let page = decode_search(body).expect("decodes");
        let matches = &page.matches;
        assert_eq!(matches.len(), 2);
        assert_eq!(matches[0].conversation_id, "C1");
        assert_eq!(matches[0].conversation_name.as_deref(), Some("general"));
        assert_eq!(matches[0].username.as_deref(), Some("ved"));
        assert_eq!(matches[1].conversation_name, None, "a DM has no name");
        assert_eq!(page.next_cursor, None);
    }

    #[test]
    fn a_user_lookup_decodes_the_display_name() {
        let body = r#"{"ok":true,"user":{"id":"U1","name":"ved","real_name":"Vedhavyas S","tz":"Asia/Kolkata"}}"#;
        let user = decode_user(body).expect("decodes");
        assert_eq!(user.name, "ved");
        assert_eq!(user.tz.as_deref(), Some("Asia/Kolkata"));
    }

    /// The resolver matches on the display name as well as the handle and
    /// real name, and a deactivated member's row is kept (and flagged) so
    /// the caller can exclude it rather than not knowing it exists.
    #[test]
    fn a_users_page_decodes_a_members_display_name_and_deleted_flag() {
        let body = r#"{
          "ok": true,
          "members": [
            {"id":"U1","name":"ved","real_name":"Vedhavyas S",
             "profile":{"display_name":"ved"}},
            {"id":"U2","name":"gina","deleted":true,
             "profile":{"display_name":"Gina Abrams"}}
          ],
          "response_metadata": {"next_cursor": "next"}
        }"#;
        let page = decode_users_page(body).expect("decodes");
        assert_eq!(page.members.len(), 2, "both rows survive the decode");
        assert_eq!(
            page.members[0].profile.as_ref().and_then(|p| p.display_name.as_deref()),
            Some("ved"),
            "the display name is what people type and the handle is not",
        );
        assert!(!page.members[0].deleted);
        assert!(page.members[1].deleted, "a deactivated member is flagged, not dropped");
        assert_eq!(page.next_cursor.as_deref(), Some("next"), "the walk can continue");
    }

    /// A `users.list` source that never stops handing back a cursor, so the
    /// walk's page cap is reachable without HTTP.
    #[derive(Default)]
    struct EndlessUsers {
        pages: std::sync::atomic::AtomicUsize,
    }

    #[async_trait::async_trait]
    impl UsersPages for EndlessUsers {
        async fn users_page(&self, _cursor: Option<&str>) -> Result<UsersPage, SlackError> {
            self.pages.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            Ok(UsersPage {
                members: vec![SlackUser {
                    id: "U1".to_owned(),
                    name: "ved".to_owned(),
                    real_name: None,
                    tz: None,
                    deleted: false,
                    profile: None,
                }],
                next_cursor: Some("more".to_owned()),
            })
        }
    }

    /// The cap is what stops a cursor that never ends; the rows already read
    /// are the answer rather than an error.
    #[tokio::test]
    async fn a_user_walk_stops_at_its_page_cap_and_keeps_what_it_read() {
        let source = EndlessUsers::default();

        let users = walk_users(&source).await.expect("the cap ends the walk without failing");

        assert_eq!(users.len(), MAX_USER_PAGES, "every page read is kept");
        assert_eq!(
            source.pages.load(std::sync::atomic::Ordering::SeqCst),
            MAX_USER_PAGES,
            "the walk stopped at the cap instead of following the cursor forever",
        );
    }

    #[test]
    fn a_file_lookup_decodes_its_private_url() {
        let body = r#"{"ok":true,"file":{"id":"F1","name":"notes.txt","url_private":"https://files.slack.com/x"}}"#;
        let file = decode_file(body).expect("decodes");
        assert_eq!(file.name, "notes.txt");
        assert_eq!(file.url_private, "https://files.slack.com/x");
    }

    /// A posted file's message is named only on the file's shares, and the
    /// share's own conversation is the channel Slack posted into - not the
    /// string the upload was addressed with.
    #[test]
    fn a_files_shares_name_the_messages_it_was_posted_as() {
        let body = r#"{"ok":true,"file":{"id":"F1","name":"notes.txt",
            "shares":{
              "public":{"C1":[{"ts":"1700000000.000100"}]},
              "private":{"D2":[{"ts":"1700000000.000200"}]}}}}"#;
        let file = decode_file(body).expect("decodes");
        assert_eq!(
            shared_messages(&file),
            vec![
                ("C1".to_owned(), "1700000000.000100".to_owned()),
                ("D2".to_owned(), "1700000000.000200".to_owned()),
            ],
            "both visibility groups name their own conversation's message",
        );

        let unshared =
            decode_file(r#"{"ok":true,"file":{"id":"F2","shares":null}}"#).expect("decodes");
        assert!(
            shared_messages(&unshared).is_empty(),
            "an explicit null shares is no shares, not a decode failure",
        );
    }

    #[test]
    fn a_draft_at_the_limit_is_one_post_and_a_longer_one_is_split() {
        let exact = "a".repeat(POST_LIMIT);
        assert_eq!(split_for_post(&exact).len(), 1, "a draft that fits posts as one message");

        let over = "a".repeat(POST_LIMIT + 1);
        let parts = split_for_post(&over);
        assert!(parts.len() > 1, "one character over must be split, not truncated: {parts:?}");
        assert!(
            parts.iter().all(|part| part.chars().count() <= POST_LIMIT),
            "no part may reach the point Slack truncates at",
        );
        assert_eq!(
            parts.iter().map(|part| part.matches('a').count()).sum::<usize>(),
            POST_LIMIT + 1,
            "splitting must carry every character",
        );
    }

    /// What the one-shot server saw. The URL is on 127.0.0.1 with an
    /// ephemeral port, so the byte helpers need no Slack credential.
    #[derive(Default, Debug)]
    struct SeenRequest {
        authorization: Option<String>,
        body: Vec<u8>,
    }

    fn find_subslice(haystack: &[u8], needle: &[u8]) -> Option<usize> {
        haystack.windows(needle.len()).position(|window| window == needle)
    }

    /// Header NAMES are case-insensitive, values are not: lowercasing the
    /// whole head would turn `Bearer xoxp-test` into `bearer xoxp-test`
    /// and hide a real mismatch behind a scaffolding bug.
    fn content_length(head: &str) -> Option<usize> {
        head.lines()
            .filter_map(|line| line.split_once(':'))
            .find(|(name, _)| name.trim().eq_ignore_ascii_case("content-length"))
            .and_then(|(_, value)| value.trim().parse().ok())
    }

    fn header_value(head: &str, wanted: &str) -> Option<String> {
        head.lines()
            .filter_map(|line| line.split_once(':'))
            .find(|(name, _)| name.trim().eq_ignore_ascii_case(wanted))
            .map(|(_, value)| value.trim().to_owned())
    }

    /// Serve exactly one request and close, on a background thread, so a
    /// test can assert on what actually went over the wire. `std::net`
    /// rather than `tokio::net` because this workspace's tokio has no
    /// `net` feature and a test is not a reason to add one.
    fn spawn_one_shot_server(
        status: &'static str,
        response_body: &'static str,
    ) -> (String, std::thread::JoinHandle<SeenRequest>) {
        use std::io::{Read, Write};

        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind a port");
        let addr = listener.local_addr().expect("local addr");
        let handle = std::thread::spawn(move || {
            let (mut stream, _) = listener.accept().expect("accept one connection");
            let mut raw = Vec::new();
            let mut chunk = [0u8; 1024];
            loop {
                let read = stream.read(&mut chunk).expect("read the request");
                if read == 0 {
                    break;
                }
                raw.extend_from_slice(&chunk[..read]);
                if let Some(end) = find_subslice(&raw, b"\r\n\r\n") {
                    let head = String::from_utf8_lossy(&raw[..end]).to_string();
                    let declared = content_length(&head).unwrap_or(0);
                    if raw.len() >= end + 4 + declared {
                        break;
                    }
                }
            }

            let end = find_subslice(&raw, b"\r\n\r\n").expect("a complete request");
            let head = String::from_utf8_lossy(&raw[..end]).to_string();
            let authorization = header_value(&head, "authorization");
            let body = raw[end + 4..].to_vec();

            let response = format!(
                "HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{response_body}",
                response_body.len()
            );
            let _ = stream.write_all(response.as_bytes());
            let _ = stream.flush();
            SeenRequest { authorization, body }
        });
        (format!("http://{addr}/file"), handle)
    }

    #[tokio::test]
    async fn get_bytes_sends_the_bearer_header() {
        let (url, seen) = spawn_one_shot_server("200 OK", "body-bytes");
        let client = SlackClient::new(reqwest::Client::new(), "xoxp-test".to_owned());

        let got = client.get_bytes(&url).await.expect("fetch");
        assert_eq!(got, b"body-bytes");
        assert_eq!(
            seen.join().expect("server thread").authorization.as_deref(),
            Some("Bearer xoxp-test"),
            "a private file URL is a 403 without this header",
        );
    }

    #[tokio::test]
    async fn a_non_success_download_is_an_error_not_an_empty_body() {
        let (url, seen) = spawn_one_shot_server("403 Forbidden", "");
        let client = SlackClient::new(reqwest::Client::new(), "xoxp-test".to_owned());

        assert!(
            client.get_bytes(&url).await.is_err(),
            "a 403 must not be mistaken for a zero-byte file",
        );
        seen.join().expect("server thread");
    }

    #[tokio::test]
    async fn post_bytes_sends_the_body_unchanged_and_no_bearer() {
        let (url, seen) = spawn_one_shot_server("200 OK", "OK - 5");
        let client = SlackClient::new(reqwest::Client::new(), "xoxp-test".to_owned());

        client.post_bytes(&url, b"hello".to_vec()).await.expect("upload");
        let seen = seen.join().expect("server thread");
        assert_eq!(seen.body, b"hello");
        assert_eq!(
            seen.authorization, None,
            "the upload URL is pre-signed and must not carry the bearer",
        );
    }

    fn history_message(ts: &str, user: &str, text: &str) -> SlackHistoryMessage {
        SlackHistoryMessage {
            ts: ts.to_owned(),
            user: Some(user.to_owned()),
            text: text.to_owned(),
            thread_ts: None,
            reply_count: 0,
            bot_name: None,
            parent_user_id: None,
            latest_reply: None,
            edited: None,
            files: Vec::new(),
        }
    }

    /// One matched message as delivery sees it, with the fields a test
    /// cares about set.
    /// A parent as Slack sends one: `thread_ts` equal to its own `ts` and
    /// a non-zero reply count. A parent built as a plain message with a
    /// reply count is a shape Slack never sends, and one the sweep would
    /// never fetch replies for.
    fn parent_with_replies(ts: &str, replies: u32) -> SlackHistoryMessage {
        SlackHistoryMessage {
            thread_ts: Some(ts.to_owned()),
            reply_count: replies,
            ..history_message(ts, "U9", "trigger")
        }
    }

    /// A parent as Slack sends one once its thread has moved: the parent's
    /// shape plus `latest_reply`, which is what the window reads to know a
    /// thread moved without fetching it.
    fn parent_with_latest_reply(ts: &str, replies: u32, latest: &str) -> SlackHistoryMessage {
        SlackHistoryMessage {
            latest_reply: Some(latest.to_owned()),
            ..parent_with_replies(ts, replies)
        }
    }

    /// A reply as Slack sends one: `thread_ts` is the parent's, and it
    /// carries `parent_user_id`.
    fn reply(ts: &str, parent: &str, user: &str, text: &str) -> SlackHistoryMessage {
        SlackHistoryMessage {
            thread_ts: Some(parent.to_owned()),
            parent_user_id: Some("U9".to_owned()),
            ..history_message(ts, user, text)
        }
    }

    /// A sweep selects a parent by the shape Slack sends it in, which is
    /// what decides whose replies are fetched.
    #[test]
    fn a_parent_with_replies_is_selected_for_its_thread() {
        assert!(
            is_thread_parent(&parent_with_replies("1.0", 2)),
            "a real parent must be selected, or its replies are never fetched",
        );
        assert!(
            !is_thread_parent(&history_message("1.0", "U9", "plain")),
            "a message with no replies starts no thread",
        );
        assert!(
            !is_thread_parent(&reply("1.1", "1.0", "U8", "a reply")),
            "a reply is not a parent, however it is spelled",
        );
    }

    /// First sight baselines from the window it already fetched rather than
    /// walking the conversation's whole past: the cursor only needs the
    /// newest message seen, and a DM class cannot afford to page every DM's
    /// history once.
    #[tokio::test]
    async fn a_first_sight_dm_baselines_from_one_read() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.seed_history_pages(
            "D1",
            vec![
                vec![history_message("200.0", "U9", "newest")],
                vec![history_message("100.0", "U9", "older")],
            ],
        );

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");

        assert_eq!(outcome.delivered, 0, "a first sight delivers nothing");
        assert_eq!(host.history_calls(), 1, "one read, not the whole walk");
        assert_eq!(
            host.watermark("acme", "D1").expect("watermark"),
            Some("200.0".to_owned()),
            "and the cursor starts at the newest message seen",
        );
    }

    /// The DM class runs on its own clock rather than the conversation
    /// tick's: with a 1-second conversation tick and a 100-second DM one, a
    /// DM is read exactly once and then not again while the fast clock keeps
    /// ticking. Deleting the clock leaves this red.
    #[tokio::test]
    async fn the_dm_class_is_read_on_its_own_clock() {
        let host = Arc::new(FakeHost::with_subscriptions(vec![sub_dm("acme")]));
        FakeHost::set_api_self(&host);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history(
            "D1",
            // Newest first, and the page reaches back past the cursor: the
            // shape a DM has, where one read covers what is new.
            vec![history_message("200.0", "U9", "a dm"), history_message("050.0", "U9", "old")],
        );

        let (tx, rx) = oneshot::channel();
        let pump = tokio::spawn(run_workspace_pump(host.clone(), "acme".to_owned(), 1, 100, rx));
        for _ in 0..60 {
            tokio::time::sleep(Duration::from_millis(50)).await;
            if !host.delivered().is_empty() {
                break;
            }
        }
        assert_eq!(
            host.delivered().first().map(|message| message.ts.as_str()),
            Some("200.0"),
            "the first DM pass runs without waiting for its interval",
        );
        let after_first = host.history_calls();
        assert_eq!(after_first, 1, "one pass, one read");

        // Several conversation ticks go by, and the window is longer than one
        // of them; none of them reads the DM.
        tokio::time::sleep(Duration::from_millis(2_500)).await;
        assert_eq!(host.history_calls(), after_first, "the DM pass does not ride the fast clock");

        tx.send(()).expect("signal shutdown");
        let _ = pump.await;
    }

    /// The seeding arithmetic at its boundary. A cursor is compared as a
    /// string, and `1790186555.000000` sorts AFTER `1790186555.0` - the same
    /// instant written shorter - so a zero fraction has to borrow a second
    /// rather than decrement to something that does not compare below it.
    #[test]
    fn just_below_borrows_a_second_at_a_zero_fraction() {
        assert!(
            "1790186555.000000" > "1790186555.0",
            "the trap this exists for: the padded form sorts after the short one",
        );
        for ts in ["1790186555.000000", "1790186555.0", "1790186555.957249"] {
            let below = just_below(ts);
            assert!(below.as_str() < ts, "`{below}` must sort below `{ts}`");
        }
        assert_eq!(just_below("1790186555.000000"), "1790186554.999999");
        assert_eq!(just_below("1790186555.957249"), "1790186555.957248");
    }

    /// Two clocks, because two things are watched: the handful of
    /// conversations a subscription names, and every DM in the workspace. A
    /// pass reads only what its own clock is for, or the DM class would cost
    /// its per-inbox reads on the conversation tick anyway.
    #[tokio::test]
    async fn each_clock_reads_only_its_own_conversations() {
        let host = FakeHost::with_subscriptions(vec![
            sub_dm("acme"),
            sub_channel("acme", "C1", SlackWatchMode::All),
        ]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history("D1", vec![history_message("200.0", "U9", "a dm")]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("200.0", "U9", "a channel")]);

        let outcome = sweep_scope(&host, &host, "acme", SweepScope::Conversations)
            .await
            .expect("the conversation pass");
        assert_eq!(outcome.delivered, 1, "the named channel only");
        assert_eq!(host.delivered()[0].conversation, "C1", "and the DM is not on this clock");

        let outcome = sweep_scope(&host, &host, "acme", SweepScope::DirectMessages)
            .await
            .expect("the DM pass");
        assert_eq!(outcome.delivered, 1, "the DM only");
        assert_eq!(host.delivered()[1].conversation, "D1", "and the channel is not on that one");
    }

    /// A DM a subscription also names rides the faster clock: reading it on
    /// both would spend a call per DM per conversation tick, which is the
    /// cost the separate clock exists to avoid.
    #[tokio::test]
    async fn a_named_dm_is_read_on_the_conversation_clock_only() {
        let host = FakeHost::with_subscriptions(vec![
            sub_dm("acme"),
            sub_channel("acme", "D1", SlackWatchMode::All),
        ]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history("D1", vec![history_message("200.0", "U9", "a dm")]);

        let dms = sweep_scope(&host, &host, "acme", SweepScope::DirectMessages)
            .await
            .expect("the DM pass");
        assert_eq!(dms.delivered, 0, "the named DM is not the DM clock's to read");
        assert!(host.delivered().is_empty(), "so it was not read at all: {:?}", host.delivered());

        sweep_scope(&host, &host, "acme", SweepScope::Conversations)
            .await
            .expect("the conversation pass");
        assert!(
            host.delivered().iter().any(|message| message.conversation == "D1"),
            "it is the conversation clock's: {:?}",
            host.delivered(),
        );
    }

    /// A quiet conversation is the common case: the sweep runs every few
    /// seconds and most of what it looks at has nothing new. It must
    /// deliver nothing at all, never an empty block.
    #[tokio::test]
    async fn a_sweep_with_nothing_new_delivers_nothing() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "100.0");
        host.seed_history("D1", vec![history_message("100.0", "U9", "already delivered")]);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 0, "a quiet tick must not deliver an empty bundle");
        assert!(host.batches().is_empty(), "and must not call the seam at all");
    }

    /// forge posts as the user, so the author cannot decide this: a
    /// message Ved typed in a watched conversation is delivered, and only
    /// the ts forge recorded when it posted is refused.
    #[tokio::test]
    async fn a_sweep_delivers_what_the_user_typed_and_refuses_what_forge_posted() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "100.0");
        host.seed_history(
            "C1",
            vec![
                history_message("200.2", "U1", "the agent's own post"),
                history_message("200.1", "U1", "what Ved typed"),
            ],
        );
        host.record_own_post("acme", "C1", "200.2");

        sweep(&host, &host, "acme").await.expect("sweep");

        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert_eq!(
            texts,
            vec!["what Ved typed".to_owned()],
            "the ledger refuses the agent's post by ts; the user's own words arrive",
        );
    }

    /// A message can reach history before the post call returns and its ts
    /// is ledgered. A conversation with a post in flight is skipped for the
    /// tick, and its cursor does not move, so the next tick reads the
    /// window whole.
    #[tokio::test]
    async fn a_conversation_with_a_post_in_flight_is_skipped_without_moving_its_cursor() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "100.0");
        host.seed_history("C1", vec![history_message("200.0", "U1", "what Ved typed")]);
        host.set_post_in_flight("acme", "C1", true);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");

        assert_eq!(outcome.delivered, 0, "the tick is skipped while a post is in flight");
        assert!(host.delivered().is_empty(), "nothing is read from that conversation");
        assert_eq!(
            host.watermark("acme", "C1").expect("watermark"),
            Some("100.0".to_owned()),
            "and the cursor holds, so the next tick reads the window whole",
        );

        host.set_post_in_flight("acme", "C1", false);
        let outcome = sweep(&host, &host, "acme").await.expect("the next tick");
        assert_eq!(
            outcome.delivered, 1,
            "the held message is delivered once the post has finished"
        );
        assert_eq!(
            host.delivered().first().map(|message| message.ts.as_str()),
            Some("200.0"),
            "and it is the message the skip held, not a lost window",
        );
    }

    /// A post whose listing failed is marked under the address it was sent
    /// with; the sweep asks under the conversation's name and DM partner
    /// too, so that mark still skips it.
    #[tokio::test]
    async fn an_alias_addressed_mark_still_skips_the_conversation() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history("D1", vec![history_message("200.0", "U9", "a dm")]);
        host.set_post_in_flight("acme", "U9", true);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");

        assert_eq!(
            outcome.delivered, 0,
            "the DM's partner address marks the conversation in flight"
        );
        assert!(host.delivered().is_empty(), "nothing is read from that DM");
    }

    /// The mention path is the same commit-to-ledger window, and the
    /// cursor has to hold for it: hits arrive newest-first, so a newer hit
    /// delivered in the same sweep would move the cursor above the skipped
    /// one and lose it for good. Two hits, the newer in another
    /// conversation, is the shape that catches that.
    #[tokio::test]
    async fn a_mention_in_a_conversation_with_a_post_in_flight_holds_the_cursor() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.seed_search(vec![
            search_match("300.2", "C1", "newer <@U1>"),
            search_match("200.1", "C2", "skipped <@U1>"),
        ]);
        host.set_post_in_flight("acme", "C2", true);

        let first = sweep_mentions(&host, &host, "acme").await.expect("first sweep");

        assert_eq!(first.delivered, 1, "the newer hit in another conversation is delivered");
        assert_eq!(
            host.watermark("acme", MENTION_CURSOR).expect("watermark"),
            None,
            "and the cursor holds below the skipped hit rather than passing it",
        );

        host.set_post_in_flight("acme", "C2", false);
        sweep_mentions(&host, &host, "acme").await.expect("second sweep");

        let delivered = host.delivered();
        let conversations: Vec<&str> =
            delivered.iter().map(|message| message.conversation.as_str()).collect();
        assert!(
            conversations.contains(&"C2"),
            "the skipped mention is delivered once the post finished: {conversations:?}",
        );
    }

    /// Two conversations with news are two blocks, each carrying its own
    /// conversation's members. One block holding both would attribute one
    /// conversation's messages to the other.
    #[tokio::test]
    async fn two_active_conversations_deliver_two_bundles() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "100.0");
        host.set_watermark("acme", "D2", "100.0");
        host.seed_history(
            "D1",
            // The wire's order: newest first.
            vec![
                history_message("300.1", "U9", "d1 newest"),
                history_message("200.1", "U9", "d1 older"),
            ],
        );
        host.seed_history("D2", vec![history_message("200.2", "U8", "d2 only")]);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 2, "one delivery per conversation, never one merged one");
        let batches = host.batches();
        assert_eq!(batches.len(), 2, "two blocks, never one per message");
        assert_ne!(batches[0][0].conversation, batches[1][0].conversation);
        assert_eq!(
            batches.iter().map(Vec::len).sum::<usize>(),
            3,
            "every message rides its own conversation's block",
        );
    }

    fn sub_dm(workspace: &str) -> SlackSubscription {
        let mut sub = sub_for(SlackSubscriptionTarget::DirectMessages);
        sub.workspace = workspace.to_owned();
        sub
    }

    fn sub_mentions(workspace: &str) -> SlackSubscription {
        let mut sub = sub_for(SlackSubscriptionTarget::Mentions);
        sub.workspace = workspace.to_owned();
        sub
    }

    fn sub_conversation_owned_by(
        workspace: &str,
        project: &str,
        team_role: Option<&str>,
        id: &str,
    ) -> SlackSubscription {
        let mut sub = sub_for(SlackSubscriptionTarget::Conversation {
            id: id.to_owned(),
            name: None,
            mode: SlackWatchMode::All,
        });
        sub.workspace = workspace.to_owned();
        sub.project = project.to_owned();
        sub.team_role = team_role.map(str::to_owned);
        sub
    }

    fn thread_owner(project: &str, team_role: Option<&str>) -> SlackThreadOwner {
        SlackThreadOwner { project: project.to_owned(), team_role: team_role.map(str::to_owned) }
    }

    fn search_match(ts: &str, conversation: &str, text: &str) -> SlackSearchMatch {
        SlackSearchMatch {
            ts: ts.to_owned(),
            text: text.to_owned(),
            conversation_id: conversation.to_owned(),
            conversation_name: None,
            username: Some("U9".to_owned()),
            user: Some("U9".to_owned()),
            thread_ts: None,
            files: Vec::new(),
        }
    }

    /// The whole reason this target is affordable: one search covers the
    /// workspace, where a per-conversation mention poll would blow the
    /// budget.
    #[tokio::test]
    async fn a_mention_sweep_makes_exactly_one_search_call_for_the_workspace() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.seed_search(vec![search_match("200.1", "C1", "ping <@U1>")]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(host.count_for("search.messages"), 1);
    }

    #[tokio::test]
    async fn only_mention_matches_newer_than_the_cursor_are_delivered() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.set_watermark("acme", MENTION_CURSOR, "150.0");
        host.seed_search(vec![
            search_match("200.1", "C1", "newer <@U1>"),
            search_match("100.1", "C1", "older <@U1>"),
        ]);

        let outcome = sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 1);
        assert_eq!(host.delivered()[0].text, "newer <@U1>");
    }

    #[tokio::test]
    async fn the_mention_cursor_advances_to_the_newest_ts() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.seed_search(vec![
            search_match("200.1", "C1", "a <@U1>"),
            search_match("300.2", "C2", "b <@U1>"),
        ]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(
            host.watermark("acme", MENTION_CURSOR).expect("watermark"),
            Some("300.2".to_owned())
        );
    }

    /// If this ever runs for a workspace with no mention target, it spends
    /// a search call for nothing on every tick and the cost of the feature
    /// silently becomes per-workspace-per-poll.
    #[tokio::test]
    async fn a_mention_sweep_with_no_targets_does_not_search_at_all() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(
            host.count_for("search.messages"),
            0,
            "an unsubscribed workspace must not spend a call",
        );
    }

    /// Without a cursor seeded at the mention, the first sweep of the new
    /// subscription delivers the newest page of the channel's history as
    /// if it were all new.
    #[tokio::test]
    async fn a_freshly_auto_subscribed_conversation_starts_from_the_mention() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.seed_search(vec![search_match("200.1", "C1", "ping <@U1>")]);
        sweep_mentions(&host, &host, "acme").await.expect("sweep");

        // The channel's own past still exists; none of it may arrive.
        host.seed_history(
            "C1",
            vec![
                history_message("250.1", "U9", "after the mention"),
                history_message("150.1", "U9", "before the mention"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("sweep");

        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert_eq!(
            texts,
            vec!["ping <@U1>".to_owned(), "after the mention".to_owned()],
            "the subscription starts at the mention, not at the channel's history",
        );
    }

    /// A page holds the newest hits, so a backlog wider than one page is
    /// lost if the cursor advances past the page. The walk follows the
    /// cursor and delivers all of them.
    #[tokio::test]
    async fn a_mention_backlog_wider_than_one_page_is_delivered_without_loss() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        let all: Vec<SlackSearchMatch> = (0..25)
            .rev()
            .map(|n| search_match(&format!("1{n:02}.1"), "C1", "ping <@U1>"))
            .collect();
        let newest = all[0].ts.clone();
        let oldest = all[24].ts.clone();
        let (page_one, page_two) = all.split_at(20);
        host.seed_search_pages(vec![page_one.to_vec(), page_two.to_vec()]);

        let outcome = sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 25, "every mention in the backlog arrives");
        assert_eq!(host.watermark("acme", MENTION_CURSOR).expect("watermark"), Some(newest));
        assert_ne!(
            host.watermark("acme", MENTION_CURSOR).expect("watermark"),
            Some(oldest),
            "nothing is skipped"
        );
    }

    /// The search query is the literal mention token, so it matches the
    /// agent's own posts that quote one. The ledger refuses those, at the
    /// indexing lag that would otherwise make a self-echo loop; a message
    /// Ved wrote himself is delivered, or his own side of the thread is
    /// missing.
    #[tokio::test]
    async fn the_mention_sweep_refuses_its_own_ledgered_post_and_delivers_the_users_own() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        let mut agent_post = search_match("300.2", "C1", "mine <@U1>");
        agent_post.user = Some("U1".to_owned());
        let mut user_post = search_match("250.1", "C1", "what I wrote <@U1>");
        user_post.user = Some("U1".to_owned());
        host.seed_search(vec![search_match("200.1", "C1", "theirs <@U1>"), agent_post, user_post]);
        host.record_own_post("acme", "C1", "300.2");

        let outcome = sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 2, "the agent's post is refused; every other hit arrives");
        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert!(!texts.iter().any(|t| t == "mine <@U1>"), "no self-echo: {texts:?}");
        assert!(
            texts.iter().any(|t| t == "what I wrote <@U1>"),
            "the user's own mention is delivered: {texts:?}",
        );
    }

    /// A dispatch failure must leave the cursor where it was, so the next
    /// sweep re-fetches the whole window; dedupe absorbs what already
    /// reached a session. The conversation's news is one delivery now, so
    /// a failure holds the whole of it rather than part.
    #[tokio::test]
    async fn a_failed_delivery_holds_the_cursor_at_its_previous_value() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history(
            "D1",
            // The wire's order: newest first.
            vec![
                history_message("300.1", "U9", "newest"),
                history_message("200.1", "U9", "in the same batch"),
                history_message("100.1", "U9", "oldest"),
            ],
        );
        host.fail_delivery_at(0);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 0, "a block that did not land is not delivered");
        assert!(host.delivered().is_empty(), "nothing of a failed block reached the session");
        assert_eq!(
            host.watermark("acme", "D1"),
            Ok(Some("050.0".to_owned())),
            "the cursor holds below the failure instead of jumping past it",
        );
    }

    #[tokio::test]
    async fn a_mention_creates_a_conversation_subscription() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.seed_search(vec![search_match("200.1", "C1", "ping <@U1>")]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(host.auto_subscribed(), vec!["C1".to_owned()]);
    }

    #[tokio::test]
    async fn an_already_watched_conversation_is_not_subscribed_twice() {
        let host = FakeHost::with_subscriptions(vec![
            sub_mentions("acme"),
            sub_channel("acme", "C1", SlackWatchMode::All),
        ]);
        host.seed_search(vec![search_match("200.1", "C1", "ping <@U1>")]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert!(host.auto_subscribed().is_empty(), "C1 is already watched");
    }

    fn sub_channel(workspace: &str, id: &str, mode: SlackWatchMode) -> SlackSubscription {
        let mut sub =
            sub_for(SlackSubscriptionTarget::Conversation { id: id.to_owned(), name: None, mode });
        sub.workspace = workspace.to_owned();
        sub
    }

    #[tokio::test]
    async fn a_sweep_delivers_only_what_follows_the_watermark() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.seed_history(
            "D1",
            vec![history_message("200.1", "U9", "newer"), history_message("100.1", "U9", "older")],
        );
        host.set_watermark("acme", "D1", "150.0");

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 1);
        assert_eq!(host.delivered()[0].text, "newer");
    }

    #[tokio::test]
    async fn a_sweep_advances_the_watermark_to_the_newest_seen() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history(
            "D1",
            // The wire's order: newest first.
            vec![history_message("300.2", "U9", "newest"), history_message("200.1", "U9", "older")],
        );

        sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(host.watermark("acme", "D1").expect("watermark"), Some("300.2".to_owned()));
    }

    /// The defect this fix exists for: a message corrected after delivery
    /// keeps its `ts`, so a ts-only cursor test drops the edit on every
    /// sweep. The correction must arrive, and the cursor must clear the
    /// edit - a cursor left below it re-offers the message every tick, and
    /// redispatches it once the delivery memory lapses.
    #[tokio::test]
    async fn an_edit_to_a_delivered_message_arrives_and_the_cursor_clears_it() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "100.0");
        let mut corrected = history_message("090.0", "U9", "deploy is RED");
        corrected.edited = Some("150.0".to_owned());
        host.seed_history("D1", vec![corrected]);

        let outcome = sweep(&host, &host, "acme").await.expect("the edit's sweep");
        assert_eq!(outcome.delivered, 1, "the correction is delivered");
        assert_eq!(host.delivered()[0].text, "deploy is RED", "with its new text");
        assert_eq!(
            host.delivered()[0].edited.as_deref(),
            Some("150.0"),
            "and it carries the edit ts the delivery memory keys on",
        );
        assert_eq!(
            host.watermark("acme", "D1"),
            Ok(Some("150.0".to_owned())),
            "the cursor clears the edit, so the next sweep does not re-offer it",
        );

        let again = sweep(&host, &host, "acme").await.expect("a quiet sweep");
        assert_eq!(again.delivered, 0, "an edit is delivered once, not every tick");
    }

    /// Without paging, a conversation that exceeds one page inside a poll
    /// interval loses the surplus: the sweep would advance the watermark
    /// past messages it never fetched, and nothing would ever report it.
    #[tokio::test]
    async fn a_sweep_reads_every_history_page_before_advancing() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history_pages(
            "D1",
            // The wire's order: newest page first.
            vec![
                vec![history_message("300.3", "U9", "three")],
                vec![history_message("200.2", "U9", "two")],
                vec![history_message("100.1", "U9", "one")],
            ],
        );

        sweep(&host, &host, "acme").await.expect("sweep");
        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert_eq!(texts, vec!["three".to_owned(), "two".to_owned(), "one".to_owned()]);
        assert_eq!(
            host.watermark("acme", "D1").expect("watermark"),
            Some("300.3".to_owned()),
            "the cursor clears every page that was read",
        );
    }

    #[tokio::test]
    async fn a_rate_limit_is_reported_rather_than_retried_inline() {
        let mut host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.fail_with_rate_limit(Duration::from_secs(7));

        let outcome = sweep(&host, &host, "acme").await.expect("a 429 is not an error");
        assert_eq!(outcome.rate_limited, Some(Duration::from_secs(7)));
    }

    #[tokio::test]
    async fn a_message_in_a_thread_pulls_its_replies_and_dedupes_the_parent() {
        // The measured behaviour: Slack repeats the parent on every page, so
        // it arrives once per page without dedupe.
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        let root =
            SlackHistoryMessage { text: "root".to_owned(), ..parent_with_replies("100.0", 2) };
        host.seed_history("C1", vec![root.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                root.clone(),
                history_message("150.0", "U1", "the user's own reply"),
                reply("200.1", "100.0", "U8", "reply one"),
                root,
                reply("300.2", "100.0", "U8", "reply two"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("sweep");
        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert_eq!(
            texts,
            vec![
                "root".to_owned(),
                "the user's own reply".to_owned(),
                "reply one".to_owned(),
                "reply two".to_owned(),
            ],
            "the parent must not repeat per page, and the user's own reply rides in",
        );
    }

    /// An edited parent is news again, which makes the sweep read its
    /// thread fresh - and a corrected reply whose own ts sits behind the
    /// conversation cursor has to ride that read in. Filtering the read on
    /// ts alone is the same drop the conversation batch had.
    #[tokio::test]
    async fn a_corrected_reply_rides_in_on_its_parents_redelivery() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        // The channel moved on past the thread: only the corrections are
        // past the cursor, the messages' own ts values are not.
        host.set_watermark("acme", "C1", "300.0");
        let mut corrected_parent = parent_with_replies("100.0", 2);
        corrected_parent.edited = Some("340.0".to_owned());
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("350.0".to_owned());
        host.seed_history("C1", vec![corrected_parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                corrected_parent,
                history_message("105.0", "U1", "the user's own reply"),
                corrected,
            ],
        );
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "150.0");

        sweep(&host, &host, "acme").await.expect("the corrections' sweep");

        let delivered = host.delivered();
        assert!(
            delivered.iter().any(|message| message.ts == "100.0" && message.text == "trigger"),
            "the corrected parent is delivered: {delivered:?}",
        );
        assert!(
            delivered
                .iter()
                .any(|message| message.ts == "150.0" && message.text == "the answer, corrected"),
            "and its thread's corrected reply rides the fresh read: {delivered:?}",
        );

        // The conversation batch hands the correction over and advances the
        // thread's edit stamp; the reply cursor stays at 150. A restart must
        // read that stamp back, or the next whole read offers the 350 edit
        // again - a mark seeded from the cursor (150) does exactly that.
        host.restart();
        let calls_before = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("the first sweep after a restart");
        assert!(host.replies_calls() > calls_before, "the thread was walked after the restart");
        assert_eq!(
            host.replies_oldest().last(),
            Some(&None),
            "the walk reads the thread whole: {:?}",
            host.replies_oldest(),
        );
        assert_eq!(
            host.delivered()
                .iter()
                .filter(|message| message.text == "the answer, corrected")
                .count(),
            1,
            "the correction is not handed over twice: {:?}",
            host.delivered(),
        );
    }

    /// A correction in a thread the user is in, with its parent never news
    /// again. An edit keeps the reply's `ts`, so `latest_reply` does not
    /// move: the window's unchanged check must not leave a participating
    /// thread unread, and the walk must judge a reply by its edit as well
    /// as its `ts`. Neither half is what the conversation path does - it
    /// re-reads the thread only when its parent is redelivered.
    #[tokio::test]
    async fn a_corrected_reply_in_a_participating_thread_arrives_without_its_parent() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent.clone(),
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "the answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "the trigger sweep delivers the reply: {:?}",
            host.delivered(),
        );

        // The parent is still in the newest page and never moves; the reply
        // below the thread cursor is corrected.
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("990.0".to_owned());
        host.seed_history("C1", vec![parent_with_latest_reply("100.0", 2, "150.0")]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent, history_message("105.0", "U1", "the user's own reply"), corrected],
        );

        sweep(&host, &host, "acme").await.expect("the correction's sweep");

        let delivered = host.delivered();
        assert!(
            delivered
                .iter()
                .any(|message| message.ts == "150.0" && message.text == "the answer, corrected"),
            "the corrected reply arrives though its parent never moved: {delivered:?}",
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0").as_deref(),
            Some("990.0"),
            "and the thread cursor clears the edit, so the next tick does not re-offer it",
        );

        // The whole read must not offer the correction a second time: the
        // watermark moved when the cheap tick handed it over, and the
        // delivery memory has lapsed long before ten minutes pass.
        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the whole read");
        let corrected = host
            .delivered()
            .iter()
            .filter(|message| message.ts == "150.0" && message.text == "the answer, corrected")
            .count();
        assert_eq!(
            corrected,
            1,
            "the correction arrives once, not once per path: {:?}",
            host.delivered()
        );
    }

    /// A thread row re-created after its owners went re-follows at
    /// `latest_reply`, which an edit does not move. The first walk filters by
    /// `ts` alone, so an old correction the previous row already handed over
    /// is not delivered again; the periodic whole read is what finds edits
    /// once the row has been walked.
    #[tokio::test]
    async fn a_recreated_thread_does_not_replay_an_edit_its_seed_already_passed() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        // The channel moved past the thread, so only the thread walk can see
        // these replies.
        host.set_watermark("acme", "C1", "300.0");
        let parent = parent_with_latest_reply("100.0", 2, "200.0");
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("990.0".to_owned());
        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent, history_message("105.0", "U1", "his own reply"), corrected],
        );
        // A re-created row, seeded at the thread's newest reply.
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "200.0");

        sweep(&host, &host, "acme").await.expect("the first walk");
        assert!(
            !host.delivered().iter().any(|message| message.ts == "150.0"),
            "the first walk filters by ts: {:?}",
            host.delivered(),
        );

        // The first walk starts the interval; age it to reach the whole pass.
        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the periodic whole read");
        assert!(
            host.delivered()
                .iter()
                .any(|message| message.ts == "150.0" && message.text == "the answer, corrected"),
            "the whole read finds the correction: {:?}",
            host.delivered(),
        );
    }

    /// **A correction handed over before a restart must not be handed over
    /// again.** The edit stamp is durable with the thread row; a restart
    /// clears the process clocks, and the first whole read after it judges
    /// every edited reply against that stamp. Lost, the read hands the
    /// thread's whole edit history over again, each one labelled old and
    /// edited.
    #[tokio::test]
    async fn a_restart_does_not_re_deliver_an_edit_the_thread_row_already_judged() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        // Replies never appear in history, so only the thread walk sees
        // them; the parent brings the thread into the sweep.
        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent.clone(),
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "the answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("the trigger sweep");
        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "the trigger sweep delivers the reply: {:?}",
            host.delivered(),
        );

        // The reply is corrected; the correction lands and moves the stamp.
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("990.0".to_owned());
        // An edit does not move `latest_reply`, so the parent's window row
        // is unchanged.
        host.seed_history("C1", vec![parent_with_latest_reply("100.0", 2, "150.0")]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent, history_message("105.0", "U1", "the user's own reply"), corrected],
        );
        sweep(&host, &host, "acme").await.expect("the correction's sweep");
        assert_eq!(
            host.delivered()
                .iter()
                .filter(|message| message.text == "the answer, corrected")
                .count(),
            1,
            "the correction is handed over once: {:?}",
            host.delivered(),
        );

        // A restart keeps the row and drops every process clock.
        host.restart();
        let calls_before = host.replies_calls();

        sweep(&host, &host, "acme").await.expect("the first sweep after a restart");
        assert!(
            host.replies_calls() > calls_before,
            "the thread was walked after the restart: {calls_before} calls before",
        );
        assert_eq!(
            host.replies_oldest().last(),
            Some(&None),
            "and the first post-restart walk reads the thread whole: {:?}",
            host.replies_oldest(),
        );
        assert_eq!(
            host.delivered()
                .iter()
                .filter(|message| message.text == "the answer, corrected")
                .count(),
            1,
            "the correction is not handed over again after the restart: {:?}",
            host.delivered(),
        );
    }

    /// A channel longer than the page cap refuses rather than returning the
    /// newest pages as if they were the whole backlog.
    #[tokio::test]
    async fn a_channel_past_the_page_cap_refuses_instead_of_returning_partial_history() {
        let host = FakeHost::default();
        let pages: Vec<Vec<SlackHistoryMessage>> = (0..=MAX_HISTORY_PAGES)
            .map(|n| vec![history_message(&format!("{}.0", 200 + n), "U8", "a message")])
            .collect();
        host.seed_history_pages("C1", pages);

        let err = fetch_history(&host, "acme", "C1", None)
            .await
            .expect_err("the walk must not read as complete");

        assert!(
            matches!(&err, SlackError::Truncated { pages, .. } if *pages == MAX_HISTORY_PAGES),
            "the refusal names the cap it hit: {err:?}",
        );
    }

    /// A caller-bounded thread read still refuses when the thread is longer
    /// than the page cap: the rows it would return are not the read.
    #[tokio::test]
    async fn a_thread_read_past_the_page_cap_refuses() {
        let host = FakeHost::default();
        let pages: Vec<Vec<SlackHistoryMessage>> = (0..=MAX_REPLY_PAGES)
            .map(|n| vec![reply(&format!("{}.0", 200 + n), "100.0", "U8", "a reply")])
            .collect();
        host.seed_replies_pages("C1", "100.0", pages);

        let err = read_thread(&host, "C1", "100.0", 50_000)
            .await
            .expect_err("the read must not stop at the cap and call it done");

        assert!(
            matches!(&err, SlackError::Truncated { pages, .. } if *pages == MAX_REPLY_PAGES),
            "{err:?}",
        );
    }

    /// A thread longer than the page cap refuses rather than reading as a
    /// complete walk: the pages collected are the oldest, so returning them
    /// as success would advance a cursor past every reply the walk never
    /// reached.
    #[tokio::test]
    async fn a_thread_past_the_page_cap_refuses_instead_of_returning_the_oldest_pages() {
        let host = FakeHost::default();
        let pages: Vec<Vec<SlackHistoryMessage>> = (0..=MAX_REPLY_PAGES)
            .map(|n| vec![reply(&format!("{}.0", 200 + n), "100.0", "U8", "a reply")])
            .collect();
        host.seed_replies_pages("C1", "100.0", pages);

        let err = fetch_replies(&host, "acme", "C1", "100.0", None)
            .await
            .expect_err("the walk must not read as complete");

        assert!(
            matches!(&err, SlackError::Truncated { pages, .. } if *pages == MAX_REPLY_PAGES),
            "the refusal names the cap it hit: {err:?}",
        );
    }

    /// **One thread's throttle must not end the sweep.** A 429 on a thread's
    /// read arms the pump's backoff and the walk moves on, so the threads
    /// behind it still deliver.
    #[tokio::test]
    async fn a_throttled_thread_does_not_starve_the_threads_after_it() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        // Past both parents, so only the thread walk can see either reply.
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        for (parent, reply_ts) in [("100.0", "150.0"), ("200.0", "250.0")] {
            host.seed_replies("C1", parent, vec![reply(reply_ts, parent, "U8", "the answer")]);
            host.follow_thread(
                "acme",
                "C1",
                parent,
                thread_owner("forge", Some("tester")),
                "050.0",
            );
            host.mark_thread_participating("acme", "C1", parent);
        }
        host.rate_limit_replies_at(0);

        let outcome = sweep(&host, &host, "acme").await.expect("a 429 is not an error");

        assert_eq!(
            outcome.rate_limited,
            Some(Duration::from_secs(5)),
            "the throttle still reaches the pump",
        );
        assert_eq!(host.replies_calls(), 2, "the throttled thread did not end the walk");
        assert_eq!(
            host.delivered().len(),
            1,
            "the thread after the throttled one still delivered: {:?}",
            host.delivered(),
        );
    }

    /// **An edit below the newest reply is not lost to a moving cursor.**
    /// The cheap tick advances the cursor to a newer reply first, so a whole
    /// read must judge the edit against its own watermark, not the cursor.
    #[tokio::test]
    async fn an_edit_below_a_newer_reply_still_arrives_on_the_whole_read() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        let parent = reply("100.0", "100.0", "U9", "the parent");
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent.clone(),
                reply("150.0", "100.0", "U8", "the answer"),
                reply("300.0", "100.0", "U8", "the second answer"),
            ],
        );
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "050.0");
        host.mark_thread_participating("acme", "C1", "100.0");
        sweep(&host, &host, "acme").await.expect("the first walk");
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("300.0".to_owned()),
            "the first walk delivered both replies",
        );

        // The older reply is corrected, and a NEWER reply lands before the
        // next whole read; the cheap tick moves the cursor past the edit.
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("400.0".to_owned());
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                corrected,
                reply("300.0", "100.0", "U8", "the second answer"),
                reply("500.0", "100.0", "U8", "a newer answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("the cheap tick");
        assert!(
            host.delivered().iter().any(|message| message.ts == "500.0"),
            "the newer reply lands first: {:?}",
            host.delivered(),
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("500.0".to_owned()),
            "and moves the cursor past the edit at 400",
        );

        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the whole read");

        assert!(
            host.delivered()
                .iter()
                .any(|message| message.ts == "150.0" && message.text == "the answer, corrected"),
            "the correction arrives even though its stamp is behind the cursor: {:?}",
            host.delivered(),
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("500.0".to_owned()),
            "and the cursor is never moved back",
        );
    }

    /// **A failed hand-off must not spend the edit watermark.** The cursor
    /// holds on a failed delivery; the watermark has to hold with it, or a
    /// correction below the cursor is refused by every later whole read.
    #[tokio::test]
    async fn a_failed_delivery_holds_the_edit_watermark() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                reply("150.0", "100.0", "U8", "the answer"),
                reply("300.0", "100.0", "U8", "the second answer"),
            ],
        );
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "050.0");
        host.mark_thread_participating("acme", "C1", "100.0");
        sweep(&host, &host, "acme").await.expect("the first walk");

        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("400.0".to_owned());
        host.seed_replies(
            "C1",
            "100.0",
            vec![corrected, reply("300.0", "100.0", "U8", "the second answer")],
        );
        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        // The first sweep already spent attempt 0; the whole read's block is
        // attempt 1, and this test fails exactly that one.
        host.fail_delivery_at(1);
        sweep(&host, &host, "acme").await.expect("the whole read");
        assert!(
            !host.delivered().iter().any(|message| message.text.contains("corrected")),
            "the failed block did not land: {:?}",
            host.delivered(),
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("300.0".to_owned()),
            "the cursor holds below the failure",
        );

        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the retry");
        assert!(
            host.delivered().iter().any(|message| message.text == "the answer, corrected"),
            "the retry still finds the correction: {:?}",
            host.delivered(),
        );

        // A newer reply moves the cursor above the correction, so the stamp,
        // never the cursor, is what judges the next edit: a mark seeded from
        // the cursor (500) would drop the 450 correction.
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                reply("150.0", "100.0", "U8", "the answer, corrected"),
                reply("300.0", "100.0", "U8", "the second answer"),
                reply("500.0", "100.0", "U8", "a newer answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("the newer reply's cheap tick");
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("500.0".to_owned()),
            "the cursor moved past the correction",
        );

        // A restart empties the cache, so the mark comes from the row: 400,
        // the last handed edit stamp, never the 500 cursor.
        host.restart();
        let mut later = reply("150.0", "100.0", "U8", "the answer, corrected again");
        later.edited = Some("450.0".to_owned());
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                later,
                reply("300.0", "100.0", "U8", "the second answer"),
                reply("500.0", "100.0", "U8", "a newer answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("the first sweep after a restart");
        assert_eq!(
            host.replies_oldest().last(),
            Some(&None),
            "the walk reads the thread whole: {:?}",
            host.replies_oldest(),
        );
        assert!(
            host.delivered().iter().any(|message| message.text == "the answer, corrected again"),
            "an edit below the cursor but above the stamp still arrives: {:?}",
            host.delivered(),
        );
    }

    /// The double mirrors the host's legacy seed: a row with no edit stamp
    /// answers with its cursor, so a test cannot pass on a mark the real
    /// host would derive differently.
    #[test]
    fn the_fake_host_seeds_an_unstamped_thread_row_from_its_cursor() {
        let host = FakeHost::default();
        host.set_thread_watermark("acme", "C1", "100.0", "500.0");

        assert_eq!(
            host.thread_edit_watermark("acme", "C1", "100.0").as_deref(),
            Some("500.0"),
            "a row with no stamp reads its cursor, as the real host does",
        );
    }

    /// The whole read runs on its own clock: the tick after a whole read is
    /// the cheap one, and only an aged stamp makes the next read whole.
    #[tokio::test]
    async fn the_whole_read_runs_on_its_own_clock_not_every_tick() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        host.seed_replies("C1", "100.0", vec![reply("150.0", "100.0", "U8", "the answer")]);
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "050.0");
        host.mark_thread_participating("acme", "C1", "100.0");

        sweep(&host, &host, "acme").await.expect("the first walk");
        assert!(
            host.replies_oldest().last().expect("a replies call").is_none(),
            "the first walk reads whole: {:?}",
            host.replies_oldest(),
        );

        sweep(&host, &host, "acme").await.expect("the cheap tick");
        assert!(
            host.replies_oldest().last().expect("a replies call").is_some(),
            "the tick after a whole read is the cheap one: {:?}",
            host.replies_oldest(),
        );

        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the aged tick");
        assert!(
            host.replies_oldest().last().expect("a replies call").is_none(),
            "an aged stamp makes the read whole again: {:?}",
            host.replies_oldest(),
        );
    }

    /// The whole-read budget is real: three due threads cost two whole reads
    /// in a sweep, and the skipped one is read whole on the next.
    #[tokio::test]
    async fn the_sweep_reads_at_most_two_threads_whole() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        for (parent, reply_ts) in [("100.0", "150.0"), ("200.0", "250.0"), ("400.0", "450.0")] {
            host.seed_replies("C1", parent, vec![reply(reply_ts, parent, "U8", "the answer")]);
            host.follow_thread(
                "acme",
                "C1",
                parent,
                thread_owner("forge", Some("tester")),
                "050.0",
            );
            host.mark_thread_participating("acme", "C1", parent);
        }
        sweep(&host, &host, "acme").await.expect("the first walks");
        for parent in ["100.0", "200.0", "400.0"] {
            host.age_thread_full_read("acme", "C1", parent, Duration::from_secs(601));
        }

        let before = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("the budgeted sweep");
        let calls = host.replies_oldest();
        let tail = &calls[before..];
        let whole = tail.iter().filter(|oldest| oldest.is_none()).count();
        assert_eq!(
            whole, MAX_FULL_THREAD_READS_PER_SWEEP,
            "the budget caps whole reads per sweep: {tail:?}",
        );

        let before = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("the next sweep");
        let calls = host.replies_oldest();
        let whole = calls[before..].iter().filter(|oldest| oldest.is_none()).count();
        assert_eq!(whole, 1, "the thread the budget skipped is read whole next tick");
    }

    /// A throttled first walk keeps its mark: losing it would replay edits
    /// the previous row already handed over.
    #[tokio::test]
    async fn a_throttled_first_walk_keeps_the_replay_guard() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        let parent = parent_with_latest_reply("100.0", 2, "200.0");
        let mut corrected = reply("150.0", "100.0", "U8", "the answer, corrected");
        corrected.edited = Some("990.0".to_owned());
        host.seed_replies("C1", "100.0", vec![parent, corrected]);
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "200.0");
        host.mark_thread_participating("acme", "C1", "100.0");
        host.rate_limit_replies_at(0);

        let first = sweep(&host, &host, "acme").await.expect("a 429 is not an error");
        assert_eq!(first.rate_limited, Some(Duration::from_secs(5)));
        assert!(
            host.thread_first_walks.lock().expect("lock").contains("acme/C1/100.0"),
            "the first-walk mark survives the 429",
        );

        host.age_thread_full_read("acme", "C1", "100.0", Duration::from_secs(601));
        sweep(&host, &host, "acme").await.expect("the retry");
        assert!(
            !host.delivered().iter().any(|message| message.ts == "150.0"),
            "the retried first walk still filters by ts: {:?}",
            host.delivered(),
        );
    }

    /// An author lookup throttled inside a thread does not end the sweep:
    /// the walk moves on and the threads behind it still deliver.
    #[tokio::test]
    async fn a_throttled_author_lookup_inside_a_thread_does_not_end_the_sweep() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        host.set_user_name("acme", "U9", "colleague");
        host.seed_replies("C1", "100.0", vec![reply("150.0", "100.0", "U8", "the answer")]);
        host.seed_replies("C1", "200.0", vec![reply("250.0", "200.0", "U9", "the other answer")]);
        for parent in ["100.0", "200.0"] {
            host.follow_thread(
                "acme",
                "C1",
                parent,
                thread_owner("forge", Some("tester")),
                "050.0",
            );
            host.mark_thread_participating("acme", "C1", parent);
        }
        host.rate_limit_user_info(Duration::from_secs(7));

        let outcome = sweep(&host, &host, "acme").await.expect("a 429 is not an error");

        assert_eq!(
            outcome.rate_limited,
            Some(Duration::from_secs(7)),
            "the throttle reaches the pump",
        );
        assert_eq!(host.replies_calls(), 2, "the walk moved on to the second thread");
        assert_eq!(
            host.delivered().len(),
            1,
            "the thread whose author is known still delivered: {:?}",
            host.delivered(),
        );
    }

    /// A thread past the page cap cannot advance its cursor: the partial read
    /// is a refusal, so the replies past the cap are not skipped for good.
    #[tokio::test]
    async fn a_thread_past_the_page_cap_holds_its_cursor() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![]);
        let pages: Vec<Vec<SlackHistoryMessage>> = (0..=MAX_REPLY_PAGES)
            .map(|n| vec![reply(&format!("{}.0", 200 + n), "100.0", "U8", "a reply")])
            .collect();
        host.seed_replies_pages("C1", "100.0", pages);
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "050.0");
        host.mark_thread_participating("acme", "C1", "100.0");

        sweep(&host, &host, "acme").await.expect("a truncated walk is not a sweep error");

        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0").as_deref(),
            Some("050.0"),
            "a partial read cannot advance the cursor",
        );
        assert!(host.delivered().is_empty(), "nothing from a partial read is delivered");
        assert!(
            host.thread_first_walks.lock().expect("lock").contains("acme/C1/100.0"),
            "and the first walk is not spent on a refusal",
        );
        assert!(
            host.thread_full_read_at("acme", "C1", "100.0").is_some(),
            "the failed attempt is stamped, so the next tick does not walk 200 pages again",
        );

        // The first-walk mark is still set, so the next tick would read whole
        // again without the stamp gating it; with the stamp it costs nothing.
        let calls = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("the tick after the refusal");
        assert_eq!(
            host.replies_calls(),
            calls,
            "a refused first walk backs off instead of re-walking 200 pages",
        );
    }

    /// The mention sweep's own-name lookup is a call like any other: a 429
    /// arms the pump's backoff rather than delivering the app's name.
    #[tokio::test]
    async fn a_throttled_own_name_in_the_mention_sweep_backs_off() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        let mut hit = search_match("200.1", "C1", "note to self <@U1>");
        hit.user = Some("U1".to_owned());
        hit.username = Some("Forge".to_owned());
        host.seed_search(vec![hit]);
        host.rate_limit_auth_test(Duration::from_secs(9));

        let outcome = sweep_mentions(&host, &host, "acme").await.expect("a 429 is not an error");

        assert_eq!(
            outcome.rate_limited,
            Some(Duration::from_secs(9)),
            "the throttle reaches the pump",
        );
        assert!(host.delivered().is_empty(), "nothing is delivered without the name");
    }

    /// The pin that would have caught the original Critical: the trigger
    /// sweep delivers a parent, and a reply that arrives on a LATER sweep
    /// still reaches the owning session - the parent has aged past the
    /// conversation watermark by then, so only the thread cursor reaches
    /// it.
    #[tokio::test]
    async fn a_reply_arriving_on_the_sweep_after_the_trigger_delivers_to_the_owning_session() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);

        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(host.delivered()[0].ts, "100.0", "the trigger itself is delivered");
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("105.0".to_owned()),
            "and the walk has read his own reply, so the cursor is past it",
        );

        // The reply arrives afterwards, already carrying an edit: a
        // correction made before the sweep ever read the reply. History
        // has nothing new; only the followed thread's own walk can reach
        // it.
        let mut arriving = history_message("150.0", "U8", "the reply");
        arriving.edited = Some("160.0".to_owned());
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent, history_message("105.0", "U1", "the user's own reply"), arriving],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        let delivered = host.delivered();
        let replies: Vec<&SlackMessage> =
            delivered.iter().filter(|message| message.ts == "150.0").collect();
        assert_eq!(replies.len(), 1, "the reply is delivered once");
        assert_eq!(replies[0].thread_ts.as_deref(), Some("100.0"), "as a reply of its thread");
        assert_eq!(
            replies[0].edited.as_deref(),
            Some("160.0"),
            "and the walk's delivery carries the edit ts",
        );
        assert_eq!(
            host.delivered_owners().last().map(|owner| owner.team_role.clone()),
            Some(Some("tester".to_owned())),
            "the reply reaches the OWNING session",
        );
        assert_eq!(
            delivered.iter().filter(|message| message.ts == "100.0").count(),
            1,
            "the repeated parent is deduped",
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("160.0".to_owned()),
            "the thread cursor clears the delivered reply's edit too, so the next tick does not \
             re-offer it",
        );
    }

    /// Fan-out on threads delivers to every owner in the record, the way
    /// a conversation's batch delivers to every matching subscription -
    /// and one owner's failed delivery holds the cursor below the reply
    /// instead of losing it.
    #[tokio::test]
    async fn every_owner_gets_a_thread_reply_and_a_failure_holds_the_cursor() {
        let host = FakeHost::with_subscriptions(vec![
            sub_conversation_owned_by("acme", "forge", Some("a"), "C1"),
            sub_conversation_owned_by("acme", "forge", Some("b"), "C1"),
        ]);
        let parent = parent_with_replies("100.0", 1);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(
            host.followed_threads("acme", "C1").first().map(|thread| thread.owners.len()),
            Some(2),
            "both sessions own the thread after both were delivered the trigger",
        );

        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                history_message("150.0", "U8", "the reply"),
            ],
        );
        // Attempts so far: the parent went to a then b. The reply's FIRST
        // owner delivery (a) fails, so the cursor must not advance even
        // though b receives it.
        host.fail_delivery_at(2);
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert_eq!(
            host.delivered().iter().filter(|message| message.ts == "150.0").count(),
            1,
            "the owner whose delivery succeeded still received the reply",
        );
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("105.0".to_owned()),
            "the cursor stays below a reply that did not reach every owner",
        );
    }

    /// A `mentions`-mode subscription asked to be told when it is named. It
    /// does not own the threads the sweep anchors - or every reply in every
    /// thread of that channel would arrive at a session that asked for
    /// mentions, and the match that decides a delivery would never be asked.
    #[tokio::test]
    async fn a_mentions_only_subscription_owns_no_thread() {
        let host =
            FakeHost::with_subscriptions(vec![sub_for(SlackSubscriptionTarget::Conversation {
                id: "C1".to_owned(),
                name: None,
                mode: SlackWatchMode::MentionsOnly,
            })]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent.clone(), history_message("105.0", "U1", "the user's own reply")],
        );
        sweep(&host, &host, "acme").await.expect("trigger sweep");

        assert!(
            host.followed_threads("acme", "C1").is_empty(),
            "the mentions subscription owns no thread",
        );

        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "an answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert!(
            !host.delivered().iter().any(|message| message.ts == "150.0"),
            "and a reply in it reaches nobody who asked for mentions only: {:?}",
            host.delivered(),
        );
    }

    /// A thread's new replies arrive as one block per owner, the shape the
    /// conversation batch delivers, so a live thread and a sleeping session's
    /// regrouped block read the same way.
    #[tokio::test]
    async fn a_thread_walks_replies_arrive_as_one_block_per_owner() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 3);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        let blocks_before = host.batches().len();

        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "one"),
                reply("160.0", "100.0", "U8", "two"),
                reply("170.0", "100.0", "U8", "three"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        let batches = host.batches();
        assert_eq!(batches.len(), blocks_before + 1, "one block, never one per reply");
        assert_eq!(batches.last().map(Vec::len), Some(3), "holding every reply the walk had");
    }

    /// Being named in a thread puts the user in it, without a reply of his
    /// own: that is the other half of the spec's rule, and the half a later
    /// reader is likeliest to simplify away.
    #[tokio::test]
    async fn a_thread_the_user_is_only_mentioned_in_delivers() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U9", "hey <@U1>, look at this"),
                reply("150.0", "100.0", "U8", "the answer"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "a thread he is named in delivers what follows: {:?}",
            host.delivered(),
        );
    }

    /// A subscription starts at its cursor; the thread anchor must not start
    /// below it. A thread first followed on that sweep seeds its newest reply,
    /// which can predate the subscription, and the thread walk filters by that
    /// cursor alone - so the reply lands though the channel read had already
    /// passed it. The floor must not stop the thread delivering once it moves.
    #[tokio::test]
    async fn a_thread_first_followed_does_not_start_below_the_conversation_cursor() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.set_watermark("acme", "C1", "200.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent.clone(),
                history_message("120.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "posted before the subscription"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("sweep");

        assert!(
            !host.delivered().iter().any(|message| message.ts == "150.0"),
            "a reply older than the conversation cursor is not news: {:?}",
            host.delivered(),
        );
        assert!(
            host.thread_cursor("acme", "C1", "100.0")
                .as_deref()
                .is_some_and(|cursor| cursor == "200.0"),
            "the first follow never starts below the conversation cursor: {:?}",
            host.thread_cursor("acme", "C1", "100.0"),
        );

        // The thread moves past the cursor: the walk runs and must deliver the
        // newest reply, while the reply behind the cursor stays out.
        let moved = parent_with_latest_reply("100.0", 3, "250.0");
        host.seed_history("C1", vec![moved.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                moved,
                history_message("120.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "posted before the subscription"),
                reply("250.0", "100.0", "U8", "posted after the subscription"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("moved sweep");

        let delivered = host.delivered();
        assert!(
            delivered.iter().any(|message| message.ts == "250.0"),
            "the first follow still delivers a thread that moves: {delivered:?}",
        );
        assert!(
            !delivered.iter().any(|message| message.ts == "150.0"),
            "the reply behind the cursor stays out: {delivered:?}",
        );
    }

    /// The floor is a floor, not a replacement: a thread whose newest reply
    /// is above the conversation cursor still starts below that reply, so the
    /// reply that brought it in is delivered and older ones are not.
    #[tokio::test]
    async fn a_thread_first_followed_above_the_cursor_seeds_below_its_newest_reply() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_latest_reply("100.0", 3, "250.0");
        host.set_watermark("acme", "C1", "150.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("200.0", "U1", "the user's own reply"),
                reply("230.0", "100.0", "U8", "older than the newest reply"),
                reply("250.0", "100.0", "U8", "the reply that brought the thread in"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("sweep");

        let delivered_messages = host.delivered();
        let delivered: Vec<&str> =
            delivered_messages.iter().map(|message| message.ts.as_str()).collect();
        assert!(delivered.contains(&"250.0"), "the newest reply is delivered: {delivered:?}");
        assert!(
            !delivered.contains(&"230.0"),
            "a reply below the newest reply is not news on a first follow: {delivered:?}",
        );
    }

    /// The seed only decides where a NEW row starts. A thread already followed
    /// keeps the cursor it has, so a reply between that cursor and the
    /// conversation cursor is still delivered.
    #[tokio::test]
    async fn an_existing_thread_keeps_its_cursor_when_the_conversation_moves() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_latest_reply("100.0", 2, "250.0");
        host.set_watermark("acme", "C1", "300.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("160.0", "U1", "the user's own reply"),
                reply("170.0", "100.0", "U8", "between the thread and conversation cursors"),
                reply("250.0", "100.0", "U8", "the newest reply"),
            ],
        );
        host.follow_thread("acme", "C1", "100.0", thread_owner("forge", Some("tester")), "150.0");
        host.mark_thread_participating("acme", "C1", "100.0");

        sweep(&host, &host, "acme").await.expect("sweep");

        let delivered = host.delivered();
        assert!(
            delivered.iter().any(|message| message.ts == "170.0"),
            "the row's own cursor governs, not the conversation's: {delivered:?}",
        );
        assert!(
            delivered.iter().any(|message| message.ts == "250.0"),
            "and the thread keeps delivering: {delivered:?}",
        );
    }

    /// Delivering every thread that had a message would deliver replies from
    /// threads the user is not in - which is every thread in the workspace.
    #[tokio::test]
    async fn a_thread_the_user_is_absent_from_delivers_nothing() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        sweep(&host, &host, "acme").await.expect("trigger sweep");

        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U9", "one"),
                reply("150.0", "100.0", "U8", "two"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert!(
            !host.delivered().iter().any(|message| message.ts == "150.0"),
            "a thread the user is not in stays silent: {:?}",
            host.delivered(),
        );
    }

    /// His own reply is usually BEHIND the thread's cursor by the time
    /// anyone answers him, which is why the walk reads the whole thread
    /// rather than only the page after the cursor.
    #[tokio::test]
    async fn a_user_reply_behind_the_thread_cursor_still_marks_the_thread() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        sweep(&host, &host, "acme").await.expect("trigger sweep");

        // The thread has moved on since, so the cursor is past his reply.
        host.set_thread_watermark("acme", "C1", "100.0", "140.0");
        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "what was said next"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "his reply behind the cursor still puts him in the thread: {:?}",
            host.delivered(),
        );
    }

    /// The sequence that actually happens: a root lands, the user replies in
    /// it from the Slack app minutes later, and someone answers him.
    ///
    /// Nothing anchors the thread on the tick that delivers the root - it has
    /// no replies yet - and history never returns a reply, so by the time he
    /// replies the root is behind the cursor for good. The only place the
    /// thread is visible again is its parent reappearing in the window with
    /// `latest_reply` set, which is what the sweep now reads.
    #[tokio::test]
    async fn an_answer_to_a_root_that_had_no_replies_yet_is_delivered() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        host.set_watermark("acme", "C1", "050.0");
        let root = history_message("100.0", "U1", "deploy is green");
        host.seed_history("C1", vec![root]);
        sweep(&host, &host, "acme").await.expect("the root's sweep");
        assert_eq!(
            host.delivered().first().map(|message| message.ts.as_str()),
            Some("100.0"),
            "his own message is delivered: it is his side of the thread",
        );
        assert!(
            host.followed_threads("acme", "C1").is_empty(),
            "a message with no replies anchors nothing",
        );

        // He replies, and someone answers him.
        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "my own reply"),
                reply("150.0", "100.0", "U8", "the answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("the answer's sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "the answer to his own reply is delivered: {:?}",
            host.delivered(),
        );

        // A thread the user is in is read on every tick, even when the
        // window says it has not moved: an edit moves nothing, so the read
        // is the only way a correction reaches him. The window's skip still
        // spares a thread he is NOT in, which its own test pins.
        let calls = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("a quiet sweep");
        assert_eq!(host.replies_calls(), calls + 1, "a participating thread is read every tick");

        // A later reply still arrives. The whole thread comes back, his own
        // reply included - the thread is known to be one he is in, and that
        // has to be what decides.
        let parent = parent_with_latest_reply("100.0", 3, "170.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![parent, reply("170.0", "100.0", "U8", "the next one")],
        );
        sweep(&host, &host, "acme").await.expect("another sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "170.0"),
            "a thread the user is already known to be in keeps delivering: {:?}",
            host.delivered(),
        );
    }

    /// A thread the user started is one he is in, and Slack subscribes him
    /// to its replies. His own message is delivered now, and the colleague
    /// answering it must arrive too.
    #[tokio::test]
    async fn a_colleagues_reply_under_the_users_own_message_is_delivered() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let mut mine = parent_with_replies("100.0", 1);
        mine.user = Some("U1".to_owned());
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![mine.clone()]);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(
            host.delivered().first().map(|message| message.ts.as_str()),
            Some("100.0"),
            "his own message is delivered",
        );

        host.seed_history("C1", vec![]);
        host.seed_replies("C1", "100.0", vec![mine, reply("150.0", "100.0", "U8", "the answer")]);
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "150.0"),
            "the answer to his own message arrives: {:?}",
            host.delivered(),
        );
    }

    /// An author Slack knows nothing about is asked about once, not once per
    /// message: that answer is settled, so it is worth keeping.
    #[tokio::test]
    async fn a_settled_absent_author_is_looked_up_once() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("200.0", "U9", "first")]);
        sweep(&host, &host, "acme").await.expect("first sweep");
        assert_eq!(host.user_info_calls(), 1, "one author, one lookup");

        host.seed_history("C1", vec![history_message("400.0", "U9", "a later one")]);
        sweep(&host, &host, "acme").await.expect("second sweep");
        assert_eq!(
            host.user_info_calls(),
            1,
            "and the settled answer is kept, or every message from him costs a call",
        );
    }

    /// A lookup that failed for any reason but a settled one says nothing
    /// about the user, so nothing is kept and the next sweep asks again.
    #[tokio::test]
    async fn a_transient_author_lookup_failure_is_retried_not_kept() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("200.0", "U9", "first")]);
        host.fail_user_info_transiently();

        sweep(&host, &host, "acme").await.expect("a failed lookup is not a failed sweep");
        assert_eq!(host.user_info_calls(), 1, "the author is asked about");
        assert!(
            host.resolved_names().is_empty(),
            "and nothing about him is remembered: {:?}",
            host.resolved_names(),
        );

        host.seed_history("C1", vec![history_message("400.0", "U9", "a later one")]);
        sweep(&host, &host, "acme").await.expect("the next sweep");
        assert_eq!(host.user_info_calls(), 2, "so the next sweep asks again");
    }

    /// Two messages from one author in one tick cost one lookup, failing or
    /// not: the sweep's own memo is what keeps a broken lookup from becoming
    /// a call per message.
    #[tokio::test]
    async fn two_messages_from_a_failing_author_cost_one_lookup() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history(
            "C1",
            vec![history_message("300.0", "U9", "second"), history_message("200.0", "U9", "first")],
        );
        host.fail_user_info_transiently();

        sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(host.user_info_calls(), 1, "one author, one lookup, two messages");
    }

    /// A rate limit on a lookup belongs to the sweep, not to the lookup: the
    /// pump must back off the way it does for every other call.
    #[tokio::test]
    async fn a_rate_limited_author_lookup_is_reported_to_the_pump() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("200.0", "U9", "hello")]);
        host.rate_limit_user_info(Duration::from_secs(9));

        let outcome = sweep(&host, &host, "acme").await.expect("a 429 is not an error");
        assert_eq!(
            outcome.rate_limited,
            Some(Duration::from_secs(9)),
            "a throttled lookup arms the pump's backoff instead of being swallowed",
        );
    }

    /// The identity fetch is a call like any other, so its 429 arms the
    /// pump's backoff too rather than being read as "no name".
    #[tokio::test]
    async fn a_rate_limited_auth_test_is_reported_to_the_pump() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        let mut message = history_message("200.0", "U1", "hello");
        message.bot_name = Some("Forge".to_owned());
        host.seed_history("C1", vec![message]);
        host.rate_limit_auth_test(Duration::from_secs(7));

        let outcome = sweep(&host, &host, "acme").await.expect("a 429 is not an error");
        assert_eq!(
            outcome.rate_limited,
            Some(Duration::from_secs(7)),
            "a throttled auth.test arms the pump's backoff instead of being swallowed",
        );
    }

    /// A thread the user is not in is read once when it moves and then left
    /// alone: the cursor advances over what was read even though nothing was
    /// delivered, which is what lets the window's `latest_reply` say the
    /// thread has not moved and cost no call at all.
    #[tokio::test]
    async fn a_thread_the_user_is_not_in_is_read_once_then_left_alone() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(host.thread_cursor("acme", "C1", "100.0"), Some("100.0".to_owned()));

        let parent = parent_with_latest_reply("100.0", 2, "150.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U9", "one"),
                reply("150.0", "100.0", "U8", "someone else"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("150.0".to_owned()),
            "the cursor advances over what was read, delivered or not",
        );

        let calls = host.replies_calls();
        sweep(&host, &host, "acme").await.expect("a quiet sweep");
        assert_eq!(host.replies_calls(), calls, "and the thread is not read again until it moves");
    }

    /// The walk's replies are usually from people who posted nothing in the
    /// channel this tick, so their names are resolved the same way a batch's
    /// are. Without that the block drops the author entirely, which is the
    /// defect this work exists to fix, on the one path it makes visible.
    #[tokio::test]
    async fn a_thread_walks_replies_carry_a_resolved_author() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_user_name("U8", "colleague");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");

        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                reply("150.0", "100.0", "U8", "what was said next"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert_eq!(
            host.delivered()
                .iter()
                .find(|message| message.ts == "150.0")
                .and_then(|message| message.author.as_deref()),
            Some("colleague"),
            "the reply's author is a name, not the id the block would drop",
        );
    }

    /// The user's reply usually arrives long after the sweep read past the
    /// parent, and history never returns replies - so the parent is below
    /// the conversation cursor forever and the thread's own walk is the only
    /// place either message is ever visible.
    #[tokio::test]
    async fn a_thread_the_user_replies_in_after_the_parent_left_the_page_still_delivers() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 1);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        host.seed_replies("C1", "100.0", vec![parent.clone()]);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(host.delivered().len(), 1, "the parent itself is delivered");

        // Nobody was in the thread when it was delivered. The user replies
        // afterwards, and someone answers him.
        host.seed_history("C1", vec![]);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                reply("150.0", "100.0", "U1", "my own reply"),
                reply("160.0", "100.0", "U8", "the answer"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert!(
            host.delivered().iter().any(|message| message.ts == "160.0"),
            "the answer to the user's own reply is delivered: {:?}",
            host.delivered(),
        );
    }

    /// Pin the user into a thread's replies before a trigger sweep. A
    /// parent reporting replies it does not have is a shape Slack never
    /// sends, and it is the replies fetch that tells the sweep the user is
    /// in the thread.
    fn seed_user_participation(host: &FakeHost, parent: &SlackHistoryMessage) {
        host.seed_replies(
            "C1",
            &parent.ts,
            vec![parent.clone(), history_message("105.0", "U1", "the user's own reply")],
        );
    }

    /// The search path sends a handle alongside the id, and the mention
    /// sweep has it for free.
    #[tokio::test]
    async fn a_mention_delivers_the_username_slack_sent() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        let mut hit = search_match("200.1", "C1", "ping <@U1>");
        hit.username = Some("architect".to_owned());
        host.seed_search(vec![hit]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(
            host.delivered()[0].author.as_deref(),
            Some("architect"),
            "the handle Slack sent is what the block shows",
        );
    }

    /// The user writes to himself from the Slack app, so the search hit's
    /// `username` can be the app's name - the same `Forge: ...` label the
    /// conversation path already refuses for that id. His own id is
    /// recognised before the wire's handle is believed, and the sweep asks
    /// `auth.test` once however many of his own mentions it carries.
    #[tokio::test]
    async fn the_users_own_mention_takes_his_name_over_the_apps() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        let mut first = search_match("300.2", "C1", "note to self <@U1>");
        first.user = Some("U1".to_owned());
        first.username = Some("Forge".to_owned());
        let mut second = search_match("200.1", "C2", "another <@U1>");
        second.user = Some("U1".to_owned());
        second.username = Some("Forge".to_owned());
        host.seed_search(vec![first, second]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");

        let delivered = host.delivered();
        assert_eq!(delivered.len(), 2, "both of his own mentions arrive");
        assert!(
            delivered.iter().all(|message| message.author.as_deref() == Some("tester")),
            "his own mentions carry his handle, not the app's name: {delivered:?}",
        );
        assert_eq!(host.auth_test_calls(), 1, "one identity for the sweep, not one per hit");
    }

    /// A conversation's message carries a bare id, so the name has to be
    /// looked up - once per user, since a lookup is a call.
    #[tokio::test]
    async fn a_conversation_message_resolves_its_author_once_per_user() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_user_name("U9", "ved");
        host.seed_history(
            "C1",
            vec![history_message("300.0", "U9", "second"), history_message("200.0", "U9", "first")],
        );

        sweep(&host, &host, "acme").await.expect("sweep");

        let delivered = host.delivered();
        assert_eq!(delivered.len(), 2, "both messages are delivered");
        assert!(
            delivered.iter().all(|message| message.author.as_deref() == Some("ved")),
            "each carries the resolved handle: {delivered:?}",
        );
        assert_eq!(host.user_info_calls(), 1, "the second message costs no lookup");
    }

    /// A bot's name rides the message itself, so it costs nothing at all.
    #[tokio::test]
    async fn a_bot_message_takes_its_name_from_the_payload() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        let mut message = history_message("300.0", "U0ATEK2EAGP", "transfer");
        message.bot_name = Some("architect2".to_owned());
        host.seed_history("C1", vec![message]);

        sweep(&host, &host, "acme").await.expect("sweep");

        assert_eq!(
            host.delivered()[0].author.as_deref(),
            Some("architect2"),
            "a bot names itself, and the block shows that",
        );
        assert_eq!(host.user_info_calls(), 0, "a bot's name is free");
    }

    /// The user posts from the Slack app, so his message carries the app's
    /// `bot_profile`. Believing it labels his words with the app's name, so
    /// his own id is recognised first and the name comes from `auth.test`.
    #[tokio::test]
    async fn the_users_own_message_takes_his_name_over_the_apps() {
        let host = FakeHost::with_subscriptions(vec![
            sub_channel("acme", "C1", SlackWatchMode::All),
            sub_channel("acme", "C2", SlackWatchMode::All),
        ]);
        host.set_watermark("acme", "C1", "050.0");
        host.set_watermark("acme", "C2", "050.0");
        let mut first = history_message("200.0", "U1", "once I do e2e testing, we should be good");
        first.bot_name = Some("Forge".to_owned());
        let mut second = history_message("300.0", "U1", "then production");
        second.bot_name = Some("Forge".to_owned());
        host.seed_history("C1", vec![first]);
        host.seed_history("C2", vec![second]);

        sweep(&host, &host, "acme").await.expect("sweep");

        let delivered = host.delivered();
        assert_eq!(delivered.len(), 2, "both conversations are delivered");
        assert!(
            delivered.iter().all(|message| message.author.as_deref() == Some("tester")),
            "his own messages carry his handle, not the app's name: {delivered:?}",
        );
        assert_eq!(
            host.auth_test_calls(),
            1,
            "one identity for the sweep, not one per message or per conversation",
        );
        assert_eq!(host.user_info_calls(), 0, "his own handle costs no users.info call");
    }

    /// The name a good `auth.test` gave is kept on the host, so a later
    /// sweep whose call blips still shows his handle rather than the app's.
    #[tokio::test]
    async fn a_later_failed_auth_test_keeps_the_name_already_learned() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        let mut first = history_message("200.0", "U1", "first");
        first.bot_name = Some("Forge".to_owned());
        host.seed_history("C1", vec![first]);
        sweep(&host, &host, "acme").await.expect("first sweep");
        assert_eq!(
            host.delivered().last().and_then(|message| message.author.as_deref()),
            Some("tester"),
            "the first sweep learns his handle",
        );

        host.fail_auth_test_transiently();
        let mut second = history_message("300.0", "U1", "second");
        second.bot_name = Some("Forge".to_owned());
        host.seed_history("C1", vec![second]);
        sweep(&host, &host, "acme").await.expect("second sweep");
        assert_eq!(
            host.delivered().last().and_then(|message| message.author.as_deref()),
            Some("tester"),
            "a failed auth.test does not bring the app's name back; the host remembers his",
        );
    }

    /// An author the token cannot look up keeps no name, so the block falls
    /// back to dropping the id rather than inventing one.
    #[tokio::test]
    async fn an_unresolvable_author_keeps_no_name() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("300.0", "U9", "hello")]);

        sweep(&host, &host, "acme").await.expect("sweep");

        assert_eq!(host.delivered()[0].author, None, "no name is invented for a failed lookup");
        assert_eq!(
            host.delivered()[0].user.as_deref(),
            Some("U9"),
            "and the id is still there for the block",
        );
    }

    /// A plain top-level message anchors nothing, or every message would
    /// grow the tracked set.
    #[tokio::test]
    async fn a_plain_message_follows_no_thread() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme", "forge", None, "C1",
        )]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("100.0", "U9", "plain")]);

        sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(host.delivered().len(), 1, "the message itself is delivered");
        assert!(
            host.followed_threads("acme", "C1").is_empty(),
            "a message with no thread and no replies anchors nothing",
        );
    }

    /// A mention inside a thread anchors that thread for the mention
    /// subscription's owner, so the back and forth continues under the
    /// parent.
    #[tokio::test]
    async fn a_mention_in_a_thread_anchors_that_thread() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.set_watermark("acme", MENTION_CURSOR, "100.0");
        let mut hit = search_match("150.0", "C1", "ping <@U1>");
        hit.thread_ts = Some("99.0".to_owned());
        host.seed_search(vec![hit]);

        sweep_mentions(&host, &host, "acme").await.expect("mention sweep");
        let threads = host.followed_threads("acme", "C1");
        assert_eq!(threads.len(), 1, "the thread of the mention is tracked");
        assert_eq!(threads[0].parent_ts, "99.0");
        assert_eq!(threads[0].owners, vec![thread_owner("forge", None)]);
        assert_eq!(
            host.thread_cursor("acme", "C1", "99.0"),
            Some("150.0".to_owned()),
            "the cursor starts at the mention's ts, never the weeks-old parent",
        );
    }

    /// A caller reading the thread, rather than advancing a cursor, gets the
    /// parent once: Slack repeats it at the top of every page, and the tool's
    /// contract says "parent first, then every reply oldest first".
    #[tokio::test]
    async fn read_thread_returns_the_parent_once_across_pages() {
        let host = FakeHost::with_subscriptions(Vec::new());
        let parent = parent_with_replies("100.0", 2);
        host.seed_replies_pages(
            "C1",
            "100.0",
            vec![
                vec![parent.clone(), history_message("110.0", "U1", "first reply")],
                vec![parent, history_message("120.0", "U1", "second reply")],
            ],
        );

        let thread = read_thread(&host, "C1", "100.0", 200).await.expect("the thread is read");
        let ts: Vec<&str> = thread.iter().map(|message| message.ts.as_str()).collect();
        assert_eq!(
            ts,
            ["100.0", "110.0", "120.0"],
            "the parent appears once and every reply follows it in order",
        );
    }

    /// A thread read stops at the requested count rather than serialising a
    /// whole long thread into one result.
    #[tokio::test]
    async fn read_thread_stops_at_the_limit() {
        let host = FakeHost::with_subscriptions(Vec::new());
        let parent = parent_with_replies("100.0", 2);
        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("110.0", "U1", "first reply"),
                history_message("120.0", "U1", "second reply"),
            ],
        );

        let thread = read_thread(&host, "C1", "100.0", 2).await.expect("the thread is read");

        assert_eq!(thread.len(), 2, "the limit bounds the read");
        assert_eq!(thread[1].ts, "110.0", "and keeps the oldest reply that fit");
    }

    /// Slack repeats the parent on every page of a thread (measured live at
    /// limit=3, and again in this PR's captured fixture). The walk must page
    /// to the end, dedupe the parent on each page, and lose nothing at the
    /// boundary.
    #[tokio::test]
    async fn a_thread_walk_pages_to_the_end_deduping_the_parent() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 3);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");

        host.seed_replies_pages(
            "C1",
            "100.0",
            vec![
                vec![
                    parent.clone(),
                    history_message("105.0", "U1", "the user's own reply"),
                    history_message("300.0", "U8", "reply three"),
                ],
                vec![
                    parent,
                    history_message("200.0", "U8", "reply two"),
                    history_message("150.0", "U8", "reply one"),
                ],
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        let delivered = host.delivered();
        let seen_ts = |ts: &str| delivered.iter().filter(|message| message.ts == ts).count();
        assert_eq!(seen_ts("100.0"), 1, "the parent is delivered once, never per page");
        assert_eq!(seen_ts("300.0"), 1, "the newest page's reply arrives");
        assert_eq!(seen_ts("200.0"), 1, "the older page's replies arrive too");
        assert_eq!(seen_ts("150.0"), 1, "nothing is lost at the page boundary");
        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("300.0".to_owned()),
            "the cursor lands on the newest reply",
        );
    }

    /// Replies never appear in history, so this walk is the one path that
    /// sees the agent's own answers to the threads it anchors - and a
    /// ledgered one must not come back, or an agent answering the echo
    /// answers itself. Ved's own reply carries no ledger row and arrives.
    #[tokio::test]
    async fn the_thread_walk_refuses_the_agents_ledgered_reply_not_the_users_own() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        host.record_own_post("acme", "C1", "150.0");

        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("150.0", "U1", "the agent's own reply"),
                history_message("140.0", "U8", "someone else's reply"),
                history_message("160.0", "U1", "what Ved typed"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        let delivered = host.delivered();
        assert!(
            !delivered.iter().any(|message| message.text == "the agent's own reply"),
            "the agent's own reply must not echo back: {delivered:?}",
        );
        assert!(
            delivered.iter().any(|message| message.text == "what Ved typed"),
            "the user's own reply is delivered: {delivered:?}",
        );
        assert!(
            delivered.iter().any(|message| message.text == "someone else's reply"),
            "and everyone else's replies still arrive",
        );
    }

    /// The thread walk's failure hold: the block is handed over whole, so a
    /// failure means none of it landed, and any cursor advance would jump
    /// above replies that did not reach every owner.
    #[tokio::test]
    async fn a_thread_walk_failure_holds_the_cursor_at_its_previous_value() {
        let host = FakeHost::with_subscriptions(vec![sub_conversation_owned_by(
            "acme",
            "forge",
            Some("tester"),
            "C1",
        )]);
        let parent = parent_with_replies("100.0", 2);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![parent.clone()]);
        seed_user_participation(&host, &parent);
        sweep(&host, &host, "acme").await.expect("trigger sweep");
        assert_eq!(host.thread_cursor("acme", "C1", "100.0"), Some("105.0".to_owned()));

        host.seed_replies(
            "C1",
            "100.0",
            vec![
                parent,
                history_message("105.0", "U1", "the user's own reply"),
                history_message("300.0", "U8", "newer reply"),
                history_message("200.0", "U8", "older reply fails"),
            ],
        );
        // Attempts: the trigger (0), then the walk's one block (1) fails.
        host.fail_delivery_at(1);
        sweep(&host, &host, "acme").await.expect("follow-up sweep");

        assert_eq!(
            host.thread_cursor("acme", "C1", "100.0"),
            Some("105.0".to_owned()),
            "the walk's cursor holds below the failed block instead of jumping past it",
        );
    }

    /// Two owners asking to be told are two owners: every Mentions
    /// subscription gets the hit, not whichever sorted first.
    #[tokio::test]
    async fn a_mention_reaches_every_mentions_subscription() {
        let host = FakeHost::with_subscriptions(vec![
            sub_conversation_owned_by("acme", "forge", Some("a"), "C1"),
            {
                let mut sub = sub_mentions("acme");
                sub.team_role = Some("a".to_owned());
                sub
            },
            {
                let mut sub = sub_mentions("acme");
                sub.team_role = Some("b".to_owned());
                sub
            },
        ]);
        host.set_watermark("acme", MENTION_CURSOR, "100.0");
        host.seed_search(vec![search_match("150.0", "C9", "ping <@U1>")]);

        sweep_mentions(&host, &host, "acme").await.expect("sweep");
        let owners: Vec<Option<String>> =
            host.delivered_owners().iter().map(|owner| owner.team_role.clone()).collect();
        assert!(
            owners.iter().any(|role| role.as_deref() == Some("a")),
            "the first owner receives the mention: {owners:?}",
        );
        assert!(
            owners.iter().any(|role| role.as_deref() == Some("b")),
            "the second mention subscription is not starved: {owners:?}",
        );
    }

    /// Without the id there is no mention query and no participation
    /// signal to read. The sweep fails quiet-but-visible instead.
    #[tokio::test]
    async fn an_unresolved_user_id_skips_the_conversation_sweep() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.set_user_id(None);
        host.seed_history("D1", vec![history_message("300.0", "U9", "pending")]);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 0, "nothing is delivered half-blind");
        assert!(host.delivered().is_empty(), "the pending window is not swept without the id");
        assert_eq!(
            host.watermark("acme", "D1").expect("watermark"),
            None,
            "and the cursor is untouched, so the next sweep picks the window up",
        );
    }

    /// A conversation deleted on Slack's side never delivers again, and
    /// the pump's Ok arm must not write the glyph straight back up after
    /// the sweep has flipped it down - pinned through the PUMP, where the
    /// clobbering happens, never through `sweep()` directly.
    #[tokio::test]
    async fn a_deleted_conversation_flips_the_glyph_down_through_the_pump() {
        // The DM class is subscribed with news of its own, so its pass runs
        // on the same workspace while the glyph is down: a DM pass that wrote
        // the glyph back up would hide a dead conversation.
        let host = Arc::new(FakeHost::with_subscriptions(vec![
            sub_channel("acme", "C1", SlackWatchMode::All),
            sub_dm("acme"),
        ]));
        FakeHost::set_api_self(&host);
        host.set_watermark("acme", "C1", "050.0");
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history("D1", vec![history_message("200.0", "U9", "a dm")]);
        host.fail_history_with(
            "C1",
            SlackError::Api {
                method: "conversations.history".to_owned(),
                error: "channel_not_found".to_owned(),
                needed: None,
            },
        );

        let (tx, rx) = oneshot::channel();
        let pump = tokio::spawn(run_workspace_pump(host.clone(), "acme".to_owned(), 1, 1, rx));
        // The pump's first tick fires after one interval; wait until the
        // glyph write has landed.
        for _ in 0..60 {
            tokio::time::sleep(Duration::from_millis(50)).await;
            if host.connected().is_some() {
                break;
            }
        }

        assert_eq!(
            host.connected(),
            Some(false),
            "a dead conversation must not read as a connected row after a wired tick",
        );

        tx.send(()).expect("signal shutdown");
        tokio::time::timeout(Duration::from_secs(2), pump)
            .await
            .expect("the pump must not outlive its shutdown")
            .expect("no panic");
    }

    /// The Slackbot conversation answers channel_not_found to a user
    /// token forever, a Slack quirk rather than a dead channel: a
    /// workspace whose only sweep failure is that DM reads connected,
    /// and its other DMs still deliver. Pinned through the PUMP, where
    /// the glyph write happens.
    #[tokio::test]
    async fn a_slackbot_dm_channel_not_found_leaves_the_glyph_connected() {
        let host = Arc::new(FakeHost::with_subscriptions(vec![sub_dm("acme")]));
        FakeHost::set_api_self(&host);
        // The Slackbot-shaped DM: listed, watermarked, never readable.
        host.seed_history("D1", vec![]);
        host.set_watermark("acme", "D1", "050.0");
        host.fail_history_with(
            "D1",
            SlackError::Api {
                method: "conversations.history".to_owned(),
                error: "channel_not_found".to_owned(),
                needed: None,
            },
        );
        // A readable DM beside it, so the tick provably sweeps instead
        // of passing on an unexercised outcome.
        host.seed_history("D2", vec![history_message("200.0", "U9", "hello from a dm")]);
        host.set_watermark("acme", "D2", "100.0");

        let (tx, rx) = oneshot::channel();
        let pump = tokio::spawn(run_workspace_pump(host.clone(), "acme".to_owned(), 1, 1, rx));
        for _ in 0..60 {
            tokio::time::sleep(Duration::from_millis(50)).await;
            if host.connected().is_some() {
                break;
            }
        }

        assert!(
            !host.delivered().is_empty(),
            "the tick ran and delivered the readable DM: {:?}",
            host.delivered(),
        );
        assert_eq!(
            host.connected(),
            Some(true),
            "the unreadable DM is a known quirk, not a dead connector",
        );

        tx.send(()).expect("signal shutdown");
        tokio::time::timeout(Duration::from_secs(2), pump)
            .await
            .expect("the pump must not outlive its shutdown")
            .expect("no panic");
    }

    #[derive(Clone, Default)]
    struct LogCapture(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);

    impl std::io::Write for LogCapture {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().expect("lock").extend_from_slice(buf);
            Ok(buf.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for LogCapture {
        type Writer = Self;
        fn make_writer(&'a self) -> Self::Writer {
            self.clone()
        }
    }

    /// The unreadable-DM skip is expected, not a failure: the log names
    /// the conversation and states the reason, so the tick line is
    /// never silent.
    #[tokio::test]
    async fn the_unreadable_dm_skip_logs_its_reason() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        host.seed_history("D1", vec![]);
        host.set_watermark("acme", "D1", "050.0");
        host.fail_history_with(
            "D1",
            SlackError::Api {
                method: "conversations.history".to_owned(),
                error: "channel_not_found".to_owned(),
                needed: None,
            },
        );

        let capture = LogCapture::default();
        let subscriber = tracing_subscriber::fmt()
            .with_writer(capture.clone())
            .with_max_level(tracing::Level::INFO)
            .finish();
        let _guard = tracing::subscriber::set_default(subscriber);

        let outcome = sweep(&host, &host, "acme").await.expect("sweep");
        assert!(!outcome.conversation_gone, "the quirk does not flip the glyph");

        let log = String::from_utf8_lossy(&capture.0.lock().expect("lock")).into_owned();
        assert!(log.contains("D1"), "the skip names the conversation: {log}");
        assert!(log.contains("withholds this DM's history"), "the skip states its reason: {log}");
    }

    /// Counts the throttle lines a sweep emitted: the message plus the
    /// `sweep` field, which is how the sources' episodes stay distinct.
    fn throttle_lines(log: &str, message: &str, sweep: &str) -> usize {
        let field = format!("sweep={sweep}");
        log.lines().filter(|line| line.contains(message) && line.contains(&field)).count()
    }

    /// A throttled workspace warns once when the episode starts, not once
    /// per pass, and says when it recovers. Both pumps and the mention
    /// sweep carry the rule.
    #[tokio::test]
    async fn a_throttled_sweep_warns_once_per_episode_and_says_when_it_recovers() {
        let host = Arc::new(FakeHost::with_subscriptions(vec![
            sub_channel("acme", "C1", SlackWatchMode::All),
            sub_dm("acme"),
            sub_mentions("acme"),
        ]));
        FakeHost::set_api_self(&host);
        // Each window reaches back past its cursor, so one pass costs one
        // history read. Each source is throttled for two of its own calls,
        // so an episode does not depend on how the sources interleave.
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history(
            "C1",
            vec![history_message("200.0", "U9", "news"), history_message("050.0", "U9", "old")],
        );
        host.set_watermark("acme", "D1", "050.0");
        host.seed_history(
            "D1",
            vec![history_message("200.0", "U9", "a dm"), history_message("050.0", "U9", "old")],
        );
        host.rate_limit_history_calls("C1", 2);
        host.rate_limit_history_calls("D1", 2);
        host.rate_limit_search_calls(2);

        let capture = LogCapture::default();
        let subscriber = tracing_subscriber::fmt()
            .with_writer(capture.clone())
            .with_max_level(tracing::Level::DEBUG)
            .with_ansi(false)
            .finish();
        let _guard = tracing::subscriber::set_default(subscriber);

        let (tx, rx) = oneshot::channel();
        let pump = tokio::spawn(run_workspace_pump(host.clone(), "acme".to_owned(), 1, 1, rx));
        for _ in 0..160 {
            tokio::time::sleep(Duration::from_millis(50)).await;
            let seen = String::from_utf8_lossy(&capture.0.lock().expect("lock")).into_owned();
            if throttle_lines(&seen, "slack sweep recovered from throttling", "conversation") == 1
                && throttle_lines(&seen, "slack sweep recovered from throttling", "dm") == 1
                && throttle_lines(&seen, "slack sweep recovered from throttling", "mentions") == 1
            {
                break;
            }
        }
        tx.send(()).expect("signal shutdown");
        tokio::time::timeout(Duration::from_secs(2), pump)
            .await
            .expect("the pump must not outlive its shutdown")
            .expect("no panic");

        let log = String::from_utf8_lossy(&capture.0.lock().expect("lock")).into_owned();
        for sweep in ["conversation", "dm", "mentions"] {
            assert_eq!(
                throttle_lines(&log, "slack throttled the sweep", sweep),
                1,
                "{sweep}: one warning per throttled episode: {log}",
            );
            assert!(
                throttle_lines(&log, "slack sweep still throttled", sweep) >= 1,
                "{sweep}: the passes inside the episode are still reported, at debug: {log}",
            );
            assert_eq!(
                throttle_lines(&log, "slack sweep recovered from throttling", sweep),
                1,
                "{sweep}: one recovery line per episode: {log}",
            );
        }
    }

    /// The per-pass detail sits below the default log floor, so a workspace
    /// throttled for hours costs one warning, not one per sweep.
    #[test]
    fn the_per_pass_throttle_detail_stays_below_info() {
        let capture = LogCapture::default();
        let subscriber = tracing_subscriber::fmt()
            .with_writer(capture.clone())
            .with_max_level(tracing::Level::INFO)
            .with_ansi(false)
            .finish();
        let _guard = tracing::subscriber::set_default(subscriber);

        let mut episode = ThrottleEpisode::default();
        let throttled = Some(Duration::from_secs(7));
        let configured = Duration::from_secs(30);
        episode.note_pass("acme", "conversation", configured, throttled);
        episode.note_pass("acme", "conversation", configured, throttled);
        episode.note_pass("acme", "conversation", configured, None);

        let log = String::from_utf8_lossy(&capture.0.lock().expect("lock")).into_owned();
        assert_eq!(
            throttle_lines(&log, "slack throttled the sweep", "conversation"),
            1,
            "the episode announces itself once: {log}",
        );
        assert_eq!(
            throttle_lines(&log, "slack sweep still throttled", "conversation"),
            0,
            "the repeated passes are debug: {log}",
        );
        assert_eq!(
            throttle_lines(&log, "slack sweep recovered from throttling", "conversation"),
            1,
            "and the end of the episode is announced: {log}",
        );
    }

    /// The headline mention case: a mention from a public channel the
    /// user has not joined auto-subscribes it, and users.conversations
    /// (membership-scoped) never lists it - the sweep must still fetch
    /// its messages and thread replies.
    #[tokio::test]
    async fn an_auto_subscribed_channel_the_user_never_joined_is_swept() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.set_watermark("acme", MENTION_CURSOR, "100.0");
        host.seed_search(vec![search_match("150.0", "C9", "ping <@U1>")]);
        sweep_mentions(&host, &host, "acme").await.expect("mention sweep");
        assert_eq!(host.auto_subscribed(), vec!["C9".to_owned()], "the mention subscribes C9");

        // C9 is absent from the membership list; only the subscription
        // set names it.
        host.seed_history_unlisted("C9", vec![history_message("200.0", "U8", "the follow-up")]);
        sweep(&host, &host, "acme").await.expect("conversation sweep");

        let delivered = host.delivered();
        assert!(
            delivered.iter().any(|message| message.text == "the follow-up"),
            "the non-member channel's messages still arrive: {delivered:?}",
        );
    }

    /// A DM-class subscription cannot be pre-seeded per conversation, so
    /// first sight baselines: the newest fetched ts becomes the cursor
    /// and the existing DM history is not delivered as new.
    #[tokio::test]
    async fn a_dm_class_subscription_baselines_on_first_sight_instead_of_replaying() {
        let host = FakeHost::with_subscriptions(vec![sub_dm("acme")]);
        // The class covers D1, which the fake registers when history is
        // seeded; its cursor is unset, the shape a fresh DM arrives in.
        host.seed_history(
            "D1",
            // The wire's order: newest first.
            vec![
                history_message("300.1", "U9", "old one"),
                history_message("200.1", "U9", "older two"),
            ],
        );

        sweep(&host, &host, "acme").await.expect("first sweep");
        assert!(
            host.delivered().is_empty(),
            "the DM's existing history is baselined, not replayed: {:?}",
            host.delivered(),
        );
        assert_eq!(
            host.watermark("acme", "D1").expect("watermark"),
            Some("300.1".to_owned()),
            "the cursor starts at the newest message seen",
        );

        host.seed_history(
            "D1",
            vec![
                history_message("400.1", "U9", "new one"),
                history_message("300.1", "U9", "old one"),
            ],
        );
        sweep(&host, &host, "acme").await.expect("second sweep");
        let texts: Vec<_> = host.delivered().into_iter().map(|m| m.text).collect();
        assert_eq!(texts, vec!["new one".to_owned()], "only what follows the baseline arrives");
    }

    /// A record written before names were captured holds none, so the
    /// Inspector renders its raw id. The sweep already has the directory
    /// in hand, so it fills that in on the next tick - re-subscribing
    /// would mint a second record rather than update this one.
    #[tokio::test]
    async fn a_sweep_backfills_a_missing_conversation_name() {
        let host =
            FakeHost::with_subscriptions(vec![sub_channel("acme", "C1", SlackWatchMode::All)]);
        host.conversations.lock().expect("lock").push(conversation_channel("C1", "ved-test"));

        sweep(&host, &host, "acme").await.expect("sweep");

        let stored = host
            .subscriptions("acme")
            .into_iter()
            .find_map(|sub| match sub.target {
                SlackSubscriptionTarget::Conversation { id, name, .. } if id == "C1" => Some(name),
                _ => None,
            })
            .expect("the C1 record");
        assert_eq!(
            stored.as_deref(),
            Some("ved-test"),
            "the sweep stamps the name the directory reports",
        );
    }

    /// The directory can hand back a name that is empty or is really the
    /// conversation id; stamping either renders `#` or `#C1`, so the
    /// sweep writes neither.
    #[tokio::test]
    async fn a_sweep_rejects_a_name_that_is_empty_or_the_id() {
        let host = FakeHost::with_subscriptions(vec![
            sub_channel("acme", "C1", SlackWatchMode::All),
            sub_channel("acme", "C2", SlackWatchMode::All),
        ]);
        host.conversations
            .lock()
            .expect("lock")
            .extend([conversation_channel("C1", ""), conversation_channel("C2", "C2")]);

        sweep(&host, &host, "acme").await.expect("sweep");

        let names: Vec<Option<String>> = host
            .subscriptions("acme")
            .into_iter()
            .filter_map(|sub| match sub.target {
                SlackSubscriptionTarget::Conversation { id, name, .. }
                    if id == "C1" || id == "C2" =>
                {
                    Some(name)
                }
                _ => None,
            })
            .collect();
        assert_eq!(names, vec![None, None], "neither an empty name nor the id is stamped");
    }

    /// Only unnamed records are filled. A conversation renamed since it
    /// was subscribed keeps the stored name, so the sweep never rewrites
    /// a record that already has one.
    #[tokio::test]
    async fn a_sweep_leaves_an_already_named_record_alone() {
        let mut sub = sub_channel("acme", "C1", SlackWatchMode::All);
        sub.target = SlackSubscriptionTarget::Conversation {
            id: "C1".to_owned(),
            name: Some("stale-name".to_owned()),
            mode: SlackWatchMode::All,
        };
        let host = FakeHost::with_subscriptions(vec![sub]);
        host.conversations.lock().expect("lock").push(conversation_channel("C1", "renamed"));

        sweep(&host, &host, "acme").await.expect("sweep");

        let stored = host
            .subscriptions("acme")
            .into_iter()
            .find_map(|sub| match sub.target {
                SlackSubscriptionTarget::Conversation { id, name, .. } if id == "C1" => Some(name),
                _ => None,
            })
            .expect("the C1 record");
        assert_eq!(
            stored.as_deref(),
            Some("stale-name"),
            "a record that already has a name is never rewritten",
        );
    }

    /// A failed mention delivery holds the mention cursor and skips the
    /// auto-subscribe, so the next tick retries the whole window instead
    /// of losing the trigger message.
    #[tokio::test]
    async fn a_failed_mention_delivery_holds_the_cursor_and_the_follow() {
        let host = FakeHost::with_subscriptions(vec![sub_mentions("acme")]);
        host.set_watermark("acme", MENTION_CURSOR, "100.0");
        host.seed_search(vec![search_match("150.0", "C9", "ping <@U1>")]);
        host.fail_delivery_at(0);

        let outcome = sweep_mentions(&host, &host, "acme").await.expect("sweep");
        assert_eq!(outcome.delivered, 0, "the failed mention is not counted");
        assert_eq!(
            host.watermark("acme", MENTION_CURSOR).expect("watermark"),
            Some("100.0".to_owned()),
            "the cursor holds at its previous value",
        );
        assert!(
            host.auto_subscribed().is_empty(),
            "a mention that did not reach a session subscribes nothing",
        );
    }

    /// Two owners on one conversation: a partial fan-out failure holds
    /// the cursor at its previous value, the same semantics the thread
    /// walk enforces.
    #[tokio::test]
    async fn a_conversation_fanout_failure_holds_the_cursor_for_every_owner() {
        let host = FakeHost::with_subscriptions(vec![
            sub_conversation_owned_by("acme", "forge", Some("a"), "C1"),
            sub_conversation_owned_by("acme", "forge", Some("b"), "C1"),
        ]);
        host.set_watermark("acme", "C1", "050.0");
        host.seed_history("C1", vec![history_message("300.0", "U9", "the message")]);
        // Attempts: a's delivery (0) succeeds, b's (1) fails.
        host.fail_delivery_at(1);

        sweep(&host, &host, "acme").await.expect("sweep");
        let delivered = host.delivered();
        assert_eq!(
            delivered.len(),
            1,
            "the owner whose delivery succeeded still received it: {delivered:?}",
        );
        assert_eq!(
            host.watermark("acme", "C1").expect("watermark"),
            Some("050.0".to_owned()),
            "the cursor holds below a message that did not reach every owner",
        );
    }

    #[tokio::test]
    async fn the_pump_stops_when_the_shutdown_fires() {
        let host = Arc::new(FakeHost::with_subscriptions(vec![sub_dm("acme")]));
        FakeHost::set_api_self(&host);
        let (tx, rx) = oneshot::channel();
        let pump =
            tokio::spawn(run_workspace_pump(host.clone(), "acme".to_owned(), 3600, 3600, rx));
        tokio::time::sleep(Duration::from_millis(50)).await;
        tx.send(()).expect("signal shutdown");
        tokio::time::timeout(Duration::from_secs(2), pump)
            .await
            .expect("the pump must not outlive its shutdown")
            .expect("no panic");
        assert_eq!(host.connected(), Some(false), "the pump marks itself disconnected on exit");
    }

    #[test]
    fn next_interval_never_sweeps_faster_than_the_configured_cadence() {
        assert_eq!(
            next_interval(Duration::from_secs(30), Some(Duration::from_secs(7))),
            Duration::from_secs(30),
            "a short Retry-After must not shorten the cadence",
        );
        assert_eq!(next_interval(Duration::from_secs(30), None), Duration::from_secs(30));
        assert_eq!(
            next_interval(Duration::from_secs(30), Some(Duration::from_secs(600))),
            Duration::from_secs(60),
            "a hostile Retry-After is capped",
        );
        assert_eq!(
            next_interval(Duration::from_secs(90), Some(Duration::from_secs(600))),
            Duration::from_secs(90),
            "the cap bounds the Retry-After, not the configured cadence",
        );
    }

    #[test]
    fn a_token_never_reaches_the_debug_output() {
        let client = SlackClient::new(reqwest::Client::new(), "xoxp-supersecret".to_owned());
        let rendered = format!("{client:?}");
        assert!(!rendered.contains("supersecret"), "token leaked: {rendered}");
    }
}