Skip to main content

magi/
task_decision.rs

1//! Task/chat-native decision lifecycle. Delivery, reading and conversation turns
2//! are deliberately absent: only an effect receipt or explicit settlement ends
3//! a decision. This record travels with the durable inquiry, not a UI card.
4use anyhow::{Result, ensure};
5use jiff::Timestamp;
6use serde::{Deserialize, Serialize};
7
8/// State of the requested decision effect, independent of message transport.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum Status {
12    /// The owner has not requested an operation.
13    AwaitingOwner,
14    /// An owner request is recorded; the consumer has not confirmed its effect.
15    Queued,
16    /// The consumer has begun the operation.
17    InProgress,
18    /// A failure or uncertain outcome needs reconciliation before retry.
19    RetryNeeded,
20    /// A durable receipt confirms the effect, or explicit settlement ends it.
21    Resolved,
22}
23
24/// An append-only explanation of a state change.
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(deny_unknown_fields)]
27pub struct Event {
28    /// Time recorded, never used as approval or resolution evidence.
29    pub at: Timestamp,
30    /// Resulting lifecycle status.
31    pub status: Status,
32    /// Owner request, effect receipt or settlement evidence.
33    pub evidence: String,
34}
35
36/// Durable decision state embedded in an inquiry.
37#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
38#[serde(deny_unknown_fields)]
39pub struct Decision {
40    /// Concise reason shown on a phone without opening the conversation.
41    pub reason: String,
42    /// Current effect status.
43    pub status: Status,
44    /// Recorded owner request; migration never manufactures one.
45    pub request: Option<String>,
46    /// Current actionable error, including uncertainty about an external call.
47    pub error: Option<String>,
48    /// The consumer proved that the last attempt failed before any effect.
49    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
50    pub retry_safe: bool,
51    /// Exact source response generation accepted by a fresh owner command.
52    /// Migration never fills this field from a saved reply.
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub source_answer_at: Option<Timestamp>,
55    /// Explicit owner confirmation that an accepted legacy effect has no
56    /// remaining work. Operational source readers must not consume it again.
57    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
58    pub legacy_settled: bool,
59    /// Complete lifecycle history; never pruned by delivery or read receipts.
60    pub history: Vec<Event>,
61}
62
63impl Decision {
64    /// File an inquiry which requires owner input.
65    pub fn awaiting(reason: String) -> Self {
66        Self {
67            reason,
68            status: Status::AwaitingOwner,
69            request: None,
70            error: None,
71            retry_safe: false,
72            source_answer_at: None,
73            legacy_settled: false,
74            history: vec![],
75        }
76    }
77
78    fn event(&mut self, status: Status, evidence: &str) -> bool {
79        if self.status == status && self.history.last().is_some_and(|e| e.evidence == evidence) {
80            return false;
81        }
82        self.status = status;
83        self.history.push(Event {
84            at: Timestamp::now(),
85            status,
86            evidence: evidence.to_owned(),
87        });
88        true
89    }
90
91    /// Record acceptance, without claiming that the command has been applied.
92    pub fn accept(&mut self, request: &str) -> Result<bool> {
93        ensure!(!request.trim().is_empty(), "decision request is empty");
94        if let Some(prior) = &self.request {
95            ensure!(
96                prior == request,
97                "decision already binds a different request"
98            );
99            return Ok(false);
100        }
101        ensure!(
102            matches!(self.status, Status::AwaitingOwner | Status::RetryNeeded),
103            "decision needs reconciliation"
104        );
105        self.request = Some(request.to_owned());
106        self.error = None;
107        Ok(self.event(Status::Queued, request))
108    }
109
110    /// The consumer begins the accepted effect; no automatic retry of uncertainty.
111    pub fn start(&mut self) -> Result<bool> {
112        ensure!(self.status == Status::Queued, "decision is not queued");
113        ensure!(self.request.is_some(), "decision has no owner request");
114        self.retry_safe = false;
115        Ok(self.event(Status::InProgress, "effect consumer started"))
116    }
117
118    /// The command was accepted but a worker/forge effect is still outstanding.
119    pub(crate) fn queued(&mut self) -> Result<bool> {
120        ensure!(
121            self.request.is_some() && self.status == Status::InProgress,
122            "decision is not executing an owner request"
123        );
124        Ok(self.event(Status::Queued, "command accepted; effect not yet confirmed"))
125    }
126
127    /// Retain an unsuccessful or uncertain operation in the active list.
128    pub fn fail(&mut self, error: &str) -> Result<bool> {
129        ensure!(
130            self.status != Status::Resolved,
131            "decision is already resolved"
132        );
133        ensure!(!error.trim().is_empty(), "decision error is empty");
134        self.error = Some(error.to_owned());
135        self.retry_safe = false;
136        Ok(self.event(Status::RetryNeeded, error))
137    }
138
139    /// Record proof that no operation began. This is distinct from uncertainty
140    /// after a write or external call; only an owner retry may requeue it.
141    pub(crate) fn fail_before_effect(&mut self, error: &str) -> Result<bool> {
142        let prior = self.retry_safe;
143        let changed = self.fail(error)?;
144        self.retry_safe = true;
145        Ok(changed || !prior)
146    }
147
148    /// Requeue the same owner request after a proven pre-execution failure.
149    pub(crate) fn retry_unapplied(&mut self) -> Result<bool> {
150        ensure!(
151            self.status == Status::RetryNeeded && self.retry_safe && self.request.is_some(),
152            "effect needs receipt reconciliation before retry"
153        );
154        self.error = None;
155        self.retry_safe = false;
156        Ok(self.event(
157            Status::Queued,
158            "owner retried a request proven not to have started",
159        ))
160    }
161
162    /// Called only after rereading the operation's authoritative durable receipt.
163    /// Also repairs a crash between application and updating this projection.
164    pub(crate) fn applied(&mut self, receipt: &str) -> Result<bool> {
165        ensure!(!receipt.trim().is_empty(), "effect receipt is empty");
166        if self.status == Status::Resolved {
167            return Ok(false);
168        }
169        self.error = None;
170        self.retry_safe = false;
171        Ok(self.event(Status::Resolved, receipt))
172    }
173
174    /// Retire passive history without claiming an owner settlement or effect.
175    pub(crate) fn retire(&mut self, reason: &str) -> Result<bool> {
176        ensure!(self.request.is_none(), "accepted effects cannot be retired");
177        ensure!(!reason.trim().is_empty(), "retirement reason is empty");
178        if self.status == Status::Resolved {
179            return Ok(false);
180        }
181        ensure!(
182            matches!(self.status, Status::AwaitingOwner | Status::RetryNeeded),
183            "active effects cannot be retired"
184        );
185        self.error = None;
186        self.retry_safe = false;
187        Ok(self.event(Status::Resolved, reason))
188    }
189
190    /// Owner settlement is distinct from an application receipt. Legacy
191    /// consumers cannot always prove their external outcome; the owner may
192    /// explicitly confirm that no effect remains after inspecting it.
193    pub(crate) fn settle_legacy(&mut self, reason: &str) -> Result<bool> {
194        ensure!(
195            self.request
196                .as_deref()
197                .is_some_and(|r| r.starts_with("decision: ")),
198            "only an accepted legacy source decision supports this settlement"
199        );
200        ensure!(
201            self.status != Status::InProgress,
202            "effect consumer is still executing"
203        );
204        ensure!(!reason.trim().is_empty(), "settlement reason is empty");
205        if self.status == Status::Resolved {
206            return Ok(false);
207        }
208        self.legacy_settled = true;
209        self.error = None;
210        self.retry_safe = false;
211        Ok(self.event(Status::Resolved, reason))
212    }
213
214    /// Explicitly settle discussion without an operation, or supersede it with
215    /// another inquiry. A queued/uncertain effect must first be reconciled by
216    /// its consumer; an owner reply alone cannot hide it.
217    pub fn settle(&mut self, reason: &str) -> Result<bool> {
218        ensure!(
219            self.status == Status::AwaitingOwner
220                || (self.status == Status::RetryNeeded
221                    && (self.request.is_none() || self.retry_safe)),
222            "an accepted effect requires receipt reconciliation"
223        );
224        ensure!(!reason.trim().is_empty(), "settlement reason is empty");
225        Ok(self.event(Status::Resolved, reason))
226    }
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232
233    #[test]
234    fn acceptance_is_not_application_and_history_explains_completion() {
235        let mut decision = Decision::awaiting("Review the publication".into());
236        decision.accept("owner requested publication").unwrap();
237        assert_eq!(decision.status, Status::Queued);
238        assert!(decision.settle("read the message").is_err());
239        decision.start().unwrap();
240        assert_eq!(decision.status, Status::InProgress);
241        decision
242            .applied("publication receipt: PR 42 confirmed")
243            .unwrap();
244        assert_eq!(decision.status, Status::Resolved);
245        assert_eq!(decision.history.len(), 3);
246        assert!(!decision.applied("same receipt after restart").unwrap());
247    }
248
249    #[test]
250    fn uncertain_effect_cannot_be_blindly_replayed_or_settled() {
251        let mut decision = Decision::awaiting("Retry checks".into());
252        decision.accept("rerun request 12").unwrap();
253        decision.start().unwrap();
254        decision
255            .fail("network lost after request: inspect receipt 12")
256            .unwrap();
257        let saved = serde_json::to_vec(&decision).unwrap();
258        let mut restarted: Decision = serde_json::from_slice(&saved).unwrap();
259        assert_eq!(restarted.status, Status::RetryNeeded);
260        assert!(restarted.start().is_err());
261        assert!(restarted.settle("reply was read").is_err());
262        assert!(restarted.accept("a different request").is_err());
263        restarted
264            .applied("receipt 12: execution confirmed by forge")
265            .unwrap();
266        assert_eq!(restarted.status, Status::Resolved);
267        assert!(restarted.error.is_none());
268    }
269
270    #[test]
271    fn explicit_settlement_requires_a_reason_and_executes_nothing() {
272        let mut decision = Decision::awaiting("Choose a direction".into());
273        assert!(decision.settle("").is_err());
274        decision
275            .settle("owner explicitly confirmed no change is necessary")
276            .unwrap();
277        assert_eq!(decision.status, Status::Resolved);
278        assert!(decision.request.is_none());
279    }
280}