Skip to main content

happenstance_sync_testkit/
ingest_suite.rs

1//! The ingest rules, their one enumeration, and the two emitters.
2//!
3//! Private: what a caller reaches is [`ingest_rules`], re-exported at the
4//! crate root, and the macros, which `#[macro_export]` puts there regardless.
5
6/// The `capability` SY-38's rule reports when the store did not put the
7/// rule's compensation where its arrangement needed it.
8///
9/// Not a fixture constant, which is why it is a description rather than an
10/// identifier: SY-37's [`NO_SECOND_PAGE`](crate::NO_SECOND_PAGE) is the
11/// precedent. Gaps are legal, so a store may place a compensation anywhere
12/// above the head.
13pub const NO_HIDDEN_CLAIM: &str = "the position an ingest's compensation takes";
14
15/// The reason SY-38's rule reports when it could not arrange a claim hidden
16/// by the call's own compensation.
17///
18/// Written by this crate rather than by the fixture, because it is the same
19/// sentence for every store that earns it.
20pub const NO_HIDDEN_CLAIM_REASON: &str = "this store did not put the rule's compensation on the identity the rule \
21     claimed, two positions past the head it assigned, so a claim the call's own compensation would \
22     hide was never arranged; SY-38's unheld-claim half held, and its compensation-hidden half is \
23     unverified for this store";
24
25/// The `capability` SY-18's ingest rule reports when the fixture declares no
26/// per-event ceiling it can exercise.
27///
28/// Names all three [`IngestFixture`](crate::IngestFixture) constants, because
29/// the rule needs every one of them absent, or too large to allocate, before
30/// it has nothing to do: `happenstance_testkit::NO_STORE_LIMITS` is the
31/// precedent.
32pub const NO_PER_EVENT_LIMITS: &str = "MAX_EVENT_DATA_LEN, MAX_TAGS_PER_EVENT, MAX_METADATA_LEN";
33
34/// The reason SY-18's ingest rule reports when it exercised no ceiling.
35///
36/// Written by this crate rather than by the fixture, because it is the same
37/// sentence for every store that earns it.
38pub const NO_PER_EVENT_LIMITS_REASON: &str = "this fixture declares no per-event ceiling the rule can exercise, none \
39     at all or only ones at or above the sizes this crate will allocate, so a \
40     store that checks only the head of each group could not be told from one \
41     that checks every event; the rule is unverified for this store";
42
43/// The most tags SY-18's ingest rule puts on one event, whatever ceiling the
44/// fixture declares (H-13).
45///
46/// A declared `MAX_TAGS_PER_EVENT` at or above this is not exercised: the
47/// over-ceiling event carries one tag more than the ceiling, and the rule does
48/// not allocate a number it was handed. Byte ceilings are capped by
49/// [`MAX_PROVOKED_BATCH_BYTES`](crate::MAX_PROVOKED_BATCH_BYTES) for the same
50/// reason.
51pub const MAX_PROVOKED_TAGS: usize = 4_096;
52
53/// The `capability` VT-36's ingest rule reports when the fixture declares no
54/// tags-per-batch ceiling it can exercise: the
55/// [`IngestFixture`](crate::IngestFixture) constant it reads.
56pub const NO_TAGS_PER_BATCH_LIMIT: &str = "MAX_TAGS_PER_BATCH";
57
58/// The reason VT-36's ingest rule reports when it exercised no ceiling.
59///
60/// Written by this crate rather than by the fixture, because it is the same
61/// sentence for every store that earns it.
62pub const NO_TAGS_PER_BATCH_LIMIT_REASON: &str = "this fixture declares no tags-per-batch ceiling the \
63     rule can exercise, none at all or one at or above the total this crate will allocate, so a \
64     store that counts each group, or only the foreign events, could not be told from one that \
65     counts the whole call; the rule is unverified for this store";
66
67/// The most tags VT-36's ingest rule puts in one call, whatever ceiling the
68/// fixture declares (H-13).
69///
70/// A declared `MAX_TAGS_PER_BATCH` at or above this is not exercised: the
71/// over-ceiling call carries one tag more than the ceiling, and the rule does
72/// not allocate a number it was handed. Twice the one ceiling a shipped
73/// adapter declares, `happenstance-cloudflare`'s 262,144, so that one is
74/// exercised; one call at this cap is about half a million owned tags.
75pub const MAX_PROVOKED_TAGS_PER_BATCH: usize = 524_288;
76
77/// The ingest rules. See the [crate documentation](crate) for what each covers.
78///
79/// Each rule is an async function taking `impl AsyncFn() -> F`, how to make a
80/// fixture rather than a fixture, as in the event-store family, and returning
81/// `Result<RuleOutcome, Violation>`.
82///
83/// # What no rule here does
84///
85/// **Decode a payload** (SY-35). Events are compared whole, identity, recorded
86/// time and the opaque bytes, and never parsed.
87///
88/// **Assert a local position it did not read back.** The specification permits
89/// gaps, so every local position compared is one the store assigned. The
90/// literal positions below are **origin** positions: facts a peer supplies.
91///
92/// **Locate an event by identity, except VT-5's.** The other rules find what
93/// they wrote by its distinct opaque bytes, so a store that re-mints on ingest
94/// fails VT-5's rule and only that one.
95///
96/// **Assume an identity the store did not state.** Each rule awaits the
97/// store's [`store_id`](happenstance_sync::IngestStore::store_id) before it
98/// arranges anything, and a failed read is a violation of the rule's own
99/// clause rather than a reason to carry on.
100pub mod ingest_rules {
101    use alloc::format;
102    use alloc::string::String;
103    use alloc::vec::Vec;
104
105    use alloc::vec;
106
107    use happenstance_core::{
108        Event, EventId, EventStore, EventType, Query, ReadOptions, RecordedAt, SequencePosition,
109        SequencedEvent, StoreId, StoreLimit, Tag, Tags, collect,
110    };
111    use happenstance_sync::{
112        Classify, FailureClass, IngestError, IngestGroup, IngestStore, Ingested, ReplicatedEvent,
113        Watermark,
114    };
115    use happenstance_testkit::RuleOutcome;
116
117    use super::{
118        MAX_PROVOKED_TAGS, MAX_PROVOKED_TAGS_PER_BATCH, NO_HIDDEN_CLAIM, NO_HIDDEN_CLAIM_REASON,
119        NO_PER_EVENT_LIMITS, NO_PER_EVENT_LIMITS_REASON, NO_TAGS_PER_BATCH_LIMIT,
120        NO_TAGS_PER_BATCH_LIMIT_REASON,
121    };
122
123    use crate::violation::{Violation, ensure};
124    use crate::{IngestFixture, MAX_PROVOKED_BATCH_BYTES};
125
126    // VT-36's arrangements, a file of their own because this one is long
127    // enough. A child module, so it reaches the helpers below through `super`
128    // without widening any of them.
129    mod batch_scope;
130    // SY-7's arrangement and the runner the rule plays, beside VT-36's for the
131    // same reason.
132    mod adjudication;
133    // SY-10's two topologies and the per-direction runner the rule plays.
134    mod topology;
135    // The seat family's merge rule, through the shipped hook both mount.
136    mod seat_rule;
137    // SY-14's call at VT-24's floor, and the first delivery scattered over it.
138    mod bulk;
139
140    const SHIPPED: EventType = EventType::from_static("Shipped");
141    const LOCAL: EventType = EventType::from_static("Local");
142    const COMPENSATED: EventType = EventType::from_static("Compensated");
143
144    /// VT-5's origin.
145    const IDENTITY_ORIGIN: StoreId = StoreId::from_bytes([0x71; 16]);
146    /// VT-9's origin.
147    const RECORDED_ORIGIN: StoreId = StoreId::from_bytes([0x76; 16]);
148    /// SY-5's origin.
149    const TAIL_ORIGIN: StoreId = StoreId::from_bytes([0x72; 16]);
150    /// SY-12's two origins, which record one byte-identical fact each.
151    const DEDUPE_ORIGIN: StoreId = StoreId::from_bytes([0x73; 16]);
152    const TWIN_ORIGIN: StoreId = StoreId::from_bytes([0x74; 16]);
153
154    /// Bytes that are not UTF-8 and parse as no codec: two bytes UTF-8 never
155    /// uses, a NUL and a two-byte sequence cut off by a non-continuation byte. A store that had to
156    /// decode a payload to dedupe it fails on these (SY-35).
157    const UNDECODABLE: &[u8; 5] = b"\xFF\xFE\x00\xC3\x28";
158
159    /// SY-38's origin, for the foreign events around each claim.
160    const CLAIM_ORIGIN: StoreId = StoreId::from_bytes([0x75; 16]);
161
162    /// SY-30's origin, for the group a fault is armed inside.
163    const ATOMIC_ORIGIN: StoreId = StoreId::from_bytes([0x77; 16]);
164
165    /// SY-18's origin, for the events held to the declared ceilings.
166    const CEILING_ORIGIN: StoreId = StoreId::from_bytes([0x78; 16]);
167
168    /// VT-5: an ingested event keeps the [`EventId`] its origin minted.
169    ///
170    /// One group of two foreign events, at origin positions 4 and 9. Read
171    /// back, exactly one held event carries each identity, with the bytes
172    /// that were sent; the store answers `contains_event_id` for both, and its
173    /// watermark for the origin is the higher of the two origin positions.
174    /// The recorded time is not compared here: it is VT-9's, and
175    /// [`ingest_preserves_the_recorded_time`] owns it, so a store that
176    /// restamps fails that rule and not this one.
177    ///
178    /// # Rejects
179    ///
180    /// A store that re-mints an ingested event under its own identity, keeping
181    /// the origin's only for its own bookkeeping.
182    /// `tests/wrong_ingest_stores.rs` carries it.
183    ///
184    /// # Errors
185    ///
186    /// A [`Violation`] of VT-5 if the store refuses the ingest, miscounts it,
187    /// or holds anything but the sent identity and bytes.
188    pub async fn ingest_preserves_origin_identity<F: IngestFixture>(
189        open: impl AsyncFn() -> F,
190    ) -> Result<RuleOutcome, Violation> {
191        const CLAUSE: &str = "VT-5";
192        let fixture = open().await;
193        let store = fixture.connect().await;
194        ensure_foreign(&store, &[IDENTITY_ORIGIN], CLAUSE).await?;
195        let sent = [
196            shipped(IDENTITY_ORIGIN, 4, -86_400_000, b"vt5-before-1970", CLAUSE)?,
197            shipped(IDENTITY_ORIGIN, 9, 1_700_000_000_000, b"vt5-after", CLAUSE)?,
198        ];
199
200        let ingested = ingest(&store, &[IngestGroup::new(&sent, &[])], CLAUSE).await?;
201
202        ensure(ingested.appended == 2, CLAUSE, || {
203            format!("the store reported {ingested:?} for two events it did not hold")
204        })?;
205        let log = read_all(&store, CLAUSE).await?;
206        for event in &sent {
207            let carrying: Vec<&SequencedEvent> =
208                log.iter().filter(|row| row.id == event.id).collect();
209            let [landed] = carrying.as_slice() else {
210                return Err(Violation::new(
211                    CLAUSE,
212                    format!(
213                        "{} held events carry {}, which was sent once; an ingested event \
214                         keeps the identity its origin minted",
215                        carrying.len(),
216                        event.id
217                    ),
218                ));
219            };
220            ensure(landed.event == event.event, CLAUSE, || {
221                format!("{} is held with bytes other than the ones sent", event.id)
222            })?;
223            ensure(holds(&store, event.id, CLAUSE).await?, CLAUSE, || {
224                format!(
225                    "the store holds {} and contains_event_id denies it",
226                    event.id
227                )
228            })?;
229        }
230        let watermark = watermark(&store, CLAUSE).await?;
231        let highest = sent.iter().map(|event| event.id.position()).max();
232        ensure(watermark.get(IDENTITY_ORIGIN) == highest, CLAUSE, || {
233            format!(
234                "the watermark for {IDENTITY_ORIGIN} is {:?}; the highest origin position \
235                 sent was {highest:?}",
236                watermark.get(IDENTITY_ORIGIN)
237            )
238        })?;
239        Ok(RuleOutcome::Ran)
240    }
241
242    /// VT-9: an ingested event keeps the [`RecordedAt`] its origin carried,
243    /// unchanged; a store stamps only what it accepts from a local append.
244    ///
245    /// One local event first, stamped by the store with whatever its clock
246    /// reads. Then one call of two groups from one origin: three events at
247    /// origin positions 2, 3 and 5, recorded before 1970, off a whole second,
248    /// and earlier than the event the origin numbered before it; and two at
249    /// positions 8 and 9, the second recorded in 2200, later than any store's
250    /// clock will read. Read back, each sent event is held with the recorded time
251    /// it was sent with. Events are found by their distinct bytes, never by
252    /// identity, so a store that re-mints fails VT-5's rule and not this one.
253    ///
254    /// Each held time is compared with the one its origin sent and with
255    /// nothing else: never with another held time, with a position, or with
256    /// the harness's clock, which VT-9 and CF-33 both forbid.
257    ///
258    /// # Rejects
259    ///
260    /// A store that restamps an ingested event with its arrival time, the one
261    /// VT-9's `Rejects:` names; one that keeps whole seconds; one that keeps
262    /// the time unsigned and holds a time before 1970 as the epoch; one that
263    /// holds recorded times non-decreasing with position; one that binds
264    /// one time per group, its head's; and one that clamps a time from the
265    /// future to its own clock. `tests/wrong_ingest_stores.rs` carries all
266    /// six.
267    ///
268    /// # Errors
269    ///
270    /// A [`Violation`] of VT-9 if the store refuses a write, miscounts the
271    /// ingest, holds a sent event other than once, or holds one with a
272    /// recorded time other than the one sent.
273    pub async fn ingest_preserves_the_recorded_time<F: IngestFixture>(
274        open: impl AsyncFn() -> F,
275    ) -> Result<RuleOutcome, Violation> {
276        const CLAUSE: &str = "VT-9";
277        let fixture = open().await;
278        let store = fixture.connect().await;
279        ensure_foreign(&store, &[RECORDED_ORIGIN], CLAUSE).await?;
280        append(&store, &[opaque(LOCAL, b"vt9-local", CLAUSE)?], CLAUSE).await?;
281        let first = [
282            shipped(RECORDED_ORIGIN, 2, -1_234, b"vt9-before-1970", CLAUSE)?,
283            shipped(
284                RECORDED_ORIGIN,
285                3,
286                1_700_000_000_123,
287                b"vt9-off-a-second",
288                CLAUSE,
289            )?,
290            shipped(
291                RECORDED_ORIGIN,
292                5,
293                1_600_000_000_456,
294                b"vt9-earlier",
295                CLAUSE,
296            )?,
297        ];
298        let second = [
299            shipped(
300                RECORDED_ORIGIN,
301                8,
302                1_650_000_000_789,
303                b"vt9-second-group",
304                CLAUSE,
305            )?,
306            // 2200-01-01, inside the ±2^53 a JavaScript number carries exactly.
307            shipped(
308                RECORDED_ORIGIN,
309                9,
310                7_258_118_400_123,
311                b"vt9-far-future",
312                CLAUSE,
313            )?,
314        ];
315        let groups = [
316            IngestGroup::new(&first, &[]),
317            IngestGroup::new(&second, &[]),
318        ];
319
320        let ingested = ingest(&store, &groups, CLAUSE).await?;
321
322        ensure_counts(ingested, (5, 0, 0), "five new foreign events", CLAUSE)?;
323        let log = read_all(&store, CLAUSE).await?;
324        for sent in first.iter().chain(&second) {
325            let held = held_once(&log, &sent.event, CLAUSE)?;
326            ensure(held.recorded_at == sent.recorded_at, CLAUSE, || {
327                format!(
328                    "{} was recorded at {} by its origin and is held as recorded at {}; an \
329                     ingested event keeps the time its origin recorded",
330                    sent.id, sent.recorded_at, held.recorded_at
331                )
332            })?;
333        }
334        Ok(RuleOutcome::Ran)
335    }
336
337    /// SY-5: an ingested event, and its compensation, land at the tail, above
338    /// every position assigned before the call, and the log below the old
339    /// head is unchanged.
340    ///
341    /// Three local events are appended. One group then arrives from an origin
342    /// that numbered its events 1 and 2, below the local head, which is what
343    /// tempts a merge, with one compensation event. Read back, every event at
344    /// or below the old head is what was there before, whole, and each foreign
345    /// event and the compensation is held once, above it. Events are found by
346    /// their distinct bytes, never by identity.
347    ///
348    /// # Rejects
349    ///
350    /// An order-preserving merge: a store that inserts an ingested event where
351    /// its origin numbered it and renumbers what follows, so a projection that
352    /// had read past that position never sees it.
353    /// `tests/wrong_ingest_stores.rs` carries it.
354    ///
355    /// # Errors
356    ///
357    /// A [`Violation`] of SY-5 if the store refuses a write, rewrites the log
358    /// below the old head, or holds a written event other than once above it.
359    pub async fn ingested_events_land_above_the_local_head<F: IngestFixture>(
360        open: impl AsyncFn() -> F,
361    ) -> Result<RuleOutcome, Violation> {
362        const CLAUSE: &str = "SY-5";
363        let fixture = open().await;
364        let store = fixture.connect().await;
365        ensure_foreign(&store, &[TAIL_ORIGIN], CLAUSE).await?;
366        let local = [
367            opaque(LOCAL, b"sy5-local-1", CLAUSE)?,
368            opaque(LOCAL, b"sy5-local-2", CLAUSE)?,
369            opaque(LOCAL, b"sy5-local-3", CLAUSE)?,
370        ];
371        let head_before = append(&store, &local, CLAUSE).await?;
372        let prefix = read_all(&store, CLAUSE).await?;
373        let sent = [
374            shipped(TAIL_ORIGIN, 1, 1_800_000_000_000, b"sy5-foreign-1", CLAUSE)?,
375            shipped(TAIL_ORIGIN, 2, 1_800_000_000_001, b"sy5-foreign-2", CLAUSE)?,
376        ];
377        let answer = [opaque(COMPENSATED, b"sy5-compensation", CLAUSE)?];
378
379        ingest(&store, &[IngestGroup::new(&sent, &answer)], CLAUSE).await?;
380
381        let log = read_all(&store, CLAUSE).await?;
382        let below: Vec<&SequencedEvent> = log
383            .iter()
384            .filter(|row| row.position <= head_before)
385            .collect();
386        ensure(below.iter().copied().eq(&prefix), CLAUSE, || {
387            format!(
388                "the log at or below the old head {head_before} changed across an ingest: it \
389                 held {} events there and now holds {}, or holds them differently",
390                prefix.len(),
391                below.len()
392            )
393        })?;
394        for written in sent.iter().map(|event| &event.event).chain(&answer) {
395            let landed = held_once(&log, written, CLAUSE)?;
396            ensure(landed.position > head_before, CLAUSE, || {
397                format!(
398                    "an ingested event of type {} landed at {}, at or below the head {head_before} \
399                     the store had assigned before the call",
400                    written.event_type(),
401                    landed.position
402                )
403            })?;
404        }
405        Ok(RuleOutcome::Ran)
406    }
407
408    /// SY-12: a re-delivery is decided on the event's identity alone, which
409    /// the store reaches without decoding a byte of the payload. With SY-11's
410    /// store half: a group that was wholly a re-delivery writes no
411    /// compensation.
412    ///
413    /// Every payload and metadata here is bytes that are not UTF-8 and parse
414    /// as no codec. One group carries two events from one origin and a third
415    /// from a second origin whose type, tags, data, metadata and recorded time
416    /// are byte-identical to the first's, so only the identity tells them
417    /// apart, and one compensation event. The first delivery lands all three
418    /// and the compensation; the same batch again lands nothing, writes no
419    /// compensation and leaves the log and head as they were; and a batch of
420    /// one held event and one new one lands exactly the new one.
421    ///
422    /// # Rejects
423    ///
424    /// A store that dedupes on content, which drops the second origin's
425    /// identical fact as though it were the first again; one that decodes a
426    /// payload to reach its dedupe key, and skips bytes it cannot parse; and
427    /// one that writes a group's compensation again when the group was a
428    /// re-delivery. `tests/wrong_ingest_stores.rs` carries all three. SY-3's `Rule:` line
429    /// names this rule since ADR-0108: its redelivery half is SY-3's assertion.
430    ///
431    /// # Errors
432    ///
433    /// A [`Violation`] of SY-12 if the store refuses an ingest, miscounts one,
434    /// or holds other than what the three deliveries should leave.
435    pub async fn dedupe_reaches_identity_without_decoding<F: IngestFixture>(
436        open: impl AsyncFn() -> F,
437    ) -> Result<RuleOutcome, Violation> {
438        const CLAUSE: &str = "SY-12";
439        let fixture = open().await;
440        let store = fixture.connect().await;
441        ensure_foreign(&store, &[DEDUPE_ORIGIN, TWIN_ORIGIN], CLAUSE).await?;
442        let first = undecodable(DEDUPE_ORIGIN, 1, b'1', CLAUSE)?;
443        let second = undecodable(DEDUPE_ORIGIN, 2, b'2', CLAUSE)?;
444        // The twin shares every byte with `first`, recorded time included:
445        // the duplication is the arrangement.
446        let twin = ReplicatedEvent::new(
447            EventId::new(TWIN_ORIGIN, first.id.position()),
448            first.recorded_at,
449            first.event.clone(),
450        );
451        let answer = [opaque(COMPENSATED, &undecodable_bytes(b'c'), CLAUSE)?];
452        let batch = [first, second.clone(), twin];
453        let group = [IngestGroup::new(&batch, &answer)];
454
455        let delivered = ingest(&store, &group, CLAUSE).await?;
456        ensure_counts(delivered, (3, 0, 1), "the first delivery", CLAUSE)?;
457        let log = read_all(&store, CLAUSE).await?;
458        let twins = log.iter().filter(|row| row.event == batch[0].event).count();
459        ensure(twins == 2, CLAUSE, || {
460            format!(
461                "two origins each sent one byte-identical event and the store holds {twins}; \
462                 only their identities differ, and both are new"
463            )
464        })?;
465        held_once(&log, &answer[0], CLAUSE)?;
466        let head_before = head(&store, CLAUSE).await?;
467
468        let again = ingest(&store, &group, CLAUSE).await?;
469        ensure_counts(again, (0, 3, 0), "the same batch again", CLAUSE)?;
470        ensure(read_all(&store, CLAUSE).await? == log, CLAUSE, || {
471            String::from("a re-delivery of a held batch changed the log")
472        })?;
473        let head_after = head(&store, CLAUSE).await?;
474        ensure(head_after == head_before, CLAUSE, || {
475            format!("a re-delivery moved the head from {head_before:?} to {head_after:?}")
476        })?;
477
478        let third = undecodable(DEDUPE_ORIGIN, 3, b'3', CLAUSE)?;
479        let partial = [second, third];
480        let landed = ingest(&store, &[IngestGroup::new(&partial, &[])], CLAUSE).await?;
481        ensure_counts(landed, (1, 1, 0), "one held event and one new one", CLAUSE)?;
482        let grown = read_all(&store, CLAUSE).await?;
483        held_once(&grown, &partial[1].event, CLAUSE)?;
484        // Identity, time and bytes, and not position: where the new event
485        // lands, and whether anything moved for it, is SY-5's to judge.
486        let rest: Vec<&SequencedEvent> = grown
487            .iter()
488            .filter(|row| row.event != partial[1].event)
489            .collect();
490        let kept = |before: &SequencedEvent| {
491            rest.iter().any(|after| {
492                after.id == before.id
493                    && after.recorded_at == before.recorded_at
494                    && after.event == before.event
495            })
496        };
497        ensure(
498            rest.len() == log.len() && log.iter().all(kept),
499            CLAUSE,
500            || {
501                format!(
502                    "a batch of one held event and one new one changed the log by more than the \
503                 new event: {} other events were held before and {} are now",
504                    log.len(),
505                    rest.len()
506                )
507            },
508        )?;
509        Ok(RuleOutcome::Ran)
510    }
511
512    /// SY-38: an event claiming the store's own identity at a position the
513    /// store did not hold when the call began refuses the **whole** call as
514    /// [`IngestError::UnheldOwnIdentity`], class [`FailureClass::Stop`], and
515    /// writes nothing. A held own identity is a re-delivery, and a skip.
516    ///
517    /// Three arrangements, each on a fresh fixture, and every claimed position
518    /// computed from the head the store assigned:
519    ///
520    /// 1. **The unheld claim.** After one local event, two groups arrive, and
521    ///    the claim, three positions past the head, is the second event of the
522    ///    second. The call is refused naming the claim; the log, head and
523    ///    watermark are as they were; and the store holds none of the three.
524    /// 2. **The held echo.** The store's own local event, sent back to it, is
525    ///    skipped, and nothing changes.
526    /// 3. **The claim the call's own compensation would hide.** The first group
527    ///    carries a compensation, which a dense store mints two positions past
528    ///    the head; the second group claims exactly that identity. The call is
529    ///    refused naming it, and writes nothing. The rule then ingests the
530    ///    first group alone to see where its compensation lands. A store that
531    ///    leaves a gap there was never shown the hidden claim, which the
532    ///    specification permits, so the rule reports
533    ///    [`Skipped`](RuleOutcome::Skipped) with [`NO_HIDDEN_CLAIM`] rather
534    ///    than a pass.
535    ///
536    /// This refusal is the one SY-33's rule, when it is written, must exempt
537    /// (ADR-0098): it is about the store's own identity, never about an
538    /// event's content.
539    ///
540    /// # Rejects
541    ///
542    /// A store that drops the claim as a re-delivery and writes the rest; one
543    /// that checks only the batch's first event; one that commits group by
544    /// group and keeps the groups before the claim; one that refuses a claim
545    /// only when it lands, so a claim meeting the call's own compensation is
546    /// skipped and two events share one identity; and one that refuses a held
547    /// echo too. `tests/wrong_ingest_stores.rs` carries all five, and the
548    /// conformant store that leaves a gap, which this rule must skip.
549    ///
550    /// # Errors
551    ///
552    /// A [`Violation`] of SY-38 if any arrangement's ingest is accepted, or
553    /// refused other than as the unheld claim it carries, or writes anything,
554    /// or if the echo is not a skip.
555    pub async fn an_unheld_own_identity_stops_the_ingest<F: IngestFixture>(
556        open: impl AsyncFn() -> F,
557    ) -> Result<RuleOutcome, Violation> {
558        an_unheld_claim_is_refused(&open().await).await?;
559        a_held_echo_is_a_skip(&open().await).await?;
560        a_claim_the_compensation_would_hide(&open().await).await
561    }
562
563    /// SY-38, the clause every arrangement below reports under.
564    const SY_38: &str = "SY-38";
565
566    /// SY-38's first arrangement: the unheld claim.
567    async fn an_unheld_claim_is_refused<F: IngestFixture>(fixture: &F) -> Result<(), Violation> {
568        let store = fixture.connect().await;
569        let own = ensure_foreign(&store, &[CLAIM_ORIGIN], SY_38).await?;
570        let head = append(&store, &[opaque(LOCAL, b"sy38-a-local", SY_38)?], SY_38).await?;
571        let claim = EventId::new(own, positions_past(head, 3)?);
572        let first = [shipped(
573            CLAIM_ORIGIN,
574            1,
575            1_800_000_000_000,
576            b"sy38-a-1",
577            SY_38,
578        )?];
579        let second = [
580            shipped(CLAIM_ORIGIN, 2, 1_800_000_000_001, b"sy38-a-2", SY_38)?,
581            forged(claim, b"sy38-a-claim")?,
582        ];
583        let before = observe(&store, SY_38).await?;
584
585        let refused = store
586            .ingest(&[
587                IngestGroup::new(&first, &[]),
588                IngestGroup::new(&second, &[]),
589            ])
590            .await;
591
592        ensure_refused(refused, claim, "a claim three positions past the head")?;
593        ensure_unchanged(
594            &store,
595            &before,
596            "an ingest refused for an unheld claim",
597            SY_38,
598        )
599        .await?;
600        for id in [first[0].id, second[0].id, claim] {
601            ensure(!holds(&store, id, SY_38).await?, SY_38, || {
602                format!("the refused ingest left {id} held")
603            })?;
604        }
605        Ok(())
606    }
607
608    /// SY-38's second arrangement: the held echo.
609    async fn a_held_echo_is_a_skip<F: IngestFixture>(fixture: &F) -> Result<(), Violation> {
610        let store = fixture.connect().await;
611        let own = own_identity(&store, SY_38).await?;
612        append(&store, &[opaque(LOCAL, b"sy38-c-local", SY_38)?], SY_38).await?;
613        let before = observe(&store, SY_38).await?;
614        let held = before
615            .log
616            .last()
617            .ok_or_else(|| Violation::new(SY_38, "the store holds nothing after an append"))?;
618        ensure(held.id.store() == own, SY_38, || {
619            format!(
620                "a local append was minted as {}, not under the store's own identity {own}",
621                held.id
622            )
623        })?;
624        let echo = [ReplicatedEvent::new(
625            held.id,
626            held.recorded_at,
627            held.event.clone(),
628        )];
629
630        let echoed = store.ingest(&[IngestGroup::new(&echo, &[])]).await;
631
632        let echoed = echoed.map_err(|error| {
633            Violation::new(
634                SY_38,
635                format!(
636                    "the store refused an echo of {}, which it holds: {error}; a held own \
637                     identity is a re-delivery, not a claim",
638                    held.id
639                ),
640            )
641        })?;
642        ensure_counts(echoed, (0, 1, 0), "an echo of a held local event", SY_38)?;
643        ensure_unchanged(&store, &before, "an echo of a held event", SY_38).await
644    }
645
646    /// SY-38's third arrangement: the claim the call's own compensation would
647    /// hide, and the check that the store let the rule arrange it.
648    async fn a_claim_the_compensation_would_hide<F: IngestFixture>(
649        fixture: &F,
650    ) -> Result<RuleOutcome, Violation> {
651        let store = fixture.connect().await;
652        let own = ensure_foreign(&store, &[CLAIM_ORIGIN], SY_38).await?;
653        let head = append(&store, &[opaque(LOCAL, b"sy38-b-local", SY_38)?], SY_38).await?;
654        let claimed = EventId::new(own, positions_past(head, 2)?);
655        let first = [shipped(
656            CLAIM_ORIGIN,
657            11,
658            1_800_000_000_011,
659            b"sy38-b-1",
660            SY_38,
661        )?];
662        let answer = [opaque(COMPENSATED, b"sy38-b-compensation", SY_38)?];
663        let second = [
664            shipped(CLAIM_ORIGIN, 12, 1_800_000_000_012, b"sy38-b-2", SY_38)?,
665            forged(claimed, b"sy38-b-claim")?,
666        ];
667        let before = observe(&store, SY_38).await?;
668
669        let refused = store
670            .ingest(&[
671                IngestGroup::new(&first, &answer),
672                IngestGroup::new(&second, &[]),
673            ])
674            .await;
675
676        ensure_refused(
677            refused,
678            claimed,
679            "a claim on the position the call's compensation takes",
680        )?;
681        ensure_unchanged(
682            &store,
683            &before,
684            "an ingest refused for a hidden claim",
685            SY_38,
686        )
687        .await?;
688
689        ingest(&store, &[IngestGroup::new(&first, &answer)], SY_38).await?;
690        let log = read_all(&store, SY_38).await?;
691        if held_once(&log, &answer[0], SY_38)?.id == claimed {
692            Ok(RuleOutcome::Ran)
693        } else {
694            Ok(RuleOutcome::Skipped {
695                capability: NO_HIDDEN_CLAIM,
696                reason: NO_HIDDEN_CLAIM_REASON,
697            })
698        }
699    }
700
701    /// The position `count` past `head`.
702    fn positions_past(head: SequencePosition, count: usize) -> Result<SequencePosition, Violation> {
703        (0..count).try_fold(head, |position, _| {
704            position
705                .next()
706                .ok_or_else(|| Violation::new(SY_38, "the store's head has no position past it"))
707        })
708    }
709
710    /// An event claiming `id`, which the rule chose, carrying `data`.
711    fn forged(id: EventId, data: &[u8]) -> Result<ReplicatedEvent, Violation> {
712        Ok(ReplicatedEvent::new(
713            id,
714            RecordedAt::from_millis(1_800_000_000_000),
715            opaque(LOCAL, data, SY_38)?,
716        ))
717    }
718
719    /// `outcome` is the refusal naming `claim`, and states the `Stop` class.
720    fn ensure_refused<E: core::error::Error + Classify>(
721        outcome: Result<Ingested, IngestError<E>>,
722        claim: EventId,
723        arrangement: &str,
724    ) -> Result<(), Violation> {
725        let error = match outcome {
726            Ok(ingested) => {
727                return Err(Violation::new(
728                    SY_38,
729                    format!(
730                        "the store accepted {arrangement} as {ingested:?}; {claim} claims its own \
731                         identity at a position it did not hold, so the call must write nothing"
732                    ),
733                ));
734            }
735            Err(error) => error,
736        };
737        let named = match &error {
738            IngestError::UnheldOwnIdentity { id, .. } => Some(*id),
739            _ => None,
740        };
741        ensure(named == Some(claim), SY_38, || {
742            format!("{arrangement} was refused as `{error}`, not as the unheld claim {claim}")
743        })?;
744        ensure(error.class() == FailureClass::Stop, SY_38, || {
745            format!(
746                "the refusal of {claim} states the class {:?}; an unheld own identity is Stop",
747                error.class()
748            )
749        })
750    }
751
752    /// SY-30: an [`IngestGroup`] lands whole or not at all, even when the
753    /// store fails between two of its rows.
754    ///
755    /// SY-30 rejects a receiver that, after a crash mid-ingest, holds four
756    /// events of a seven-event batch. A conformant store decides every refusal
757    /// before it writes, so the case no other rule reaches is a fault inside
758    /// the write, and only the adapter can inject one:
759    /// [`IngestFixture::MID_GROUP_FAULT`]. A fixture that declines it is
760    /// reported [`Skipped`](RuleOutcome::Skipped) with its stated reason.
761    ///
762    /// Three arrangements, each on a fresh fixture, one per cut inside a
763    /// four-row group of three foreign events and one compensation event:
764    /// after the first, the second and the third row the store writes. Each
765    /// appends a local event, so "unchanged" is not "empty", and ingests an
766    /// unarmed control group of the same shape, which must land as three
767    /// appended and one compensation. Then it arms the fault and ingests the
768    /// armed group. The ingest must return `Err`. The log, head and watermark
769    /// must be as they were, and the store must hold none of the group's
770    /// events.
771    ///
772    /// On the ingest path a losing event and its compensation are one group,
773    /// so a cut between them is the state SY-2 forbids a reader to see. The
774    /// claim is SY-30's because SY-2 is frozen.
775    ///
776    /// # Rejects
777    ///
778    /// A store that decides the whole call and then writes it in separately
779    /// committed chunks; one that commits a group's foreign rows and its
780    /// compensation as two writes; one that rolls the group back and answers
781    /// `Ok`, so a runner advances past a group that never landed; and a
782    /// fixture whose arm does nothing. `tests/wrong_ingest_stores.rs` carries
783    /// all four. A store that absorbs every fault its fixture can arm, and
784    /// commits the group anyway, must decline the capability: this rule
785    /// requires the armed ingest to fail.
786    ///
787    /// # Does not reject
788    ///
789    /// A store that commits group by group, each group whole. That is SY-38's
790    /// mistake and its rule's to catch (`UnheldOwnIdentity` means nothing in
791    /// the call was written), and this rule faults one group only.
792    ///
793    /// # Errors
794    ///
795    /// A [`Violation`] of SY-30 if the fixture cannot arm the fault, if the
796    /// control group is refused or miscounted, if the armed ingest returns
797    /// `Ok`, or if it leaves anything of the group behind.
798    pub async fn ingest_group_is_atomic_under_a_mid_group_fault<F: IngestFixture>(
799        open: impl AsyncFn() -> F,
800    ) -> Result<RuleOutcome, Violation> {
801        if let Some(reason) = F::MID_GROUP_FAULT.reason() {
802            return Ok(RuleOutcome::Skipped {
803                capability: "MID_GROUP_FAULT",
804                reason,
805            });
806        }
807        // Every cut inside a four-row group, so the rule does not depend on
808        // the store writing the compensation before or after the foreign rows.
809        for after in 1..=3 {
810            a_fault_inside_the_group(&open().await, after).await?;
811        }
812        Ok(RuleOutcome::Ran)
813    }
814
815    /// SY-30, the clause rule 1's arrangement reports under.
816    const SY_30: &str = "SY-30";
817
818    /// One arrangement of SY-30's rule: a group of three foreign rows and one
819    /// compensation row, faulted while its `after + 1`-th row is written.
820    async fn a_fault_inside_the_group<F: IngestFixture>(
821        fixture: &F,
822        after: usize,
823    ) -> Result<(), Violation> {
824        let store = fixture.connect().await;
825        ensure_foreign(&store, &[ATOMIC_ORIGIN], SY_30).await?;
826        append(&store, &[opaque(LOCAL, b"sy30-local", SY_30)?], SY_30).await?;
827        // The control: the same shape, unarmed, lands whole.
828        let control = [
829            shipped(
830                ATOMIC_ORIGIN,
831                1,
832                1_800_000_000_001,
833                b"sy30-control-1",
834                SY_30,
835            )?,
836            shipped(
837                ATOMIC_ORIGIN,
838                2,
839                1_800_000_000_002,
840                b"sy30-control-2",
841                SY_30,
842            )?,
843            shipped(
844                ATOMIC_ORIGIN,
845                3,
846                1_800_000_000_003,
847                b"sy30-control-3",
848                SY_30,
849            )?,
850        ];
851        let control_answer = [opaque(COMPENSATED, b"sy30-control-compensation", SY_30)?];
852        let landed = ingest(
853            &store,
854            &[IngestGroup::new(&control, &control_answer)],
855            SY_30,
856        )
857        .await?;
858        ensure_counts(landed, (3, 0, 1), "the unarmed control group", SY_30)?;
859
860        let armed = [
861            shipped(ATOMIC_ORIGIN, 4, 1_800_000_000_004, b"sy30-armed-1", SY_30)?,
862            shipped(ATOMIC_ORIGIN, 5, 1_800_000_000_005, b"sy30-armed-2", SY_30)?,
863            shipped(ATOMIC_ORIGIN, 6, 1_800_000_000_006, b"sy30-armed-3", SY_30)?,
864        ];
865        let answer = [opaque(COMPENSATED, b"sy30-armed-compensation", SY_30)?];
866        let before = observe(&store, SY_30).await?;
867        fixture.arm_mid_group_fault(after).await?;
868
869        let outcome = store.ingest(&[IngestGroup::new(&armed, &answer)]).await;
870
871        let row = after.saturating_add(1);
872        ensure(outcome.is_err(), SY_30, || {
873            format!(
874                "the fixture armed a fault at row {row} of a four-row group and the ingest \
875                 returned Ok; a fault that never fires shows nothing about what a failed group \
876                 leaves, so a store that absorbs every fault must decline MID_GROUP_FAULT"
877            )
878        })?;
879        ensure_unchanged(
880            &store,
881            &before,
882            &format!("an ingest faulted at row {row} of one group"),
883            SY_30,
884        )
885        .await?;
886        for event in &armed {
887            ensure(!holds(&store, event.id, SY_30).await?, SY_30, || {
888                format!(
889                    "an ingest faulted at row {row} of one group left {} held; a group lands \
890                     whole or not at all",
891                    event.id
892                )
893            })?;
894        }
895        Ok(())
896    }
897
898    /// SY-18: a store holds **every** event an ingest writes to the
899    /// per-event ceilings it declares, not the head of each group, and an
900    /// event over one refuses the whole call.
901    ///
902    /// SY-18 says an event that cannot land is discovered at ingest, so the
903    /// refusal has to be a true one: [`IngestError::ExceedsStoreLimit`]
904    /// naming the limit and the magnitude, class [`FailureClass::Park`], with
905    /// nothing written. The rule reads the ceilings from the fixture's
906    /// [`MAX_EVENT_DATA_LEN`](IngestFixture::MAX_EVENT_DATA_LEN),
907    /// [`MAX_TAGS_PER_EVENT`](IngestFixture::MAX_TAGS_PER_EVENT) and
908    /// [`MAX_METADATA_LEN`](IngestFixture::MAX_METADATA_LEN), and for each
909    /// declared one, on a fresh fixture, after one local event:
910    ///
911    /// 1. **The control.** Two groups, the second carrying an event exactly
912    ///    at the ceiling behind its head and a compensation whose second event
913    ///    is exactly at it too, land as three appended and two compensations,
914    ///    each sized event found by its bytes.
915    /// 2. **Over, in the foreign events.** Two groups, the second's second
916    ///    event one over the ceiling: refused, the log, head and watermark as
917    ///    they were, and none of the three events held.
918    /// 3. **Over, in the compensation.** One group whose compensation's second
919    ///    event is one over: refused in the same way.
920    ///
921    /// A ceiling at or above [`MAX_PROVOKED_TAGS`]
922    /// tags or [`MAX_PROVOKED_BATCH_BYTES`]
923    /// bytes is not exercised, because the over-ceiling event is allocated
924    /// whole (H-13). A fixture that leaves the rule nothing to exercise is
925    /// reported [`Skipped`](RuleOutcome::Skipped) with
926    /// [`NO_PER_EVENT_LIMITS`].
927    ///
928    /// # Rejects
929    ///
930    /// A store that holds only each group's first event to its ceilings; one
931    /// that never checks the compensation it writes itself; and one that
932    /// refuses an event exactly at a ceiling, which only the control sees.
933    /// `tests/wrong_ingest_stores.rs` carries all three.
934    ///
935    /// # Does not reject
936    ///
937    /// A head-only check of the store's own identity. That is SY-38's rule's,
938    /// whose unheld claim already sits behind a group's head, so a mutant
939    /// that checked only each group's head for it would fail that rule too.
940    /// Nor the batch limit, which is `Split`, not a fact about one event.
941    ///
942    /// # Errors
943    ///
944    /// A [`Violation`] of SY-18 if the control is refused or miscounted, or if
945    /// an over-ceiling call is accepted, refused as anything but that limit
946    /// and magnitude or with a class other than `Park`, or leaves anything
947    /// behind. The wrong-arm message cites VT-25.
948    pub async fn ingest_validates_every_event_not_the_head<F: IngestFixture>(
949        open: impl AsyncFn() -> F,
950    ) -> Result<RuleOutcome, Violation> {
951        let declared = [
952            (
953                StoreLimit::EventDataLen,
954                F::MAX_EVENT_DATA_LEN,
955                MAX_PROVOKED_BATCH_BYTES,
956            ),
957            (
958                StoreLimit::TagsPerEvent,
959                F::MAX_TAGS_PER_EVENT,
960                MAX_PROVOKED_TAGS,
961            ),
962            (
963                StoreLimit::MetadataLen,
964                F::MAX_METADATA_LEN,
965                MAX_PROVOKED_BATCH_BYTES,
966            ),
967        ];
968        let mut exercised = false;
969        for (limit, ceiling, cap) in declared {
970            // Below the cap, so one over the ceiling is still inside it (H-13).
971            let Some(ceiling) = ceiling.filter(|ceiling| *ceiling < cap) else {
972                continue;
973            };
974            every_event_is_held_to(&open().await, limit, ceiling).await?;
975            exercised = true;
976        }
977        Ok(if exercised {
978            RuleOutcome::Ran
979        } else {
980            RuleOutcome::Skipped {
981                capability: NO_PER_EVENT_LIMITS,
982                reason: NO_PER_EVENT_LIMITS_REASON,
983            }
984        })
985    }
986
987    /// SY-18, the clause rule 2's arrangements report under.
988    const SY_18: &str = "SY-18";
989
990    /// SY-18's arrangements for one declared `ceiling` on `limit`.
991    async fn every_event_is_held_to<F: IngestFixture>(
992        fixture: &F,
993        limit: StoreLimit,
994        ceiling: usize,
995    ) -> Result<(), Violation> {
996        let over = ceiling
997            .checked_add(1)
998            .ok_or_else(|| Violation::new(SY_18, "the declared ceiling has no size past it"))?;
999        let store = fixture.connect().await;
1000        ensure_foreign(&store, &[CEILING_ORIGIN], SY_18).await?;
1001        append(&store, &[opaque(LOCAL, b"sy18-local", SY_18)?], SY_18).await?;
1002
1003        // The control: the same shapes, each sized event exactly at the
1004        // ceiling, land. Found by their bytes, never their identities.
1005        let head_group = [shipped(
1006            CEILING_ORIGIN,
1007            1,
1008            1_800_000_000_001,
1009            b"sy18-control-1",
1010            SY_18,
1011        )?];
1012        let at_ceiling = [
1013            shipped(
1014                CEILING_ORIGIN,
1015                2,
1016                1_800_000_000_002,
1017                b"sy18-control-2",
1018                SY_18,
1019            )?,
1020            sized_shipped(CEILING_ORIGIN, 3, AT_FOREIGN, limit, ceiling)?,
1021        ];
1022        let at_answer = [
1023            opaque(COMPENSATED, b"sy18-control-compensation", SY_18)?,
1024            sized(AT_COMPENSATION, limit, ceiling)?,
1025        ];
1026        let landed = ingest(
1027            &store,
1028            &[
1029                IngestGroup::new(&head_group, &[]),
1030                IngestGroup::new(&at_ceiling, &at_answer),
1031            ],
1032            SY_18,
1033        )
1034        .await?;
1035        ensure_counts(
1036            landed,
1037            (3, 0, 2),
1038            "two groups whose sized events are exactly at the ceiling",
1039            SY_18,
1040        )?;
1041        let log = read_all(&store, SY_18).await?;
1042        held_once(&log, &at_ceiling[1].event, SY_18)?;
1043        held_once(&log, &at_answer[1], SY_18)?;
1044        let before = observe(&store, SY_18).await?;
1045
1046        // A: an event over the ceiling behind the second group's head, so a
1047        // store that holds only each group's first event to it writes it.
1048        let first = [shipped(
1049            CEILING_ORIGIN,
1050            4,
1051            1_800_000_000_004,
1052            b"sy18-a-1",
1053            SY_18,
1054        )?];
1055        let second = [
1056            shipped(CEILING_ORIGIN, 5, 1_800_000_000_005, b"sy18-a-2", SY_18)?,
1057            sized_shipped(CEILING_ORIGIN, 6, OVER_FOREIGN, limit, over)?,
1058        ];
1059        let refused = store
1060            .ingest(&[
1061                IngestGroup::new(&first, &[]),
1062                IngestGroup::new(&second, &[]),
1063            ])
1064            .await;
1065        let what = "a group whose foreign event is one over the ceiling";
1066        ensure_exceeds(refused, limit, over, what)?;
1067        ensure_unchanged(&store, &before, what, SY_18).await?;
1068        for id in [first[0].id, second[0].id, second[1].id] {
1069            ensure(!holds(&store, id, SY_18).await?, SY_18, || {
1070                format!("{what} was refused and left {id} held")
1071            })?;
1072        }
1073
1074        // B: an event over the ceiling behind the head of a group's
1075        // compensation, which the store writes itself.
1076        let lone = [shipped(
1077            CEILING_ORIGIN,
1078            7,
1079            1_800_000_000_007,
1080            b"sy18-b-1",
1081            SY_18,
1082        )?];
1083        let answer = [
1084            opaque(COMPENSATED, b"sy18-b-compensation", SY_18)?,
1085            sized(OVER_COMPENSATION, limit, over)?,
1086        ];
1087        let refused = store.ingest(&[IngestGroup::new(&lone, &answer)]).await;
1088        let what = "a group whose compensation is one over the ceiling";
1089        ensure_exceeds(refused, limit, over, what)?;
1090        ensure_unchanged(&store, &before, what, SY_18).await?;
1091        ensure(!holds(&store, lone[0].id, SY_18).await?, SY_18, || {
1092            format!("{what} was refused and left {} held", lone[0].id)
1093        })
1094    }
1095
1096    /// What a sized event's bytes are filled with. Never parsed (SY-35), and
1097    /// ASCII so a store that decodes a payload fails SY-12's rule and not this
1098    /// one.
1099    const FILLER: u8 = b'.';
1100
1101    // The event types that tell the rule's sized events apart, since their
1102    // sized field is filler.
1103    const AT_FOREIGN: EventType = EventType::from_static("CeilingAtForeign");
1104    const AT_COMPENSATION: EventType = EventType::from_static("CeilingAtCompensation");
1105    const OVER_FOREIGN: EventType = EventType::from_static("CeilingOverForeign");
1106    const OVER_COMPENSATION: EventType = EventType::from_static("CeilingOverCompensation");
1107
1108    /// An event of `event_type` whose `limit` field measures `len` in that
1109    /// limit's unit: `len` opaque bytes of data or metadata, or `len` distinct
1110    /// tags. Nothing else is set, so no other ceiling is approached.
1111    fn sized(event_type: EventType, limit: StoreLimit, len: usize) -> Result<Event, Violation> {
1112        let invalid = |error: &dyn core::fmt::Display| {
1113            Violation::new(SY_18, format!("the rule's own event is invalid: {error}"))
1114        };
1115        let data = if limit == StoreLimit::EventDataLen {
1116            vec![FILLER; len]
1117        } else {
1118            Vec::new()
1119        };
1120        let event = Event::new(event_type, data).map_err(|error| invalid(&error))?;
1121        match limit {
1122            StoreLimit::EventDataLen => Ok(event),
1123            StoreLimit::MetadataLen => Ok(event.with_metadata(vec![FILLER; len])),
1124            StoreLimit::TagsPerEvent => {
1125                let tags = (0..len)
1126                    .map(|i| Tag::new(format!("t:{i}")))
1127                    .collect::<Result<Tags, _>>()
1128                    .map_err(|error| invalid(&error))?;
1129                Ok(event.with_tags(tags))
1130            }
1131            // The batch limit is not about one event, and `StoreLimit` is
1132            // `#[non_exhaustive]`: the rule only ever builds the three above.
1133            _ => Err(Violation::new(
1134                SY_18,
1135                format!("the rule cannot size an event against the {limit} limit"),
1136            )),
1137        }
1138    }
1139
1140    /// A foreign event from `origin` at origin `position`, sized by [`sized`].
1141    fn sized_shipped(
1142        origin: StoreId,
1143        position: u64,
1144        event_type: EventType,
1145        limit: StoreLimit,
1146        len: usize,
1147    ) -> Result<ReplicatedEvent, Violation> {
1148        let position = SequencePosition::new(position)
1149            .ok_or_else(|| Violation::new(SY_18, "the rule's origin position is zero"))?;
1150        Ok(ReplicatedEvent::new(
1151            EventId::new(origin, position),
1152            RecordedAt::from_millis(1_800_000_000_000),
1153            sized(event_type, limit, len)?,
1154        ))
1155    }
1156
1157    /// `outcome` is the refusal of `len` against `limit`, and states `Park`.
1158    fn ensure_exceeds<E: core::error::Error + Classify>(
1159        outcome: Result<Ingested, IngestError<E>>,
1160        limit: StoreLimit,
1161        len: usize,
1162        arrangement: &str,
1163    ) -> Result<(), Violation> {
1164        let error = match outcome {
1165            Ok(ingested) => {
1166                return Err(Violation::new(
1167                    SY_18,
1168                    format!(
1169                        "the store accepted {arrangement} as {ingested:?}; it declares that \
1170                         ceiling, so every event an ingest writes is held to it, not the head of \
1171                         each group"
1172                    ),
1173                ));
1174            }
1175            Err(error) => error,
1176        };
1177        let named = match &error {
1178            IngestError::ExceedsStoreLimit {
1179                limit: refused,
1180                len: measured,
1181                ..
1182            } => Some((*refused, *measured)),
1183            _ => None,
1184        };
1185        ensure(named == Some((limit, len)), SY_18, || {
1186            format!(
1187                "{arrangement} was refused as `{error}`, not as the {limit} limit exceeded by \
1188                 {len}; VT-25 makes a capacity refusal one a runner can tell from a retry"
1189            )
1190        })?;
1191        ensure(error.class() == FailureClass::Park, SY_18, || {
1192            format!(
1193                "the refusal of {arrangement} states {:?}; a per-event ceiling is Park",
1194                error.class()
1195            )
1196        })
1197    }
1198
1199    /// VT-36 on the ingest path: a store that declares a tags-per-batch
1200    /// ceiling holds the **whole call** to it, every foreign event and every
1201    /// compensation event of every group counted together, and refuses a call
1202    /// one tag over as [`IngestError::ExceedsStoreLimit`] naming
1203    /// [`StoreLimit::TagsPerBatch`] and the call's total, class
1204    /// [`FailureClass::Split`], with nothing written (ADR-0100). SY-18 is why
1205    /// the refusal has to be a true one.
1206    ///
1207    /// The rule reads the ceiling from the fixture's
1208    /// [`MAX_TAGS_PER_BATCH`](IngestFixture::MAX_TAGS_PER_BATCH), checks that
1209    /// it is at least the fixture's own
1210    /// [`MAX_TAGS_PER_EVENT`](IngestFixture::MAX_TAGS_PER_EVENT) and has a
1211    /// total past it, and then, on one fresh fixture, after one local event:
1212    ///
1213    /// 1. **The control.** Two groups whose tags, the second group's
1214    ///    compensation included, sum to exactly the ceiling, land: every
1215    ///    foreign event appended and both compensation events written.
1216    /// 2. **Over, spread across groups.** Two groups, each at or under the
1217    ///    ceiling on its own, one tag over it together: refused, the log,
1218    ///    head and watermark as they were, and no event of either held.
1219    /// 3. **Over, in the compensation alone.** One group whose foreign events
1220    ///    are at or under the ceiling and whose compensation takes the call
1221    ///    one tag over: refused in the same way.
1222    ///
1223    /// Tags are spread over many events, each one tag under a declared
1224    /// per-event ceiling, so no event approaches its own ceiling and a store
1225    /// off by one there fails SY-18's rule and not this one. A ceiling at or
1226    /// above [`MAX_PROVOKED_TAGS_PER_BATCH`] is not exercised, because the
1227    /// over-ceiling call is allocated whole (H-13). A fixture that declares
1228    /// no ceiling, or only one that large, is reported
1229    /// [`Skipped`](RuleOutcome::Skipped) with [`NO_TAGS_PER_BATCH_LIMIT`].
1230    ///
1231    /// # Not checked: the call's length
1232    ///
1233    /// `IngestFixture` declares no events-per-call ceiling, so the rule cannot
1234    /// check before it writes that the over-ceiling call fits under one, the
1235    /// "reachable" half of VT-36 that the event-store family checks against
1236    /// `MAX_EVENTS_PER_BATCH`. A store whose call-length ceiling is too small
1237    /// for `ceiling + 1` tags at the rule's spread fails the second
1238    /// arrangement naming the limit it refused under instead.
1239    ///
1240    /// # Rejects
1241    ///
1242    /// A store that holds each group to the ceiling apart, the append path's
1243    /// check reused per group; one that counts the foreign events and never
1244    /// the compensation it writes itself; one that refuses a call exactly at
1245    /// the ceiling, which only the control sees; and one that refuses the
1246    /// total under the per-event limit, `Park`, so a runner parks a call that
1247    /// would have landed halved. `tests/wrong_ingest_stores.rs` carries all
1248    /// four.
1249    ///
1250    /// # Errors
1251    ///
1252    /// A [`Violation`] of VT-36 if the declared ceiling is incoherent, if the
1253    /// control is refused or miscounted, or if an over-ceiling call is
1254    /// accepted, refused as anything but that limit and total or with a class
1255    /// other than `Split`, or leaves anything behind. The wrong-arm message
1256    /// cites VT-25.
1257    pub async fn ingest_holds_the_call_to_its_tags_per_batch_ceiling<F: IngestFixture>(
1258        open: impl AsyncFn() -> F,
1259    ) -> Result<RuleOutcome, Violation> {
1260        let skipped = RuleOutcome::Skipped {
1261            capability: NO_TAGS_PER_BATCH_LIMIT,
1262            reason: NO_TAGS_PER_BATCH_LIMIT_REASON,
1263        };
1264        let Some(ceiling) = F::MAX_TAGS_PER_BATCH else {
1265            return Ok(skipped);
1266        };
1267        // Coherence first, which allocates nothing, so a ceiling too large to
1268        // exercise is still held to its declaration.
1269        let per_event = batch_scope::per_event::<F>(ceiling)?;
1270        // Below the cap, so one over the ceiling is still inside it (H-13).
1271        if ceiling >= MAX_PROVOKED_TAGS_PER_BATCH {
1272            return Ok(skipped);
1273        }
1274        batch_scope::the_call_is_held_to(&open().await, ceiling, per_event).await?;
1275        Ok(RuleOutcome::Ran)
1276    }
1277
1278    /// SY-7: a compensation is written only by the store the assignment names
1279    /// the fact family's adjudicator, and filed under that store's own
1280    /// identity, which is how a log records who authored it.
1281    ///
1282    /// Two stores each take the same pair of conflicting claims on one seat,
1283    /// from two foreign origins, in opposite orders. The rule plays the runner
1284    /// above them and holds the assignment: the first store adjudicates the
1285    /// seat family and the second does not. Where the runner finds the pulled
1286    /// claim's guard matched by what the store holds (SY-6's evidence), it
1287    /// hands the adjudicator a reversal to write with the claim, in one group,
1288    /// and hands the other store the claim alone. Read back, the adjudicator's
1289    /// log holds one reversal, carrying the adjudicator's identity, and the
1290    /// other store's holds none. Reversals are found by type, never decoded.
1291    ///
1292    /// # Rejects
1293    ///
1294    /// A store that mints a compensation under an incarnation it never read,
1295    /// a placeholder, rather than its own identity: its log then says a store
1296    /// nobody assigned authored the reversal, and every such store files every
1297    /// compensation under that one identity, so two stores' reversals at one
1298    /// position collapse into one when they meet, which is SY-7's marker's
1299    /// escape reached by losing an event. `tests/wrong_ingest_stores.rs`
1300    /// carries it, and asserts SY-38's rule reports its compensation-hidden
1301    /// half skipped against it, since the compensation is not where its own
1302    /// identity would put it.
1303    ///
1304    /// # Does not reject
1305    ///
1306    /// **Every peer adjudicating**, the wrong implementation SY-7 names. That
1307    /// is a runner configuration, so the rule plays the runner, mounting the
1308    /// shipped `runner::Adjudicate` hook on the adjudicator and
1309    /// `runner::Accept` on the other, and always honours the assignment. A
1310    /// runner that adjudicates under `Accept` is rejected in
1311    /// `happenstance-sync`'s `tests/runner/wrong_runners.rs` (#450). The
1312    /// configuration SY-7 forbids is run by the clause's falsification test,
1313    /// in this crate's own tests, where two adjudicators answer one conflict
1314    /// twice and reverse opposite claims.
1315    ///
1316    /// # Errors
1317    ///
1318    /// A [`Violation`] of SY-7 if the fixture gives both stores one identity,
1319    /// if a store refuses or miscounts an ingest, or if either log holds a
1320    /// reversal its store was not assigned, lacks the one it was, or files it
1321    /// under another identity.
1322    pub async fn only_the_adjudicator_compensates<F: IngestFixture>(
1323        open: impl AsyncFn() -> F,
1324    ) -> Result<RuleOutcome, Violation> {
1325        let conflict =
1326            adjudication::take_the_conflicting_pair(&open, adjudication::Assignment::Adjudicator)
1327                .await?;
1328        adjudication::judge(&conflict).await?;
1329        Ok(RuleOutcome::Ran)
1330    }
1331
1332    /// SY-10: the runner may give each direction of one edge its own merge
1333    /// rule, and a store takes what each direction hands it, judging nothing
1334    /// itself.
1335    ///
1336    /// Two walks over two stores each, both played by one runner that holds a
1337    /// merge rule per direction. Every claim is decided under the guard "no
1338    /// claim on this seat", and travels with it only where a real runner would
1339    /// send it: a local append records no guard (SY-6), so an end's own claim
1340    /// travels unguarded, and an ingested claim keeps the guard it arrived
1341    /// under (SY-30). The hub adjudicates by fact family (SY-35), never by a
1342    /// guard.
1343    ///
1344    /// * **Hub and spoke**, in the shipped `Edge::step`'s order, pull before
1345    ///   push. The hub holds another spoke's claim, ingested under its
1346    ///   origin's guard. The spoke appends its own. It pulls the other claim,
1347    ///   whose guard its own log breaks, and takes it unjudged: one event, no
1348    ///   reversal. It pushes its own and the hub adjudicates it, writing the
1349    ///   claim with its reversal (SY-7). The spoke pulls the reversal. Both
1350    ///   logs end with the two claims and the hub's one reversal, and the
1351    ///   spoke still holds its own claim under its own identity (E2E-45).
1352    /// * **Peer to peer.** Each peer appends its own claim. Neither
1353    ///   adjudicates the family on this edge, so each takes the other's claim
1354    ///   unjudged. Both logs end with the two claims and no reversal.
1355    ///
1356    /// Every ingest's counts must be what the runner handed the store, and
1357    /// every log is compared by type and bytes, never decoded (SY-35).
1358    ///
1359    /// # Rejects
1360    ///
1361    /// A store with the merge rule built in: it answers a group whose
1362    /// travelling guard its log breaks with a reversal of its own, in the
1363    /// same write. As a spoke it judges the guarded claim the hub sends,
1364    /// which is SY-10's falsifier, and writes a reversal no direction asked
1365    /// for. `tests/wrong_ingest_stores.rs` carries it.
1366    ///
1367    /// And a store that gives up its own fact when a peer's claim on the same
1368    /// seat arrives, as an upsert keyed by the fact family does: it re-mints
1369    /// its own claim under a new identity, so every log still compares equal
1370    /// by type and bytes, and only the check that each end still holds its
1371    /// own claim under its own identity sees it. `tests/wrong_ingest_stores.rs`
1372    /// carries it too.
1373    ///
1374    /// # Does not reject
1375    ///
1376    /// **A runner that forces one rule on both directions.** The rule plays
1377    /// the runner, mounting each direction's merge rule through the shipped
1378    /// `runner::Adjudicate` hook, and always honours each direction's. That
1379    /// configuration, the hub's rule on the spoke, is the clause's
1380    /// falsification test, in this crate's own tests: it leaves no claim to
1381    /// the seat standing. The shipped runner's half is checked in
1382    /// `happenstance-sync`'s `tests/runner/wrong_runners.rs` (#450): an edge
1383    /// judges only what it pulls, by the rule it was given, and never what it
1384    /// pushes; a `StoreSyncPeer` judges what it is pushed.
1385    ///
1386    /// **A spoke rolled back on a refused push (SY-34).** The walk plays no
1387    /// refusal (SY-33), because the store is never told of one: a declined
1388    /// push is the far peer's answer to `SyncPeer::push`, and every port the
1389    /// runner holds over the store only adds events, so the rollback cannot be
1390    /// written through them and no store could fail a check at the refusal.
1391    /// The runner's half is held in `happenstance-sync`'s runner tests:
1392    /// `tests/runner/directions.rs`, whose declined step keeps the spoke's own
1393    /// claim, and `tests/runner/main.rs`'s
1394    /// `a_refused_push_keeps_the_log_and_the_watermark_and_records_the_class`.
1395    ///
1396    /// # Errors
1397    ///
1398    /// A [`Violation`] of SY-10 if the fixture gives both stores of an edge one
1399    /// identity, if a store cannot say who it is, refuses its own claim or an
1400    /// ingest, miscounts one, or ends holding other facts than its edge's
1401    /// rules leave, or without its own claim.
1402    pub async fn directional_merge_rules_compose<F: IngestFixture>(
1403        open: impl AsyncFn() -> F,
1404    ) -> Result<RuleOutcome, Violation> {
1405        let hub = topology::hub_and_spoke(&open, topology::HUB_AND_SPOKE).await?;
1406        topology::judge(&hub, &topology::hub_and_spoke_facts()).await?;
1407        let peers = topology::peer_to_peer(&open, topology::PEER_TO_PEER).await?;
1408        topology::judge(&peers, &topology::peer_to_peer_facts()).await?;
1409        Ok(RuleOutcome::Ran)
1410    }
1411
1412    /// SY-14: a pulled batch lands in **one** ingest call, however many of
1413    /// its events the store already holds, and the same call again changes
1414    /// nothing. With VT-24 on the ingest path: the call is
1415    /// [`MIN_SUPPORTED_EVENTS_PER_BATCH`](happenstance_core::MIN_SUPPORTED_EVENTS_PER_BATCH)
1416    /// foreign events, the push the minimum peer declares it takes, and every
1417    /// store takes it.
1418    ///
1419    /// One origin numbers 128 events 1 to 128, each with bytes of its own and
1420    /// no tags, in seven groups of 1, 3, 4, 8, 16, 32 and 64. A first call
1421    /// delivers every third event and the last, 44 in all, each in the group
1422    /// it travels in: the first group whole, every other in part, and held
1423    /// events past the first half of the call. Then the whole batch arrives in
1424    /// one call. It must land, counted 84 appended and 44 skipped, leaving
1425    /// each event held once, found by its bytes, and every row the first call
1426    /// wrote still held with its identity, time and bytes. The same call again
1427    /// is 128 skips and leaves the log, head and watermark as they were.
1428    ///
1429    /// The round trip the clause bounds is the `ingest` call: one per pulled
1430    /// batch, which is all the port can see. How many requests an adapter
1431    /// spends inside one call is its own to pin, and CF-33 leaves request
1432    /// counting to it: `happenstance-neon` pins one request per push.
1433    ///
1434    /// # Rejects
1435    ///
1436    /// A store that consults what it holds for the first 64 foreign events of
1437    /// a call only, as one that sends one chunk of identities and forgets to
1438    /// loop does, and writes a held event past the chunk again; SY-12's
1439    /// three-event call cannot see it. And a store whose ingest refuses a
1440    /// call of more than 64 events as over its batch limit, which refuses
1441    /// the minimum peer's push. `tests/wrong_ingest_stores.rs` carries both.
1442    ///
1443    /// # Does not reject
1444    ///
1445    /// An adapter that spends one request per event inside one `ingest`
1446    /// call. No port method sees a request, so that is the adapter's own
1447    /// test, as `happenstance-neon`'s scripted request count is.
1448    ///
1449    /// # Errors
1450    ///
1451    /// A [`Violation`] of SY-14 if the store refuses a call or miscounts it,
1452    /// or holds other than each event once with the first call's rows
1453    /// unchanged, or if the re-delivery changes anything; of VT-24 if a call
1454    /// is refused as over a capacity limit.
1455    pub async fn bulk_ingest_is_idempotent_in_bounded_round_trips<F: IngestFixture>(
1456        open: impl AsyncFn() -> F,
1457    ) -> Result<RuleOutcome, Violation> {
1458        let fixture = open().await;
1459        bulk::the_floor_lands_once(&fixture.connect().await).await?;
1460        Ok(RuleOutcome::Ran)
1461    }
1462
1463    /// What a refused or skipped ingest must leave as it found it.
1464    #[derive(Debug, PartialEq)]
1465    struct Observed {
1466        log: Vec<SequencedEvent>,
1467        head: Option<SequencePosition>,
1468        watermark: Watermark,
1469    }
1470
1471    async fn observe<S: EventStore + IngestStore>(
1472        store: &S,
1473        clause: &'static str,
1474    ) -> Result<Observed, Violation> {
1475        Ok(Observed {
1476            log: read_all(store, clause).await?,
1477            head: head(store, clause).await?,
1478            watermark: watermark(store, clause).await?,
1479        })
1480    }
1481
1482    /// The store's log, head and watermark are `before`'s after `what`.
1483    async fn ensure_unchanged<S: EventStore + IngestStore>(
1484        store: &S,
1485        before: &Observed,
1486        what: &str,
1487        clause: &'static str,
1488    ) -> Result<(), Violation> {
1489        let after = observe(store, clause).await?;
1490        ensure(after == *before, clause, || {
1491            format!(
1492                "{what} changed the store: it held {} events at head {:?} before and holds {} at \
1493                 head {:?} after, or its watermark moved",
1494                before.log.len(),
1495                before.head,
1496                after.log.len(),
1497                after.head
1498            )
1499        })
1500    }
1501
1502    /// Whether the store holds `id`.
1503    async fn holds<S: EventStore>(
1504        store: &S,
1505        id: EventId,
1506        clause: &'static str,
1507    ) -> Result<bool, Violation> {
1508        store.contains_event_id(id).await.map_err(|error| {
1509            Violation::new(
1510                clause,
1511                format!("the store refused contains_event_id: {error}"),
1512            )
1513        })
1514    }
1515
1516    /// The store's own identity, or a violation of `clause` when it cannot
1517    /// read it: a rule must not arrange a claim, or call an origin foreign,
1518    /// against an identity the store never stated.
1519    async fn own_identity<S: IngestStore>(
1520        store: &S,
1521        clause: &'static str,
1522    ) -> Result<StoreId, Violation> {
1523        store.store_id().await.map_err(|error| {
1524            Violation::new(
1525                clause,
1526                format!("the store could not read its own identity: {error}"),
1527            )
1528        })
1529    }
1530
1531    /// Every origin a rule uses is foreign to the store under test, or the
1532    /// rule would be testing SY-38 by accident. Answers the store's own
1533    /// identity, which the SY-38 arrangements claim.
1534    async fn ensure_foreign<S: IngestStore>(
1535        store: &S,
1536        origins: &[StoreId],
1537        clause: &'static str,
1538    ) -> Result<StoreId, Violation> {
1539        let own = own_identity(store, clause).await?;
1540        ensure(!origins.contains(&own), clause, || {
1541            format!(
1542                "the fixture's store has the incarnation {own}, which this rule uses as a \
1543                 foreign origin; a fixture must give each store a fresh one"
1544            )
1545        })?;
1546        Ok(own)
1547    }
1548
1549    /// A foreign event from `origin` at origin `position`, recorded at
1550    /// `millis`, carrying `data` as opaque bytes.
1551    fn shipped(
1552        origin: StoreId,
1553        position: u64,
1554        millis: i64,
1555        data: &[u8],
1556        clause: &'static str,
1557    ) -> Result<ReplicatedEvent, Violation> {
1558        let position = SequencePosition::new(position)
1559            .ok_or_else(|| Violation::new(clause, "the rule's origin position is zero"))?;
1560        Ok(ReplicatedEvent::new(
1561            EventId::new(origin, position),
1562            RecordedAt::from_millis(millis),
1563            opaque(SHIPPED, data, clause)?,
1564        ))
1565    }
1566
1567    /// An event of `event_type` whose data is `data`, never parsed (SY-35).
1568    fn opaque(
1569        event_type: EventType,
1570        data: &[u8],
1571        clause: &'static str,
1572    ) -> Result<Event, Violation> {
1573        Event::new(event_type, data.to_vec()).map_err(|error| {
1574            Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1575        })
1576    }
1577
1578    /// Ingests `groups`, which the store must accept.
1579    async fn ingest<S: IngestStore>(
1580        store: &S,
1581        groups: &[IngestGroup<'_>],
1582        clause: &'static str,
1583    ) -> Result<Ingested, Violation> {
1584        store.ingest(groups).await.map_err(|error| {
1585            Violation::new(
1586                clause,
1587                format!("the store refused an ingest it must accept: {error}"),
1588            )
1589        })
1590    }
1591
1592    /// [`UNDECODABLE`] followed by `suffix`, so each event's bytes are its own.
1593    fn undecodable_bytes(suffix: u8) -> Vec<u8> {
1594        let mut bytes = UNDECODABLE.to_vec();
1595        bytes.push(suffix);
1596        bytes
1597    }
1598
1599    /// A foreign event from `origin` whose data and metadata are both
1600    /// undecodable, tagged so a content comparison has a tag to compare too.
1601    fn undecodable(
1602        origin: StoreId,
1603        position: u64,
1604        suffix: u8,
1605        clause: &'static str,
1606    ) -> Result<ReplicatedEvent, Violation> {
1607        let mut event = shipped(
1608            origin,
1609            position,
1610            1_800_000_000_000,
1611            &undecodable_bytes(suffix),
1612            clause,
1613        )?;
1614        event.event = event
1615            .event
1616            .with_metadata(undecodable_bytes(suffix.wrapping_add(0x80)))
1617            .with_tags([Tag::from_static("item:undecodable")].into_iter().collect());
1618        Ok(event)
1619    }
1620
1621    /// `ingested` is `(appended, skipped, compensated)`, or a violation naming
1622    /// `what` was ingested.
1623    fn ensure_counts(
1624        ingested: Ingested,
1625        (appended, skipped, compensated): (usize, usize, usize),
1626        what: &str,
1627        clause: &'static str,
1628    ) -> Result<(), Violation> {
1629        let got = (ingested.appended, ingested.skipped, ingested.compensated);
1630        ensure(got == (appended, skipped, compensated), clause, || {
1631            format!(
1632                "{what} was counted as (appended, skipped, compensated) {got:?}; it should be \
1633                 {:?}",
1634                (appended, skipped, compensated)
1635            )
1636        })
1637    }
1638
1639    /// The store's head.
1640    async fn head<S: EventStore>(
1641        store: &S,
1642        clause: &'static str,
1643    ) -> Result<Option<SequencePosition>, Violation> {
1644        store
1645            .head()
1646            .await
1647            .map_err(|error| Violation::new(clause, format!("the store refused its head: {error}")))
1648    }
1649
1650    /// Appends `events` locally, without a condition, and returns the last
1651    /// position the store assigned.
1652    async fn append<S: EventStore>(
1653        store: &S,
1654        events: &[Event],
1655        clause: &'static str,
1656    ) -> Result<SequencePosition, Violation> {
1657        store.append(events, None).await.map_err(|error| {
1658            Violation::new(clause, format!("the store refused a local append: {error}"))
1659        })
1660    }
1661
1662    /// The one event in `log` whose bytes are `written`'s, found without its
1663    /// identity.
1664    fn held_once<'log>(
1665        log: &'log [SequencedEvent],
1666        written: &Event,
1667        clause: &'static str,
1668    ) -> Result<&'log SequencedEvent, Violation> {
1669        let mut matching = log.iter().filter(|row| row.event == *written);
1670        match (matching.next(), matching.next()) {
1671            (Some(landed), None) => Ok(landed),
1672            (found, _) => Err(Violation::new(
1673                clause,
1674                format!(
1675                    "an event of type {} was written once and is held {}",
1676                    written.event_type(),
1677                    if found.is_some() {
1678                        "more than once"
1679                    } else {
1680                        "nowhere"
1681                    }
1682                ),
1683            )),
1684        }
1685    }
1686
1687    /// Every event the store holds, in position order.
1688    async fn read_all<S: EventStore>(
1689        store: &S,
1690        clause: &'static str,
1691    ) -> Result<Vec<SequencedEvent>, Violation> {
1692        collect(store.read(&Query::all(), ReadOptions::new()))
1693            .await
1694            .map_err(|error| {
1695                Violation::new(
1696                    clause,
1697                    format!("the store refused a read of its log: {error}"),
1698                )
1699            })
1700    }
1701
1702    /// The store's watermark.
1703    async fn watermark<S: IngestStore>(
1704        store: &S,
1705        clause: &'static str,
1706    ) -> Result<Watermark, Violation> {
1707        store.watermark().await.map_err(|error| {
1708            Violation::new(clause, format!("the store refused its watermark: {error}"))
1709        })
1710    }
1711}
1712
1713/// Hands the complete ingest rule set to `$callback`.
1714///
1715/// This family's single enumeration. `$callback` is the path of a macro that
1716/// accepts a comma-separated list of identifiers, and it is invoked once, with
1717/// every rule in [`ingest_rules`].
1718///
1719/// # Examples
1720///
1721/// ```
1722/// macro_rules! rule_names {
1723///     ($($name:ident),* $(,)?) => { [ $( stringify!($name) ),* ] };
1724/// }
1725///
1726/// let names = happenstance_sync_testkit::for_each_ingest_store_rule!(rule_names);
1727/// assert!(names.contains(&"ingest_preserves_origin_identity"));
1728/// assert!(names.contains(&"an_unheld_own_identity_stops_the_ingest"));
1729/// ```
1730#[macro_export]
1731macro_rules! for_each_ingest_store_rule {
1732    // Raw token trees rather than `$cb:path`, for the reason the event-store
1733    // family's enumeration records: a parsed `path` cannot sit in callee
1734    // position inside an expression.
1735    ($($callback:tt)+) => {
1736        $($callback)+! {
1737            // --- An ingested event keeps its origin's identity (VT-5) -------
1738            ingest_preserves_origin_identity,
1739
1740            // --- An ingested event keeps its origin's recorded time (VT-9) --
1741            ingest_preserves_the_recorded_time,
1742
1743            // --- An ingested event lands at the tail (SY-5) -----------------
1744            ingested_events_land_above_the_local_head,
1745
1746            // --- Dedupe is by identity, never content (SY-12, SY-11) --------
1747            dedupe_reaches_identity_without_decoding,
1748
1749            // --- An unheld own identity stops the ingest (SY-38) ------------
1750            an_unheld_own_identity_stops_the_ingest,
1751
1752            // --- A group lands whole under a fault (SY-30) ------------------
1753            ingest_group_is_atomic_under_a_mid_group_fault,
1754
1755            // --- Every event is held to the declared ceilings (SY-18) -------
1756            ingest_validates_every_event_not_the_head,
1757
1758            // --- A call is held to its tags-per-batch ceiling (VT-36, SY-18) -
1759            ingest_holds_the_call_to_its_tags_per_batch_ceiling,
1760
1761            // --- Only the assigned adjudicator compensates (SY-7) ------------
1762            only_the_adjudicator_compensates,
1763
1764            // --- Each direction of an edge keeps its own merge rule (SY-10) -
1765            directional_merge_rules_compose,
1766
1767            // --- A pulled batch at VT-24's floor lands in one call (SY-14) --
1768            bulk_ingest_is_idempotent_in_bounded_round_trips,
1769        }
1770    };
1771}
1772
1773/// Emits one `#[tokio::test]` per ingest rule.
1774///
1775/// The caller's crate needs `tokio` with `macros` and `rt` in its
1776/// `dev-dependencies`. The default emitter of
1777/// [`ingest_store_conformance!`](crate::ingest_store_conformance).
1778#[macro_export]
1779macro_rules! emit_ingest_tokio {
1780    ($($name:ident),* $(,)?) => {
1781        $(
1782            #[tokio::test]
1783            async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1784                $crate::__private::ingest_rules::$name(__ingest_fixture)
1785                    .await?
1786                    .report(::core::stringify!($name));
1787                Ok(())
1788            }
1789        )*
1790    };
1791}
1792
1793/// Emits one plain `#[test]` per ingest rule, driven by
1794/// [`happenstance_testkit::block_on`].
1795///
1796/// No runtime and no `Send` bound, so this is the harness a `!Send` store runs
1797/// under.
1798#[macro_export]
1799macro_rules! emit_ingest_blocking {
1800    ($($name:ident),* $(,)?) => {
1801        $(
1802            #[test]
1803            fn $name() -> ::core::result::Result<(), $crate::Violation> {
1804                $crate::__private::block_on(
1805                    $crate::__private::ingest_rules::$name(__ingest_fixture),
1806                )?
1807                .report(::core::stringify!($name));
1808                Ok(())
1809            }
1810        )*
1811    };
1812}
1813
1814/// Emits one `#[wasm_bindgen_test]` per ingest rule.
1815///
1816/// The caller's crate needs `wasm-bindgen-test` in its `dev-dependencies`,
1817/// gated on `cfg(target_arch = "wasm32")`. A skip is logged through
1818/// `console_log!` rather than reported on stdout, which writes nowhere on that
1819/// target: [`emit_sync_wasm!`](crate::emit_sync_wasm)'s twin. This is the
1820/// harness the Durable Object's ingest store runs the family under.
1821#[macro_export]
1822macro_rules! emit_ingest_wasm {
1823    ($($name:ident),* $(,)?) => {
1824        $(
1825            #[::wasm_bindgen_test::wasm_bindgen_test]
1826            async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1827                let __outcome =
1828                    $crate::__private::ingest_rules::$name(__ingest_fixture).await?;
1829                if let Some(__line) = __outcome.skip_line(::core::stringify!($name)) {
1830                    ::wasm_bindgen_test::console_log!("{}", __line);
1831                }
1832                Ok(())
1833            }
1834        )*
1835    };
1836}
1837
1838/// Expands to a `[&str; N]` of the rule names, for the orphan meta-test.
1839///
1840/// Not an emitter and not promised; exported only because `macro_rules!` has no
1841/// other way to reach another crate's tests.
1842#[doc(hidden)]
1843#[macro_export]
1844macro_rules! __ingest_rule_names {
1845    ($($name:ident),* $(,)?) => { [ $( ::core::stringify!($name) ),* ] };
1846}
1847
1848/// Every `pub async fn` declared at the top level of this file's
1849/// `ingest_rules` module: the same four-space prefix `cargo xtask spec-trace`
1850/// reads.
1851#[cfg(test)]
1852fn declared_rules() -> Vec<&'static str> {
1853    const SOURCE: &str = include_str!("ingest_suite.rs");
1854    const PREFIX: &str = "    pub async fn ";
1855
1856    SOURCE
1857        .lines()
1858        .filter_map(|line| line.strip_prefix(PREFIX))
1859        .filter_map(|rest| {
1860            rest.split(|c: char| !c.is_alphanumeric() && c != '_')
1861                .next()
1862        })
1863        .collect()
1864}
1865
1866/// No rule exists without appearing in the enumeration, and none is
1867/// enumerated without existing: `no_orphan_sync_rules`, one family over.
1868#[cfg(test)]
1869#[test]
1870fn no_orphan_ingest_rules() {
1871    let registered = crate::for_each_ingest_store_rule!(crate::__ingest_rule_names);
1872    let declared = declared_rules();
1873
1874    assert!(
1875        !declared.is_empty(),
1876        "the source scan matched no rule at all"
1877    );
1878    let orphans: Vec<_> = declared
1879        .iter()
1880        .filter(|name| !registered.contains(*name))
1881        .collect();
1882    assert!(
1883        orphans.is_empty(),
1884        "these rules are absent from `for_each_ingest_store_rule!`, so no harness runs them: \
1885         {orphans:?}"
1886    );
1887    let missing: Vec<_> = registered
1888        .iter()
1889        .filter(|name| !declared.contains(*name))
1890        .collect();
1891    assert!(
1892        missing.is_empty(),
1893        "these rules are registered but not declared in `ingest_suite.rs`: {missing:?}"
1894    );
1895}
1896
1897#[cfg(test)]
1898mod tests {
1899    use core::future::Future;
1900
1901    use happenstance_testkit::{RuleOutcome, block_on};
1902
1903    use super::{
1904        MAX_PROVOKED_TAGS, MAX_PROVOKED_TAGS_PER_BATCH, NO_PER_EVENT_LIMITS,
1905        NO_PER_EVENT_LIMITS_REASON, NO_TAGS_PER_BATCH_LIMIT, NO_TAGS_PER_BATCH_LIMIT_REASON,
1906        ingest_rules,
1907    };
1908    use crate::{IngestFixture, MemoryIngestFixture, MemoryIngestHandle};
1909
1910    /// The oracle, declaring a tag ceiling at the rule's cap and nothing else.
1911    struct TagsAtTheCap(MemoryIngestFixture);
1912
1913    impl IngestFixture for TagsAtTheCap {
1914        type Store = MemoryIngestHandle;
1915        const MAX_TAGS_PER_EVENT: Option<usize> = Some(MAX_PROVOKED_TAGS);
1916
1917        fn connect(&self) -> impl Future<Output = Self::Store> {
1918            self.0.connect()
1919        }
1920    }
1921
1922    /// A ceiling the rule would have to allocate past its cap to exceed is
1923    /// not exercised (H-13), and a fixture with nothing else declared is a
1924    /// skip, not a pass. The oracle enforces no ceiling, so an exercised one
1925    /// would fail here.
1926    #[test]
1927    fn a_ceiling_at_the_cap_is_not_exercised() {
1928        let outcome = block_on(ingest_rules::ingest_validates_every_event_not_the_head(
1929            async || TagsAtTheCap(MemoryIngestFixture::new()),
1930        ));
1931
1932        assert_eq!(
1933            outcome.map_err(|violation| violation.clause()),
1934            Ok(RuleOutcome::Skipped {
1935                capability: NO_PER_EVENT_LIMITS,
1936                reason: NO_PER_EVENT_LIMITS_REASON,
1937            })
1938        );
1939    }
1940
1941    /// The tags-per-batch skip, as the rule reports it.
1942    const BATCH_SKIP: RuleOutcome = RuleOutcome::Skipped {
1943        capability: NO_TAGS_PER_BATCH_LIMIT,
1944        reason: NO_TAGS_PER_BATCH_LIMIT_REASON,
1945    };
1946
1947    /// A fixture that declares no tags-per-batch ceiling is a skip, not a
1948    /// pass: the oracle enforces none, so a rule that ran would fail here.
1949    #[test]
1950    fn a_fixture_declaring_no_tags_per_batch_ceiling_is_a_skip() {
1951        let outcome = block_on(
1952            ingest_rules::ingest_holds_the_call_to_its_tags_per_batch_ceiling(async || {
1953                MemoryIngestFixture::new()
1954            }),
1955        );
1956
1957        assert_eq!(
1958            outcome.map_err(|violation| violation.clause()),
1959            Ok(BATCH_SKIP)
1960        );
1961    }
1962
1963    /// The oracle, declaring a tags-per-batch ceiling at the rule's cap and
1964    /// nothing else.
1965    struct BatchAtTheCap(MemoryIngestFixture);
1966
1967    impl IngestFixture for BatchAtTheCap {
1968        type Store = MemoryIngestHandle;
1969        const MAX_TAGS_PER_BATCH: Option<usize> = Some(MAX_PROVOKED_TAGS_PER_BATCH);
1970
1971        fn connect(&self) -> impl Future<Output = Self::Store> {
1972            self.0.connect()
1973        }
1974    }
1975
1976    /// A tags-per-batch ceiling the rule would have to allocate past its cap
1977    /// to exceed is not exercised (H-13), and is reported as a skip.
1978    #[test]
1979    fn a_tags_per_batch_ceiling_at_the_cap_is_not_exercised() {
1980        let outcome = block_on(
1981            ingest_rules::ingest_holds_the_call_to_its_tags_per_batch_ceiling(async || {
1982                BatchAtTheCap(MemoryIngestFixture::new())
1983            }),
1984        );
1985
1986        assert_eq!(
1987            outcome.map_err(|violation| violation.clause()),
1988            Ok(BATCH_SKIP)
1989        );
1990    }
1991
1992    /// The oracle, declaring a tags-per-batch ceiling of `BATCH` and a
1993    /// per-event one of 8.
1994    struct Incoherent<const BATCH: usize>(MemoryIngestFixture);
1995
1996    impl<const BATCH: usize> IngestFixture for Incoherent<BATCH> {
1997        type Store = MemoryIngestHandle;
1998        const MAX_TAGS_PER_EVENT: Option<usize> = Some(8);
1999        const MAX_TAGS_PER_BATCH: Option<usize> = Some(BATCH);
2000
2001        fn connect(&self) -> impl Future<Output = Self::Store> {
2002            self.0.connect()
2003        }
2004    }
2005
2006    /// A ceiling below the fixture's own per-event one is a violation before
2007    /// anything is written: a split never reaches a batch that lands.
2008    #[test]
2009    fn a_ceiling_below_the_per_event_one_is_a_violation() {
2010        let outcome = block_on(
2011            ingest_rules::ingest_holds_the_call_to_its_tags_per_batch_ceiling(async || {
2012                Incoherent::<4>(MemoryIngestFixture::new())
2013            }),
2014        );
2015
2016        let violation = outcome.expect_err("a ceiling of 4 under 8 per event is incoherent");
2017        assert_eq!(violation.clause(), "VT-36");
2018        assert!(
2019            violation.message().contains("below its own ceiling of 8"),
2020            "{violation}"
2021        );
2022    }
2023
2024    /// `usize::MAX` has no total past it, and is held to its declaration
2025    /// although it is far past the cap.
2026    #[test]
2027    fn a_ceiling_of_usize_max_is_a_violation() {
2028        let outcome = block_on(
2029            ingest_rules::ingest_holds_the_call_to_its_tags_per_batch_ceiling(async || {
2030                Incoherent::<{ usize::MAX }>(MemoryIngestFixture::new())
2031            }),
2032        );
2033
2034        let violation = outcome.expect_err("usize::MAX is not a ceiling");
2035        assert_eq!(violation.clause(), "VT-36");
2036        assert!(violation.message().contains("usize::MAX"), "{violation}");
2037    }
2038}