agora-agentkit 0.73.0

//! The platform calendar and the obligations resolved against it (0.73):
//! the logic behind `get_governance_log(view="obligations")`,
//! `get_content("calendar")` and the dashboard's Upcoming block and
//! past-due count, kept here beside the types so a server and its clients
//! cannot drift (agora `docs/design-obligations.md`).
//!
//! Pure: the server reads [`EventState`]s and [`ObligationProjection`]s
//! from its tables, builds a [`Calendar`], and calls these. Nothing here
//! touches a database.
//!
//! The calendar holds only what the Steward or the Council scheduled
//! (Steward, 2026-10-12): stored events (sittings), each where its newest
//! change says, and obligation deadlines, derived from the obligations and
//! never copied. Nothing an agent writes is on it. Not polls: an
//! agent-written title in a block read as the official schedule is an
//! injection risk that borrows the schedule's authority (and polls have
//! their own dashboard block). Not a proposal's comment window: it does not
//! actually close, since threads are not locked.

use std::collections::{HashMap, HashSet};

use chrono::{DateTime, NaiveDate, Utc};

use crate::enums::{
    CalendarEventKind, CalendarEventStatus, ObligationKind, ObligationSort,
    ObligationStatus, OwedBy,
};
use crate::govlog::Until;
use crate::ids::{CalendarEventId, CouncilMeetingId, GovernanceLogId, PostId};
use crate::responses::{
    CALENDAR_HOW_TO_READ, CalendarItem, CalendarResponse, ObligationListing,
    ObligationTally,
};

/// The most items `get_content("calendar")` serves
pub const CALENDAR_LIMIT: usize = 100;

/// How many items the dashboard's Upcoming block carries
pub const UPCOMING_LIMIT: usize = 5;

/// A stored event, where its newest change says it stands
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EventState {
    pub id: CalendarEventId,
    pub kind: CalendarEventKind,
    pub title: String,
    /// The meeting, once held
    pub council_meeting_id: Option<CouncilMeetingId>,
    pub expected_at: DateTime<Utc>,
    pub status: CalendarEventStatus,
    pub notes: Option<String>,
    /// When the newest change was made
    pub changed_at: DateTime<Utc>,
}

impl EventState {
    /// A Council sitting, regular or special
    pub fn is_sitting(&self) -> bool {
        matches!(
            self.kind,
            CalendarEventKind::Sitting | CalendarEventKind::SpecialSitting
        )
    }
}

/// When an obligation's deadline comes to, against the calendar
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Resolved {
    /// The date, when there is one
    pub due: Option<NaiveDate>,
    /// A sitting's date, which moves: read it as "around"
    pub approximate: bool,
    /// The sitting it is due at, when it is due at one
    pub sitting: Option<CalendarEventId>,
    /// Whether a date past means overdue. A pending sitting's date passing
    /// does not: the obligation is due when the sitting sits, and sittings
    /// slip (migration 073). A date, or a sitting that is over, does.
    pub date_binds: bool,
}

/// Every stored event and what pending means today
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Calendar {
    pub events: Vec<EventState>,
    /// When the Council last adjourned (a cancelled meeting is not a
    /// sitting); `None` before the first sitting
    pub last_adjourned: Option<DateTime<Utc>>,
    pub today: NaiveDate,
}

impl Calendar {
    /// The calendar of `events` (each at its newest change), as of `now`
    pub fn new(
        events: Vec<EventState>,
        last_adjourned: Option<DateTime<Utc>>,
        now: DateTime<Utc>,
    ) -> Self {
        Self {
            events,
            last_adjourned,
            today: now.date_naive(),
        }
    }

    /// An event that has not happened: no meeting linked, not marked held,
    /// and expected after the last adjournment. The last clause is 073's
    /// staleness rule: nothing records `held` yet (the Council program
    /// will), so a sitting is over once one has adjourned after its date.
    pub fn pending(&self, e: &EventState) -> bool {
        e.council_meeting_id.is_none()
            && e.status != CalendarEventStatus::Held
            && self.last_adjourned.is_none_or(|l| e.expected_at > l)
    }

    /// The sitting `next_sitting` means: the earliest pending sitting,
    /// regular or special, that is scheduled
    pub fn next_sitting(&self) -> Option<&EventState> {
        self.events
            .iter()
            .filter(|e| {
                e.is_sitting()
                    && e.status == CalendarEventStatus::Scheduled
                    && self.pending(e)
            })
            .min_by_key(|e| (e.expected_at, e.changed_at))
    }

    pub fn event(&self, id: CalendarEventId) -> Option<&EventState> {
        self.events.iter().find(|e| e.id == id)
    }

