Skip to main content

qualia_core_db/net/peer/replication/
pair.rs

1//! Durable pairing of network operation, graph/artifact effect, and receipt.
2//!
3//! One owner binds three things under one SHA-384 [`operation_id`]:
4//! the CORE-03 [`IntentTable`] intent, the exact effect bytes, and the
5//! [`ReceiptClass`]. Transport ACK is never a durable receipt.
6//!
7//! # Crash / finality (CORE-03 [`IntentTable`] contract)
8//!
9//! Pairing is the in-memory CORE-03 intent contract. It does **not** claim
10//! OS process-kill disk durability. [`crate::net::peer::replication::crash::disk_backend_crash_injected`]
11//! is false.
12//!
13//! - **Identity-only after crash before effect:** restart exposes a bound
14//!   operation identity. Receipt class is [`ReceiptClass::Identity`], not
15//!   durable.
16//! - **Effect without commit:** local effect may be recorded. Receipt class
17//!   stays [`ReceiptClass::Effect`]. Not durable.
18//! - **Commit without durable ACK:** recover as durable **only** if a
19//!   commit marker is present in the recovered stream. This module does not
20//!   invent a durable receipt from a live ACK. A commit marker is the
21//!   durability evidence `recover_pair` re-applies.
22//! - **Aborted or incomplete markers:** not durable.
23//!
24//! Restart that replays a commit marker plus a matching effect digest can
25//! re-apply [`DeliveryStage::DurableApplied`]. Transport ACK after any of
26//! these stages remains Identity or Effect.
27
28use crate::crypto::network::digest::sha384;
29use crate::net::peer::replication::operation::{
30    operation_id, tx_from_operation_id, OpTable, OperationDesc,
31};
32use crate::net::peer::replication::receipts::{self, ReceiptClass, ReceiptTable};
33use crate::net::qdnf::errors::QdnfError;
34use crate::net::qdnf::session::datagrams::DeliveryStage;
35use crate::net::qdnf::types::{Generation, StrongDigest};
36use crate::wal_intent::{
37    bind_exact_object, ArtifactKind, IntentRecord, IntentTable, MarkerKind, TxId, MAX_INTENTS,
38    MAX_OBJECT_BYTES,
39};
40
41/// Network operation + exact effect + receipt class under one operation id.
42#[derive(Clone, Copy, Debug, PartialEq, Eq)]
43pub struct DurablePairing {
44    pub op_id: StrongDigest,
45    pub tx: TxId,
46    pub effect_digest: StrongDigest,
47    pub receipt_class: ReceiptClass,
48}
49
50fn pairing_from(
51    op_id: StrongDigest,
52    tx: TxId,
53    effect_digest: StrongDigest,
54    receipts: &ReceiptTable,
55) -> Result<DurablePairing, QdnfError> {
56    Ok(DurablePairing {
57        op_id,
58        tx,
59        effect_digest,
60        receipt_class: receipts::class_of(receipts, op_id)?,
61    })
62}
63
64/// Stage intent + identity + local effect. Does not mark [`ReceiptClass::DurableReceipt`].
65///
66/// Empty `effect_bytes` is malformed. Duplicate `operation_id` is idempotent
67/// when the effect digest matches, [`QdnfError::Conflict`] if it differs.
68///
69/// `ops` is the operation-identity table. Pairing owns [`IntentTable`] staging
70/// of the exact effect bytes and does not call [`OpTable::submit`] (that
71/// would occupy the same [`TxId`] with a different object).
72pub fn stage_paired(
73    intents: &mut IntentTable,
74    receipts: &mut ReceiptTable,
75    ops: &mut OpTable,
76    desc: &OperationDesc,
77    effect_bytes: &[u8],
78    writer_id: u64,
79    authority_generation: Generation,
80) -> Result<DurablePairing, QdnfError> {
81    if effect_bytes.is_empty() {
82        return Err(QdnfError::Malformed);
83    }
84
85    let effect_digest = sha384(effect_bytes);
86    let op_id = operation_id(desc);
87    let tx = tx_from_operation_id(&op_id);
88    let _ = ops.get_committed(&op_id);
89
90    match receipts::effect_digest_of(receipts, op_id) {
91        Ok(existing) if existing == effect_digest => {
92            return pairing_from(op_id, tx, effect_digest, receipts);
93        }
94        Ok(_) => return Err(QdnfError::Conflict),
95        Err(QdnfError::Unauthorized) => {}
96        Err(QdnfError::Incomplete) => {}
97        Err(e) => return Err(e),
98    }
99
100    let mut copy = [0u8; MAX_OBJECT_BYTES];
101    let object = bind_exact_object(ArtifactKind::Evidence, effect_bytes, &mut copy)?;
102    match intents.stage_intent(tx, object, writer_id, authority_generation) {
103        Ok(_) => {}
104        Err(QdnfError::Conflict) => {
105            if let Ok(existing) = receipts::effect_digest_of(receipts, op_id) {
106                if existing != effect_digest {
107                    return Err(QdnfError::Conflict);
108                }
109            }
110        }
111        Err(e) => return Err(e),
112    }
113
114    receipts::bind_identity(receipts, op_id)?;
115    receipts::bind_effect_digest(receipts, op_id, effect_digest)?;
116    pairing_from(op_id, tx, effect_digest, receipts)
117}
118
119/// Commit the staged intent, then ACK [`DeliveryStage::DurableApplied`].
120///
121/// Commit failure (including stale generation) does not ACK durable. Receipt
122/// class stays below [`ReceiptClass::DurableReceipt`]. A second commit of an
123/// already-committed tx is treated as already durable at the intent layer
124/// ([`QdnfError::Conflict`]) and the durable ACK is still applied.
125pub fn commit_pair(
126    intents: &mut IntentTable,
127    receipts: &mut ReceiptTable,
128    pairing: DurablePairing,
129    generation: Generation,
130) -> Result<DurablePairing, QdnfError> {
131    match intents.commit(pairing.tx, generation) {
132        Ok(()) => {}
133        Err(QdnfError::Conflict) => {}
134        Err(e) => return Err(e),
135    }
136    let class = receipts::acknowledge(receipts, pairing.op_id, DeliveryStage::DurableApplied)?;
137    Ok(DurablePairing {
138        receipt_class: class,
139        ..pairing
140    })
141}
142
143/// Rebuild receipt class from a CORE-03 marker stream.
144///
145/// Uses [`IntentTable::recover_into`]. Committed marker + matching effect
146/// digest → re-apply durable. Aborted or incomplete → not durable.
147///
148/// Recovered markers do not carry writer id or generation (`encode_marker`
149/// does not encode them). Restaging into `intents` uses writer `0` and
150/// [`Generation::ZERO`]. `ops` cannot be rebuilt from the marker stream
151/// (no [`OperationDesc`] on the wire).
152pub fn recover_pair(
153    stream: &[u8],
154    intents: &mut IntentTable,
155    receipts: &mut ReceiptTable,
156    ops: &mut OpTable,
157    desc: &OperationDesc,
158    effect_digest: StrongDigest,
159) -> Result<DurablePairing, QdnfError> {
160    if effect_digest == StrongDigest::ZERO {
161        return Err(QdnfError::Malformed);
162    }
163
164    let op_id = operation_id(desc);
165    let tx = tx_from_operation_id(&op_id);
166    let _ = ops.get_committed(&op_id);
167
168    let mut recovered = [IntentRecord::EMPTY; MAX_INTENTS];
169    let n = IntentTable::recover_into(stream, &mut recovered)?;
170
171    let mut terminal: Option<MarkerKind> = None;
172    let mut matched_digest = StrongDigest::ZERO;
173    let mut i = 0usize;
174    while i < n {
175        let rec = recovered[i];
176        if rec.tx.bytes == tx.bytes {
177            terminal = Some(rec.kind);
178            matched_digest = rec.object.digest;
179        }
180        i += 1;
181    }
182
183    let kind = terminal.ok_or(QdnfError::Incomplete)?;
184    let digest_matches = matched_digest == effect_digest;
185
186    if digest_matches || kind == MarkerKind::Abort {
187        restage_recovered(intents, tx, effect_digest, kind)?;
188    }
189
190    receipts::bind_identity(receipts, op_id)?;
191    match kind {
192        MarkerKind::Commit if digest_matches => {
193            receipts::bind_effect_digest(receipts, op_id, effect_digest)?;
194            let class = receipts::acknowledge(receipts, op_id, DeliveryStage::DurableApplied)?;
195            Ok(DurablePairing {
196                op_id,
197                tx,
198                effect_digest,
199                receipt_class: class,
200            })
201        }
202        MarkerKind::Intent if digest_matches => {
203            receipts::bind_effect_digest(receipts, op_id, effect_digest)?;
204            pairing_from(op_id, tx, effect_digest, receipts)
205        }
206        MarkerKind::Abort => pairing_from(op_id, tx, effect_digest, receipts),
207        MarkerKind::Commit | MarkerKind::Intent => pairing_from(op_id, tx, effect_digest, receipts),
208    }
209}
210
211fn restage_recovered(
212    intents: &mut IntentTable,
213    tx: TxId,
214    effect_digest: StrongDigest,
215    kind: MarkerKind,
216) -> Result<(), QdnfError> {
217    let object = crate::wal_intent::ExactObjectRef {
218        kind: ArtifactKind::Evidence,
219        digest: effect_digest,
220        byte_len: 0,
221    };
222    match intents.stage_intent(tx, object, 0, Generation::ZERO) {
223        Ok(_) => {}
224        Err(QdnfError::Conflict) => return Ok(()),
225        Err(e) => return Err(e),
226    }
227    match kind {
228        MarkerKind::Commit => match intents.commit(tx, Generation::ZERO) {
229            Ok(()) => Ok(()),
230            Err(QdnfError::Conflict) => Ok(()),
231            Err(e) => Err(e),
232        },
233        MarkerKind::Abort => match intents.abort(tx, Generation::ZERO) {
234            Ok(()) => Ok(()),
235            Err(QdnfError::Conflict) => Ok(()),
236            Err(e) => Err(e),
237        },
238        MarkerKind::Intent => Ok(()),
239    }
240}
241
242#[cfg(test)]
243mod tests {
244    use super::*;
245    use crate::net::peer::replication::crash::disk_backend_crash_injected;
246    use crate::net::peer::replication::operation::MAX_PARENTS;
247    use crate::wal_intent::MARKER_LEN;
248
249    fn sample(seq: u32) -> OperationDesc {
250        OperationDesc {
251            author: StrongDigest([0x11; 48]),
252            epoch: 1,
253            sequence: seq,
254            scope: 7,
255            contract: StrongDigest([0x22; 48]),
256            purpose: StrongDigest([0x33; 48]),
257            payload_digest: StrongDigest([0x44; 48]),
258            parents: [StrongDigest::ZERO; MAX_PARENTS],
259            parent_count: 0,
260        }
261    }
262
263    fn encode(kind: MarkerKind, tx: TxId, digest: &StrongDigest) -> [u8; MARKER_LEN] {
264        let mut buf = [0u8; MARKER_LEN];
265        IntentTable::encode_marker(kind, tx, digest, &mut buf).unwrap();
266        buf
267    }
268
269    #[test]
270    fn empty_bytes_are_malformed() {
271        let mut intents = IntentTable::new();
272        let mut receipts = ReceiptTable::new();
273        let mut ops = OpTable::new();
274        assert_eq!(
275            stage_paired(
276                &mut intents,
277                &mut receipts,
278                &mut ops,
279                &sample(1),
280                &[],
281                9,
282                Generation(1),
283            ),
284            Err(QdnfError::Malformed)
285        );
286    }
287
288    #[test]
289    fn same_op_id_different_effect_is_conflict() {
290        let mut intents = IntentTable::new();
291        let mut receipts = ReceiptTable::new();
292        let mut ops = OpTable::new();
293        let desc = sample(2);
294        let gen = Generation(1);
295        stage_paired(
296            &mut intents,
297            &mut receipts,
298            &mut ops,
299            &desc,
300            b"alpha",
301            4,
302            gen,
303        )
304        .unwrap();
305        assert_eq!(
306            stage_paired(
307                &mut intents,
308                &mut receipts,
309                &mut ops,
310                &desc,
311                b"beta!",
312                4,
313                gen,
314            ),
315            Err(QdnfError::Conflict)
316        );
317    }
318
319    #[test]
320    fn same_op_id_same_effect_is_idempotent() {
321        let mut intents = IntentTable::new();
322        let mut receipts = ReceiptTable::new();
323        let mut ops = OpTable::new();
324        let desc = sample(3);
325        let gen = Generation(1);
326        let first = stage_paired(
327            &mut intents,
328            &mut receipts,
329            &mut ops,
330            &desc,
331            b"same-bytes",
332            5,
333            gen,
334        )
335        .unwrap();
336        let second = stage_paired(
337            &mut intents,
338            &mut receipts,
339            &mut ops,
340            &desc,
341            b"same-bytes",
342            5,
343            gen,
344        )
345        .unwrap();
346        assert_eq!(first.op_id, second.op_id);
347        assert_eq!(first.effect_digest, second.effect_digest);
348        assert_eq!(first.receipt_class, ReceiptClass::Effect);
349        assert_eq!(second.receipt_class, ReceiptClass::Effect);
350    }
351
352    #[test]
353    fn transport_ack_after_stage_is_never_durable() {
354        let mut intents = IntentTable::new();
355        let mut receipts = ReceiptTable::new();
356        let mut ops = OpTable::new();
357        let desc = sample(4);
358        let pairing = stage_paired(
359            &mut intents,
360            &mut receipts,
361            &mut ops,
362            &desc,
363            b"effect",
364            6,
365            Generation(1),
366        )
367        .unwrap();
368        let class =
369            receipts::acknowledge(&mut receipts, pairing.op_id, DeliveryStage::TransportAck)
370                .unwrap();
371        assert_ne!(class, ReceiptClass::DurableReceipt);
372        assert!(class == ReceiptClass::Identity || class == ReceiptClass::Effect);
373        assert_eq!(class, ReceiptClass::Effect);
374    }
375
376    #[test]
377    fn stale_generation_cannot_commit() {
378        let mut intents = IntentTable::new();
379        let mut receipts = ReceiptTable::new();
380        let mut ops = OpTable::new();
381        let desc = sample(5);
382        let old = Generation(1);
383        let pairing = stage_paired(
384            &mut intents,
385            &mut receipts,
386            &mut ops,
387            &desc,
388            b"stale",
389            9,
390            old,
391        )
392        .unwrap();
393        intents.withdraw_authority(9, Generation(2)).unwrap();
394        assert_eq!(
395            commit_pair(&mut intents, &mut receipts, pairing, old),
396            Err(QdnfError::StaleGeneration)
397        );
398        assert_eq!(
399            receipts::class_of(&receipts, pairing.op_id).unwrap(),
400            ReceiptClass::Effect
401        );
402        assert_ne!(
403            receipts::class_of(&receipts, pairing.op_id).unwrap(),
404            ReceiptClass::DurableReceipt
405        );
406    }
407
408    #[test]
409    fn recover_commit_marker_is_durable_abort_is_not() {
410        assert!(!disk_backend_crash_injected());
411        let desc = sample(6);
412        let effect = b"recover-me";
413        let effect_digest = sha384(effect);
414        let op_id = operation_id(&desc);
415        let tx = tx_from_operation_id(&op_id);
416
417        let commit_log = encode(MarkerKind::Commit, tx, &effect_digest);
418        let mut intents = IntentTable::new();
419        let mut receipts = ReceiptTable::new();
420        let mut ops = OpTable::new();
421        let durable = recover_pair(
422            &commit_log,
423            &mut intents,
424            &mut receipts,
425            &mut ops,
426            &desc,
427            effect_digest,
428        )
429        .unwrap();
430        assert_eq!(durable.receipt_class, ReceiptClass::DurableReceipt);
431        assert_eq!(
432            intents.commit(tx, Generation::ZERO),
433            Err(QdnfError::Conflict)
434        );
435
436        let abort_log = encode(MarkerKind::Abort, tx, &effect_digest);
437        let mut intents_a = IntentTable::new();
438        let mut receipts_a = ReceiptTable::new();
439        let mut ops_a = OpTable::new();
440        let aborted = recover_pair(
441            &abort_log,
442            &mut intents_a,
443            &mut receipts_a,
444            &mut ops_a,
445            &desc,
446            effect_digest,
447        )
448        .unwrap();
449        assert_ne!(aborted.receipt_class, ReceiptClass::DurableReceipt);
450    }
451}