Skip to main content

clm_rust_core/layer2/sync/
service.rs

1use crate::layer2::sync::codec::unframe_record;
2use crate::layer2::sync::petri::{
3    compute_marking_state_hash, evaluate_lifecycle_guard,
4    resolve_concurrent_head_winner,
5};
6pub use crate::layer2::sync::types::{
7    SyncContractError, SyncFrameTransport, SyncOutboxPort,
8};
9pub(crate) use crate::layer2::sync::types::{
10    kind_to_lifecycle, normalize_qualified_hash, TERMINAL_ERROR_CODES,
11};
12use crate::layer2::sync::types::{
13    MCardRecord, ReceiveOutcome, RecordFrame, SyncOutboxEntry, TransferAttempt,
14    TransitionGateResult, TransitionPayload,
15};
16use std::collections::{BTreeMap, BTreeSet};
17
18pub struct MCardSyncEngine {
19    pub node_id: String,
20    pub is_disposed: bool,
21    pub records: BTreeMap<String, MCardRecord>,
22    pub handle_markings: BTreeMap<String, BTreeMap<String, i64>>,
23    pub handle_heads: BTreeMap<String, Option<String>>,
24    pub handle_clocks: BTreeMap<String, BTreeMap<String, u64>>,
25    pub transitions: Vec<TransitionPayload>,
26    pub committed_transfers: BTreeSet<String>,
27    pub outbox: BTreeMap<String, SyncOutboxEntry>,
28    pub transfer_marking: BTreeMap<String, i64>,
29    pub transport: Option<Box<dyn SyncFrameTransport>>,
30    pub outbox_port: Option<Box<dyn SyncOutboxPort>>,
31}
32
33impl MCardSyncEngine {
34    pub fn new(node_id: &str) -> Self {
35        Self::new_with_ports(node_id, None, None)
36    }
37
38    pub fn new_with_ports(
39        node_id: &str,
40        transport: Option<Box<dyn SyncFrameTransport>>,
41        outbox_port: Option<Box<dyn SyncOutboxPort>>,
42    ) -> Self {
43        let mut transfer_marking = BTreeMap::new();
44        transfer_marking.insert("p_source".to_string(), 0);
45        transfer_marking.insert("p_in_flight".to_string(), 0);
46        transfer_marking.insert("p_target".to_string(), 0);
47        transfer_marking.insert("p_rejected".to_string(), 0);
48        let mut engine = Self {
49            node_id: node_id.to_string(),
50            is_disposed: false,
51            records: BTreeMap::new(),
52            handle_markings: BTreeMap::new(),
53            handle_heads: BTreeMap::new(),
54            handle_clocks: BTreeMap::new(),
55            transitions: Vec::new(),
56            committed_transfers: BTreeSet::new(),
57            outbox: BTreeMap::new(),
58            transfer_marking,
59            transport,
60            outbox_port,
61        };
62        if let Some(port) = engine.outbox_port.as_ref() {
63            if let Ok(entries) = port.load_outbox() {
64                for entry in entries {
65                    let place = match entry.status.as_str() {
66                        "queued" => "p_source",
67                        "in_flight" => "p_in_flight",
68                        "committed" => "p_target",
69                        "rejected" => "p_rejected",
70                        _ => "p_in_flight",
71                    };
72                    *engine.transfer_marking.entry(place.to_string()).or_insert(0) += 1;
73                    engine.outbox.insert(entry.delivery_id.clone(), entry);
74                }
75            }
76        }
77        engine
78    }
79
80    pub fn default_lifecycle_marking() -> BTreeMap<String, i64> {
81        let mut m = BTreeMap::new();
82        m.insert("p_unborn".to_string(), 1);
83        m.insert("p_active".to_string(), 0);
84        m.insert("p_retired_tombstone".to_string(), 0);
85        m.insert("p_conflict_quarantine".to_string(), 0);
86        m
87    }
88
89    pub(crate) fn persist_outbox(&self) -> Result<(), String> {
90        match self.outbox_port.as_ref() {
91            Some(port) => {
92                let entries: Vec<SyncOutboxEntry> = self.outbox.values().cloned().collect();
93                port.save_outbox(&entries)
94            }
95            None => Ok(()),
96        }
97    }
98
99    pub fn admit_record_frame(&mut self, frame: &RecordFrame) -> Result<(String, bool), (String, String)> {
100        let (rec, q_hash) = unframe_record(frame, crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3)?;
101        let bare = q_hash.split(':').nth(1).unwrap_or("").to_string();
102        let replayed = self.records.contains_key(&bare);
103        if !replayed {
104            self.records.insert(bare, rec);
105        }
106        Ok((q_hash, replayed))
107    }
108
109    pub fn apply_transition(
110        &mut self,
111        transition_id: &str,
112        payload: &TransitionPayload,
113        record_frames: &[RecordFrame],
114    ) -> TransitionGateResult {
115        let current = self
116            .handle_markings
117            .get(&payload.handle)
118            .cloned()
119            .unwrap_or_else(Self::default_lifecycle_marking);
120
121        let mut verified = Vec::new();
122        for frame in record_frames {
123            match unframe_record(frame, crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3) {
124                Ok((rec, q_hash)) => {
125                    let bare = q_hash.split(':').nth(1).unwrap_or("").to_string();
126                    verified.push((bare, rec));
127                }
128                Err((err_code, reason)) => {
129                    let pre_hash = compute_marking_state_hash(&current);
130                    return TransitionGateResult {
131                        enabled: false,
132                        transition_id: transition_id.to_string(),
133                        pre_marking: current.clone(),
134                        post_marking: current,
135                        pre_state_hash: pre_hash.clone(),
136                        post_state_hash: pre_hash,
137                        error_code: Some(err_code),
138                        reason: Some(reason),
139                    };
140                }
141            }
142        }
143
144        let gate = evaluate_lifecycle_guard(&current, transition_id, Some(payload));
145        if !gate.enabled {
146            return gate;
147        }
148
149        for (bare, rec) in verified {
150            self.records.insert(bare, rec);
151        }
152        self.handle_markings
153            .insert(payload.handle.clone(), gate.post_marking.clone());
154        let prev_clock = self.handle_clocks.get(&payload.handle).cloned().unwrap_or_default();
155        let prev_head = self.handle_heads.get(&payload.handle).and_then(|h| h.as_deref());
156        let (_, winner, _, merged_clock) = resolve_concurrent_head_winner(
157            prev_head,
158            payload.to.as_deref(),
159            &prev_clock,
160            &payload.clock,
161        );
162        self.handle_heads.insert(
163            payload.handle.clone(),
164            if payload.kind == "TOMBSTONE" { None } else { winner },
165        );
166        self.handle_clocks.insert(payload.handle.clone(), merged_clock);
167        self.transitions.push(payload.clone());
168        gate
169    }
170
171    pub fn receive_attempt(
172        &mut self,
173        attempt: &TransferAttempt,
174        records: &[RecordFrame],
175    ) -> ReceiveOutcome {
176        if self.committed_transfers.contains(&attempt.transfer_id) {
177            return ReceiveOutcome { ok: true, committed: true, replayed: true, ..Default::default() };
178        }
179        let verified = match self.validate_inbound_attempt(attempt, records) {
180            Ok(v) => v,
181            Err((code, reason)) => {
182                return ReceiveOutcome {
183                    ok: false,
184                    committed: false,
185                    replayed: false,
186                    error_code: Some(code),
187                    reason: Some(reason),
188                }
189            }
190        };
191        for (bare, rec, _) in verified {
192            self.records.insert(bare, rec);
193        }
194        self.committed_transfers.insert(attempt.transfer_id.clone());
195        ReceiveOutcome { ok: true, committed: true, replayed: false, ..Default::default() }
196    }
197
198    /// Legacy inbound API preserved for backward compatibility. Prefer
199    /// `receive_attempt` for full declared-hash and transition validation.
200    pub fn receive_transfer(
201        &mut self,
202        transfer_id: &str,
203        records: &[RecordFrame],
204    ) -> Result<bool, (String, String)> {
205        let mut hashes = Vec::with_capacity(records.len());
206        for frame in records {
207            let (_, q_hash) = unframe_record(frame, crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3)?;
208            hashes.push(q_hash);
209        }
210        let attempt = TransferAttempt {
211            transfer_id: transfer_id.to_string(),
212            delivery_id: format!("legacy:{transfer_id}"),
213            source_node_id: String::new(),
214            target_node_id: self.node_id.clone(),
215            record_hashes: hashes,
216            transitions: Vec::new(),
217            attempt_count: 1,
218        };
219        let outcome = self.receive_attempt(&attempt, records);
220        if outcome.ok {
221            Ok(outcome.replayed)
222        } else {
223            Err((
224                outcome.error_code.unwrap_or_else(|| "malformed".to_string()),
225                outcome.reason.unwrap_or_else(|| "inbound rejected".to_string()),
226            ))
227        }
228    }
229
230    pub fn dispose(&mut self) {
231        self.is_disposed = true;
232    }
233}
234
235impl Drop for MCardSyncEngine {
236    fn drop(&mut self) {
237        self.dispose();
238    }
239}