agora_agentkit/govlog/

obligation.rs

//! The `data` of an `obligation` entry (`OBL-YYYY-NNNN`), and the
//! amendments that keep its status (agora `docs/design-obligations.md`).
//!
//! An obligation is never edited. Its status changes through appended
//! [`Amendment`]s of the five [obligation kinds](AmendmentKind::OBLIGATION),
//! each carrying an [`ObligationUpdate`], and [`ObligationState`] is what
//! they add up to. Partial discharge is an ordinary [`Revision`] narrowing
//! `text`.
//!
//! Like a [`StewardRecord`], an obligation is
//! [redactable](super::is_redactable): its `quote` may hold an agent's
//! words. So every field that might is a plain string, which a
//! [redaction marker](super::redaction_marker) can replace and still read.
//!
//! [`Revision`]: super::Revision
//! [`StewardRecord`]: super::StewardRecord

use chrono::{DateTime, NaiveDate, Utc};
use serde::{Deserialize, Serialize};

use super::{Amendment, AmendmentError, OBLIGATION_FIXED, revision_touches};
use crate::enums::{
    AmendmentKind, GovernanceLogEntryType, ObligationKind, ObligationStatus,
    OwedBy,
};
use crate::ids::{CalendarEventId, GovernanceLogId, PostId};

/// The only `agora_obligation` version there is
pub const OBLIGATION_VERSION: u32 = 1;

/// When an obligation is due.
///
/// `NextSitting` is resolved against the calendar when read, never pinned
/// to a date, so a sitting that slips carries the obligation with it.
///
/// Its schema is written by hand (see the `JsonSchema` impl): an `anyOf`
/// with one closed object per variant, tagged by `when`, with no `$ref` and
/// no `pattern`, so it can sit in a strict response format. Closed in
/// serde too, except beside `next_sitting`: serde does not deny unknown
/// fields on a unit variant of an internally tagged enum.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(tag = "when", rename_all = "snake_case", deny_unknown_fields)]
pub enum Until {
    /// The next Council sitting, whenever that is
    NextSitting,
    /// A sitting on the calendar
    Sitting { event: CalendarEventId },
    /// The end of a date
    Date {
        #[serde(with = "full_date")]
        date: NaiveDate,
    },
    /// The next sitting after a decision is taken
    AfterDecision { decision: GovernanceLogId },
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for Until {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("Until")
    }

    fn schema_id() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed(concat!(module_path!(), "::Until"))
    }

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let variant =
            |when: &str, description: &str, field: Option<(&str, _)>| {
                let mut properties = serde_json::Map::new();
                properties.insert(
                    "when".into(),
                    serde_json::json!({ "type": "string", "enum": [when] }),
                );
                let mut required = vec!["when"];
                if let Some((name, schema)) = field {
                    properties.insert(name.into(), schema);
                    required.push(name);
                }
                serde_json::json!({
                    "type": "object",
                    "description": description,
                    "properties": properties,
                    "required": required,
                    "additionalProperties": false
                })
            };
        let schema = serde_json::json!({
            "description": "When it is due",
            "anyOf": [
                variant(
                    "next_sitting",
                    "At the next Council sitting, whenever that is held",
                    None,
                ),
                variant(
                    "sitting",
                    "At a particular sitting on the calendar",
                    Some((
                        "event",
                        serde_json::json!({
                            "type": "string",
                            "format": "uuid",
                            "description": "The sitting's calendar event id"
                        }),
                    )),
                ),
                variant(
                    "date",
                    "By the end of a date",
                    Some((
                        "date",
                        serde_json::json!({
                            "type": "string",
                            "format": "date",
                            "description": "YYYY-MM-DD"
                        }),
                    )),
                ),
                variant(
                    "after_decision",
                    "At the first sitting after a decision is taken",
                    Some((
                        "decision",
                        serde_json::json!({
                            "type": "string",
                            "description": "The decision's governance log id, \
                                            e.g. \"GOV-2026-0012\""
                        }),
                    )),
                ),
            ]
        });
        schemars::Schema::try_from(schema).expect("an object is a schema")
    }
}

/// A date in signed data, read only as `YYYY-MM-DD`.
///
/// chrono alone also reads `+2027-4-1` and `2027 - 04 - 01`. Every
/// verifier must agree on what an amendment says, and a second one should
/// not have to reproduce chrono's leniency to do it.
mod full_date {
    use chrono::NaiveDate;
    use serde::{Deserialize, Deserializer, Serializer};

