Skip to main content

clm_rust_core/layer2/sync/
outbox_ops.rs

1// Layer 2 outbox orchestration, split out of `service.rs` (Sprint 532).
2// Behaviour is unchanged; these are inherent methods on `MCardSyncEngine`.
3
4use crate::layer2::sync::codec::{derive_delivery_id, derive_transfer_id};
5use crate::layer2::sync::petri::evaluate_transfer_guard;
6use crate::layer2::sync::service::SyncContractError;
7use crate::layer2::sync::service::{MCardSyncEngine, TERMINAL_ERROR_CODES};
8use crate::layer2::sync::types::{
9    RecordFrame, RetryOutcome, SyncOutboxEntry, TransferAttempt, TransferSendResult, TransitionPayload,
10};
11
12impl MCardSyncEngine {
13    pub fn enqueue_transfer(
14        &mut self,
15        target_node_id: &str,
16        records: Vec<RecordFrame>,
17        transitions: Vec<TransitionPayload>,
18        disambiguator: &str,
19    ) -> Result<SyncOutboxEntry, SyncContractError> {
20        let mut sorted_hashes: Vec<String> = records.iter().map(|r| r.hash.clone()).collect();
21        sorted_hashes.sort();
22        let hashes_json: Vec<String> = sorted_hashes.iter().map(|h| format!("\"{h}\"")).collect();
23        let canon = format!(
24            "{{\"disambiguator\":\"{}\",\"records\":[{}],\"targetNodeId\":\"{}\",\"transitions\":{}}}",
25            disambiguator,
26            hashes_json.join(","),
27            target_node_id,
28            transitions.len()
29        );
30        let q_ref = format!("blake3:{}", blake3::hash(canon.as_bytes()).to_hex());
31        let transfer_id = derive_transfer_id(&q_ref);
32        let delivery_id = derive_delivery_id(&q_ref, target_node_id);
33
34        if let Some(existing) = self.outbox.get(&delivery_id) {
35            return Ok(existing.clone());
36        }
37
38        let previous_marking = self.transfer_marking.clone();
39        *self.transfer_marking.entry("p_source".to_string()).or_insert(0) += 1;
40        let gate = evaluate_transfer_guard(&self.transfer_marking, "t_enqueue_push", 1);
41        if !gate.enabled {
42            self.transfer_marking = previous_marking;
43            return Err(SyncContractError::new(
44                "guard-rejected",
45                format!("Enqueue rejected: {}", gate.reason.unwrap_or_else(|| "unknown reason".to_string())),
46            ));
47        }
48        self.transfer_marking = gate.post_marking;
49
50        let entry = SyncOutboxEntry {
51            transfer_id,
52            delivery_id: delivery_id.clone(),
53            target_node_id: target_node_id.to_string(),
54            status: "in_flight".to_string(),
55            attempt_count: 0,
56            records,
57            transitions,
58            last_error: None,
59            error_code: None,
60            prior_transfer_id: None,
61        };
62        self.outbox.insert(delivery_id.clone(), entry.clone());
63        if let Err(err) = self.persist_outbox() {
64            self.outbox.remove(&delivery_id);
65            self.transfer_marking = previous_marking;
66            return Err(SyncContractError::new(
67                "storage-aborted",
68                format!("Failed to persist outbox for {delivery_id}: {err}"),
69            ));
70        }
71        Ok(entry)
72    }
73
74    /// Flush eligible outbox entries through the transport. The exact durable
75    /// entry must exist before any network I/O; transport errors are treated
76    /// as transient and keep the entry retryable.
77    pub fn flush_outbox(&mut self) -> Result<Vec<SyncOutboxEntry>, SyncContractError> {
78        if self.is_disposed || self.transport.is_none() {
79            return Ok(self.outbox.values().cloned().collect());
80        }
81        let eligible: Vec<String> = self
82            .outbox
83            .iter()
84            .filter(|(_, e)| e.status == "in_flight" || e.status == "queued")
85            .map(|(id, _)| id.clone())
86            .collect();
87        for delivery_id in eligible {
88            let entry = match self.outbox.get(&delivery_id) {
89                Some(e) => e.clone(),
90                None => continue,
91            };
92            if !self.is_durably_queued(&entry) {
93                return Err(SyncContractError::new(
94                    "storage-aborted",
95                    format!("Durable outbox entry missing or mismatched for {delivery_id}"),
96                ));
97            }
98            let attempt = TransferAttempt {
99                transfer_id: entry.transfer_id.clone(),
100                delivery_id: entry.delivery_id.clone(),
101                source_node_id: self.node_id.clone(),
102                target_node_id: entry.target_node_id.clone(),
103                record_hashes: entry.records.iter().map(|r| r.hash.clone()).collect(),
104                transitions: entry.transitions.clone(),
105                attempt_count: entry.attempt_count + 1,
106            };
107            let res = match self
108                .transport
109                .as_ref()
110                .expect("transport checked")
111                .send_transfer(&attempt, &entry.records)
112            {
113                Ok(r) => r,
114                Err(err) => TransferSendResult {
115                    ok: false,
116                    committed: false,
117                    replayed: false,
118                    transient: true,
119                    error_code: Some("transport-transient".to_string()),
120                    reason: Some(err),
121                },
122            };
123            let mut updated = entry.clone();
124            updated.attempt_count = attempt.attempt_count;
125            if res.ok && res.committed {
126                self.transfer_marking =
127                    evaluate_transfer_guard(&self.transfer_marking, "t_commit_push", 1).post_marking;
128                updated.status = "committed".to_string();
129            } else if res.transient {
130                self.transfer_marking =
131                    evaluate_transfer_guard(&self.transfer_marking, "t_retry", 1).post_marking;
132                updated.status = "in_flight".to_string();
133                updated.last_error = res.reason.clone();
134                updated.error_code =
135                    Some(res.error_code.clone().unwrap_or_else(|| "transport-transient".to_string()));
136            } else {
137                self.transfer_marking =
138                    evaluate_transfer_guard(&self.transfer_marking, "t_reject", 1).post_marking;
139                updated.status = "rejected".to_string();
140                updated.last_error = res.reason.clone();
141                updated.error_code =
142                    Some(res.error_code.clone().unwrap_or_else(|| "guard-rejected".to_string()));
143            }
144            self.outbox.insert(delivery_id.clone(), updated);
145            if let Err(err) = self.persist_outbox() {
146                return Err(SyncContractError::new(
147                    "storage-aborted",
148                    format!("Failed to persist outbox for {delivery_id}: {err}"),
149                ));
150            }
151        }
152        Ok(self.outbox.values().cloned().collect())
153    }
154
155    pub fn retry_transfer(&mut self, delivery_id: &str) -> RetryOutcome {
156        let Some(entry) = self.outbox.get(delivery_id).cloned() else {
157            return RetryOutcome {
158                ok: false,
159                error_code: Some("guard-rejected".to_string()),
160                reason: Some("Transfer is not in rejected status".to_string()),
161                ..Default::default()
162            };
163        };
164        if entry.status != "rejected" {
165            return RetryOutcome {
166                ok: false,
167                error_code: Some("guard-rejected".to_string()),
168                reason: Some("Transfer is not in rejected status".to_string()),
169                ..Default::default()
170            };
171        }
172        if let Some(code) = entry.error_code.as_deref() {
173            if TERMINAL_ERROR_CODES.contains(&code) {
174                return RetryOutcome {
175                    ok: false,
176                    error_code: Some(code.to_string()),
177                    reason: Some("Terminal integrity failure cannot retry".to_string()),
178                    ..Default::default()
179                };
180            }
181        }
182        let g1 = evaluate_transfer_guard(&self.transfer_marking, "t_retry_transfer", 1);
183        if !g1.enabled {
184            return RetryOutcome {
185                ok: false,
186                error_code: Some("guard-rejected".to_string()),
187                reason: g1.reason,
188                ..Default::default()
189            };
190        }
191        self.transfer_marking =
192            evaluate_transfer_guard(&g1.post_marking, "t_prepare_transfer", 1).post_marking;
193        let mut updated = entry.clone();
194        updated.status = "in_flight".to_string();
195        updated.prior_transfer_id = Some(entry.transfer_id.clone());
196        updated.transfer_id = format!("{}:retry:{}", entry.transfer_id, entry.attempt_count);
197        self.outbox.insert(delivery_id.to_string(), updated.clone());
198        let _ = self.persist_outbox();
199        RetryOutcome { ok: true, entry: Some(updated), ..Default::default() }
200    }
201}