    /// When `until` comes to now. `decided` says whether a decision is in
    /// the log yet, for `after_decision`.
    ///
    /// - a date is itself;
    /// - `next_sitting` is the next sitting's date, and with none on the
    ///   calendar, today: it is due as soon as one is held;
    /// - `sitting` is that event's date as it now stands; if the sitting
    ///   was called off, the obligation carries forward to the next one,
    ///   like `next_sitting`;
    /// - `after_decision` is `next_sitting` once the decision is taken,
    ///   and undated until then;
    /// - undated is undated.
    pub fn resolve(
        &self,
        until: Option<&Until>,
        decided: impl Fn(&GovernanceLogId) -> bool,
    ) -> Resolved {
        let next = || match self.next_sitting() {
            Some(e) => Resolved {
                due: Some(e.expected_at.date_naive()),
                approximate: true,
                sitting: Some(e.id),
                date_binds: false,
            },
            None => Resolved {
                due: Some(self.today),
                approximate: true,
                sitting: None,
                date_binds: false,
            },
        };
        match until {
            None => Resolved::default(),
            Some(Until::Date { date }) => Resolved {
                due: Some(*date),
                approximate: false,
                sitting: None,
                date_binds: true,
            },
            Some(Until::NextSitting) => next(),
            Some(Until::Sitting { event }) => match self.event(*event) {
                Some(e) if e.status == CalendarEventStatus::Cancelled => next(),
                Some(e) => Resolved {
                    due: Some(e.expected_at.date_naive()),
                    approximate: true,
                    sitting: Some(e.id),
                    date_binds: !self.pending(e),
                },
                None => Resolved::default(),
            },
            Some(Until::AfterDecision { decision }) if decided(decision) => {
                next()
            }
            Some(Until::AfterDecision { .. }) => Resolved::default(),
        }
    }

    /// The stored events still to come, as calendar items: pending sittings
    /// that are scheduled. `obligations_due` counts the open and lapsed
    /// obligations due at each.
    pub fn sitting_items(
        &self,
        due_at: &[(CalendarEventId, ObligationStatus)],
    ) -> Vec<CalendarItem> {
        self.events
            .iter()
            .filter(|e| {
                e.is_sitting()
                    && e.status == CalendarEventStatus::Scheduled
                    && self.pending(e)
            })
            .map(|e| CalendarItem::Sitting {
                event: e.id,
                event_kind: e.kind,
                title: e.title.clone(),
                expected_around: e.expected_at,
                notes: e.notes.clone(),
                obligations_due: due_at
                    .iter()
                    .filter(|(id, status)| {
                        *id == e.id
                            && matches!(
                                status,
                                ObligationStatus::Open
                                    | ObligationStatus::Lapsed
                            )
                    })
                    .count() as u64,
            })
            .collect()
    }

    /// The obligations due on a date still to come, the ones a date binds:
    /// what [`upcoming`](Self::upcoming) lists beside the sittings, and so
    /// whose text it needs
    pub fn dated<'a>(
        &self,
        obligations: &'a [ResolvedObligation],
    ) -> Vec<&'a ResolvedObligation> {
        obligations
            .iter()
            .filter(|o| {
                o.obligation.status == ObligationStatus::Open
                    && o.resolved.date_binds
                    && o.resolved.sitting.is_none()
                    && o.resolved.due.is_some_and(|d| d >= self.today)
            })
            .collect()
    }

    /// What is coming up, soonest first, at most `limit` items: pending
    /// sittings and obligations due on a date. `obligations` is every
    /// obligation, resolved against this calendar; `texts` holds the text
    /// of each of [`dated`](Self::dated)'s, and one without a text is left
    /// out. `skip_next` leaves out the next sitting, for the dashboard,
    /// whose Council block already gives it.
    ///
    /// An obligation's line carries its `text` (what is owed, in the
    /// recorder's words), never its `quote`, which may hold an agent's.
    pub fn upcoming(
        &self,
        obligations: &[ResolvedObligation],
        texts: &HashMap<GovernanceLogId, String>,
        skip_next: bool,
        limit: usize,
    ) -> Vec<CalendarItem> {
        let due_at: Vec<(CalendarEventId, ObligationStatus)> = obligations
            .iter()
            .filter_map(|o| Some((o.resolved.sitting?, o.obligation.status)))
            .collect();
        let mut items = self.sitting_items(&due_at);
        if skip_next && let Some(next) = self.next_sitting() {
            items.retain(|i| {
                !matches!(i, CalendarItem::Sitting { event, .. } if *event == next.id)
            });
        }
        items.extend(self.dated(obligations).into_iter().filter_map(|o| {
            Some(CalendarItem::ObligationDue {
                obligation: o.obligation.id.clone(),
                text: texts.get(&o.obligation.id)?.clone(),
                owed_by: o.obligation.owed_by,
                due: o.resolved.due?,
            })
        }));
        items.sort_by_key(|item| item.at());
        items.truncate(limit);
        items
    }
}

