use anyhow::{Result, ensure};
use jiff::Timestamp;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Status {
AwaitingOwner,
Queued,
InProgress,
RetryNeeded,
Resolved,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Event {
pub at: Timestamp,
pub status: Status,
pub evidence: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Decision {
pub reason: String,
pub status: Status,
pub request: Option<String>,
pub error: Option<String>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub retry_safe: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source_answer_at: Option<Timestamp>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub legacy_settled: bool,
pub history: Vec<Event>,
}
impl Decision {
pub fn awaiting(reason: String) -> Self {
Self {
reason,
status: Status::AwaitingOwner,
request: None,
error: None,
retry_safe: false,
source_answer_at: None,
legacy_settled: false,
history: vec![],
}
}
fn event(&mut self, status: Status, evidence: &str) -> bool {
if self.status == status && self.history.last().is_some_and(|e| e.evidence == evidence) {
return false;
}
self.status = status;
self.history.push(Event {
at: Timestamp::now(),
status,
evidence: evidence.to_owned(),
});
true
}
pub fn accept(&mut self, request: &str) -> Result<bool> {
ensure!(!request.trim().is_empty(), "decision request is empty");
if let Some(prior) = &self.request {
ensure!(
prior == request,
"decision already binds a different request"
);
return Ok(false);
}
ensure!(
matches!(self.status, Status::AwaitingOwner | Status::RetryNeeded),
"decision needs reconciliation"
);
self.request = Some(request.to_owned());
self.error = None;
Ok(self.event(Status::Queued, request))
}
pub fn start(&mut self) -> Result<bool> {
ensure!(self.status == Status::Queued, "decision is not queued");
ensure!(self.request.is_some(), "decision has no owner request");
self.retry_safe = false;
Ok(self.event(Status::InProgress, "effect consumer started"))
}
pub(crate) fn queued(&mut self) -> Result<bool> {
ensure!(
self.request.is_some() && self.status == Status::InProgress,
"decision is not executing an owner request"
);
Ok(self.event(Status::Queued, "command accepted; effect not yet confirmed"))
}
pub fn fail(&mut self, error: &str) -> Result<bool> {
ensure!(
self.status != Status::Resolved,
"decision is already resolved"
);
ensure!(!error.trim().is_empty(), "decision error is empty");
self.error = Some(error.to_owned());
self.retry_safe = false;
Ok(self.event(Status::RetryNeeded, error))
}
pub(crate) fn fail_before_effect(&mut self, error: &str) -> Result<bool> {
let prior = self.retry_safe;
let changed = self.fail(error)?;
self.retry_safe = true;
Ok(changed || !prior)
}
pub(crate) fn retry_unapplied(&mut self) -> Result<bool> {
ensure!(
self.status == Status::RetryNeeded && self.retry_safe && self.request.is_some(),
"effect needs receipt reconciliation before retry"
);
self.error = None;
self.retry_safe = false;
Ok(self.event(
Status::Queued,
"owner retried a request proven not to have started",
))
}
pub(crate) fn applied(&mut self, receipt: &str) -> Result<bool> {
ensure!(!receipt.trim().is_empty(), "effect receipt is empty");
if self.status == Status::Resolved {
return Ok(false);
}
self.error = None;
self.retry_safe = false;
Ok(self.event(Status::Resolved, receipt))
}
pub(crate) fn retire(&mut self, reason: &str) -> Result<bool> {
ensure!(self.request.is_none(), "accepted effects cannot be retired");
ensure!(!reason.trim().is_empty(), "retirement reason is empty");
if self.status == Status::Resolved {
return Ok(false);
}
ensure!(
matches!(self.status, Status::AwaitingOwner | Status::RetryNeeded),
"active effects cannot be retired"
);
self.error = None;
self.retry_safe = false;
Ok(self.event(Status::Resolved, reason))
}
pub(crate) fn settle_legacy(&mut self, reason: &str) -> Result<bool> {
ensure!(
self.request
.as_deref()
.is_some_and(|r| r.starts_with("decision: ")),
"only an accepted legacy source decision supports this settlement"
);
ensure!(
self.status != Status::InProgress,
"effect consumer is still executing"
);
ensure!(!reason.trim().is_empty(), "settlement reason is empty");
if self.status == Status::Resolved {
return Ok(false);
}
self.legacy_settled = true;
self.error = None;
self.retry_safe = false;
Ok(self.event(Status::Resolved, reason))
}
pub fn settle(&mut self, reason: &str) -> Result<bool> {
ensure!(
self.status == Status::AwaitingOwner
|| (self.status == Status::RetryNeeded
&& (self.request.is_none() || self.retry_safe)),
"an accepted effect requires receipt reconciliation"
);
ensure!(!reason.trim().is_empty(), "settlement reason is empty");
Ok(self.event(Status::Resolved, reason))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn acceptance_is_not_application_and_history_explains_completion() {
let mut decision = Decision::awaiting("Review the publication".into());
decision.accept("owner requested publication").unwrap();
assert_eq!(decision.status, Status::Queued);
assert!(decision.settle("read the message").is_err());
decision.start().unwrap();
assert_eq!(decision.status, Status::InProgress);
decision
.applied("publication receipt: PR 42 confirmed")
.unwrap();
assert_eq!(decision.status, Status::Resolved);
assert_eq!(decision.history.len(), 3);
assert!(!decision.applied("same receipt after restart").unwrap());
}
#[test]
fn uncertain_effect_cannot_be_blindly_replayed_or_settled() {
let mut decision = Decision::awaiting("Retry checks".into());
decision.accept("rerun request 12").unwrap();
decision.start().unwrap();
decision
.fail("network lost after request: inspect receipt 12")
.unwrap();
let saved = serde_json::to_vec(&decision).unwrap();
let mut restarted: Decision = serde_json::from_slice(&saved).unwrap();
assert_eq!(restarted.status, Status::RetryNeeded);
assert!(restarted.start().is_err());
assert!(restarted.settle("reply was read").is_err());
assert!(restarted.accept("a different request").is_err());
restarted
.applied("receipt 12: execution confirmed by forge")
.unwrap();
assert_eq!(restarted.status, Status::Resolved);
assert!(restarted.error.is_none());
}
#[test]
fn explicit_settlement_requires_a_reason_and_executes_nothing() {
let mut decision = Decision::awaiting("Choose a direction".into());
assert!(decision.settle("").is_err());
decision
.settle("owner explicitly confirmed no change is necessary")
.unwrap();
assert_eq!(decision.status, Status::Resolved);
assert!(decision.request.is_none());
}
}