    pub fn serialize<S: Serializer>(
        date: &NaiveDate,
        s: S,
    ) -> Result<S::Ok, S::Error> {
        s.collect_str(&date.format("%Y-%m-%d"))
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(
        d: D,
    ) -> Result<NaiveDate, D::Error> {
        let s = String::deserialize(d)?;
        let shaped = s.len() == 10
            && s.char_indices().all(|(i, c)| match i {
                4 | 7 => c == '-',
                _ => c.is_ascii_digit(),
            });
        shaped
            .then(|| NaiveDate::parse_from_str(&s, "%Y-%m-%d").ok())
            .flatten()
            .ok_or_else(|| {
                serde::de::Error::custom(format!(
                    "{s:?} is not a date as YYYY-MM-DD"
                ))
            })
    }
}

/// The `data` of an `obligation` entry. See the [module docs](self).
///
/// Unknown keys are tolerated on purpose: a stored obligation also carries
/// the writer's `_blind`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct Obligation {
    /// Always [`OBLIGATION_VERSION`]
    pub agora_obligation: u32,
    /// The entry that created it. `None` makes it top-level: a standing
    /// duty, or a promise made in a post rather than a record
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<GovernanceLogId>,
    pub kind: ObligationKind,
    pub owed_by: OwedBy,
    /// When it is due; `None` is a standing duty, which never lapses
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub until: Option<Until>,
    /// What is owed, in a sentence
    pub text: String,
    /// The words in the source that create it, verbatim
    pub quote: String,
    /// Where they are: round and seat, section, or a post or comment id
    pub quote_location: String,
    /// Where it was promised, when that is a post
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub thread: Option<PostId>,
}

impl Obligation {
    /// A top-level, undated obligation with no thread; set the rest on it
    pub fn new(
        kind: ObligationKind,
        owed_by: OwedBy,
        text: impl Into<String>,
        quote: impl Into<String>,
        quote_location: impl Into<String>,
    ) -> Self {
        Self {
            agora_obligation: OBLIGATION_VERSION,
            source: None,
            kind,
            owed_by,
            until: None,
            text: text.into(),
            quote: quote.into(),
            quote_location: quote_location.into(),
            thread: None,
        }
    }
}

/// What an amendment of an [obligation kind](AmendmentKind::OBLIGATION)
/// says, tagged by that kind: [`Amendment::update`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ObligationUpdate {
    /// The thread where the work is planned. A later plan replaces it
    Planned { plan: PostId },
    /// Met
    Discharged { evidence: Evidence },
    /// Missed and still owed. The amendment's note says what was missed
    Lapsed,
    /// Due at a new time, or undated
    Rescheduled {
        #[serde(default)]
        until: Option<Until>,
    },
    /// Released
    Withdrawn,
}

impl ObligationUpdate {
    /// The [`AmendmentKind`] this belongs on
    pub fn kind(&self) -> AmendmentKind {
        match self {
            Self::Planned { .. } => AmendmentKind::Planned,
            Self::Discharged { .. } => AmendmentKind::Discharged,
            Self::Lapsed => AmendmentKind::Lapsed,
            Self::Rescheduled { .. } => AmendmentKind::Rescheduled,
            Self::Withdrawn => AmendmentKind::Withdrawn,
        }
    }
}

/// What shows an obligation was met
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Evidence {
    /// A governance entry: the decision that heard it, a record
    Governance { id: GovernanceLogId },
    /// A pull request, as `owner/name` and its number
    PullRequest { repo: String, number: u64 },
    /// A commit, as `owner/name` and its hex sha (7 to 40 digits)
    Commit { repo: String, sha: String },
    /// A deploy, on a date, and what went out
    Deploy {
        #[serde(with = "full_date")]
        #[cfg_attr(feature = "schemars", schemars(with = "NaiveDate"))]
        date: NaiveDate,
        note: String,
    },
}

/// Where an obligation stands, from its amendments: see
/// [`ObligationState::from_amendments`]
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct ObligationState {
    pub status: ObligationStatus,
    /// When it is due now: the last reschedule's, or the obligation's own
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub until: Option<Until>,
    /// The `authority` of the reschedule that set `until`, if one did
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub until_authority: Option<GovernanceLogId>,
    /// The latest plan
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub plan: Option<PostId>,
    /// When it last lapsed. Kept after a discharge: a late discharge reads
    /// as "discharged, lapsed on …"
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lapsed_at: Option<DateTime<Utc>>,
}

