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