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