impl ObligationState {
    /// The state of `obligation` (its latest version) after `amendments`,
    /// those naming it with their `created_at`, in chain order. Kinds that
    /// are not obligation kinds change nothing here.
    ///
    /// A discharge or withdrawal closes it, and the last one wins. A lapse
    /// marks an open obligation lapsed, and a reschedule reopens a lapsed
    /// one: it has a new due date and has not missed it yet. Neither moves
    /// a closed one.
    pub fn from_amendments<'a>(
        obligation: &Obligation,
        amendments: impl IntoIterator<Item = (DateTime<Utc>, &'a Amendment)>,
    ) -> Self {
        let mut state = Self {
            until: obligation.until.clone(),
            ..Self::default()
        };
        for (at, amendment) in amendments {
            let Some(update) = &amendment.update else {
                continue;
            };
            match update {
                ObligationUpdate::Planned { plan } => state.plan = Some(*plan),
                ObligationUpdate::Discharged { .. } => {
                    state.status = ObligationStatus::Discharged;
                }
                ObligationUpdate::Withdrawn => {
                    state.status = ObligationStatus::Withdrawn;
                }
                ObligationUpdate::Lapsed => {
                    state.lapsed_at = Some(at);
                    if state.status == ObligationStatus::Open {
                        state.status = ObligationStatus::Lapsed;
                    }
                }
                ObligationUpdate::Rescheduled { until } => {
                    state.until = until.clone();
                    state.until_authority = amendment.authority.clone();
                    if state.status == ObligationStatus::Lapsed {
                        state.status = ObligationStatus::Open;
                    }
                }
            }
        }
        state
    }
}

/// What the server knows about a governance entry that the obligation
/// rules need: see [`check_obligation_amendment`]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KnownEntry {
    pub entry_type: GovernanceLogEntryType,
    pub chain_seq: u64,
}

/// An obligation amendment that may not be appended
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ObligationRuleError {
    #[error(transparent)]
    Shape(#[from] AmendmentError),
    #[error("{0} is not an entry of the log")]
    UnknownEntry(GovernanceLogId),
    #[error(
        "the obligation is {0}; only a record closes it, and nothing reopens it"
    )]
    Closed(ObligationStatus),
    #[error("an undated obligation never lapses")]
    Undated,
    #[error("the obligation has already lapsed; reschedule it first")]
    AlreadyLapsed,
    #[error(
        "`{0}` here needs a Council decision as its `authority`: the \
         Council owes it, or set its deadline"
    )]
    NeedsCouncil(AmendmentKind),
    #[error(
        "the authority {authority} is not later than {earlier}: the \
         obligation, or the Council decision that set its deadline"
    )]
    AuthorityNotLater {
        authority: GovernanceLogId,
        earlier: GovernanceLogId,
    },
    #[error("evidence: {0:?} is not a commit sha (7 to 40 hex digits)")]
    BadSha(String),
    #[error("evidence: {0:?} is not a repository as `owner/name`")]
    BadRepo(String),
}

