Skip to main content

happenstance_sync_testkit/
sync_suite.rs

1//! The sync rules, their one enumeration, and the three emitters.
2//!
3//! Private: what a caller reaches is [`rules`], re-exported at the crate root,
4//! and the macros, which `#[macro_export]` puts there regardless.
5
6/// The `capability` SY-37's rule reports when the peer never showed it a
7/// second page: the two declared limits that decide how much one pull carries.
8///
9/// Not a fixture constant, which is why it is spelled with its path: the
10/// limits are the peer's own declaration, and they are what an adapter author
11/// changes (or a fixture narrows) to let the rule see a page boundary.
12pub const NO_SECOND_PAGE: &str = "PeerLimits::max_batch_events, PeerLimits::max_batch_bytes";
13
14/// The reason SY-37's rule reports when the peer never showed it a second page.
15///
16/// Written by this crate rather than by the fixture, as
17/// `happenstance_testkit::NO_CEILING_REASON` is, because it is the same
18/// sentence for every peer that earns it. What the skip leaves unverified is
19/// the whole of SY-37: the rule cannot fail a peer whose every answer fits in
20/// one pull.
21///
22/// A peer that refused one of the rule's logs earns [`LOG_REFUSED`] instead,
23/// because the fix is the opposite one: not narrower limits, but a push that
24/// honours the limits already declared.
25pub const NO_SECOND_PAGE_REASON: &str = "this peer showed no page boundary: one pull carried everything the rule \
26     wrote, so a `Nothing` answered at a boundary could not be checked; narrow \
27     the declared batch limits to let the rule see a page. SY-37 is unverified \
28     for this peer";
29
30/// The `capability` SY-37's rule reports when the peer showed no page boundary
31/// and refused a push of one of its logs that its own declaration admits.
32///
33/// Distinct from [`NO_SECOND_PAGE`] because the two need opposite fixes: that
34/// one asks for smaller limits, this one for a peer that takes what its limits
35/// already say it takes. Which log was refused is in the reason:
36/// [`COUNT_LOG_REFUSED_REASON`] or [`BYTE_LOG_REFUSED_REASON`].
37pub const LOG_REFUSED: &str = "SyncPeer::push, within the peer's own PeerLimits";
38
39/// The reason SY-37's rule reports when the peer refused its count-cut log.
40///
41/// That log pushes at most [`PeerLimits::max_batch_events`] events of at most
42/// three payload bytes to a push, so a refusal is the peer stating batch
43/// limits it does not impose. **SY-18's batch rule judges that:**
44/// [`peer_takes_a_batch_at_its_declared_limits`] pushes `max_batch_events`
45/// events at once, at least as many as any push of this log carries, since
46/// [`MAX_PROVOKED_BATCH_EVENTS`] is above the log's 257, and fails a peer that
47/// refuses them. This skip names the refusal for SY-37's own sake, and only
48/// when the byte-cut log did not page: a byte-cut log that paged makes the
49/// rule [`RuleOutcome::Ran`]. When both logs are refused this is the reason
50/// given, because a refused byte-cut log fails `peer_declares_its_own_limits`
51/// as well.
52///
53/// [`RuleOutcome::Ran`]: happenstance_testkit::RuleOutcome::Ran
54/// [`peer_takes_a_batch_at_its_declared_limits`]: rules::peer_takes_a_batch_at_its_declared_limits
55/// [`MAX_PROVOKED_BATCH_EVENTS`]: crate::MAX_PROVOKED_BATCH_EVENTS
56///
57/// [`PeerLimits::max_batch_events`]: happenstance_sync::PeerLimits::max_batch_events
58pub const COUNT_LOG_REFUSED_REASON: &str = "this peer refused a push of the count-cut log, whose pushes carry at \
59     most `max_batch_events` events of at most three bytes each: its declared \
60     batch limits are not the limits it imposes, which SY-18's \
61     `peer_takes_a_batch_at_its_declared_limits` judges, and the log showed no \
62     page; SY-37 is unverified for this peer";
63
64/// The reason SY-37's rule reports when the peer refused its byte-cut log, and
65/// the count-cut log showed no page.
66///
67/// That log pushes one event to a push, its payload
68/// [`PeerLimits::max_event_bytes`] capped by `max_batch_bytes`: no larger than
69/// the boundary event `peer_declares_its_own_limits` pushes alone. So a
70/// refusal is the peer taking smaller events than it declares, SY-18's
71/// subject, and a peer that refuses it on size fails that rule too. Because
72/// each push holds one event, a peer that overstates only `max_batch_bytes`
73/// takes the log and pages it, which no rule could otherwise judge.
74///
75/// [`PeerLimits::max_event_bytes`]: happenstance_sync::PeerLimits::max_event_bytes
76pub const BYTE_LOG_REFUSED_REASON: &str = "this peer refused a one-event push of the byte-cut log, whose events are \
77     sized from its declared `max_event_bytes`: it takes smaller events than \
78     it declares (SY-18's subject, judged by its rule), and the count-cut log \
79     showed no page; SY-37 is unverified for this peer";
80
81/// The `capability` SY-31's rule reports when the peer's
82/// acknowledgement confirmed none of what the rule pushed.
83///
84/// Not a fixture constant, as [`NO_SECOND_PAGE`] is not: it names the field
85/// whose value left the rule nothing to check.
86pub const NO_CONFIRMATION: &str = "Ack::confirmed";
87
88/// The reason SY-31's rule reports when the peer confirmed none of what it
89/// pushed.
90///
91/// Written by this crate rather than by the fixture, because it is the same
92/// sentence for every peer that earns it. Confirming nothing is safe, since a
93/// spoke re-pushes and a re-delivery is a no-op, but it leaves the rule no
94/// confirmation to hold to the log.
95pub const NO_CONFIRMATION_REASON: &str = "this peer acknowledged the rule's push and confirmed none of the events \
96     in it, so no confirmation could be held to what a fresh handle reads \
97     back; confirming nothing is safe, because a spoke re-pushes and a \
98     re-delivery is a no-op, but SY-31's durability half is unverified for \
99     this peer";
100
101/// The sync rules. See the [crate documentation](crate) for what each covers.
102///
103/// Each rule is an async function taking `impl AsyncFn() -> F` — not a fixture
104/// but how to make one, as in the event-store family — and returning
105/// `Result<RuleOutcome, Violation>`.
106///
107/// # What no rule here does
108///
109/// **Decode a payload** (SY-35). Events are compared whole — identity, recorded
110/// time and the opaque bytes — and never parsed. A suite that parsed `data`
111/// would certify a peer that does, and ADR-0003's guarantee is that no peer
112/// needs to.
113///
114/// **Hold two peers** (SY-8). Where a clause speaks of two peers, the rule plays
115/// one of them itself: it is the side that pushes and pulls, and the fixture's
116/// peer is the far side.
117pub mod rules {
118    use alloc::collections::BTreeMap;
119    use alloc::format;
120    use alloc::string::String;
121    use alloc::vec;
122    use alloc::vec::Vec;
123
124    use happenstance_core::{
125        AppendCondition, Event, EventId, EventType, MAX_EVENT_TYPE_LEN, MAX_TAG_LEN,
126        MIN_SUPPORTED_EVENT_DATA_LEN, MIN_SUPPORTED_TAGS_PER_EVENT, Query, QueryItem, RecordedAt,
127        SequencePosition, StoreId, Tag, Tags,
128    };
129    use happenstance_sync::{
130        Ack, Classify, EventGroup, PeerLimits, PushBatch, ReplicatedEvent, SyncPeer, Waiting,
131    };
132    use happenstance_testkit::{Reopened, RuleOutcome};
133
134    use crate::kv_capped::turnstile_seat_map;
135    use crate::violation::{Violation, ensure};
136    use crate::{MAX_PROVOKED_BATCH_BYTES, MAX_PROVOKED_BATCH_EVENTS, SyncFixture};
137
138    mod retention;
139    mod whole_log;
140
141    /// The most pulls a rule makes before it decides the peer will never say
142    /// it has caught up. Far above what two or three tiny groups need under the
143    /// minimum conformant limits; its job is to turn a peer that loops into a
144    /// failure rather than a hang (H-13).
145    const MAX_PULLS: usize = 64;
146
147    /// The most groups past one that SY-37's rule writes to a peer in one log,
148    /// whatever limits the peer declares (H-13). Twice the minimum conformant
149    /// `max_batch_events`, so the reference peer pages more than once.
150    const FILL_CAP: usize = 256;
151
152    const SEAT_CLAIMED: EventType = EventType::from_static("SeatClaimed");
153    const CLAIM_REVERSED: EventType = EventType::from_static("ClaimReversed");
154    const READING_TAKEN: EventType = EventType::from_static("ReadingTaken");
155
156    /// Two origins and an adjudicating hub, as raw store identities.
157    const ORIGIN_A: StoreId = StoreId::from_bytes([0x11; 16]);
158    const ORIGIN_B: StoreId = StoreId::from_bytes([0x22; 16]);
159    const HUB: StoreId = StoreId::from_bytes([0x33; 16]);
160
161    /// SY-18's three origins: the one that committed the seat map, and the two
162    /// whose events sit at the declared boundary, in data and in metadata.
163    const SEAT_MAP_ORIGIN: StoreId = StoreId::from_bytes([0x44; 16]);
164    const BOUNDARY_ORIGIN: StoreId = StoreId::from_bytes([0x55; 16]);
165    const METADATA_ORIGIN: StoreId = StoreId::from_bytes([0x66; 16]);
166
167    /// SY-31's two origins, whose events the rule pushes in one batch.
168    const DURABLE_ORIGIN: StoreId = StoreId::from_bytes([0x81; 16]);
169    const DURABLE_TWIN: StoreId = StoreId::from_bytes([0x82; 16]);
170
171    /// SY-23's three origins, in `EventId` order: the derive sorts a
172    /// [`StoreId`] by its bytes.
173    const ORDER_LOW: StoreId = StoreId::from_bytes([0xA1; 16]);
174    const ORDER_MID: StoreId = StoreId::from_bytes([0xA2; 16]);
175    const ORDER_HIGH: StoreId = StoreId::from_bytes([0xA3; 16]);
176
177    /// The type of every event SY-18's batch rule pushes.
178    const BATCH_FILLED: EventType = EventType::from_static("BatchFilled");
179
180    /// SY-18's batch rule's two origins: the push at the declared event count
181    /// with empty payloads, and the push at that count and the declared bytes.
182    const COUNT_CORNER_ORIGIN: StoreId = StoreId::from_bytes([0x91; 16]);
183    const BYTE_CORNER_ORIGIN: StoreId = StoreId::from_bytes([0x92; 16]);
184
185    /// SY-30's origin, whose three groups the envelope rule pushes in one batch.
186    const GROUPS_ORIGIN: StoreId = StoreId::from_bytes([0x93; 16]);
187    /// The type of every event SY-30's rule pushes.
188    const GROUP_WRITTEN: EventType = EventType::from_static("GroupWritten");
189    /// The types SY-30's two guards name. Nothing the suite writes carries
190    /// either, so a peer that evaluated the guards would find nothing to refuse
191    /// and only SY-1's rule judges that mistake.
192    const GUARDED_FIRST: EventType = EventType::from_static("GroupGuardedFirst");
193    const GUARDED_LAST: EventType = EventType::from_static("GroupGuardedLast");
194
195    /// SY-1: a peer appends every replicated event it does not already hold,
196    /// and never evaluates an append condition — the origin's or its own — as a
197    /// precondition.
198    ///
199    /// Two origins each claim the same seat under **byte-identical,
200    /// position-free** guards: each decision was valid where it was made, and
201    /// together they conflict. The rule pushes both, as the two origins would,
202    /// and then pulls the peer's whole log. Both claims must be there.
203    ///
204    /// # Rejects
205    ///
206    /// A peer that evaluates the travelling guard against what it holds and
207    /// refuses — or silently drops — the second claim. It is the natural first
208    /// cut, because the guard arrives on the wire already, and it produces a
209    /// peer set that never converges. `tests/wrong_peers.rs` carries both
210    /// spellings: one that acknowledges the dropped claim as nothing appended,
211    /// which the ack check catches, and one that acknowledges it as appended
212    /// and drops it anyway, which only the pull of the whole log can see.
213    ///
214    /// # Errors
215    ///
216    /// A [`Violation`] of SY-1 if the peer refuses either push, reports either
217    /// claim as anything but newly appended, or does not hand both back.
218    pub async fn ingest_never_rejects<F: SyncFixture>(
219        open: impl AsyncFn() -> F,
220    ) -> Result<RuleOutcome, Violation> {
221        const CLAUSE: &str = "SY-1";
222        let fixture = open().await;
223        let peer = fixture.connect().await;
224        let guard = seat_guard(CLAUSE)?;
225
226        let mine = claim(ORIGIN_A, CLAUSE)?;
227        let theirs = claim(ORIGIN_B, CLAUSE)?;
228        for event in [&mine, &theirs] {
229            let batch = PushBatch::new(vec![EventGroup::new(
230                Some(guard.clone()),
231                vec![event.clone()],
232            )]);
233            let ack = peer.push(&batch).await.map_err(|error| {
234                Violation::new(
235                    CLAUSE,
236                    format!(
237                        "the peer refused a replicated claim from {}: {error}",
238                        event.id
239                    ),
240                )
241            })?;
242            ensure(ack.appended == 1 && ack.skipped == 0, CLAUSE, || {
243                format!(
244                    "the peer acknowledged the claim from {} as {} appended and {} skipped; \
245                     it held nothing with that identity, so it must append it",
246                    event.id, ack.appended, ack.skipped
247                )
248            })?;
249        }
250
251        let held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
252            .await?
253            .into_iter()
254            .flat_map(|group| group.events)
255            .collect();
256        for expected in [&mine, &theirs] {
257            ensure(held.contains(expected), CLAUSE, || {
258                format!(
259                    "the claim from {} is not in the peer's log, byte for byte; a conflicting \
260                     claim already there is not a reason to drop it",
261                    expected.id
262                )
263            })?;
264        }
265        Ok(RuleOutcome::Ran)
266    }
267
268    /// SY-2, the transport's half: a losing event and the compensation that
269    /// answers it travel as one group, and a peer hands them back as one group.
270    ///
271    /// A hub has adjudicated a conflict: one claim won, and the other is sent on
272    /// together with the reversal the hub wrote for it, in one
273    /// [`EventGroup`]. Whoever pulls that from this peer ingests a group at a
274    /// time, atomically (`IngestStore::ingest`), so a peer that splits the group
275    /// hands its reader a log where the losing claim stands with nothing
276    /// resolving it. The store-side half — one ingest commits the group whole —
277    /// rides on ES-18 and on the ingest suite.
278    ///
279    /// # Rejects
280    ///
281    /// A peer that flattens what it is pushed into one group per event, or
282    /// that pages by event count and ends a pull between the two.
283    /// `tests/wrong_peers.rs` carries both.
284    ///
285    /// # Does not reject
286    ///
287    /// **Compensate-after-commit**, the defect SY-2's own `Rejects` paragraph
288    /// names: ingest the losing event, return, and author the compensation
289    /// afterwards. That is the authoring side's mistake, made before anything
290    /// reaches a peer, and a rule that holds only a peer cannot see it — this
291    /// rule hands the peer a group that is already whole. The authoring half is
292    /// tracked by #320; until it lands, a green run here certifies the
293    /// transport and nothing upstream of it.
294    ///
295    /// # Errors
296    ///
297    /// A [`Violation`] of SY-2 if the peer refuses the pushes, or if the group
298    /// it hands back with the losing claim does not also hold its reversal.
299    pub async fn compensation_is_atomic_with_the_losing_event<F: SyncFixture>(
300        open: impl AsyncFn() -> F,
301    ) -> Result<RuleOutcome, Violation> {
302        const CLAUSE: &str = "SY-2";
303        let fixture = open().await;
304        let peer = fixture.connect().await;
305
306        let winner = claim(ORIGIN_A, CLAUSE)?;
307        let losing = claim(ORIGIN_B, CLAUSE)?;
308        let reversal = replicated(HUB, CLAIM_REVERSED, CLAUSE)?;
309        let batch = PushBatch::new(vec![
310            EventGroup::new(None, vec![winner]),
311            EventGroup::new(None, vec![losing.clone(), reversal.clone()]),
312        ]);
313        peer.push(&batch).await.map_err(|error| {
314            Violation::new(
315                CLAUSE,
316                format!("the peer refused a batch well inside the minimum limits: {error}"),
317            )
318        })?;
319
320        let groups = pull_everything(&peer, CLAUSE).await?;
321        let Some(carrying) = groups.iter().find(|group| group.events.contains(&losing)) else {
322            return Err(Violation::new(
323                CLAUSE,
324                format!("the losing claim {} never came back", losing.id),
325            ));
326        };
327        ensure(carrying.events.contains(&reversal), CLAUSE, || {
328            format!(
329                "the losing claim {} came back in a group without its reversal {}; a reader \
330                 ingesting that group commits the claim with nothing resolving it",
331                losing.id, reversal.id
332            )
333        })?;
334        Ok(RuleOutcome::Ran)
335    }
336
337    /// SY-18: a peer declares the limits it imposes, synchronously, and the
338    /// declaration is true: an event it admits lands, so a runner that read it
339    /// learns of an event that cannot land *before* pushing, not at ingest.
340    ///
341    /// The rule plays that runner. It reads [`SyncPeer::limits`] before it
342    /// pushes anything, and then:
343    ///
344    /// 1. reads it again, because a declaration that changes between two reads
345    ///    cannot be relied on before a push;
346    /// 2. holds `max_event_bytes` to VT-21's floor,
347    ///    [`MIN_SUPPORTED_EVENT_DATA_LEN`]. Every peer the suite is mounted on
348    ///    passes this line, which is where the floor is compared across the
349    ///    peer set;
350    /// 3. runs the Turnstile experiment: a 340,000-byte seat map, already
351    ///    committed at its origin. If the declaration admits it, it is pushed
352    ///    and must land. If not, the runner parks it without a round trip,
353    ///    which is the prevention, and nothing is pushed;
354    /// 4. pushes two events at the declaration's own boundary and at the
355    ///    contract's envelope floors at once: `max_event_bytes` of opaque bytes
356    ///    (capped by `max_batch_bytes`), carried once in data and once in
357    ///    metadata, because the declaration bounds the two together; a type of
358    ///    [`MAX_EVENT_TYPE_LEN`] bytes; and [`MIN_SUPPORTED_TAGS_PER_EVENT`]
359    ///    tags of [`MAX_TAG_LEN`] bytes each. The declaration must admit each,
360    ///    and each must land, acknowledged as appended. A limit on the envelope
361    ///    or on metadata that the peer imposes without declaring it is a limit
362    ///    discovered at ingest;
363    /// 5. pulls the whole log back: every event that landed is held, byte for
364    ///    byte, which rejects a peer that accepts and truncates.
365    ///
366    /// The asynchronous form of the declaration, which SY-18 also rejects,
367    /// cannot be written: `limits` is not `async` on the port, so the compiler
368    /// is that check and no mutant is needed for it.
369    ///
370    /// A peer that declares more than [`MAX_PROVOKED_BATCH_BYTES`] has its
371    /// boundary tested at that ceiling rather than at its declaration, because
372    /// the event is allocated whole (H-13). The rule still runs.
373    ///
374    /// # Rejects
375    ///
376    /// `tests/wrong_limits.rs` carries eight mistakes over the KV-capped
377    /// reference peer, one for each check above:
378    ///
379    /// * declarations rewritten over unchanged behaviour: no value cap, which
380    ///   admits the seat map that ingest then parks; the raw 131,072-byte value
381    ///   cap, as if a value held the payload alone, which admits a boundary
382    ///   event ingest refuses; a byte below VT-21's floor; a declaration that
383    ///   changes between two reads; and `max_batch_events` of zero, which
384    ///   admits no event at all;
385    /// * behaviour changed under an honest declaration: a cap of 1,024 bytes on
386    ///   metadata, Workers KV's, that the declaration does not state; data
387    ///   truncated on a large push and acknowledged as appended; and a large
388    ///   event stored whole and acknowledged as skipped.
389    ///
390    /// # Does not reject
391    ///
392    /// A runner that ignores `limits()`. That is the runner's defect, and #244
393    /// owns it; a peer can only make its declaration true. Nor limits that go
394    /// stale between the read and the push: [`PeerLimits::admits`] is advisory,
395    /// and what keeps that survivable is the `Park` and `Split` classes SY-36
396    /// checks.
397    ///
398    /// Nor a lie about `max_batch_bytes` or `max_batch_events` alone. This rule
399    /// holds the limits a peer imposes on *an event*, and reads the batch
400    /// limits only to size the boundary event. A batch at them that is refused
401    /// is [`peer_takes_a_batch_at_its_declared_limits`]'s to judge, and a
402    /// batch over them is SY-36's `Split`, not a fact that can never land.
403    ///
404    /// [`PeerLimits::admits`]: happenstance_sync::PeerLimits::admits
405    ///
406    /// # Errors
407    ///
408    /// A [`Violation`] of SY-18 if the declaration changes between two reads,
409    /// declares below VT-21's floor, or admits no event at its own boundary;
410    /// or if an event the declaration admits is refused, acknowledged as
411    /// anything but one appended, or not handed back whole. The floor breach
412    /// cites VT-21 in its message.
413    pub async fn peer_declares_its_own_limits<F: SyncFixture>(
414        open: impl AsyncFn() -> F,
415    ) -> Result<RuleOutcome, Violation> {
416        const CLAUSE: &str = "SY-18";
417        let fixture = open().await;
418        let peer = fixture.connect().await;
419
420        let limits = peer.limits();
421        let again = peer.limits();
422        ensure(again == limits, CLAUSE, || {
423            format!(
424                "the peer declared {limits:?} and then {again:?}; a declaration that changes \
425                 between two reads cannot be relied on before a push"
426            )
427        })?;
428        ensure(
429            limits.max_event_bytes >= MIN_SUPPORTED_EVENT_DATA_LEN,
430            CLAUSE,
431            || {
432                format!(
433                    "the peer declares max_event_bytes of {}, below VT-21's floor of \
434                     {MIN_SUPPORTED_EVENT_DATA_LEN}",
435                    limits.max_event_bytes
436                )
437            },
438        )?;
439
440        let mut landed = Vec::new();
441        let seat_map = one_event(turnstile_seat_map(SEAT_MAP_ORIGIN, CLAUSE)?);
442        if limits.admits(&seat_map) {
443            push_admitted(&peer, &seat_map, "the 340,000-byte seat map", CLAUSE).await?;
444            landed.push(seat_map);
445        }
446
447        let size = limits
448            .max_event_bytes
449            .min(limits.max_batch_bytes)
450            .min(MAX_PROVOKED_BATCH_BYTES);
451        for carrier in [Carrier::Data, Carrier::Metadata] {
452            let boundary = one_event(event_at_the_envelope_floors(size, carrier, CLAUSE)?);
453            ensure(limits.admits(&boundary), CLAUSE, || {
454                format!(
455                    "the declaration {limits:?} admits no event of {size} bytes in its \
456                     {carrier:?}, the size it states it accepts"
457                )
458            })?;
459            push_admitted(&peer, &boundary, carrier.describe(), CLAUSE).await?;
460            landed.push(boundary);
461        }
462
463        let held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
464            .await?
465            .into_iter()
466            .flat_map(|group| group.events)
467            .collect();
468        for expected in landed.iter().flat_map(PushBatch::events) {
469            ensure(held.contains(expected), CLAUSE, || {
470                format!(
471                    "event {} of {} bytes was acknowledged and is not in the peer's log, \
472                     byte for byte",
473                    expected.id,
474                    expected.payload_len()
475                )
476            })?;
477        }
478        Ok(RuleOutcome::Ran)
479    }
480
481    /// SY-36: every error a peer reports states its failure class, and the
482    /// class is the one its adapter says it is.
483    ///
484    /// The fixture drives a fresh handle into every refusal it can produce and
485    /// declares each one's class ([`SyncFixture::refusals`]); the rule checks
486    /// that each provocation was refused, and that the error's
487    /// [`Classify::class`] answers what was declared. The class is read twice
488    /// from the same value, because SY-36 makes it a function of the error
489    /// alone.
490    ///
491    /// # Rejects
492    ///
493    /// A peer that reports every failure as one class — the opaque error
494    /// ADR-0026 rejected, with a trait impl bolted on so it compiles.
495    /// `tests/wrong_peers.rs` carries it, as `Transient` for everything, which
496    /// retries a batch that can only ever be split.
497    ///
498    /// The rule's other three refusals each have a mutant there too: a fixture
499    /// that declares no refusal, a peer that accepts the push its fixture says
500    /// it refuses, and an error whose class changes between two reads.
501    ///
502    /// # Errors
503    ///
504    /// A [`Violation`] of SY-36 if the fixture declares no refusal, if a
505    /// provocation succeeds, or if a refusal's class is not the declared one or
506    /// changes between two reads.
507    pub async fn every_refusal_states_its_class<F: SyncFixture>(
508        open: impl AsyncFn() -> F,
509    ) -> Result<RuleOutcome, Violation> {
510        const CLAUSE: &str = "SY-36";
511        let fixture = open().await;
512        let peer = fixture.connect().await;
513
514        let refusals = fixture.refusals(&peer).await?;
515        ensure(!refusals.is_empty(), CLAUSE, || {
516            String::from(
517                "the fixture declared no refusal; every peer can be refused something, and a \
518                 rule checked against nothing has checked nothing",
519            )
520        })?;
521        for refusal in refusals {
522            let Err(error) = refusal.outcome else {
523                return Err(Violation::new(
524                    CLAUSE,
525                    format!(
526                        "the peer accepted {}, which its fixture says it refuses",
527                        refusal.provoked_by
528                    ),
529                ));
530            };
531            let (first, second) = (error.class(), error.class());
532            ensure(first == second, CLAUSE, || {
533                format!(
534                    "the refusal of {} answered {first:?} and then {second:?}; the class must \
535                     be a function of the error alone",
536                    refusal.provoked_by
537                )
538            })?;
539            ensure(first == refusal.declared, CLAUSE, || {
540                format!(
541                    "the refusal of {} ({error}) states {first:?}, and its fixture declares \
542                     {:?}",
543                    refusal.provoked_by, refusal.declared
544                )
545            })?;
546        }
547        Ok(RuleOutcome::Ran)
548    }
549
550    /// SY-37: a peer that answers a pull with [`Waiting::Nothing`] hands back
551    /// an empty batch on the next pull from the token that answer carried.
552    ///
553    /// The rule writes two logs, each to a fresh peer from `open`:
554    ///
555    /// 1. **Cut by count**: 257 single-event groups of a few bytes, pushed at
556    ///    most [`PeerLimits::max_batch_events`] to a push, so a peer that pages
557    ///    at any event count up to 256 shows a page boundary.
558    /// 2. **Cut by bytes**: single-event groups whose payloads are sized from
559    ///    the declared limits so [`PeerLimits::max_batch_bytes`] ends a page
560    ///    before the event count does, one group past that page, pushed one
561    ///    event to a push so the pull alone draws the boundary. Written only
562    ///    where the bytes do cut first, and the log fits in 257 groups and
563    ///    64 MiB.
564    ///
565    /// On each it follows the peer's tokens from the start, and on the first
566    /// `Nothing` pulls once more from that token. That pull must be empty. A
567    /// peer that never says `Nothing` passes: it costs its runner the empty
568    /// pull, and never a missed event.
569    ///
570    /// A log the peer refuses to take is not built, and shows no page. Whose
571    /// failure the refusal is depends on the log. The byte-cut log goes one
572    /// event to a push, each sized from [`PeerLimits::max_event_bytes`] and no
573    /// larger than SY-18's boundary event, so refusing it is SY-18's subject,
574    /// and `peer_declares_its_own_limits` judges it; a peer that overstates
575    /// only `max_batch_bytes` takes it. The count-cut log is tiny events, at
576    /// most `max_batch_events` to a push, so refusing it is a lie about the
577    /// batch limits, which that rule says it does not judge and
578    /// [`peer_takes_a_batch_at_its_declared_limits`] judges.
579    ///
580    /// If neither log showed a second non-empty page, the rule could not have
581    /// failed the peer, and it reports a skip rather than a pass: naming
582    /// [`LOG_REFUSED`] if the peer refused a log, with
583    /// [`COUNT_LOG_REFUSED_REASON`] or [`BYTE_LOG_REFUSED_REASON`] saying which
584    /// (the count-cut one if both), and [`NO_SECOND_PAGE`] if it took every log
585    /// the rule wrote and one pull carried each. The two need opposite fixes: a
586    /// push that honours the declared limits, and narrower limits. One log that
587    /// paged is enough for the rule to have run, so a refusal of the other is
588    /// not reported over it.
589    ///
590    /// The bound on pulls — one more than the log has groups — is the suite's
591    /// liveness guard, not SY-37's claim: a peer that ignores its token and
592    /// keeps handing back groups is reported here, and fails SY-1's and SY-2's
593    /// rules too.
594    ///
595    /// [`NO_SECOND_PAGE`]: crate::NO_SECOND_PAGE
596    /// [`LOG_REFUSED`]: crate::LOG_REFUSED
597    /// [`COUNT_LOG_REFUSED_REASON`]: crate::COUNT_LOG_REFUSED_REASON
598    /// [`BYTE_LOG_REFUSED_REASON`]: crate::BYTE_LOG_REFUSED_REASON
599    ///
600    /// # Rejects
601    ///
602    /// A peer that says `Nothing` because its page ran out rather than its log
603    /// — the natural slip for an adapter that reports "this page is the last
604    /// one I fetched" — so a runner that believes it stops short and the rest
605    /// of the log waits for the next wake. `tests/wrong_peers.rs` carries two:
606    /// a peer that says `Nothing` on every pull, which the count-cut log
607    /// catches, and one that says it whenever a page carried fewer events than
608    /// `max_batch_events`, which only the byte-cut log can catch.
609    ///
610    /// # Does not reject
611    ///
612    /// A wrong [`Waiting::Events`] count: it is advisory, and checking it would
613    /// need a snapshot of the far side the port does not offer. Nor a peer
614    /// that says `Nothing` while stalled behind a group too large for any pull:
615    /// SY-37 forbids it, but a conformant push cannot put such a group on the
616    /// far side, so the rule cannot build the case. Nor a peer whose single
617    /// pull carries all of both logs, which it reports as a skip; the caps
618    /// bound the work against a peer that declares huge limits (H-13), at that
619    /// price.
620    ///
621    /// # Errors
622    ///
623    /// A [`Violation`] of SY-37 if the peer refuses a pull, keeps handing back
624    /// groups past the log the rule wrote, or hands back events on the pull
625    /// after it said nothing was waiting.
626    pub async fn nothing_waiting_means_the_next_pull_is_empty<F: SyncFixture>(
627        open: impl AsyncFn() -> F,
628    ) -> Result<RuleOutcome, Violation> {
629        const CLAUSE: &str = "SY-37";
630
631        let by_count = {
632            let fixture = open().await;
633            let peer = fixture.connect().await;
634            write_log(&peer, Fill::cut_by_count(&peer.limits()), CLAUSE).await?
635        };
636
637        let fixture = open().await;
638        let peer = fixture.connect().await;
639        let by_bytes = match Fill::cut_by_bytes(&peer.limits()) {
640            Some(fill) => write_log(&peer, fill, CLAUSE).await?,
641            // Not written: the count cuts first, or the log would pass a cap.
642            None => Log::NoPage,
643        };
644
645        Ok(match (by_count, by_bytes) {
646            (Log::Paged, _) | (_, Log::Paged) => RuleOutcome::Ran,
647            // The count-cut refusal first: it is the batch-limit lie, which
648            // SY-18's batch rule judges, while its per-event rule reports the
649            // byte-cut one.
650            (Log::Refused, _) => RuleOutcome::Skipped {
651                capability: crate::LOG_REFUSED,
652                reason: crate::COUNT_LOG_REFUSED_REASON,
653            },
654            (Log::NoPage, Log::Refused) => RuleOutcome::Skipped {
655                capability: crate::LOG_REFUSED,
656                reason: crate::BYTE_LOG_REFUSED_REASON,
657            },
658            (Log::NoPage, Log::NoPage) => RuleOutcome::Skipped {
659                capability: crate::NO_SECOND_PAGE,
660                reason: crate::NO_SECOND_PAGE_REASON,
661            },
662        })
663    }
664
665    /// SY-31: an [`Ack`] confirms only what the far side still holds once the
666    /// handle that acknowledged is gone.
667    ///
668    /// SY-31's confirmation watermark is advanced to [`Ack::confirmed`], "what
669    /// the far side has now durably seen", and SY-24's forwarding never offers
670    /// anything at or below it again. So a confirmation sent before the write
671    /// is durable loses that write for good: the spoke's watermark has passed
672    /// it, and nothing re-sends it.
673    ///
674    /// The rule pushes one batch of two groups from two origins, at origin
675    /// positions 3 and 7 and 2, drops the handle that pushed, reopens the
676    /// fixture when it can, connects a fresh handle onto it and pulls
677    /// everything. Then every pushed event at or below the confirmed mark for
678    /// its origin is held, byte for byte, and every confirmed mark names an
679    /// event the fresh handle holds. `confirmed` is read as a high-water mark,
680    /// never as everything up to: no position below a mark that the rule did
681    /// not push is assumed held.
682    ///
683    /// "Not durable" is observed as "gone once the acking handle is dropped",
684    /// and, when the fixture declares [`SyncFixture::REOPEN`], as "gone once
685    /// the fixture is reopened", the process crash CF-17 lets a fixture stage.
686    /// The reopen must answer [`Reopened::Discarded`]; a fixture that declares
687    /// the capability and keeps the provided `reopen` is a violation here. A
688    /// fixture that declines it is run as before, and a peer that buffers in
689    /// memory every handle shares, and would lose it to a crash, passes: that
690    /// is what the declension costs, and its reason is the fixture's to state.
691    ///
692    /// [`Reopened::Discarded`]: happenstance_testkit::Reopened::Discarded
693    ///
694    /// A peer whose ack confirms none of the pushed events has given the rule
695    /// nothing to check, so the rule reports
696    /// [`Skipped`](RuleOutcome::Skipped) with
697    /// [`NO_CONFIRMATION`](crate::NO_CONFIRMATION) rather than a pass.
698    ///
699    /// [`Ack`]: happenstance_sync::Ack
700    /// [`Ack::confirmed`]: happenstance_sync::Ack::confirmed
701    ///
702    /// # Rejects
703    ///
704    /// A write-behind cache that acknowledges a push on admission and commits
705    /// it later, so a handle dropped in between has confirmed what the peer
706    /// never held. `tests/wrong_peers.rs` carries it, and the peer that
707    /// confirms nothing, which this rule must skip. `tests/wrong_reopens.rs`
708    /// carries the same cache in memory every handle shares, which only a
709    /// reopen can show.
710    ///
711    /// # Errors
712    ///
713    /// A [`Violation`] of SY-31 if the peer refuses the push or a pull, if a
714    /// fixture declaring [`SyncFixture::REOPEN`] reopened nothing, if a
715    /// confirmed event is not held by a fresh handle, or if a confirmed mark
716    /// names no event the fresh handle holds.
717    pub async fn ack_never_confirms_a_non_durable_event<F: SyncFixture>(
718        open: impl AsyncFn() -> F,
719    ) -> Result<RuleOutcome, Violation> {
720        const CLAUSE: &str = "SY-31";
721        let fixture = open().await;
722        let first = durable_reading(DURABLE_ORIGIN, 3, b"sy31-p-3", CLAUSE)?;
723        let second = durable_reading(DURABLE_ORIGIN, 7, b"sy31-p-7", CLAUSE)?;
724        let other = durable_reading(DURABLE_TWIN, 2, b"sy31-q-2", CLAUSE)?;
725        let batch = PushBatch::new(vec![
726            EventGroup::new(None, vec![first, second]),
727            EventGroup::new(None, vec![other]),
728        ]);
729
730        let ack = {
731            let peer = fixture.connect().await;
732            peer.push(&batch).await.map_err(|error| {
733                Violation::new(
734                    CLAUSE,
735                    format!("the peer refused a batch well inside the minimum limits: {error}"),
736                )
737            })?
738            // The acking handle is dropped here: what it confirmed must
739            // outlive it.
740        };
741        if F::REOPEN.is_supported() {
742            ensure(
743                fixture.reopen().await == Reopened::Discarded,
744                CLAUSE,
745                || {
746                    String::from(
747                        "the fixture declares REOPEN supported and its reopen answered \
748                         `Nothing`: `SyncFixture::reopen` is not overridden, or its override \
749                         reopened nothing, so the crash this rule stages never happened",
750                    )
751                },
752            )?;
753        }
754
755        let fresh = fixture.connect().await;
756        let held: Vec<ReplicatedEvent> = pull_everything(&fresh, CLAUSE)
757            .await?
758            .into_iter()
759            .flat_map(|group| group.events)
760            .collect();
761        let covered: Vec<&ReplicatedEvent> = batch
762            .events()
763            .filter(|event| {
764                ack.confirmed
765                    .get(event.id.store())
766                    .is_some_and(|confirmed| event.id.position() <= confirmed)
767            })
768            .collect();
769        if covered.is_empty() {
770            return Ok(RuleOutcome::Skipped {
771                capability: crate::NO_CONFIRMATION,
772                reason: crate::NO_CONFIRMATION_REASON,
773            });
774        }
775        for event in covered {
776            ensure(held.contains(event), CLAUSE, || {
777                format!(
778                    "the peer confirmed {} and a fresh handle onto it does not hold it, byte for \
779                     byte; a spoke's watermark passes it, so it is never pushed again",
780                    event.id
781                )
782            })?;
783        }
784        // The high-water reading: each mark names a position the peer holds,
785        // and nothing is inferred about the positions below it.
786        for (origin, position) in ack.confirmed.iter() {
787            let id = EventId::new(origin, position);
788            ensure(held.iter().any(|event| event.id == id), CLAUSE, || {
789                format!(
790                    "the peer confirmed {id} as the highest position it holds from {origin}, \
791                     and a fresh handle onto it holds no event with that identity"
792                )
793            })?;
794        }
795        Ok(RuleOutcome::Ran)
796    }
797
798    /// SY-18: a peer's declared batch limits are the limits it imposes: a push
799    /// at the declared corner, which the declaration admits, lands whole.
800    ///
801    /// [`peer_declares_its_own_limits`] holds the declaration to one event at a
802    /// time. This rule holds its other half, [`PeerLimits::max_batch_events`]
803    /// and [`PeerLimits::max_batch_bytes`], to a push as large as they say. A
804    /// runner that honours them and is refused anyway has been told a limit
805    /// that is not the one imposed, and learns the real one at ingest. The
806    /// rule plays that runner. It reads [`SyncPeer::limits`] once, and then:
807    ///
808    /// 1. takes the corner's event count, `max_batch_events` capped by
809    ///    [`MAX_PROVOKED_BATCH_EVENTS`], and its bytes, `max_batch_bytes`
810    ///    capped by [`MAX_PROVOKED_BATCH_BYTES`] and by what that many events
811    ///    can carry with none over `max_event_bytes`;
812    /// 2. pushes the **count corner**: that many single-event groups with
813    ///    empty payloads. The declaration must admit it, and it must land,
814    ///    every event acknowledged as appended;
815    /// 3. pushes the **full corner**, when it has any bytes: as many
816    ///    single-event groups again, from a second origin, whose payloads
817    ///    total exactly the corner's bytes and differ by at most one byte. The
818    ///    same must hold;
819    /// 4. pulls the whole log back: every event of both pushes is held, byte
820    ///    for byte, which rejects a peer that acknowledges what it dropped.
821    ///
822    /// Two pushes rather than one, so a refusal names the limit that was not
823    /// imposed: the count corner carries no bytes. And the events are as small
824    /// as the corner allows, with no guard, tags or metadata, so a lie about a
825    /// per-event limit, which is [`peer_declares_its_own_limits`]'s to judge,
826    /// cannot fail this rule as well.
827    ///
828    /// [`PeerLimits::max_batch_events`]: happenstance_sync::PeerLimits::max_batch_events
829    /// [`PeerLimits::max_batch_bytes`]: happenstance_sync::PeerLimits::max_batch_bytes
830    /// [`MAX_PROVOKED_BATCH_EVENTS`]: crate::MAX_PROVOKED_BATCH_EVENTS
831    /// [`MAX_PROVOKED_BATCH_BYTES`]: crate::MAX_PROVOKED_BATCH_BYTES
832    ///
833    /// # Rejects
834    ///
835    /// `tests/wrong_peers.rs` carries five, each over the reference peer:
836    /// a peer that takes fewer events to a push than it declares, and one that
837    /// declares twice the `max_batch_bytes` it enforces, which SY-37's rule
838    /// also uses to attribute its skips; two that refuse *at* the declared
839    /// limit, `>=` where the declaration means `>`, one on the event count and
840    /// one on the bytes, which pin each corner to the declaration exactly; and
841    /// a peer that stores only the head of a large push and acknowledges all
842    /// of it, which only the pull-back sees.
843    ///
844    /// # Does not reject
845    ///
846    /// A peer that *accepts* more than it declares: a runner that reads the
847    /// declaration never sends more, so nothing is lost. Nor the refusal of a
848    /// push one byte over the declaration, which is SY-36's `Split` and
849    /// [`every_refusal_states_its_class`]'s to judge. Nor a pull larger than
850    /// the declaration: the batch limits bind a push. Nor a declaration of
851    /// `max_batch_events` of zero, which [`peer_declares_its_own_limits`]
852    /// fails and this rule has no corner to push into, so it pushes nothing
853    /// and runs. Nor a peer whose limits are true up to the caps and false
854    /// above them, because the corner is built at the caps.
855    ///
856    /// # Errors
857    ///
858    /// A [`Violation`] of SY-18 if the declaration does not admit one of the
859    /// corners, if the peer refuses either push or acknowledges it as anything
860    /// but every event appended, or if an event of either is not handed back
861    /// whole; or if the peer refuses a pull or keeps handing back groups past
862    /// one pull per event pushed.
863    pub async fn peer_takes_a_batch_at_its_declared_limits<F: SyncFixture>(
864        open: impl AsyncFn() -> F,
865    ) -> Result<RuleOutcome, Violation> {
866        const CLAUSE: &str = "SY-18";
867        let fixture = open().await;
868        let peer = fixture.connect().await;
869
870        let limits = peer.limits();
871        let events = limits.max_batch_events.min(MAX_PROVOKED_BATCH_EVENTS);
872        if events == 0 {
873            // A declaration that admits no event: `peer_declares_its_own_limits`
874            // fails it, and there is no corner here to push into.
875            return Ok(RuleOutcome::Ran);
876        }
877
878        // The most bytes `events` events carry with none over `max_event_bytes`.
879        let bytes = limits
880            .max_batch_bytes
881            .min(MAX_PROVOKED_BATCH_BYTES)
882            .min(events.saturating_mul(limits.max_event_bytes));
883
884        let mut landed =
885            vec![push_the_corner(&peer, &limits, COUNT_CORNER_ORIGIN, events, 0, CLAUSE).await?];
886        if bytes > 0 {
887            landed.push(
888                push_the_corner(&peer, &limits, BYTE_CORNER_ORIGIN, events, bytes, CLAUSE).await?,
889            );
890        }
891
892        // One pull per event pushed, and the empty one that ends the log: a
893        // peer that pages one event at a time still fits (H-13).
894        let pushed = landed
895            .iter()
896            .map(|batch| batch.events().count())
897            .sum::<usize>();
898        let held: BTreeMap<EventId, ReplicatedEvent> =
899            pull_up_to(&peer, pushed.saturating_add(1), CLAUSE)
900                .await?
901                .into_iter()
902                .flat_map(|group| group.events)
903                .map(|event| (event.id, event))
904                .collect();
905        for expected in landed.iter().flat_map(PushBatch::events) {
906            ensure(held.get(&expected.id) == Some(expected), CLAUSE, || {
907                format!(
908                    "event {} of {} bytes, in a push at the declared batch limits, was \
909                     acknowledged and is not in the peer's log, byte for byte",
910                    expected.id,
911                    expected.payload_len()
912                )
913            })?;
914        }
915        Ok(RuleOutcome::Ran)
916    }
917
918    /// SY-30: the decomposition into independently conditioned groups is kept
919    /// end to end. What a peer is pushed as three groups it hands back as
920    /// those three groups: the same boundaries, the same events in order, and
921    /// the same guards.
922    ///
923    /// One push of `[a1, a2]` under a guard, `[b1]` under none, and `[c1, c2]`
924    /// under a second guard, all from one origin, well inside the minimum
925    /// limits; then a pull of the whole log. Both guards are position-free, so
926    /// SY-6's refusal of a guard carrying `after` never reaches them, and they
927    /// name types nothing in the suite writes, so a peer that evaluated them
928    /// would refuse nothing here.
929    ///
930    /// A peer that relays is what makes this the transport's obligation and not
931    /// only the envelope's: a hub that forwards a spoke's group merged with its
932    /// neighbours, or without its guard, publishes a decomposition the origin
933    /// never made, and the next hop can no longer tell which events were
934    /// decided together, or under what (SY-39 is the store's half).
935    ///
936    /// # Rejects
937    ///
938    /// The page-as-one-group peer #420 replaced, which hands a pull back as one
939    /// unguarded group, and a peer that keeps every boundary and drops the
940    /// guard. `tests/wrong_peers.rs` carries both, and SY-2's two mutants, the
941    /// flattener and the peer that pages by event, fail this rule too.
942    ///
943    /// # Errors
944    ///
945    /// A [`Violation`] of SY-30 if the peer refuses the push or a pull, or hands
946    /// back anything but the groups it was pushed.
947    pub async fn push_envelope_preserves_group_boundaries<F: SyncFixture>(
948        open: impl AsyncFn() -> F,
949    ) -> Result<RuleOutcome, Violation> {
950        const CLAUSE: &str = "SY-30";
951        let fixture = open().await;
952        let peer = fixture.connect().await;
953
954        let first = guard_on(GUARDED_FIRST, CLAUSE)?;
955        let last = guard_on(GUARDED_LAST, CLAUSE)?;
956        let pushed = vec![
957            EventGroup::new(Some(first), vec![grouped(1, CLAUSE)?, grouped(2, CLAUSE)?]),
958            EventGroup::new(None, vec![grouped(3, CLAUSE)?]),
959            EventGroup::new(Some(last), vec![grouped(4, CLAUSE)?, grouped(5, CLAUSE)?]),
960        ];
961        let batch = PushBatch::new(pushed);
962        peer.push(&batch).await.map_err(|error| {
963            Violation::new(
964                CLAUSE,
965                format!("the peer refused three groups well inside the minimum limits: {error}"),
966            )
967        })?;
968
969        let held = pull_everything(&peer, CLAUSE).await?;
970        let shape = |groups: &[EventGroup]| -> Vec<(usize, bool)> {
971            groups
972                .iter()
973                .map(|group| (group.events.len(), group.guard.is_some()))
974                .collect()
975        };
976        ensure(held == batch.groups, CLAUSE, || {
977            format!(
978                "the peer was pushed groups of (events, guarded) {:?} and handed back {:?}; a \
979                 reader of that log cannot tell which events were decided together, or under \
980                 what",
981                shape(&batch.groups),
982                shape(&held)
983            )
984        })?;
985        Ok(RuleOutcome::Ran)
986    }
987
988    /// SY-28, and SY-27 beneath it: a round trip preserves the whole log. Once
989    /// the two sides have pushed and pulled to quiescence, each holds the same
990    /// set of `EventId`s, each event with byte-identical type, tags, data and
991    /// metadata, and the recorded time it was pushed with (VT-9).
992    ///
993    /// The rule plays one side (SY-8). It pushes a log spread over both axes
994    /// a filter on `Query`'s surface cuts along, types and tags — two origins,
995    /// three event types, two regions, a confidential pricing slice in a
996    /// two-event group, an untagged event and one with metadata — pulls from
997    /// the start until the peer hands back an empty batch, and holds what came
998    /// back to what went: every identity, every byte. It compares no position
999    /// (SY-19): an identity is the origin's, compared whole, and the origin
1000    /// positions leave gaps, as a conformant origin may.
1001    ///
1002    /// # Rejects
1003    ///
1004    /// A peer that replicates a slice: one that withholds from its
1005    /// counterpart the events a type or tag filter matches, among the types
1006    /// and tags the rule's own log carries — the scoped hub or filtered spoke
1007    /// ADR-0027 kept off the 1.0 port. It stores and acknowledges every
1008    /// push truthfully, so no other rule sees it. `tests/wrong_scopes.rs`
1009    /// carries it with three filters, by tag, by type, and by type and tag.
1010    ///
1011    /// # Does not reject
1012    ///
1013    /// An identity the rule never pushed: on a far side that holds more, the
1014    /// rule's side would hold it too once it had pulled, and the two sets would
1015    /// still agree. Nor a peer that hands an event back twice, byte-identical:
1016    /// redelivery is SY-11's, and the model family judges it. Nor a filter that
1017    /// matches none of the rule's events, such as one on a tag its log never
1018    /// carries: the rule sees only what it pushed.
1019    ///
1020    /// # Errors
1021    ///
1022    /// A [`Violation`] of SY-28 if the peer refuses the push or a pull, keeps
1023    /// handing back groups past the suite's pull bound, withholds a pushed
1024    /// event, hands one back changed, or hands one identity back as two
1025    /// different events.
1026    pub async fn round_trip_preserves_the_whole_log<F: SyncFixture>(
1027        open: impl AsyncFn() -> F,
1028    ) -> Result<RuleOutcome, Violation> {
1029        const CLAUSE: &str = "SY-28";
1030        let fixture = open().await;
1031        let peer = fixture.connect().await;
1032        let log = whole_log::sliced_log(CLAUSE)?;
1033        peer.push(&log).await.map_err(|error| {
1034            Violation::new(
1035                CLAUSE,
1036                format!("the peer refused a batch well inside the minimum limits: {error}"),
1037            )
1038        })?;
1039        let handed_back = pull_everything(&peer, CLAUSE).await?;
1040        whole_log::holds_the_whole_log(
1041            &log,
1042            handed_back.into_iter().flat_map(|group| group.events),
1043            CLAUSE,
1044        )?;
1045        Ok(RuleOutcome::Ran)
1046    }
1047
1048    /// SY-32: a peer that has forgotten history reports the floor, and
1049    /// refuses a resume token below it with class
1050    /// [`Reseed`](happenstance_sync::FailureClass::Reseed), so a peer that was
1051    /// offline longer than its retention window is told it cannot converge
1052    /// rather than converging on a strict subset in silence.
1053    ///
1054    /// The rule plays the vessel (SY-8). A shore origin's log is pushed one
1055    /// group per day, on a test clock: days 0 and 10, then a pull to the end
1056    /// whose token is the vessel that goes offline on day 10; days 20, 50 and
1057    /// 70, then a pull from that token to the end whose token is a vessel that
1058    /// last synced on day 70; then days 100 and 125. On day 130 the fixture
1059    /// compacts on a 90-day window, forgetting days 0 to 20. Then:
1060    ///
1061    /// * the peer's [`retention_floor`](happenstance_sync::PeerLimits::retention_floor)
1062    ///   names one of the events it was asked to forget;
1063    /// * a pull from the day-10 token is refused with class `Reseed`;
1064    /// * so is a pull from the start: a peer that has compacted cannot hand a
1065    ///   strict subset to an edge that lost its token, or to a runner that
1066    ///   drops its token on a stop;
1067    /// * a pull from the day-70 token hands back exactly the events of days 100
1068    ///   and 125, compared whole (SY-35), each once.
1069    ///
1070    /// A fixture that declines [`COMPACTION`](crate::SyncFixture::COMPACTION)
1071    /// is reported [`Skipped`](RuleOutcome::Skipped) with its stated reason.
1072    ///
1073    /// # Rejects
1074    ///
1075    /// A peer that compacts and answers the stale token anyway: one that
1076    /// drains its log without an offset, so the old index lands on a later
1077    /// group, and one that declares a floor and answers a stale token from
1078    /// it, and one that serves a pull from the start from its floor. Each
1079    /// converges on a strict subset in silence. Also a peer that refuses and
1080    /// declares no floor or its oldest retained event as one, one that refuses
1081    /// as `Transient`, which a runner retries for ever, and one that refuses
1082    /// every token once compacted. `tests/wrong_retention.rs` carries all seven.
1083    ///
1084    /// # Does not reject
1085    ///
1086    /// A floor naming the wrong forgotten event: any event the rule asked the
1087    /// peer to forget passes, and the reference peer's unit tests pin which
1088    /// one. Nor a scattered purge, which SY-32 does not report in 1.x.
1089    ///
1090    /// # Errors
1091    ///
1092    /// A [`Violation`] of SY-32 if the peer refuses a push or a resumable
1093    /// pull, declares no floor or a floor it was not asked to forget, answers
1094    /// the stale token or a pull from the start, refuses either with a class
1095    /// other than `Reseed`, or hands
1096    /// back anything but the events written after the recent token.
1097    pub async fn retention_gap_is_reported_not_silent<F: SyncFixture>(
1098        open: impl AsyncFn() -> F,
1099    ) -> Result<RuleOutcome, Violation> {
1100        let fixture = open().await;
1101        if let Some(reason) = F::COMPACTION.reason() {
1102            return Ok(RuleOutcome::Skipped {
1103                capability: "COMPACTION",
1104                reason,
1105            });
1106        }
1107        let peer = fixture.connect().await;
1108        retention::reported_not_silent(&fixture, &peer).await?;
1109        Ok(RuleOutcome::Ran)
1110    }
1111
1112    /// What one log SY-37's rule wrote showed it.
1113    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1114    enum Log {
1115        /// Built, and a second non-empty page was seen: a `Nothing` at a
1116        /// boundary could have been a lie, and was checked.
1117        Paged,
1118        /// Built, or not written at all, and no page boundary was seen.
1119        NoPage,
1120        /// The peer refused a push of it, so it was not built.
1121        Refused,
1122    }
1123
1124    /// Whether the peer took every push of a log.
1125    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1126    enum Pushed {
1127        All,
1128        Refused,
1129    }
1130
1131    /// Writes `fill` to `peer` and, if the peer took it, follows its tokens.
1132    async fn write_log<P: SyncPeer>(
1133        peer: &P,
1134        fill: Fill,
1135        clause: &'static str,
1136    ) -> Result<Log, Violation> {
1137        Ok(match fill_with_readings(peer, fill, clause).await? {
1138            Pushed::Refused => Log::Refused,
1139            Pushed::All if follow_tokens(peer, fill.groups, clause).await? => Log::Paged,
1140            Pushed::All => Log::NoPage,
1141        })
1142    }
1143
1144    /// One log SY-37's rule writes: how many single-event groups, how many
1145    /// payload bytes each carries at least, and how many groups go in a push.
1146    #[derive(Debug, Clone, Copy)]
1147    struct Fill {
1148        groups: usize,
1149        payload: usize,
1150        per_push: usize,
1151    }
1152
1153    impl Fill {
1154        /// The cap plus one groups with tiny payloads, whatever the peer
1155        /// declares: a peer that pages at any count up to the cap shows a
1156        /// second page, including one whose declaration understates it.
1157        fn cut_by_count(limits: &PeerLimits) -> Self {
1158            Self {
1159                groups: FILL_CAP.saturating_add(1),
1160                payload: 0,
1161                per_push: limits.max_batch_events.max(1),
1162            }
1163        }
1164
1165        /// One group more than `max_batch_bytes` admits at the largest payload
1166        /// the peer takes, when that is fewer events than `max_batch_events`;
1167        /// `None` when the count cuts first or the log would pass either cap.
1168        ///
1169        /// Pushed one event at a time. The page boundary is the pull's to
1170        /// draw, and a push of one event no larger than SY-18's boundary event
1171        /// can be refused only for a per-event limit, which SY-18's rule
1172        /// judges. A push of a full page would also be refused by a peer that
1173        /// overstates `max_batch_bytes` alone, which is SY-18's batch rule's
1174        /// to judge, not this log's.
1175        fn cut_by_bytes(limits: &PeerLimits) -> Option<Self> {
1176            let payload = limits.max_event_bytes.min(limits.max_batch_bytes);
1177            let per_page = limits.max_batch_bytes.checked_div(payload)?;
1178            let groups = per_page.checked_add(1)?;
1179            let bytes = groups.checked_mul(payload)?;
1180            let fits = per_page < limits.max_batch_events
1181                && groups <= FILL_CAP.saturating_add(1)
1182                && bytes <= MAX_PROVOKED_BATCH_BYTES;
1183            fits.then_some(Self {
1184                groups,
1185                payload,
1186                per_push: 1,
1187            })
1188        }
1189    }
1190
1191    /// Follows `peer`'s tokens from the start of a log of `groups` groups, and
1192    /// checks the pull after the first `Nothing`. Answers whether a second
1193    /// non-empty page was seen, which is when a `Nothing` could have been a
1194    /// lie about a page boundary.
1195    async fn follow_tokens<P: SyncPeer>(
1196        peer: &P,
1197        groups: usize,
1198        clause: &'static str,
1199    ) -> Result<bool, Violation> {
1200        let refused = |error| Violation::new(clause, format!("the peer refused a pull: {error}"));
1201        let mut resume = None;
1202        let mut pages = 0_usize;
1203        // The suite's liveness guard: a log of `groups` groups cannot fill more
1204        // non-empty pulls than that unless the peer repeats itself; one more for
1205        // the pull that ends it.
1206        for _ in 0..=groups {
1207            let pulled = peer.pull(resume.as_ref()).await.map_err(refused)?;
1208            if !pulled.batch.groups.is_empty() {
1209                pages = pages.saturating_add(1);
1210            }
1211            match pulled.waiting {
1212                Waiting::Nothing => {
1213                    let next = peer.pull(Some(&pulled.resume)).await.map_err(refused)?;
1214                    let missed = next.batch.events().count();
1215                    ensure(missed == 0, clause, || {
1216                        format!(
1217                            "the peer said nothing was waiting, and the next pull from the token \
1218                             it returned carried {missed} event(s); a runner that believed it \
1219                             stopped short of them"
1220                        )
1221                    })?;
1222                    return Ok(pages >= 2);
1223                }
1224                Waiting::Unknown | Waiting::Events(_) if pulled.batch.groups.is_empty() => {
1225                    return Ok(pages >= 2);
1226                }
1227                Waiting::Unknown | Waiting::Events(_) => resume = Some(pulled.resume),
1228            }
1229        }
1230        Err(Violation::new(
1231            clause,
1232            format!(
1233                "the peer was still handing back groups of a {groups}-group log after {} pulls",
1234                groups.saturating_add(1)
1235            ),
1236        ))
1237    }
1238
1239    /// SY-23: the order a deployment may rely on peer-independently,
1240    /// [`EventId`] order, is the same on this peer as on every other, whatever
1241    /// order the events arrived in.
1242    ///
1243    /// The rule plays the other peer, which holds the events as their origins
1244    /// wrote them. Three origins number their events with gaps, which the
1245    /// contract allows, and the rule pushes them one to a push in an arrival
1246    /// order unlike their `EventId` order, in which an origin's higher position
1247    /// arrives before its lower one, as a delayed page lands after a later one.
1248    /// It then pulls the peer's whole log, sorts it by `EventId` and compares
1249    /// it with its own copy, sorted the same way, event by event and byte for
1250    /// byte. Nothing is decoded (SY-35), and the rule never asks the peer for
1251    /// an order: where it hands events back in arrival order, SY-25's subject,
1252    /// the sort makes that irrelevant.
1253    ///
1254    /// # Rejects
1255    ///
1256    /// A peer that dedupes by the highest origin position it has seen from
1257    /// each origin rather than by identity: the cheap shortcut its own
1258    /// [`Ack::confirmed`] watermark invites. It drops an origin's lower event
1259    /// when it arrives after a higher one, so its `EventId` order is missing
1260    /// an event every other peer's has, and a deployment sorting by it
1261    /// produces different output there. `tests/wrong_orders.rs` carries it,
1262    /// beside its faithful control.
1263    ///
1264    /// # Does not reject
1265    ///
1266    /// An `Ord` on [`EventId`] other than `(origin, origin_position)`, sorted
1267    /// with the origin first, which is the other half of SY-23. That order is
1268    /// `happenstance-core`'s derive (`identity.rs`, VT-5), and no peer can
1269    /// supply its own. The rule sorts with it, so a change there would move
1270    /// the order on every peer together, which this rule cannot see.
1271    ///
1272    /// # Errors
1273    ///
1274    /// A [`Violation`] of SY-23 if the peer refuses a push or a pull, or if
1275    /// its log, sorted by `EventId`, is not the pushed events sorted the same
1276    /// way.
1277    pub async fn event_id_order_is_identical_on_every_peer<F: SyncFixture>(
1278        open: impl AsyncFn() -> F,
1279    ) -> Result<RuleOutcome, Violation> {
1280        const CLAUSE: &str = "SY-23";
1281        let fixture = open().await;
1282        let peer = fixture.connect().await;
1283        let arriving = arrival_order(CLAUSE)?;
1284        for event in &arriving {
1285            peer.push(&one_event(event.clone()))
1286                .await
1287                .map_err(|error| {
1288                    Violation::new(
1289                        CLAUSE,
1290                        format!("the peer refused a one-event push of {}: {error}", event.id),
1291                    )
1292                })?;
1293        }
1294
1295        let mut held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
1296            .await?
1297            .into_iter()
1298            .flat_map(|group| group.events)
1299            .collect();
1300        held.sort_by_key(|event| event.id);
1301        let mut origins = arriving;
1302        origins.sort_by_key(|event| event.id);
1303        let ids = |events: &[ReplicatedEvent]| -> Vec<EventId> {
1304            events.iter().map(|event| event.id).collect()
1305        };
1306        ensure(ids(&held) == ids(&origins), CLAUSE, || {
1307            format!(
1308                "sorted by EventId, the peer holds {:?} and its origins wrote {:?}; a \
1309                 deployment that sorts by EventId gets different output on this peer",
1310                ids(&held),
1311                ids(&origins)
1312            )
1313        })?;
1314        for (kept, written) in held.iter().zip(&origins) {
1315            ensure(kept == written, CLAUSE, || {
1316                format!(
1317                    "{} is held with a recorded time or bytes other than its origin's; sorted \
1318                     by EventId, the two logs agree on identities and not on content",
1319                    kept.id
1320                )
1321            })?;
1322        }
1323        Ok(RuleOutcome::Ran)
1324    }
1325
1326    /// Pushes `fill.groups` single-event groups from [`ORIGIN_A`], at most
1327    /// `fill.per_push` to a push. Answers whether the peer took them all.
1328    async fn fill_with_readings<P: SyncPeer>(
1329        peer: &P,
1330        fill: Fill,
1331        clause: &'static str,
1332    ) -> Result<Pushed, Violation> {
1333        let Fill {
1334            groups: count,
1335            payload,
1336            per_push: chunk,
1337        } = fill;
1338        let mut position = SequencePosition::FIRST;
1339        let mut groups = Vec::with_capacity(chunk.min(count));
1340        for reading in 1..=count {
1341            // Distinct opaque bytes per event, padded to the fill's payload
1342            // size, and never parsed (SY-35).
1343            let mut data = reading.to_string().into_bytes();
1344            data.resize(data.len().max(payload), 0);
1345            let event = Event::new(READING_TAKEN, data).map_err(|error| {
1346                Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1347            })?;
1348            groups.push(EventGroup::new(
1349                None,
1350                vec![ReplicatedEvent::new(
1351                    EventId::new(ORIGIN_A, position),
1352                    RecordedAt::from_millis(1_800_000_000_000),
1353                    event,
1354                )],
1355            ));
1356            position = position
1357                .next()
1358                .ok_or_else(|| Violation::new(clause, "the rule's log ran out of positions"))?;
1359
1360            if groups.len() == chunk || reading == count {
1361                let batch = PushBatch::new(core::mem::take(&mut groups));
1362                // A refusal here is the peer disagreeing with its own
1363                // declaration. Whose failure that is depends on the log: for
1364                // the byte-cut log, one event sized from `max_event_bytes` to a
1365                // push, it is SY-18's per-event rule's to judge; for the
1366                // count-cut log, tiny events at most `max_batch_events` to a
1367                // push, it is a lie about batch limits, SY-18's batch rule's
1368                // to judge. The caller reports which, as a skip, unless the
1369                // other log paged.
1370                if peer.push(&batch).await.is_err() {
1371                    return Ok(Pushed::Refused);
1372                }
1373            }
1374        }
1375        Ok(Pushed::All)
1376    }
1377
1378    /// Pulls from the start of the peer's log until it hands back an empty
1379    /// batch, which the port defines as caught up.
1380    ///
1381    /// It ignores [`Pulled::waiting`](happenstance_sync::Pulled::waiting) on
1382    /// purpose, so a peer wrong about it fails SY-37's rule and only that one.
1383    async fn pull_everything<P: SyncPeer>(
1384        peer: &P,
1385        clause: &'static str,
1386    ) -> Result<Vec<EventGroup>, Violation> {
1387        pull_up_to(peer, MAX_PULLS, clause).await
1388    }
1389
1390    /// [`pull_everything`], giving up after `max_pulls` pulls rather than
1391    /// [`MAX_PULLS`]: for a rule whose log is too long for that bound.
1392    async fn pull_up_to<P: SyncPeer>(
1393        peer: &P,
1394        max_pulls: usize,
1395        clause: &'static str,
1396    ) -> Result<Vec<EventGroup>, Violation> {
1397        let mut groups = Vec::new();
1398        let mut resume: Option<P::Resume> = None;
1399        for _ in 0..max_pulls {
1400            let pulled = peer.pull(resume.as_ref()).await.map_err(|error| {
1401                Violation::new(clause, format!("the peer refused a pull: {error}"))
1402            })?;
1403            if pulled.batch.groups.is_empty() {
1404                return Ok(groups);
1405            }
1406            groups.extend(pulled.batch.groups);
1407            resume = Some(pulled.resume);
1408        }
1409        Err(Violation::new(
1410            clause,
1411            format!("the peer was still handing back groups after {max_pulls} pulls"),
1412        ))
1413    }
1414
1415    /// SY-23's log, in the order it arrives: three origins, each numbering
1416    /// its events with gaps, interleaved unlike their `EventId` order, and the
1417    /// low origin's and the high origin's higher position each arriving before
1418    /// its lower one. The positions are what the origins chose to send, never
1419    /// a claim about what a peer assigns.
1420    fn arrival_order(clause: &'static str) -> Result<Vec<ReplicatedEvent>, Violation> {
1421        [
1422            (ORDER_LOW, 5),
1423            (ORDER_MID, 3),
1424            (ORDER_HIGH, 4),
1425            (ORDER_LOW, 2),
1426            (ORDER_HIGH, 1),
1427            (ORDER_MID, 8),
1428        ]
1429        .into_iter()
1430        .map(|(origin, position)| {
1431            let data = format!("sy23 {origin} {position}");
1432            durable_reading(origin, position, data.as_bytes(), clause)
1433        })
1434        .collect()
1435    }
1436
1437    /// `event` as a batch of one group.
1438    fn one_event(event: ReplicatedEvent) -> PushBatch {
1439        PushBatch::new(vec![EventGroup::new(None, vec![event])])
1440    }
1441
1442    /// Pushes `batch`, which the peer's declaration admits, and requires it to
1443    /// land as one event appended. A refusal here is the failure SY-18 exists
1444    /// to move: found at ingest, after the origin committed.
1445    async fn push_admitted<P: SyncPeer>(
1446        peer: &P,
1447        batch: &PushBatch,
1448        what: &str,
1449        clause: &'static str,
1450    ) -> Result<(), Violation> {
1451        let ack = push_or_report(
1452            peer,
1453            batch,
1454            what,
1455            "the failure was relocated to ingest, not prevented",
1456            clause,
1457        )
1458        .await?;
1459        ensure(ack.appended == 1 && ack.skipped == 0, clause, || {
1460            format!(
1461                "the peer acknowledged {what} as {} appended and {} skipped; it held nothing \
1462                 with that identity, so it must append it",
1463                ack.appended, ack.skipped
1464            )
1465        })
1466    }
1467
1468    /// Pushes `batch`, which the peer's declaration admits, and reports a
1469    /// refusal as `what` refused, followed by `meaning`: what the refusal says
1470    /// about the peer.
1471    async fn push_or_report<P: SyncPeer>(
1472        peer: &P,
1473        batch: &PushBatch,
1474        what: &str,
1475        meaning: &str,
1476        clause: &'static str,
1477    ) -> Result<Ack, Violation> {
1478        peer.push(batch).await.map_err(|error| {
1479            Violation::new(
1480                clause,
1481                format!(
1482                    "the declared limits admit {what} and the push refused it ({error}, class \
1483                     {:?}): {meaning}",
1484                    error.class()
1485                ),
1486            )
1487        })
1488    }
1489
1490    /// Builds the batch at a corner of `limits` — `events` single-event
1491    /// groups carrying `bytes` payload bytes between them — checks that the
1492    /// declaration admits it, and pushes it: it must land whole, every event
1493    /// acknowledged as appended. Answers the batch, for the pull-back.
1494    async fn push_the_corner<P: SyncPeer>(
1495        peer: &P,
1496        limits: &PeerLimits,
1497        origin: StoreId,
1498        events: usize,
1499        bytes: usize,
1500        clause: &'static str,
1501    ) -> Result<PushBatch, Violation> {
1502        let batch = batch_at_the_corner(origin, events, bytes, clause)?;
1503        let what = format!("a push of {events} events and {bytes} payload bytes");
1504        ensure(limits.admits(&batch), clause, || {
1505            format!(
1506                "the declaration {limits:?} does not admit {what}, a batch at the limits \
1507                 it states"
1508            )
1509        })?;
1510        let ack = push_or_report(
1511            peer,
1512            &batch,
1513            &what,
1514            "a declared batch limit this peer does not impose",
1515            clause,
1516        )
1517        .await?;
1518        let expected = u64::try_from(events).map_err(|error| {
1519            Violation::new(
1520                clause,
1521                format!("the rule's own event count is too large: {error}"),
1522            )
1523        })?;
1524        ensure(ack.appended == expected && ack.skipped == 0, clause, || {
1525            format!(
1526                "the peer acknowledged {what} as {} appended and {} skipped; it held none of \
1527                 those identities, so it must append all {expected}",
1528                ack.appended, ack.skipped
1529            )
1530        })?;
1531        Ok(batch)
1532    }
1533
1534    /// `events` single-event groups from `origin`, at its positions from the
1535    /// first, whose payloads total exactly `bytes`: each `bytes / events`
1536    /// long, and the first `bytes % events` one byte longer. The bytes are
1537    /// zeros and are never parsed (SY-35).
1538    ///
1539    /// Single-event groups with no guard, no tags and no metadata, so a peer
1540    /// has nothing to cut, evaluate or cap but the batch itself.
1541    fn batch_at_the_corner(
1542        origin: StoreId,
1543        events: usize,
1544        bytes: usize,
1545        clause: &'static str,
1546    ) -> Result<PushBatch, Violation> {
1547        let no_events = || Violation::new(clause, "the rule built a corner of no events");
1548        let base = bytes.checked_div(events).ok_or_else(no_events)?;
1549        let longer = bytes.checked_rem(events).ok_or_else(no_events)?;
1550
1551        let mut position = SequencePosition::FIRST;
1552        let mut groups = Vec::with_capacity(events);
1553        for index in 0..events {
1554            let size = if index < longer {
1555                base.saturating_add(1)
1556            } else {
1557                base
1558            };
1559            let event = Event::new(BATCH_FILLED, vec![0_u8; size]).map_err(|error| {
1560                Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1561            })?;
1562            groups.push(EventGroup::new(
1563                None,
1564                vec![ReplicatedEvent::new(
1565                    EventId::new(origin, position),
1566                    RecordedAt::from_millis(1_800_000_000_000),
1567                    event,
1568                )],
1569            ));
1570            position = position
1571                .next()
1572                .ok_or_else(|| Violation::new(clause, "the rule's corner ran out of positions"))?;
1573        }
1574        Ok(PushBatch::new(groups))
1575    }
1576
1577    /// Which of an event's two opaque fields carries a boundary event's bytes.
1578    ///
1579    /// Both, one event each, because `max_event_bytes` bounds
1580    /// [`ReplicatedEvent::payload_len`], which is data and metadata together:
1581    /// a peer that stores metadata somewhere smaller has a limit its
1582    /// declaration does not state.
1583    #[derive(Debug, Clone, Copy)]
1584    enum Carrier {
1585        Data,
1586        Metadata,
1587    }
1588
1589    impl Carrier {
1590        /// What the violation message calls the event this carrier builds.
1591        const fn describe(self) -> &'static str {
1592            match self {
1593                Self::Data => "an event at the declared boundary, in its data",
1594                Self::Metadata => "an event at the declared boundary, in its metadata",
1595            }
1596        }
1597
1598        /// Each boundary event's origin, so the two are distinct facts.
1599        const fn origin(self) -> StoreId {
1600            match self {
1601                Self::Data => BOUNDARY_ORIGIN,
1602                Self::Metadata => METADATA_ORIGIN,
1603            }
1604        }
1605    }
1606
1607    /// An event at every envelope floor the contract sets, carrying `size`
1608    /// opaque bytes (SY-35) in `carrier`: a type of [`MAX_EVENT_TYPE_LEN`]
1609    /// bytes and [`MIN_SUPPORTED_TAGS_PER_EVENT`] distinct tags of
1610    /// [`MAX_TAG_LEN`] bytes.
1611    fn event_at_the_envelope_floors(
1612        size: usize,
1613        carrier: Carrier,
1614        clause: &'static str,
1615    ) -> Result<ReplicatedEvent, Violation> {
1616        let event_type = EventType::new("L".repeat(MAX_EVENT_TYPE_LEN)).map_err(|error| {
1617            Violation::new(clause, format!("the rule's own type is invalid: {error}"))
1618        })?;
1619        let tags = (0..MIN_SUPPORTED_TAGS_PER_EVENT)
1620            .map(|i| Tag::new(format!("{i:0>MAX_TAG_LEN$}")))
1621            .collect::<Result<Tags, _>>()
1622            .map_err(|error| {
1623                Violation::new(clause, format!("the rule's own tag is invalid: {error}"))
1624            })?;
1625        let bytes = vec![0_u8; size];
1626        let event = match carrier {
1627            Carrier::Data => Event::new(event_type, bytes),
1628            Carrier::Metadata => {
1629                Event::new(event_type, Vec::new()).map(|event| event.with_metadata(bytes))
1630            }
1631        }
1632        .map_err(|error| {
1633            Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1634        })?
1635        .with_tags(tags);
1636        Ok(ReplicatedEvent::new(
1637            EventId::new(carrier.origin(), SequencePosition::FIRST),
1638            RecordedAt::from_millis(1_800_000_000_000),
1639            event,
1640        ))
1641    }
1642
1643    /// The guard both claims travel under: "nobody has claimed seat s1", with
1644    /// no position, so it is byte-identical wherever it was written.
1645    fn seat_guard(clause: &'static str) -> Result<AppendCondition, Violation> {
1646        let item = QueryItem::new([SEAT_CLAIMED], seat()).map_err(|error| {
1647            Violation::new(clause, format!("the rule's own query is invalid: {error}"))
1648        })?;
1649        Ok(AppendCondition::new(Query::from_item(item)))
1650    }
1651
1652    fn seat() -> Tags {
1653        [Tag::from_static("seat:s1")].into_iter().collect()
1654    }
1655
1656    /// A position-free guard naming `event_type`, for SY-30's groups.
1657    fn guard_on(event_type: EventType, clause: &'static str) -> Result<AppendCondition, Violation> {
1658        let item = QueryItem::of_types([event_type]).map_err(|error| {
1659            Violation::new(clause, format!("the rule's own query is invalid: {error}"))
1660        })?;
1661        Ok(AppendCondition::new(Query::from_item(item)))
1662    }
1663
1664    /// The SY-30 origin's event at its own `position`, with a payload of its
1665    /// own so "the same events" means byte for byte (SY-35).
1666    fn grouped(position: u64, clause: &'static str) -> Result<ReplicatedEvent, Violation> {
1667        let at = SequencePosition::new(position)
1668            .ok_or_else(|| Violation::new(clause, "the rule's origin position is zero"))?;
1669        let event = Event::new(GROUP_WRITTEN, format!("group-{position}").into_bytes()).map_err(
1670            |error| Violation::new(clause, format!("the rule's own event is invalid: {error}")),
1671        )?;
1672        Ok(ReplicatedEvent::new(
1673            EventId::new(GROUPS_ORIGIN, at),
1674            RecordedAt::from_millis(1_800_000_000_000),
1675            event,
1676        ))
1677    }
1678
1679    /// `origin`'s claim on the seat, the first event in its log.
1680    fn claim(origin: StoreId, clause: &'static str) -> Result<ReplicatedEvent, Violation> {
1681        replicated(origin, SEAT_CLAIMED, clause)
1682    }
1683
1684    /// A reading `origin` recorded at its own `position`, carrying `data` as
1685    /// opaque bytes (SY-35).
1686    fn durable_reading(
1687        origin: StoreId,
1688        position: u64,
1689        data: &[u8],
1690        clause: &'static str,
1691    ) -> Result<ReplicatedEvent, Violation> {
1692        let position = SequencePosition::new(position)
1693            .ok_or_else(|| Violation::new(clause, "the rule's origin position is zero"))?;
1694        let event = Event::new(READING_TAKEN, data.to_vec()).map_err(|error| {
1695            Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1696        })?;
1697        Ok(ReplicatedEvent::new(
1698            EventId::new(origin, position),
1699            RecordedAt::from_millis(1_800_000_000_000),
1700            event,
1701        ))
1702    }
1703
1704    fn replicated(
1705        origin: StoreId,
1706        event_type: EventType,
1707        clause: &'static str,
1708    ) -> Result<ReplicatedEvent, Violation> {
1709        // The payload is opaque bytes and stays that way (SY-35): a distinct
1710        // value per origin, so "byte for byte" means something.
1711        let event = Event::new(event_type, origin.to_string().into_bytes())
1712            .map_err(|error| {
1713                Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1714            })?
1715            .with_tags(seat());
1716        Ok(ReplicatedEvent::new(
1717            EventId::new(origin, SequencePosition::FIRST),
1718            RecordedAt::from_millis(1_800_000_000_000),
1719            event,
1720        ))
1721    }
1722
1723    #[cfg(test)]
1724    mod tests {
1725        use alloc::collections::BTreeSet;
1726
1727        use happenstance_sync::ReplicatedEvent;
1728
1729        use super::{BYTE_CORNER_ORIGIN, batch_at_the_corner};
1730
1731        /// The corner's arithmetic at its edges: no bytes, an exact multiple,
1732        /// a remainder of one, fewer bytes than events, and a large corner.
1733        #[test]
1734        fn a_corner_carries_exactly_its_events_and_bytes_spread_evenly() {
1735            let cases: [(usize, usize); 6] = [
1736                (1, 0),
1737                (128, 0),
1738                (128, 65_536),
1739                (128, 65_537),
1740                (3, 2),
1741                (10, 1_048_576),
1742            ];
1743            for (events, bytes) in cases {
1744                let batch = batch_at_the_corner(BYTE_CORNER_ORIGIN, events, bytes, "SY-18")
1745                    .expect("a corner of at least one event builds");
1746                let sizes: Vec<usize> = batch.events().map(ReplicatedEvent::payload_len).collect();
1747                let ids: BTreeSet<_> = batch.events().map(|event| event.id).collect();
1748                let case = format!("{events} events, {bytes} bytes");
1749
1750                assert_eq!(sizes.len(), events, "{case}: the event count");
1751                assert_eq!(batch.payload_len(), bytes, "{case}: the payload total");
1752                let spread = sizes.iter().max().zip(sizes.iter().min());
1753                assert!(
1754                    spread.is_some_and(|(max, min)| max - min <= 1),
1755                    "{case}: sizes {sizes:?} differ by more than one byte"
1756                );
1757                assert_eq!(ids.len(), events, "{case}: every identity is distinct");
1758                assert!(
1759                    batch.groups.iter().all(|group| group.events.len() == 1),
1760                    "{case}: every group carries one event"
1761                );
1762            }
1763        }
1764
1765        /// The remainder goes to the first events, one byte each.
1766        #[test]
1767        fn a_corner_with_a_remainder_lengthens_its_first_events() {
1768            let batch = batch_at_the_corner(BYTE_CORNER_ORIGIN, 128, 65_537, "SY-18")
1769                .expect("a corner of 128 events builds");
1770            let sizes: Vec<usize> = batch.events().map(ReplicatedEvent::payload_len).collect();
1771            assert_eq!(sizes.first(), Some(&513));
1772            assert!(sizes.iter().skip(1).all(|size| *size == 512), "{sizes:?}");
1773        }
1774
1775        /// A corner of no events is the rule's own mistake, reported as a
1776        /// violation rather than a division by zero.
1777        #[test]
1778        fn a_corner_of_no_events_is_a_violation_not_a_panic() {
1779            for bytes in [0, 1, 65_536] {
1780                let built = batch_at_the_corner(BYTE_CORNER_ORIGIN, 0, bytes, "SY-18");
1781                assert_eq!(
1782                    built
1783                        .map(|batch| batch.payload_len())
1784                        .map_err(|v| v.clause()),
1785                    Err("SY-18"),
1786                    "0 events, {bytes} bytes"
1787                );
1788            }
1789        }
1790    }
1791}
1792
1793/// Hands the complete sync rule set to `$callback`.
1794///
1795/// This family's single enumeration. `$callback` is the path of a macro that
1796/// accepts a comma-separated list of identifiers, and it is invoked once, with
1797/// every rule in [`rules`].
1798///
1799/// # Examples
1800///
1801/// ```
1802/// macro_rules! rule_names {
1803///     ($($name:ident),* $(,)?) => { [ $( stringify!($name) ),* ] };
1804/// }
1805///
1806/// let names = happenstance_sync_testkit::for_each_sync_peer_rule!(rule_names);
1807/// assert!(names.contains(&"ingest_never_rejects"));
1808/// ```
1809#[macro_export]
1810macro_rules! for_each_sync_peer_rule {
1811    // Raw token trees rather than `$cb:path`, for the reason the event-store
1812    // family's enumeration records: a parsed `path` cannot sit in callee
1813    // position inside an expression.
1814    ($($callback:tt)+) => {
1815        $($callback)+! {
1816            // --- Ingest never refuses (SY-1) --------------------------------
1817            ingest_never_rejects,
1818
1819            // --- A group travels whole (SY-2) -------------------------------
1820            compensation_is_atomic_with_the_losing_event,
1821
1822            // --- EventId order is the same on every peer (SY-23) ------------
1823            event_id_order_is_identical_on_every_peer,
1824
1825            // --- A peer declares its own limits (SY-18) ---------------------
1826            peer_declares_its_own_limits,
1827            peer_takes_a_batch_at_its_declared_limits,
1828
1829            // --- Every refusal states its class (SY-36) ---------------------
1830            every_refusal_states_its_class,
1831
1832            // --- Nothing waiting means nothing waiting (SY-37) --------------
1833            nothing_waiting_means_the_next_pull_is_empty,
1834
1835            // --- An ack confirms only what is durable (SY-31) ---------------
1836            ack_never_confirms_a_non_durable_event,
1837
1838            // --- The group decomposition survives the peer (SY-30) ----------
1839            push_envelope_preserves_group_boundaries,
1840
1841            // --- A round trip preserves the whole log (SY-27, SY-28) --------
1842            round_trip_preserves_the_whole_log,
1843
1844            // --- A retention gap is reported, not silent (SY-32) ------------
1845            retention_gap_is_reported_not_silent,
1846        }
1847    };
1848}
1849
1850/// Emits one `#[tokio::test]` per sync rule.
1851///
1852/// The caller's crate needs `tokio` with `macros` and `rt` in its
1853/// `dev-dependencies`. The default emitter of
1854/// [`sync_peer_conformance!`](crate::sync_peer_conformance).
1855#[macro_export]
1856macro_rules! emit_sync_tokio {
1857    ($($name:ident),* $(,)?) => {
1858        $(
1859            #[tokio::test]
1860            async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1861                $crate::__private::rules::$name(__conformance_fixture)
1862                    .await?
1863                    .report(::core::stringify!($name));
1864                Ok(())
1865            }
1866        )*
1867    };
1868}
1869
1870/// Emits one plain `#[test]` per sync rule, driven by
1871/// [`happenstance_testkit::block_on`].
1872///
1873/// No runtime and no `Send` bound, so this is the harness a `!Send` peer runs
1874/// under — and the one SY-17's rule names.
1875#[macro_export]
1876macro_rules! emit_sync_blocking {
1877    ($($name:ident),* $(,)?) => {
1878        $(
1879            #[test]
1880            fn $name() -> ::core::result::Result<(), $crate::Violation> {
1881                $crate::__private::block_on($crate::__private::rules::$name(__conformance_fixture))?
1882                    .report(::core::stringify!($name));
1883                Ok(())
1884            }
1885        )*
1886    };
1887}
1888
1889/// Emits one `#[wasm_bindgen_test]` per sync rule.
1890///
1891/// The caller's crate needs `wasm-bindgen-test` in its `dev-dependencies`,
1892/// gated on `cfg(target_arch = "wasm32")`. A skip is logged through
1893/// `console_log!` rather than reported on stdout, which writes nowhere on that
1894/// target — the event-store family's `emit_wasm` says why at length.
1895#[macro_export]
1896macro_rules! emit_sync_wasm {
1897    ($($name:ident),* $(,)?) => {
1898        $(
1899            #[::wasm_bindgen_test::wasm_bindgen_test]
1900            async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1901                let __outcome = $crate::__private::rules::$name(__conformance_fixture).await?;
1902                if let Some(__line) = __outcome.skip_line(::core::stringify!($name)) {
1903                    ::wasm_bindgen_test::console_log!("{}", __line);
1904                }
1905                Ok(())
1906            }
1907        )*
1908    };
1909}
1910
1911/// Expands to a `[&str; N]` of the rule names, for the orphan meta-test.
1912///
1913/// Not an emitter and not promised; exported only because `macro_rules!` has no
1914/// other way to reach another crate's tests.
1915#[doc(hidden)]
1916#[macro_export]
1917macro_rules! __sync_rule_names {
1918    ($($name:ident),* $(,)?) => { [ $( ::core::stringify!($name) ),* ] };
1919}
1920
1921/// Every `pub async fn` declared at the top level of this file's `rules`
1922/// module — the same four-space prefix `cargo xtask spec-trace` reads.
1923#[cfg(test)]
1924fn declared_rules() -> Vec<&'static str> {
1925    const SOURCE: &str = include_str!("sync_suite.rs");
1926    const PREFIX: &str = "    pub async fn ";
1927
1928    SOURCE
1929        .lines()
1930        .filter_map(|line| line.strip_prefix(PREFIX))
1931        .filter_map(|rest| {
1932            rest.split(|c: char| !c.is_alphanumeric() && c != '_')
1933                .next()
1934        })
1935        .collect()
1936}
1937
1938/// No rule exists without appearing in the enumeration, and none is
1939/// enumerated without existing — the event-store family's `no_orphan_rules`,
1940/// one family over.
1941#[cfg(test)]
1942#[test]
1943fn no_orphan_sync_rules() {
1944    let registered = crate::for_each_sync_peer_rule!(crate::__sync_rule_names);
1945    let declared = declared_rules();
1946
1947    assert!(
1948        !declared.is_empty(),
1949        "the source scan matched no rule at all"
1950    );
1951    let orphans: Vec<_> = declared
1952        .iter()
1953        .filter(|name| !registered.contains(*name))
1954        .collect();
1955    assert!(
1956        orphans.is_empty(),
1957        "these rules are absent from `for_each_sync_peer_rule!`, so no harness runs them: \
1958         {orphans:?}"
1959    );
1960    let missing: Vec<_> = registered
1961        .iter()
1962        .filter(|name| !declared.contains(*name))
1963        .collect();
1964    assert!(
1965        missing.is_empty(),
1966        "these rules are registered but not declared in `sync_suite.rs`: {missing:?}"
1967    );
1968}