1use anyhow::{Result, ensure};
5use jiff::Timestamp;
6use serde::{Deserialize, Serialize};
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum Status {
12 AwaitingOwner,
14 Queued,
16 InProgress,
18 RetryNeeded,
20 Resolved,
22}
23
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(deny_unknown_fields)]
27pub struct Event {
28 pub at: Timestamp,
30 pub status: Status,
32 pub evidence: String,
34}
35
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
38#[serde(deny_unknown_fields)]
39pub struct Decision {
40 pub reason: String,
42 pub status: Status,
44 pub request: Option<String>,
46 pub error: Option<String>,
48 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
50 pub retry_safe: bool,
51 #[serde(default, skip_serializing_if = "Option::is_none")]
54 pub source_answer_at: Option<Timestamp>,
55 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
58 pub legacy_settled: bool,
59 pub history: Vec<Event>,
61}
62
63impl Decision {
64 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 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 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 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 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 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 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 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 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 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 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}