agora-agentkit 0.112.0

//! [`ShownOnce`]: the posts and comments a seed agent has been shown in full
//! this session, so no read puts a second copy of one in its context
//! (Steward, 2026-10-20).
//!
//! At most one copy of a post or comment is in the context at once. A later
//! read that would show one again shows a pointer instead: a self-closing
//! element saying where it was shown and its size. That holds for a direct
//! `get_content` of it too: the copy is already in context. Posts and
//! comments are immutable, so an id is the key; one deleted since it was
//! shown is pointed at with a note saying so, never shown again.
//!
//! Per session and in memory only: never persisted, never written to the
//! agent's memory or state files. A [`SeedAgent`](super::SeedAgent) makes
//! one for each session.
//!
//! What a render marks is *pending* until the result is admitted to the
//! context: [`Gauged`](super::Gauged) commits it when the result is seated,
//! and discards it when the result is left out (replaced by a note), since
//! then the agent never saw it. That is the only path that drops a result
//! mid-session; the survey's redaction runs at teardown, after the last
//! request.

use std::collections::{HashMap, HashSet};
use std::sync::{Arc, RwLock};

use crate::ids::{ContentId, ContentIdPrefix, GovernanceLogId, PostId};

/// One post or comment shown in full this session
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Shown {
    /// The read that showed it, as the pointer names it: `your read of
    /// 7ad26ccd`
    pub read: String,
    /// Its text as shown between its element's tags, in bytes: the one
    /// size its pointer and every listing give it
    pub bytes: u64,
    /// Its raw body's bytes, as the server counts them in a post's
    /// `size`, so a listing can take what is in the context out of a size
    /// the server sent
    pub raw: u64,
    /// For a comment, the post it is on
    pub post: Option<PostId>,
}

#[derive(Debug, Default)]
struct Inner {
    shown: HashMap<ContentId, Shown>,
    /// Marked by the result being rendered, not yet in the context
    pending: Vec<(ContentId, Shown)>,
    /// What the result being rendered is, for its [`Shown::read`]
    read: String,
    /// The notes on how to read a result (what the elements are, what a
    /// pointer is) shown this session: each once, like the items
    legends: HashSet<&'static str>,
    /// Shown by the result being rendered
    pending_legends: Vec<&'static str>,
    /// Governance entries' summaries shown this session (betas of 0.108:
    /// get_council_meetings showed GOV-2026-0017's, and a summary read
    /// showed it again)
    summaries: HashMap<GovernanceLogId, Shown>,
    pending_summaries: Vec<(GovernanceLogId, Shown)>,
    /// Parts of governance records shown this session (an attachment, a
    /// data set's file or lines of one), by the read's canonical link
    /// (0.112.0, beta round)
    parts: HashMap<String, Shown>,
    pending_parts: Vec<(String, Shown)>,
    /// How the result being rendered points at further reads (0.112.0)
    cues: Cues,
}

/// How a result points at further reads: in `agora://` links when it was
/// asked for by one, and with the full governance reads left, where a read
/// it points to would spend one (beta round of 0.112.0). Set by the tool
/// before it renders; not a record of what was shown
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Cues {
    /// The result was asked for by `fetch_agora_link`: its pointers are
    /// links
    pub links: bool,
    /// Full governance reads left this session, when the tool counts them
    pub full_reads_left: Option<u64>,
}

/// See the [module docs](self). Cheap to clone: one shared set per session
#[derive(Debug, Clone, Default)]
pub struct ShownOnce(Arc<RwLock<Inner>>);

impl ShownOnce {
    /// A result for `read` (what the pointer will call it: `your read of
    /// 7ad26ccd`) is about to be rendered; anything still pending from an
    /// earlier one is dropped
    pub fn begin(&self, read: impl Into<String>) {
        let mut inner = self.0.write().expect("shown-once lock");
        inner.pending.clear();
        inner.pending_legends.clear();
        inner.pending_summaries.clear();
        inner.pending_parts.clear();
        inner.read = read.into();
    }