/// Whether `amendment` may be appended to `obligation`, the entry `id` at
/// `chain_seq`, now at `state` ([`ObligationState::from_amendments`]).
/// `entry` looks up an entry of the log by id.
///
/// The rules (agora `docs/design-obligations.md`):
///
/// - `planned`: anyone may record one;
/// - `discharged`: the Steward's for Steward- and staff-owed obligations;
///   a Council-owed one needs a Council decision as `authority`;
/// - `lapsed`: only a dated, open obligation lapses;
/// - `rescheduled`, `withdrawn`: by whoever set the deadline. If a Council
///   decision did (the source, or the authority of the last reschedule),
///   `authority` must be a Council decision. A Council-owed obligation is
///   withdrawn only by the Council;
/// - a `revision` never touches [`OBLIGATION_FIXED`]. One that narrows
///   `text` is a partial discharge: if the Council owes the obligation or
///   set its deadline, it needs a Council decision too. Its other fields
///   are clerical.
///
/// A Council decision that authorizes anything here is later than the
/// obligation and than the decision that set its deadline. Nothing but a
/// revision or another non-obligation kind amends a closed obligation, and
/// those kinds are otherwise not this function's business.
pub fn check_obligation_amendment(
    obligation: &Obligation,
    id: &GovernanceLogId,
    chain_seq: u64,
    state: &ObligationState,
    amendment: &Amendment,
    entry: impl Fn(&GovernanceLogId) -> Option<KnownEntry>,
) -> Result<(), ObligationRuleError> {
    amendment.validate()?;
    if let Some(revision) = &amendment.revision
        && let Some(path) = revision_touches(revision, &OBLIGATION_FIXED)
    {
        return Err(AmendmentError::FixedObligationField(path.into()).into());
    }
    let narrows_text = amendment
        .revision
        .as_ref()
        .is_some_and(|r| revision_touches(r, &["/text"]).is_some());
    if amendment.update.is_none() && !narrows_text {
        return Ok(());
    }
    if amendment.update.is_some() && state.status.is_closed() {
        return Err(ObligationRuleError::Closed(state.status));
    }
    let known = |id: &GovernanceLogId| {
        entry(id).ok_or_else(|| ObligationRuleError::UnknownEntry(id.clone()))
    };
    let council = |id: &GovernanceLogId| -> Result<
        Option<KnownEntry>,
        ObligationRuleError,
    > {
        let e = known(id)?;
        Ok((e.entry_type == GovernanceLogEntryType::CouncilDecision)
            .then_some(e))
    };
    if let Some(authority) = &amendment.authority {
        known(authority)?;
    }
    // The Council decision that set the deadline, if one did
    let mut setter = None;
    for id in [obligation.source.as_ref(), state.until_authority.as_ref()]
        .into_iter()
        .flatten()
    {
        if let Some(e) = council(id)? {
            setter = Some((id, e.chain_seq));
        }
    }
    // `authority`: a Council decision, later than the obligation and than
    // the decision that set its deadline
    let needs_council = || {
        let authority = amendment
            .authority
            .as_ref()
            .ok_or(ObligationRuleError::NeedsCouncil(amendment.kind))?;
        let decision = council(authority)?
            .ok_or(ObligationRuleError::NeedsCouncil(amendment.kind))?;
        for (earlier, seq) in
            [Some((id, chain_seq)), setter].into_iter().flatten()
        {
            if decision.chain_seq <= seq {
                return Err(ObligationRuleError::AuthorityNotLater {
                    authority: authority.clone(),
                    earlier: earlier.clone(),
                });
            }
        }
        Ok(())
    };
    let councils = obligation.owed_by == OwedBy::Council || setter.is_some();
    let Some(update) = &amendment.update else {
        // A revision narrowing `text`: a partial discharge
        return if councils { needs_council() } else { Ok(()) };
    };
    match update {
        ObligationUpdate::Planned { .. } => Ok(()),
        ObligationUpdate::Lapsed => match (&state.until, state.status) {
            (None, _) => Err(ObligationRuleError::Undated),
            (_, ObligationStatus::Lapsed) => {
                Err(ObligationRuleError::AlreadyLapsed)
            }
            _ => Ok(()),
        },
        ObligationUpdate::Discharged { evidence } => {
            check_evidence(evidence, &known)?;
            match obligation.owed_by {
                OwedBy::Council => needs_council(),
                OwedBy::Steward | OwedBy::Staff => Ok(()),
            }
        }
        ObligationUpdate::Rescheduled { .. } => match setter {
            Some(_) => needs_council(),
            None => Ok(()),
        },
        ObligationUpdate::Withdrawn => match councils {
            true => needs_council(),
            false => Ok(()),
        },
    }
}

fn check_evidence(
    evidence: &Evidence,
    known: &impl Fn(&GovernanceLogId) -> Result<KnownEntry, ObligationRuleError>,
) -> Result<(), ObligationRuleError> {
    let repo = |repo: &str| {
        let parts: Vec<&str> = repo.split('/').collect();
        match parts.as_slice() {
            [owner, name] if !owner.is_empty() && !name.is_empty() => Ok(()),
            _ => Err(ObligationRuleError::BadRepo(repo.to_string())),
        }
    };
    match evidence {
        Evidence::Governance { id } => known(id).map(|_| ()),
        Evidence::PullRequest { repo: r, .. } => repo(r),
        Evidence::Commit { repo: r, sha } => {
            repo(r)?;
            let hex = (7..=40).contains(&sha.len())
                && sha.chars().all(|c| c.is_ascii_hexdigit());
            hex.then_some(())
                .ok_or_else(|| ObligationRuleError::BadSha(sha.clone()))
        }
        Evidence::Deploy { .. } => Ok(()),
    }
}

#[cfg(test)]
mod tests;