Skip to main content

datum_persistence/
testkit.rs

1//! Public conformance suite for persistence storage backends.
2//!
3//! Out-of-tree backends should run every suite relevant to the capabilities
4//! they implement against isolated backend instances. Backend errors are
5//! returned; invariant violations panic with an assertion message so ordinary
6//! Rust test runners report the failed obligation directly. The query suites
7//! are the normative executable contract for invariant 12: current/live
8//! boundaries, inclusive ordering, gapless resume, and durable coalescing.
9
10use std::{
11    collections::HashSet,
12    sync::atomic::{AtomicU8, AtomicU64, Ordering},
13    time::Duration,
14};
15
16use futures_util::StreamExt;
17use tokio::time::timeout;
18
19use crate::{
20    AppendOutcome, AtomicWrite, DurableStateStore, EventStream, Journal, PersistenceError,
21    PersistenceId, PersistenceResult, ReplayRange, Revision, SelectedSnapshot, SequenceNr,
22    SerializedPayload, SerializerId, SnapshotCriteria, SnapshotMetadata, SnapshotStore,
23    StoredEvent, Tag,
24    query::{
25        DurableStateChange, DurableStateChangesQuery, EventEnvelope, EventsByPersistenceIdQuery,
26        EventsByTagQuery, Offset, PersistenceIdsQuery, QueryMode, QueryStream,
27    },
28};
29
30static TEST_NAMESPACE: AtomicU64 = AtomicU64::new(1);
31const QUERY_WAIT: Duration = Duration::from_secs(2);
32const FAILING_JOURNAL_PASS: u8 = 0;
33const FAILING_JOURNAL_FAIL_NEXT: u8 = 1;
34const FAILING_JOURNAL_REJECT_NEXT: u8 = 2;
35
36/// In-memory journal test double with one-shot append failure controls.
37#[derive(Debug, Default)]
38pub struct FailingJournal {
39    inner: crate::MemoryJournal,
40    next_append: AtomicU8,
41}
42
43impl FailingJournal {
44    /// Creates an empty pass-through journal.
45    #[must_use]
46    pub fn new() -> Self {
47        Self::default()
48    }
49
50    /// Makes the next append return a storage failure, then resumes pass-through behavior.
51    pub fn fail_next_append(&self) {
52        self.next_append
53            .store(FAILING_JOURNAL_FAIL_NEXT, Ordering::Release);
54    }
55
56    /// Makes the next append deterministically reject every atomic write.
57    pub fn reject_next_append(&self) {
58        self.next_append
59            .store(FAILING_JOURNAL_REJECT_NEXT, Ordering::Release);
60    }
61}
62
63#[async_trait::async_trait]
64impl Journal for FailingJournal {
65    async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>> {
66        match self
67            .next_append
68            .swap(FAILING_JOURNAL_PASS, Ordering::AcqRel)
69        {
70            FAILING_JOURNAL_FAIL_NEXT => Err(PersistenceError::Failure(
71                "injected journal append failure".into(),
72            )),
73            FAILING_JOURNAL_REJECT_NEXT => Ok(writes
74                .into_iter()
75                .map(|_| AppendOutcome::Rejected {
76                    reason: "injected journal append rejection".into(),
77                })
78                .collect()),
79            _ => self.inner.append(writes).await,
80        }
81    }
82
83    async fn highest_sequence_nr(
84        &self,
85        persistence_id: &PersistenceId,
86        from_hint: SequenceNr,
87    ) -> PersistenceResult<SequenceNr> {
88        self.inner
89            .highest_sequence_nr(persistence_id, from_hint)
90            .await
91    }
92
93    async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream> {
94        self.inner.replay(range).await
95    }
96
97    async fn delete_to(
98        &self,
99        persistence_id: &PersistenceId,
100        inclusive: SequenceNr,
101    ) -> PersistenceResult<()> {
102        self.inner.delete_to(persistence_id, inclusive).await
103    }
104}
105
106/// Asserts the complete WP-PS2 journal storage contract.
107pub async fn assert_journal_conformance(journal: &dyn Journal) -> PersistenceResult<()> {
108    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
109    let unknown_id = test_id("journal-unknown", namespace);
110    assert_eq!(
111        journal
112            .highest_sequence_nr(&unknown_id, SequenceNr::new(99))
113            .await?,
114        SequenceNr::new(0),
115        "an unknown persistence id must have watermark zero regardless of the hint"
116    );
117
118    assert!(matches!(
119        AtomicWrite::new(Vec::new()),
120        Err(PersistenceError::InvalidAtomicWrite(_))
121    ));
122    let mismatched_id = test_id("journal-mismatched", namespace);
123    assert!(matches!(
124        AtomicWrite::new(vec![event(&unknown_id, 1, 1), event(&mismatched_id, 2, 2),]),
125        Err(PersistenceError::InvalidAtomicWrite(_))
126    ));
127    assert!(matches!(
128        AtomicWrite::new(vec![event(&unknown_id, 1, 1), event(&unknown_id, 3, 3),]),
129        Err(PersistenceError::InvalidAtomicWrite(_))
130    ));
131
132    let ordered_id = test_id("journal-ordered", namespace);
133    let outcomes = journal
134        .append(vec![
135            atomic(vec![
136                event(&ordered_id, 1, 1),
137                event(&ordered_id, 2, 2),
138                event(&ordered_id, 3, 3),
139            ]),
140            atomic(vec![event(&ordered_id, 4, 4)]),
141            atomic(vec![event(&ordered_id, 5, 5)]),
142        ])
143        .await?;
144    assert_eq!(
145        outcomes.len(),
146        3,
147        "append must return one outcome per input"
148    );
149    assert!(
150        outcomes
151            .iter()
152            .all(|outcome| *outcome == AppendOutcome::Accepted),
153        "valid sequential writes must be accepted"
154    );
155
156    let all = replay(journal, replay_range(&ordered_id, 1, 5, u64::MAX)).await?;
157    assert_sequence_nrs(&all, &[1, 2, 3, 4, 5]);
158    assert_eq!(
159        all[1].metadata,
160        Some(payload(102)),
161        "journal replay must preserve optional metadata frames"
162    );
163    assert_eq!(all[1].tags, vec![Tag::new("even")]);
164
165    let bounded = replay(journal, replay_range(&ordered_id, 2, 4, u64::MAX)).await?;
166    assert_sequence_nrs(&bounded, &[2, 3, 4]);
167    let limited = replay(journal, replay_range(&ordered_id, 2, 5, 2)).await?;
168    assert_sequence_nrs(&limited, &[2, 3]);
169    assert!(
170        replay(journal, replay_range(&ordered_id, 5, 4, u64::MAX))
171            .await?
172            .is_empty(),
173        "reversed replay bounds must be empty"
174    );
175    assert!(
176        replay(journal, replay_range(&ordered_id, 1, 5, 0))
177            .await?
178            .is_empty(),
179        "replay max zero must be empty"
180    );
181
182    journal.delete_to(&ordered_id, SequenceNr::new(3)).await?;
183    assert_sequence_nrs(
184        &replay(journal, replay_range(&ordered_id, 1, 5, u64::MAX)).await?,
185        &[4, 5],
186    );
187    assert_eq!(
188        journal
189            .highest_sequence_nr(&ordered_id, SequenceNr::new(0))
190            .await?,
191        SequenceNr::new(5),
192        "the high watermark must survive a prefix delete"
193    );
194    journal
195        .delete_to(&ordered_id, SequenceNr::new(u64::MAX))
196        .await?;
197    assert!(
198        replay(journal, replay_range(&ordered_id, 1, u64::MAX, u64::MAX))
199            .await?
200            .is_empty(),
201        "delete-to-MAX must hide the entire stored range"
202    );
203    assert_eq!(
204        journal
205            .highest_sequence_nr(&ordered_id, SequenceNr::new(u64::MAX))
206            .await?,
207        SequenceNr::new(5),
208        "the high watermark must survive delete-to-MAX"
209    );
210    assert_eq!(
211        journal
212            .append(vec![atomic(vec![event(&ordered_id, 6, 6)])])
213            .await?,
214        vec![AppendOutcome::Accepted],
215        "a delete-to-MAX must not hide later events above the preserved watermark"
216    );
217    assert_sequence_nrs(
218        &replay(journal, replay_range(&ordered_id, 1, u64::MAX, u64::MAX)).await?,
219        &[6],
220    );
221
222    let rejected_id = test_id("journal-rejected", namespace);
223    assert_eq!(
224        journal
225            .append(vec![atomic(vec![event(&rejected_id, 1, 10)])])
226            .await?,
227        vec![AppendOutcome::Accepted]
228    );
229    let sibling_id = test_id("journal-sibling", namespace);
230    let outcomes = journal
231        .append(vec![
232            atomic(vec![event(&rejected_id, 3, 30), event(&rejected_id, 4, 40)]),
233            atomic(vec![event(&sibling_id, 1, 50), event(&sibling_id, 2, 60)]),
234        ])
235        .await?;
236    assert_eq!(
237        outcomes.len(),
238        2,
239        "append must return one outcome per input"
240    );
241    assert!(matches!(
242        &outcomes[0],
243        AppendOutcome::Rejected { reason } if !reason.is_empty()
244    ));
245    assert_eq!(outcomes[1], AppendOutcome::Accepted);
246    assert_sequence_nrs(
247        &replay(journal, replay_range(&rejected_id, 1, u64::MAX, u64::MAX)).await?,
248        &[1],
249    );
250    assert_sequence_nrs(
251        &replay(journal, replay_range(&sibling_id, 1, u64::MAX, u64::MAX)).await?,
252        &[1, 2],
253    );
254
255    Ok(())
256}
257
258/// Asserts the complete WP-PS2 snapshot-store contract.
259pub async fn assert_snapshot_store_conformance(
260    snapshots: &dyn SnapshotStore,
261) -> PersistenceResult<()> {
262    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
263    let persistence_id = test_id("snapshot", namespace);
264    assert!(
265        snapshots
266            .load(&persistence_id, &SnapshotCriteria::latest())
267            .await?
268            .is_none(),
269        "snapshot absence must be returned as None, not a load failure"
270    );
271    assert!(
272        snapshots
273            .load(&persistence_id, &SnapshotCriteria::none())
274            .await?
275            .is_none(),
276        "SnapshotCriteria::none must never select a snapshot"
277    );
278
279    for (sequence_nr, timestamp_ms, marker) in [(1, 100, 1), (3, 300, 3), (2, 200, 2)] {
280        snapshots
281            .save(
282                snapshot_metadata(&persistence_id, sequence_nr, timestamp_ms),
283                format!("datum-tck-state-adapter-v{marker}"),
284                payload(marker),
285            )
286            .await?;
287    }
288    let latest = require_snapshot(
289        snapshots
290            .load(&persistence_id, &SnapshotCriteria::latest())
291            .await?,
292    );
293    assert_eq!(latest.metadata.sequence_nr, SequenceNr::new(3));
294    assert_eq!(latest.adapter_manifest, "datum-tck-state-adapter-v3");
295    assert_eq!(latest.state, payload(3));
296
297    let exact_two = SnapshotCriteria {
298        min_sequence_nr: SequenceNr::new(2),
299        max_sequence_nr: SequenceNr::new(2),
300        min_timestamp_ms: 200,
301        max_timestamp_ms: 200,
302    };
303    assert_eq!(
304        require_snapshot(snapshots.load(&persistence_id, &exact_two).await?).state,
305        payload(2),
306        "all snapshot criteria bounds must be inclusive"
307    );
308
309    let replacement = snapshot_metadata(&persistence_id, 3, 350);
310    snapshots
311        .save(
312            replacement.clone(),
313            "datum-tck-state-adapter-v33".into(),
314            payload(33),
315        )
316        .await?;
317    let latest = require_snapshot(
318        snapshots
319            .load(&persistence_id, &SnapshotCriteria::latest())
320            .await?,
321    );
322    assert_eq!(latest.metadata, replacement);
323    assert_eq!(latest.adapter_manifest, "datum-tck-state-adapter-v33");
324    assert_eq!(latest.state, payload(33));
325    snapshots
326        .delete(snapshot_metadata(&persistence_id, 3, 300))
327        .await?;
328    assert_eq!(
329        require_snapshot(
330            snapshots
331                .load(&persistence_id, &SnapshotCriteria::latest())
332                .await?,
333        )
334        .state,
335        payload(33),
336        "deleting replaced metadata must not remove the current same-sequence snapshot"
337    );
338
339    snapshots
340        .delete(snapshot_metadata(&persistence_id, 2, 200))
341        .await?;
342    assert!(snapshots.load(&persistence_id, &exact_two).await?.is_none());
343
344    for (sequence_nr, timestamp_ms) in [(4, 400), (5, 500), (6, 600)] {
345        snapshots
346            .save(
347                snapshot_metadata(&persistence_id, sequence_nr, timestamp_ms),
348                format!("datum-tck-state-adapter-v{sequence_nr}"),
349                payload(sequence_nr),
350            )
351            .await?;
352    }
353    let delete_range = SnapshotCriteria {
354        min_sequence_nr: SequenceNr::new(4),
355        max_sequence_nr: SequenceNr::new(5),
356        min_timestamp_ms: 400,
357        max_timestamp_ms: 500,
358    };
359    snapshots
360        .delete_matching(&persistence_id, &delete_range)
361        .await?;
362    assert!(
363        snapshots
364            .load(&persistence_id, &delete_range)
365            .await?
366            .is_none(),
367        "delete_matching must remove every snapshot inside the inclusive criteria"
368    );
369    assert_eq!(
370        require_snapshot(
371            snapshots
372                .load(&persistence_id, &SnapshotCriteria::latest())
373                .await?,
374        )
375        .metadata
376        .sequence_nr,
377        SequenceNr::new(6),
378        "delete_matching must preserve snapshots outside its criteria"
379    );
380
381    Ok(())
382}
383
384/// Asserts the complete WP-PS2 durable-state storage contract.
385pub async fn assert_durable_state_store_conformance(
386    durable_state: &dyn DurableStateStore,
387) -> PersistenceResult<()> {
388    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
389    let persistence_id = test_id("durable", namespace);
390    let absent = durable_state.get(&persistence_id).await?;
391    assert_eq!(absent.revision, Revision::new(0));
392    assert!(
393        absent.state.is_none(),
394        "unknown durable state must be absent"
395    );
396
397    let invalid_first_revision = durable_state
398        .upsert(&persistence_id, Revision::new(2), payload(2), None)
399        .await
400        .expect_err("the first durable-state write must use revision one");
401    assert!(matches!(
402        invalid_first_revision,
403        PersistenceError::RevisionConflict {
404            expected,
405            actual,
406            ..
407        } if expected == Revision::new(1) && actual == Revision::new(2)
408    ));
409    assert_eq!(durable_state.get(&persistence_id).await?, absent);
410
411    durable_state
412        .upsert(
413            &persistence_id,
414            Revision::new(1),
415            payload(1),
416            Some(Tag::new("blue")),
417        )
418        .await?;
419    let first = durable_state.get(&persistence_id).await?;
420    assert_eq!(first.revision, Revision::new(1));
421    assert_eq!(first.state, Some(payload(1)));
422    assert_eq!(first.tag, Some(Tag::new("blue")));
423
424    let conflict = durable_state
425        .upsert(&persistence_id, Revision::new(3), payload(3), None)
426        .await
427        .expect_err("a skipped durable-state revision must conflict");
428    assert!(matches!(
429        conflict,
430        PersistenceError::RevisionConflict {
431            persistence_id: ref conflict_id,
432            expected,
433            actual,
434        } if conflict_id == &persistence_id
435            && expected == Revision::new(2)
436            && actual == Revision::new(3)
437    ));
438    assert_eq!(
439        durable_state.get(&persistence_id).await?,
440        first,
441        "a CAS conflict must not change stored durable state"
442    );
443
444    durable_state
445        .upsert(&persistence_id, Revision::new(2), payload(2), None)
446        .await?;
447    assert_eq!(durable_state.get(&persistence_id).await?.tag, None);
448    durable_state
449        .delete(&persistence_id, Revision::new(3))
450        .await?;
451    let tombstone = durable_state.get(&persistence_id).await?;
452    assert_eq!(tombstone.revision, Revision::new(3));
453    assert!(
454        tombstone.state.is_none(),
455        "delete must leave an absent-state tombstone at the advanced revision"
456    );
457    assert_eq!(
458        tombstone.tag, None,
459        "delete must clear the durable-state tag"
460    );
461
462    let stale_delete = durable_state
463        .delete(&persistence_id, Revision::new(3))
464        .await
465        .expect_err("reusing the tombstone revision must conflict");
466    assert!(matches!(
467        stale_delete,
468        PersistenceError::RevisionConflict {
469            expected,
470            actual,
471            ..
472        } if expected == Revision::new(4) && actual == Revision::new(3)
473    ));
474    assert_eq!(durable_state.get(&persistence_id).await?, tombstone);
475
476    Ok(())
477}
478
479/// Normative conformance contract for `events_by_persistence_id` backends.
480///
481/// Out-of-tree and future first-party query implementations must run this
482/// suite against an isolated journal/query pair. It verifies inclusive bounds,
483/// sequence ordering, the `Current` snapshot boundary, and later delivery plus
484/// finite-range completion for `Live`.
485pub async fn assert_events_by_persistence_id_query_conformance(
486    journal: &dyn Journal,
487    query: &dyn EventsByPersistenceIdQuery,
488) -> PersistenceResult<()> {
489    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
490    let persistence_id = test_id("query-pid-bounds", namespace);
491    append_accepted(
492        journal,
493        vec![
494            event(&persistence_id, 1, 1),
495            event(&persistence_id, 2, 2),
496            event(&persistence_id, 3, 3),
497            event(&persistence_id, 4, 4),
498            event(&persistence_id, 5, 5),
499        ],
500    )
501    .await?;
502
503    let bounded = collect_query(
504        query
505            .events_by_persistence_id(
506                &persistence_id,
507                SequenceNr::new(2),
508                SequenceNr::new(4),
509                QueryMode::Current,
510            )
511            .await?,
512        "current per-id inclusive range",
513    )
514    .await?;
515    assert_envelope_sequence_nrs(&bounded, &[2, 3, 4]);
516
517    let current_at_boundary = query
518        .events_by_persistence_id(
519            &persistence_id,
520            SequenceNr::new(1),
521            SequenceNr::new(6),
522            QueryMode::Current,
523        )
524        .await?;
525    append_accepted(journal, vec![event(&persistence_id, 6, 6)]).await?;
526    let boundary_events = collect_query(current_at_boundary, "current per-id boundary").await?;
527    assert_envelope_sequence_nrs(&boundary_events, &[1, 2, 3, 4, 5]);
528
529    let live_id = test_id("query-pid-live", namespace);
530    append_accepted(journal, vec![event(&live_id, 1, 11)]).await?;
531    let mut live = query
532        .events_by_persistence_id(
533            &live_id,
534            SequenceNr::new(1),
535            SequenceNr::new(3),
536            QueryMode::Live,
537        )
538        .await?;
539    let first = require_query_item(&mut live, "initial live per-id event").await?;
540    assert_eq!(first.sequence_nr, SequenceNr::new(1));
541
542    append_accepted(
543        journal,
544        vec![event(&live_id, 2, 12), event(&live_id, 3, 13)],
545    )
546    .await?;
547    let second = require_query_item(&mut live, "second live per-id event").await?;
548    let third = require_query_item(&mut live, "third live per-id event").await?;
549    assert_eq!(second.sequence_nr, SequenceNr::new(2));
550    assert_eq!(third.sequence_nr, SequenceNr::new(3));
551    assert!(
552        next_query_item(&mut live, "finite live per-id completion")
553            .await?
554            .is_none(),
555        "a live per-id query must complete after its finite inclusive upper bound"
556    );
557
558    Ok(())
559}
560
561/// Normative conformance contract for `events_by_tag` backends.
562///
563/// The suite verifies backend-global tag ordering and gapless offset resume
564/// after a simulated disconnect. Duplicate re-emission at resume is accepted;
565/// omission of any not-yet-observed event is not.
566pub async fn assert_events_by_tag_query_conformance(
567    journal: &dyn Journal,
568    query: &dyn EventsByTagQuery,
569) -> PersistenceResult<()> {
570    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
571    let tag = Tag::new(format!("query-order-{namespace}"));
572    let first_id = test_id("query-tag-first", namespace);
573    let second_id = test_id("query-tag-second", namespace);
574    append_accepted(journal, vec![tagged_event(&first_id, 1, 101, &tag)]).await?;
575    append_accepted(journal, vec![tagged_event(&second_id, 1, 102, &tag)]).await?;
576    append_accepted(journal, vec![tagged_event(&first_id, 2, 103, &tag)]).await?;
577
578    let ordered = collect_query(
579        query
580            .events_by_tag(&tag, Offset::NoOffset, QueryMode::Current)
581            .await?,
582        "current tag ordering",
583    )
584    .await?;
585    assert_eq!(
586        ordered
587            .iter()
588            .map(|envelope| (&envelope.persistence_id, envelope.sequence_nr.as_u64()))
589            .collect::<Vec<_>>(),
590        vec![(&first_id, 1), (&second_id, 1), (&first_id, 2)],
591        "tag queries must preserve the backend's global append order"
592    );
593    assert_strict_sequence_offsets(&ordered);
594
595    let resume_tag = Tag::new(format!("query-resume-{namespace}"));
596    let resume_id = test_id("query-tag-resume", namespace);
597    append_accepted(
598        journal,
599        vec![
600            tagged_event(&resume_id, 1, 201, &resume_tag),
601            tagged_event(&resume_id, 2, 202, &resume_tag),
602            tagged_event(&resume_id, 3, 203, &resume_tag),
603        ],
604    )
605    .await?;
606
607    let mut disconnected = query
608        .events_by_tag(&resume_tag, Offset::NoOffset, QueryMode::Live)
609        .await?;
610    let first = require_query_item(&mut disconnected, "first pre-disconnect tag event").await?;
611    let second = require_query_item(&mut disconnected, "second pre-disconnect tag event").await?;
612    let resume_offset = second.offset;
613    drop(disconnected);
614
615    append_accepted(journal, vec![tagged_event(&resume_id, 4, 204, &resume_tag)]).await?;
616    let resumed = collect_query(
617        query
618            .events_by_tag(&resume_tag, resume_offset, QueryMode::Current)
619            .await?,
620        "resumed current tag query",
621    )
622    .await?;
623
624    let observed = std::iter::once(first)
625        .chain(std::iter::once(second))
626        .chain(resumed)
627        .filter(|envelope| envelope.persistence_id == resume_id)
628        .map(|envelope| envelope.sequence_nr.as_u64())
629        .collect::<HashSet<_>>();
630    assert_eq!(
631        observed,
632        HashSet::from([1, 2, 3, 4]),
633        "resuming from the last observed offset must not lose unseen tag events"
634    );
635
636    Ok(())
637}
638
639/// Normative conformance contract for persistence-id discovery backends.
640///
641/// The suite verifies that `Current` completes at its captured boundary and
642/// that `Live` discovers an id first written after the query begins.
643pub async fn assert_persistence_ids_query_conformance(
644    journal: &dyn Journal,
645    query: &dyn PersistenceIdsQuery,
646) -> PersistenceResult<()> {
647    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
648    let first_id = test_id("query-ids-first", namespace);
649    let second_id = test_id("query-ids-second", namespace);
650    let third_id = test_id("query-ids-third", namespace);
651    append_accepted(journal, vec![event(&first_id, 1, 301)]).await?;
652
653    let current_at_boundary = query.persistence_ids(QueryMode::Current).await?;
654    append_accepted(journal, vec![event(&second_id, 1, 302)]).await?;
655    let current = collect_query(current_at_boundary, "current persistence ids boundary").await?;
656    assert!(current.contains(&first_id));
657    assert!(
658        !current.contains(&second_id),
659        "Current persistence_ids must exclude ids first written after its boundary"
660    );
661
662    let mut live = query.persistence_ids(QueryMode::Live).await?;
663    let initial_count = 2;
664    let mut initial = Vec::with_capacity(initial_count);
665    for _ in 0..initial_count {
666        initial.push(require_query_item(&mut live, "initial live persistence id").await?);
667    }
668    assert!(initial.contains(&first_id));
669    assert!(initial.contains(&second_id));
670
671    append_accepted(journal, vec![event(&third_id, 1, 303)]).await?;
672    assert_eq!(
673        require_query_item(&mut live, "later live persistence id").await?,
674        third_id
675    );
676
677    Ok(())
678}
679
680/// Normative conformance contract for durable-state change query backends.
681///
682/// The suite verifies latest-per-id coalescing, eventual observation of the
683/// newest rapid revision, deletion tombstones, and gapless resume. Intermediate
684/// revisions and duplicate resume emissions are both permitted.
685pub async fn assert_durable_state_changes_query_conformance(
686    durable_state: &dyn DurableStateStore,
687    query: &dyn DurableStateChangesQuery,
688) -> PersistenceResult<()> {
689    let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
690    let tag = Tag::new(format!("query-durable-{namespace}"));
691    let persistence_id = test_id("query-durable", namespace);
692    for revision in 1..=3 {
693        durable_state
694            .upsert(
695                &persistence_id,
696                Revision::new(revision),
697                payload(revision),
698                Some(tag.clone()),
699            )
700            .await?;
701    }
702
703    let current = collect_query(
704        query
705            .changes(&tag, Offset::NoOffset, QueryMode::Current)
706            .await?,
707        "current durable-state changes",
708    )
709    .await?;
710    let matching = current
711        .iter()
712        .filter(|change| change.persistence_id() == &persistence_id)
713        .collect::<Vec<_>>();
714    assert_eq!(
715        matching.len(),
716        1,
717        "Current durable changes must coalesce to one latest value per id"
718    );
719    assert_eq!(matching[0].revision(), Revision::new(3));
720    assert!(matches!(matching[0], DurableStateChange::Updated(_)));
721
722    let mut live = query
723        .changes(&tag, Offset::NoOffset, QueryMode::Live)
724        .await?;
725    let initial = require_query_item(&mut live, "initial live durable change").await?;
726    assert_eq!(initial.revision(), Revision::new(3));
727
728    for revision in 4..=6 {
729        durable_state
730            .upsert(
731                &persistence_id,
732                Revision::new(revision),
733                payload(revision),
734                Some(tag.clone()),
735            )
736            .await?;
737    }
738    let latest = timeout(QUERY_WAIT, async {
739        loop {
740            match live.next().await {
741                Some(Ok(change)) if change.persistence_id() == &persistence_id => {
742                    if change.revision() == Revision::new(6) {
743                        break Ok(change);
744                    }
745                }
746                Some(Ok(_)) => {}
747                Some(Err(error)) => break Err(error),
748                None => {
749                    break Err(PersistenceError::Failure(
750                        "live durable query completed before the latest revision".into(),
751                    ));
752                }
753            }
754        }
755    })
756    .await
757    .map_err(|_| PersistenceError::Failure("latest durable revision timed out".into()))??;
758    let resume_offset = latest.offset();
759    drop(live);
760
761    durable_state
762        .delete(&persistence_id, Revision::new(7))
763        .await?;
764    let resumed = collect_query(
765        query
766            .changes(&tag, resume_offset, QueryMode::Current)
767            .await?,
768        "resumed durable-state changes",
769    )
770    .await?;
771    assert!(
772        resumed.iter().any(|change| {
773            matches!(
774                change,
775                DurableStateChange::Deleted(deleted)
776                    if deleted.persistence_id == persistence_id
777                        && deleted.revision == Revision::new(7)
778            )
779        }),
780        "resuming after the latest observed durable offset must expose the later tombstone"
781    );
782
783    Ok(())
784}
785
786fn test_id(kind: &str, namespace: u64) -> PersistenceId {
787    PersistenceId::new("datum-tck", format!("{kind}-{namespace}"))
788        .expect("conformance-suite ids are valid")
789}
790
791fn payload(marker: u64) -> SerializedPayload {
792    SerializedPayload::new(
793        SerializerId::new(7),
794        "datum-tck-v1",
795        marker.to_be_bytes().to_vec(),
796    )
797}
798
799fn event(persistence_id: &PersistenceId, sequence_nr: u64, marker: u64) -> StoredEvent {
800    let is_even = sequence_nr & 1 == 0;
801    StoredEvent {
802        persistence_id: persistence_id.clone(),
803        sequence_nr: SequenceNr::new(sequence_nr),
804        adapter_manifest: "datum-tck-adapter-v1".to_owned(),
805        writer_uuid: "datum-tck-writer".to_owned(),
806        timestamp_ms: i64::try_from(marker).expect("test marker fits i64"),
807        metadata: is_even.then(|| payload(marker + 100)),
808        payload: payload(marker),
809        tags: is_even.then(|| Tag::new("even")).into_iter().collect(),
810    }
811}
812
813fn tagged_event(
814    persistence_id: &PersistenceId,
815    sequence_nr: u64,
816    marker: u64,
817    tag: &Tag,
818) -> StoredEvent {
819    let mut event = event(persistence_id, sequence_nr, marker);
820    event.tags = vec![tag.clone()];
821    event
822}
823
824fn atomic(events: Vec<StoredEvent>) -> AtomicWrite {
825    AtomicWrite::new(events).expect("conformance-suite writes are internally valid")
826}
827
828fn replay_range(persistence_id: &PersistenceId, from: u64, to: u64, max: u64) -> ReplayRange {
829    ReplayRange {
830        persistence_id: persistence_id.clone(),
831        from: SequenceNr::new(from),
832        to: SequenceNr::new(to),
833        max,
834    }
835}
836
837async fn replay(journal: &dyn Journal, range: ReplayRange) -> PersistenceResult<Vec<StoredEvent>> {
838    let stream = journal.replay(range).await?;
839    collect_events(stream).await
840}
841
842async fn collect_events(mut stream: EventStream) -> PersistenceResult<Vec<StoredEvent>> {
843    let mut events = Vec::new();
844    while let Some(event) = stream.next().await {
845        events.push(event?);
846    }
847    Ok(events)
848}
849
850async fn append_accepted(journal: &dyn Journal, events: Vec<StoredEvent>) -> PersistenceResult<()> {
851    let outcome = journal.append_one(atomic(events)).await?;
852    assert_eq!(
853        outcome,
854        AppendOutcome::Accepted,
855        "conformance-suite setup writes must be accepted"
856    );
857    Ok(())
858}
859
860async fn collect_query<T>(stream: QueryStream<T>, context: &str) -> PersistenceResult<Vec<T>> {
861    timeout(QUERY_WAIT, async move {
862        let mut stream = stream;
863        let mut items = Vec::new();
864        while let Some(item) = stream.next().await {
865            items.push(item?);
866        }
867        Ok(items)
868    })
869    .await
870    .map_err(|_| PersistenceError::Failure(format!("{context} timed out")))?
871}
872
873async fn next_query_item<T>(
874    stream: &mut QueryStream<T>,
875    context: &str,
876) -> PersistenceResult<Option<T>> {
877    timeout(QUERY_WAIT, stream.next())
878        .await
879        .map_err(|_| PersistenceError::Failure(format!("{context} timed out")))?
880        .transpose()
881}
882
883async fn require_query_item<T>(stream: &mut QueryStream<T>, context: &str) -> PersistenceResult<T> {
884    next_query_item(stream, context).await?.ok_or_else(|| {
885        PersistenceError::Failure(format!("{context} completed without an expected item"))
886    })
887}
888
889fn assert_sequence_nrs(events: &[StoredEvent], expected: &[u64]) {
890    let actual = events
891        .iter()
892        .map(|event| event.sequence_nr.as_u64())
893        .collect::<Vec<_>>();
894    assert_eq!(actual, expected, "replay sequence numbers differ");
895}
896
897fn assert_envelope_sequence_nrs(events: &[EventEnvelope], expected: &[u64]) {
898    let actual = events
899        .iter()
900        .map(|event| event.sequence_nr.as_u64())
901        .collect::<Vec<_>>();
902    assert_eq!(actual, expected, "query sequence numbers differ");
903}
904
905fn assert_strict_sequence_offsets(events: &[EventEnvelope]) {
906    // Sequence offsets must strictly increase. Timestamp offsets order
907    // lexicographically on (epoch_micros, seq_nr) and may repeat an equal pair
908    // (duplicate re-emission is allowed; gaps are not). Mixed offset kinds or
909    // NoOffset in emitted events are conformance failures.
910    let mut sequences = Vec::new();
911    let mut timestamps = Vec::new();
912    for event in events {
913        match event.offset {
914            Offset::Sequence(offset) => sequences.push(offset),
915            Offset::Timestamp {
916                epoch_micros,
917                seq_nr,
918            } => timestamps.push((epoch_micros, seq_nr)),
919            other => panic!("an emitted event must carry a concrete offset, got {other:?}"),
920        }
921    }
922    assert!(
923        sequences.is_empty() || timestamps.is_empty(),
924        "a backend must not mix offset kinds in one stream"
925    );
926    assert!(
927        sequences.windows(2).all(|pair| pair[0] < pair[1]),
928        "tag-query sequence offsets must follow strict global append order: {sequences:?}"
929    );
930    assert!(
931        timestamps.windows(2).all(|pair| pair[0] <= pair[1]),
932        "tag-query timestamp offsets must be non-decreasing: {timestamps:?}"
933    );
934}
935
936fn snapshot_metadata(
937    persistence_id: &PersistenceId,
938    sequence_nr: u64,
939    timestamp_ms: i64,
940) -> SnapshotMetadata {
941    SnapshotMetadata {
942        persistence_id: persistence_id.clone(),
943        sequence_nr: SequenceNr::new(sequence_nr),
944        timestamp_ms,
945    }
946}
947
948fn require_snapshot(snapshot: Option<SelectedSnapshot>) -> SelectedSnapshot {
949    snapshot.expect("a matching saved snapshot must be returned")
950}
951
952#[cfg(test)]
953mod tests {
954    use super::*;
955    use crate::{MemoryDurableStateStore, MemoryJournal, MemorySnapshotStore};
956
957    #[tokio::test]
958    async fn memory_backends_pass_the_public_conformance_suite() -> PersistenceResult<()> {
959        assert_journal_conformance(&MemoryJournal::new()).await?;
960        assert_snapshot_store_conformance(&MemorySnapshotStore::new()).await?;
961        assert_durable_state_store_conformance(&MemoryDurableStateStore::new()).await?;
962        Ok(())
963    }
964
965    struct FailingSnapshotStore;
966
967    #[async_trait::async_trait]
968    impl SnapshotStore for FailingSnapshotStore {
969        async fn load(
970            &self,
971            _persistence_id: &PersistenceId,
972            _criteria: &SnapshotCriteria,
973        ) -> PersistenceResult<Option<SelectedSnapshot>> {
974            Err(PersistenceError::Failure(
975                "injected snapshot load failure".to_owned(),
976            ))
977        }
978
979        async fn save(
980            &self,
981            _metadata: SnapshotMetadata,
982            _adapter_manifest: String,
983            _state: SerializedPayload,
984        ) -> PersistenceResult<()> {
985            Ok(())
986        }
987
988        async fn delete(&self, _metadata: SnapshotMetadata) -> PersistenceResult<()> {
989            Ok(())
990        }
991
992        async fn delete_matching(
993            &self,
994            _persistence_id: &PersistenceId,
995            _criteria: &SnapshotCriteria,
996        ) -> PersistenceResult<()> {
997            Ok(())
998        }
999    }
1000
1001    #[tokio::test]
1002    async fn snapshot_conformance_does_not_treat_load_failure_as_absence() {
1003        let error = assert_snapshot_store_conformance(&FailingSnapshotStore)
1004            .await
1005            .expect_err("the injected load failure must propagate");
1006        assert!(
1007            matches!(error, PersistenceError::Failure(message) if message.contains("injected"))
1008        );
1009    }
1010}