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 settle_legacy(&mut self, reason: &str) -> Result<bool> {
178 ensure!(
179 self.request
180 .as_deref()
181 .is_some_and(|r| r.starts_with("decision: ")),
182 "only an accepted legacy source decision supports this settlement"
183 );
184 ensure!(
185 self.status != Status::InProgress,
186 "effect consumer is still executing"
187 );
188 ensure!(!reason.trim().is_empty(), "settlement reason is empty");
189 if self.status == Status::Resolved {
190 return Ok(false);
191 }
192 self.legacy_settled = true;
193 self.error = None;
194 self.retry_safe = false;
195 Ok(self.event(Status::Resolved, reason))
196 }
197
198 pub fn settle(&mut self, reason: &str) -> Result<bool> {
202 ensure!(
203 self.status == Status::AwaitingOwner
204 || (self.status == Status::RetryNeeded
205 && (self.request.is_none() || self.retry_safe)),
206 "an accepted effect requires receipt reconciliation"
207 );
208 ensure!(!reason.trim().is_empty(), "settlement reason is empty");
209 Ok(self.event(Status::Resolved, reason))
210 }
211}
212
213#[cfg(test)]
214mod tests {
215 use super::*;
216
217 #[test]
218 fn acceptance_is_not_application_and_history_explains_completion() {
219 let mut decision = Decision::awaiting("Review the publication".into());
220 decision.accept("owner requested publication").unwrap();
221 assert_eq!(decision.status, Status::Queued);
222 assert!(decision.settle("read the message").is_err());
223 decision.start().unwrap();
224 assert_eq!(decision.status, Status::InProgress);
225 decision
226 .applied("publication receipt: PR 42 confirmed")
227 .unwrap();
228 assert_eq!(decision.status, Status::Resolved);
229 assert_eq!(decision.history.len(), 3);
230 assert!(!decision.applied("same receipt after restart").unwrap());
231 }
232
233 #[test]
234 fn uncertain_effect_cannot_be_blindly_replayed_or_settled() {
235 let mut decision = Decision::awaiting("Retry checks".into());
236 decision.accept("rerun request 12").unwrap();
237 decision.start().unwrap();
238 decision
239 .fail("network lost after request: inspect receipt 12")
240 .unwrap();
241 let saved = serde_json::to_vec(&decision).unwrap();
242 let mut restarted: Decision = serde_json::from_slice(&saved).unwrap();
243 assert_eq!(restarted.status, Status::RetryNeeded);
244 assert!(restarted.start().is_err());
245 assert!(restarted.settle("reply was read").is_err());
246 assert!(restarted.accept("a different request").is_err());
247 restarted
248 .applied("receipt 12: execution confirmed by forge")
249 .unwrap();
250 assert_eq!(restarted.status, Status::Resolved);
251 assert!(restarted.error.is_none());
252 }
253
254 #[test]
255 fn explicit_settlement_requires_a_reason_and_executes_nothing() {
256 let mut decision = Decision::awaiting("Choose a direction".into());
257 assert!(decision.settle("").is_err());
258 decision
259 .settle("owner explicitly confirmed no change is necessary")
260 .unwrap();
261 assert_eq!(decision.status, Status::Resolved);
262 assert!(decision.request.is_none());
263 }
264}