made_core/value_objects/delivery/
attention_kind.rs

1use std::fmt;
2
3use serde::{Deserialize, Serialize};
4
5/// Why a ceremony is worth the integrator's attention.
6///
7/// A closed list, because the loop's stopping rules are written over it:
8/// a kind the engine cannot name is a kind an integrator cannot be told
9/// to stop for.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
11#[serde(rename_all = "snake_case")]
12pub enum AttentionKind {
13    /// A step produced a result the integrator can take up.
14    ResultAvailable,
15    /// A completed step's own output says it was not accepted.
16    ReviewRejected,
17    /// A step failed or ran out of time.
18    StepFailed,
19    /// The ceremony cannot move without something outside it.
20    Blocked,
21    /// A human guard needs a person, or a person has just answered one.
22    HumanDecisionRequested,
23    /// A ceremony or state deadline passed.
24    DeadlineExceeded,
25    /// Nothing has happened for longer than the policy tolerates.
26    InactivityDetected,
27    /// A supervisor asked a question of whoever is working.
28    InterventionRequested,
29    /// The ceremony reached a terminal phase.
30    CeremonyEnded,
31}
32
33impl AttentionKind {
34    /// Every kind, which is also the default policy's selection.
35    pub const ALL: [Self; 9] = [
36        Self::ResultAvailable,
37        Self::ReviewRejected,
38        Self::StepFailed,
39        Self::Blocked,
40        Self::HumanDecisionRequested,
41        Self::DeadlineExceeded,
42        Self::InactivityDetected,
43        Self::InterventionRequested,
44        Self::CeremonyEnded,
45    ];
46
47    /// The kind a derived identity ends with, when it ends with one.
48    ///
49    /// [`AttentionEventId::derive`](super::AttentionEventId::derive)
50    /// spells the kind into the identity, and the ledger holds that
51    /// identity rather than the event. Reading it back is what lets a
52    /// queue be weighed — which of the things waiting may be dropped —
53    /// without keeping a second copy of what each delivery is about.
54    #[must_use]
55    pub fn from_label(label: &str) -> Option<Self> {
56        Self::ALL.into_iter().find(|kind| kind.as_str() == label)
57    }
58
59    #[must_use]
60    pub const fn as_str(self) -> &'static str {
61        match self {
62            Self::ResultAvailable => "result_available",
63            Self::ReviewRejected => "review_rejected",
64            Self::StepFailed => "step_failed",
65            Self::Blocked => "blocked",
66            Self::HumanDecisionRequested => "human_decision_requested",
67            Self::DeadlineExceeded => "deadline_exceeded",
68            Self::InactivityDetected => "inactivity_detected",
69            Self::InterventionRequested => "intervention_requested",
70            Self::CeremonyEnded => "ceremony_ended",
71        }
72    }
73
74    /// Whether dropping this kind under overflow would lose a decision.
75    ///
76    /// Overflow discards the oldest item that nobody is waiting on. A
77    /// human decision, a block or the end of a ceremony are things the
78    /// loop stops for, so they are never the ones discarded.
79    #[must_use]
80    pub const fn is_blocking(self) -> bool {
81        matches!(
82            self,
83            Self::Blocked
84                | Self::HumanDecisionRequested
85                | Self::CeremonyEnded
86                | Self::DeadlineExceeded
87                | Self::InterventionRequested
88        )
89    }
90}
91
92impl fmt::Display for AttentionKind {
93    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
94        formatter.write_str(self.as_str())
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn every_kind_is_listed_once_and_serialises_as_its_name() {
104        let mut seen = std::collections::BTreeSet::new();
105        for kind in AttentionKind::ALL {
106            assert!(seen.insert(kind), "{kind} is listed twice");
107            assert_eq!(
108                serde_json::to_string(&kind).unwrap(),
109                format!("\"{}\"", kind.as_str())
110            );
111        }
112        assert_eq!(seen.len(), 9);
113    }
114
115    #[test]
116    fn results_and_inactivity_are_the_droppable_kinds() {
117        assert!(!AttentionKind::ResultAvailable.is_blocking());
118        assert!(!AttentionKind::InactivityDetected.is_blocking());
119        assert!(AttentionKind::HumanDecisionRequested.is_blocking());
120    }
121}
made_core/value_objects/delivery/attention_kind.rs

made_core/value_objects/delivery/
attention_kind.rs