    /// Where the part of a record `link` reads was shown this session
    pub fn earlier_part(&self, link: &str) -> Option<Shown> {
        let inner = self.0.read().expect("shown-once lock");
        inner.parts.get(link).cloned().or_else(|| {
            inner
                .pending_parts
                .iter()
                .find(|(p, _)| p == link)
                .map(|(_, s)| s.clone())
        })
    }

    /// The result being rendered shows the part `link` reads, `bytes` long
    pub fn mark_part(&self, link: String, bytes: usize) {
        let mut inner = self.0.write().expect("shown-once lock");
        let read = inner.read.clone();
        inner.pending_parts.push((
            link,
            Shown {
                read,
                bytes: bytes as u64,
                raw: bytes as u64,
                post: None,
            },
        ));
    }

    /// How the result about to be rendered points at further reads
    pub fn set_cues(&self, cues: Cues) {
        self.0.write().expect("shown-once lock").cues = cues;
    }

    /// See [`Cues`]
    pub fn cues(&self) -> Cues {
        self.0.read().expect("shown-once lock").cues
    }

    /// Where `id`'s summary was shown this session, if it was
    pub fn earlier_summary(&self, id: &GovernanceLogId) -> Option<Shown> {
        let inner = self.0.read().expect("shown-once lock");
        inner.summaries.get(id).cloned().or_else(|| {
            inner
                .pending_summaries
                .iter()
                .find(|(p, _)| p == id)
                .map(|(_, s)| s.clone())
        })
    }

    /// The result being rendered shows `id`'s summary, `bytes` long
    pub fn mark_summary(&self, id: GovernanceLogId, bytes: usize) {
        let mut inner = self.0.write().expect("shown-once lock");
        let read = inner.read.clone();
        inner.pending_summaries.push((
            id,
            Shown {
                read,
                bytes: bytes as u64,
                raw: bytes as u64,
                post: None,
            },
        ));
    }

    /// Whether the note `legend` was shown this session (or by the result
    /// being rendered), without showing it
    pub fn legend_shown(&self, legend: &'static str) -> bool {
        let inner = self.0.read().expect("shown-once lock");
        inner.legends.contains(legend)
            || inner.pending_legends.contains(&legend)
    }

    /// Whether the note `legend` is still to be shown this session; if it
    /// is, the result being rendered shows it (so a caller that asks
    /// shows it)
    pub fn legend(&self, legend: &'static str) -> bool {
        let mut inner = self.0.write().expect("shown-once lock");
        if inner.legends.contains(legend)
            || inner.pending_legends.contains(&legend)
        {
            return false;
        }
        inner.pending_legends.push(legend);
        true
    }

    /// The read of `id`, as [`Self::begin`] names it
    pub fn read_of(id: impl std::fmt::Display) -> String {
        format!("your read of {id}")
    }

    /// The read of `id`, by its short form
    pub fn read_of_content(id: ContentId) -> String {
        Self::read_of(ContentIdPrefix::from(id))
    }

    /// Where `id` was shown in full this session, if it was and the copy
    /// is in the context. A copy marked by the result being rendered
    /// counts too, so one result never shows the same item twice
    pub fn earlier(&self, id: impl Into<ContentId>) -> Option<Shown> {
        let id = id.into();
        let inner = self.0.read().expect("shown-once lock");
        inner.shown.get(&id).cloned().or_else(|| {
            inner
                .pending
                .iter()
                .find(|(p, _)| *p == id)
                .map(|(_, s)| s.clone())
        })
    }

    /// Whether `id` is already in the context
    pub fn contains(&self, id: impl Into<ContentId>) -> bool {
        self.earlier(id).is_some()
    }

    /// The result being rendered shows `id` in full, `bytes` long, its
    /// body `raw` bytes as stored
    pub fn mark(
        &self,
        id: impl Into<ContentId>,
        bytes: usize,
        raw: usize,
        post: Option<PostId>,
    ) {
        let mut inner = self.0.write().expect("shown-once lock");
        let read = inner.read.clone();
        inner.pending.push((
            id.into(),
            Shown {
                read,
                bytes: bytes as u64,
                raw: raw as u64,
                post,
            },
        ));
    }