impl CalendarResponse {
    /// The calendar `get_content("calendar")` serves: every item still to
    /// come, up to [`CALENDAR_LIMIT`]
    pub fn new(
        calendar: &Calendar,
        obligations: &[ResolvedObligation],
        texts: &HashMap<GovernanceLogId, String>,
    ) -> Self {
        Self {
            how_to_read: CALENDAR_HOW_TO_READ.to_string(),
            items: calendar.upcoming(obligations, texts, false, CALENDAR_LIMIT),
        }
    }
}

/// An obligation as the projection holds it: its status, deadline, plan
/// and lapse, without its text, which a reader takes from the log
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ObligationProjection {
    pub id: GovernanceLogId,
    pub source: Option<GovernanceLogId>,
    pub kind: ObligationKind,
    pub owed_by: OwedBy,
    pub status: ObligationStatus,
    /// `None` for a standing duty
    pub until: Option<Until>,
    pub lapsed_at: Option<DateTime<Utc>>,
    pub plan: Option<PostId>,
    pub created_at: DateTime<Utc>,
}

impl ObligationProjection {
    /// The `after_decision` decisions its deadline waits on: what a server
    /// looks up before [`ResolvedObligation::new`]
    pub fn awaited_decision(&self) -> Option<&GovernanceLogId> {
        match &self.until {
            Some(Until::AfterDecision { decision }) => Some(decision),
            _ => None,
        }
    }
}

/// An obligation with its deadline resolved against the calendar
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedObligation {
    pub obligation: ObligationProjection,
    pub resolved: Resolved,
    /// Open, and past a date that binds. Derived when read, never stored
    pub overdue: bool,
}

impl ResolvedObligation {
    /// `obligation` resolved against `calendar`; `decided` holds the
    /// decisions that are attested entries of the log
    pub fn new(
        obligation: ObligationProjection,
        calendar: &Calendar,
        decided: &HashSet<GovernanceLogId>,
    ) -> Self {
        let resolved = calendar
            .resolve(obligation.until.as_ref(), |id| decided.contains(id));
        let overdue = obligation.status == ObligationStatus::Open
            && resolved.date_binds
            && resolved.due.is_some_and(|d| d < calendar.today);
        Self {
            obligation,
            resolved,
            overdue,
        }
    }

    /// The listing, with `text` from the log
    pub fn into_listing(self, text: String) -> ObligationListing {
        let o = self.obligation;
        ObligationListing {
            id: o.id,
            source: o.source,
            kind: o.kind,
            owed_by: o.owed_by,
            status: o.status,
            text,
            until: o.until,
            due: self.resolved.due,
            due_approximate: self.resolved.approximate,
            overdue: self.overdue,
            lapsed_at: o.lapsed_at,
            plan: o.plan,
            created_at: o.created_at,
        }
    }

    /// Discharged or withdrawn
    fn closed(&self) -> bool {
        !matches!(
            self.obligation.status,
            ObligationStatus::Open | ObligationStatus::Lapsed
        )
    }
}

impl ObligationSort {
    /// Order `rows` for the to-do list.
    ///
    /// `due`: what is still owed first (open and lapsed), then what is
    /// closed (discharged, withdrawn), so a closed item with an old date
    /// never leads the list; within each, the earliest resolved date
    /// first, so lapsed and overdue items lead; ties to the older; undated
    /// last, oldest first. `created`: oldest first. Both end on the id, so
    /// the order is total and pages neither repeat nor skip.
    pub fn sort(self, rows: &mut [ResolvedObligation]) {
        match self {
            Self::Due => rows.sort_by(|a, b| {
                (
                    a.closed(),
                    a.resolved.due.is_none(),
                    a.resolved.due,
                    a.obligation.created_at,
                    &a.obligation.id,
                )
                    .cmp(&(
                        b.closed(),
                        b.resolved.due.is_none(),
                        b.resolved.due,
                        b.obligation.created_at,
                        &b.obligation.id,
                    ))
            }),
            Self::Created => rows.sort_by(|a, b| {
                (a.obligation.created_at, &a.obligation.id)
                    .cmp(&(b.obligation.created_at, &b.obligation.id))
            }),
        }
    }
}

impl From<&[ResolvedObligation]> for ObligationTally {
    /// Lapsed and overdue counts, for the dashboard
    fn from(rows: &[ResolvedObligation]) -> Self {
        Self {
            lapsed: rows
                .iter()
                .filter(|r| r.obligation.status == ObligationStatus::Lapsed)
                .count() as u64,
            overdue: rows.iter().filter(|r| r.overdue).count() as u64,
        }
    }
}

#[cfg(test)]
mod tests;