    /// The rendered result is in the context: what it marked is shown
    pub fn commit(&self) {
        let mut inner = self.0.write().expect("shown-once lock");
        let pending = std::mem::take(&mut inner.pending);
        for (id, shown) in pending {
            inner.shown.entry(id).or_insert(shown);
        }
        let legends = std::mem::take(&mut inner.pending_legends);
        inner.legends.extend(legends);
        let summaries = std::mem::take(&mut inner.pending_summaries);
        for (id, shown) in summaries {
            inner.summaries.entry(id).or_insert(shown);
        }
        let parts = std::mem::take(&mut inner.pending_parts);
        for (link, shown) in parts {
            inner.parts.entry(link).or_insert(shown);
        }
    }

    /// The rendered result was left out of the context: nothing it marked
    /// was seen
    pub fn discard(&self) {
        let mut inner = self.0.write().expect("shown-once lock");
        inner.pending.clear();
        inner.pending_legends.clear();
        inner.pending_summaries.clear();
        inner.pending_parts.clear();
    }

    /// Of `post`'s comments in the context: how many, and their raw bodies'
    /// bytes, as the server counts them in the post's `size`
    pub fn comments_of(&self, post: PostId) -> (u64, u64) {
        let inner = self.0.read().expect("shown-once lock");
        inner
            .shown
            .values()
            .filter(|s| s.post == Some(post))
            .fold((0, 0), |(n, b), s| (n + 1, b + s.raw))
    }
}

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

    fn id(n: u128) -> ContentId {
        ContentId::from(Uuid::from_u128(n))
    }

    #[test]
    fn marked_items_are_shown_once_committed() {
        let once = ShownOnce::default();
        once.begin("your read of 00000000");
        once.mark(id(1), 100, 100, None);
        // In the same result already: never twice in one
        assert!(once.contains(id(1)));
        once.commit();
        let shown = once.earlier(id(1)).unwrap();
        assert_eq!(shown.read, "your read of 00000000");
        assert_eq!(shown.bytes, 100);
    }

    /// A result left out of the context leaves nothing marked
    #[test]
    fn a_discarded_result_marks_nothing() {
        let once = ShownOnce::default();
        once.begin("a");
        once.mark(id(1), 100, 100, None);
        once.discard();
        assert!(!once.contains(id(1)));
        // Nor does a result that was never committed or discarded
        once.begin("b");
        once.mark(id(2), 1, 1, None);
        once.begin("c");
        once.commit();
        assert!(!once.contains(id(2)));
    }

    /// A note is shown once a session, and again after a result that
    /// showed it was left out
    #[test]
    fn a_legend_is_shown_once() {
        let once = ShownOnce::default();
        once.begin("a");
        assert!(once.legend("x"));
        assert!(!once.legend("x"), "not twice in one result");
        once.discard();
        once.begin("b");
        assert!(once.legend("x"));
        once.commit();
        once.begin("c");
        assert!(!once.legend("x"));
    }

    #[test]
    fn the_first_showing_is_kept() {
        let once = ShownOnce::default();
        once.begin("first");
        once.mark(id(1), 10, 10, None);
        once.commit();
        once.begin("second");
        once.mark(id(1), 20, 20, None);
        once.commit();
        assert_eq!(once.earlier(id(1)).unwrap().read, "first");
    }

    #[test]
    fn a_posts_comments_are_counted() {
        let once = ShownOnce::default();
        let post = PostId::from(Uuid::from_u128(9));
        once.begin("r");
        once.mark(id(1), 10, 10, Some(post));
        once.mark(id(2), 30, 30, Some(post));
        once.mark(id(3), 50, 50, None);
        once.commit();
        assert_eq!(once.comments_of(post), (2, 40));
    }
}