tributaries 0.1.0

Cross-platform filesystem notification: overlapping watch subscriptions are subsumed into disjoint roots, and every event is attributed back to each subscription covering it.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
use core::num::NonZeroU64;
use std::{ffi::OsString, path::Path};

use tributary_proto::{Epoch, ScopeId};

use super::EpochLedger;
use crate::{route::RoutableEvent, subscription::Subscription};

/// A path's `OsString` components — the located-key form the fs source keys on.
fn key(path: &str) -> Vec<OsString> {
  Path::new(path)
    .components()
    .map(|c| c.as_os_str().to_os_string())
    .collect()
}

/// A minimal stand-in for a raw event — the same shape `route::tests` uses, so the
/// ledger's fan-out + stamp is exercised without any real source's private event
/// constructor. Routing reads its endpoint keys and whether it is a `Rescan`; its
/// per-subscriber delivery is the [`Subscription`] paired with which projection it got,
/// which the ledger then stamps — so a move test can confirm every projection of one
/// raw move carries that subscriber's stamp.
struct FakeEvent {
  key: Vec<OsString>,
  from: Option<Vec<OsString>>,
  rescan: bool,
}

/// Which projection a subscriber received (mirrors `route::tests`), so a move test can
/// assert the stamp lands on the right projection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Projection {
  Whole,
  MoveOut,
  MoveIn,
}

impl FakeEvent {
  fn change(path: &str) -> Self {
    Self {
      key: key(path),
      from: None,
      rescan: false,
    }
  }

  fn rescan(path: &str) -> Self {
    Self {
      key: key(path),
      from: None,
      rescan: true,
    }
  }

  fn moved(from: &str, to: &str) -> Self {
    Self {
      key: key(to),
      from: Some(key(from)),
      rescan: false,
    }
  }
}

impl RoutableEvent<OsString> for FakeEvent {
  type Delivered = (Subscription, Projection);

  fn key(&self) -> &[OsString] {
    self.key.as_slice()
  }

  fn move_from(&self) -> Option<&[OsString]> {
    self.from.as_deref()
  }

  fn is_rescan(&self) -> bool {
    self.rescan
  }

  fn deliver(&self, sub: Subscription) -> (Subscription, Projection) {
    (sub, Projection::Whole)
  }

  fn deliver_move_out(&self, sub: Subscription) -> (Subscription, Projection) {
    (sub, Projection::MoveOut)
  }

  fn deliver_move_in(&self, sub: Subscription) -> (Subscription, Projection) {
    (sub, Projection::MoveIn)
  }
}

fn sub(id: u64) -> Subscription {
  Subscription::for_test(ScopeId::new(NonZeroU64::new(id).expect("nonzero id")))
}

/// A root serving the given subscribers, each registered at its own key (the two
/// inputs `stamp_and_fan_out`'s coverage step needs). The root path itself is
/// immaterial — the coverage step keys on the subscribers and their own keys.
struct Fixture {
  subscribers: Vec<Subscription>,
  keys: Vec<(Subscription, Vec<OsString>)>,
}

impl Fixture {
  fn new(_root_path: &str, subscribers: &[(u64, &str)]) -> Self {
    let mut subs = Vec::new();
    let mut keys = Vec::new();
    for &(id, path) in subscribers {
      let s = sub(id);
      subs.push(s);
      keys.push((s, key(path)));
    }
    Self {
      subscribers: subs,
      keys,
    }
  }

  fn canonical_of(&self, s: Subscription) -> Option<&[OsString]> {
    self
      .keys
      .iter()
      .find(|(candidate, _)| *candidate == s)
      .map(|(_, k)| k.as_slice())
  }

  /// Fan `event` (raw fs epoch `raw`) out through `ledger`, returning each covered
  /// subscriber paired with the umbrella stamp the ledger assigned it.
  fn deliver(
    &self,
    ledger: &mut EpochLedger,
    event: &FakeEvent,
    raw: Epoch,
  ) -> Vec<(Subscription, Epoch)> {
    self
      .deliver_projected(ledger, event, raw)
      .into_iter()
      .map(|(s, _projection, stamp)| (s, stamp))
      .collect()
  }

  /// Like [`deliver`](Self::deliver) but also returns each delivery's projection, so a
  /// move test can assert the stamp lands on the right per-endpoint projection.
  fn deliver_projected(
    &self,
    ledger: &mut EpochLedger,
    event: &FakeEvent,
    raw: Epoch,
  ) -> Vec<(Subscription, Projection, Epoch)> {
    ledger.stamp_and_fan_out(
      event,
      raw,
      &self.subscribers,
      |s| self.canonical_of(s),
      // These tests exercise coverage + epoch rebasing, not the filter, so admit
      // every covered delivery (the filter gate is covered in `route::tests`).
      |_sub, _delivered| true,
      |(s, _projection)| *s,
      |(s, projection), stamp| (s, projection, stamp),
    )
  }

  /// Like [`deliver`](Self::deliver) but with the admission gate under test: a delivery is kept
  /// only when `admit(sub)` returns `true`. Lets a test drive a filtered-OUT delivery through the
  /// same admit-then-stamp seam and confirm a rejected delivery never reaches
  /// [`stamp`](EpochLedger::stamp).
  fn deliver_gated(
    &self,
    ledger: &mut EpochLedger,
    event: &FakeEvent,
    raw: Epoch,
    admit: impl Fn(Subscription) -> bool,
  ) -> Vec<(Subscription, Epoch)> {
    ledger.stamp_and_fan_out(
      event,
      raw,
      &self.subscribers,
      |s| self.canonical_of(s),
      |sub, _delivered| admit(sub),
      |(s, _projection)| *s,
      |(s, _projection), stamp| (s, stamp),
    )
  }
}

/// The single-subscription stamp path is monotone within one root: fs epochs 0,1,2
/// stamp to 0,1,2 from base START.
#[test]
fn stamps_are_monotone_within_a_root() {
  let mut ledger = EpochLedger::new();
  let fx = Fixture::new("/a", &[(1, "/a")]);
  let s = sub(1);

  let mut stamps = Vec::new();
  for raw in 0..3 {
    let delivered = fx.deliver(&mut ledger, &FakeEvent::change("/a/file"), Epoch::new(raw));
    assert_eq!(
      delivered,
      vec![(s, Epoch::new(raw))],
      "stamp = base(0) + raw"
    );
    stamps.push(delivered[0].1);
  }
  assert!(
    stamps.windows(2).all(|w| w[0] <= w[1]),
    "stamps are monotone-nondecreasing within one root"
  );
}

/// The RISK-1 regression: on a widen re-point, the new root's genuine post-widen
/// events (which restart at fs epoch 0) must NOT be dominated by the synthetic widen
/// `Rescan`. The pre-fix bug fed raw fs epochs into a single linear high-water and
/// minted the Rescan above it, so 0,1 came out < the Rescan and a conforming consumer
/// would drop them — silent loss. Rebasing stamps them at `hw.next()+0,+1`.
#[test]
fn post_widen_new_root_events_are_not_dominated_by_the_widen_rescan() {
  let mut ledger = EpochLedger::new();
  let s = sub(1);

  // Root A serves subscription 1. Three events at fs epochs 0,1,2.
  let root_a = Fixture::new("/a/b", &[(1, "/a/b")]);
  let mut pre_widen = Vec::new();
  for raw in 0..3 {
    let delivered = root_a.deliver(&mut ledger, &FakeEvent::change("/a/b/f"), Epoch::new(raw));
    assert_eq!(delivered.len(), 1, "the lone covering sub is served");
    pre_widen.push(delivered[0].1);
  }
  assert_eq!(
    pre_widen,
    vec![Epoch::new(0), Epoch::new(1), Epoch::new(2)],
    "pre-widen stamps track the raw fs epochs from base START"
  );

  // WIDEN re-point of subscription 1 onto the new wider root /a. Its high-water is 2,
  // so the synthetic Rescan is minted at 3 (= hw.next()).
  let rescan_stamp = ledger.repoint(s);
  assert_eq!(
    rescan_stamp,
    Epoch::new(3),
    "the widen Rescan is minted one past the subscription's high-water"
  );

  // The newly-armed wider root /a now delivers genuine events, whose fs epochs
  // RESTART at 0,1 (per-ScopeId, fresh kernel arm). Rebasing stamps them at 3+0, 3+1.
  let root_b = Fixture::new("/a", &[(1, "/a")]);
  let mut post_widen = Vec::new();
  for raw in 0..2 {
    let delivered = root_b.deliver(&mut ledger, &FakeEvent::change("/a/b/f"), Epoch::new(raw));
    assert_eq!(delivered.len(), 1, "the sub still covers events under /a/b");
    post_widen.push(delivered[0].1);
  }
  assert_eq!(
    post_widen,
    vec![Epoch::new(3), Epoch::new(4)],
    "post-widen stamps rebase onto hw.next()+raw, not the raw fs epoch"
  );

  // (a) Every pre-widen event is DOMINATED by the Rescan (strictly less) — correct:
  // the consumer re-enumerates over them.
  assert!(
    pre_widen.iter().all(|&e| e < rescan_stamp),
    "pre-widen events are dominated by the widen Rescan"
  );

  // (b) THE FIX: every post-widen new-root event is NOT dominated by the Rescan
  // (tie-or-exceeds it). The pre-fix bug would make these < rescan_stamp and lose
  // them.
  assert!(
    post_widen.iter().all(|&e| e >= rescan_stamp),
    "post-widen new-root events are NOT dominated by the widen Rescan (RISK-1)"
  );

  // (c) The whole delivered stamp sequence for the subscription — pre-widen, the
  // Rescan, then post-widen — is monotone-nondecreasing.
  let whole: Vec<Epoch> = pre_widen
    .iter()
    .copied()
    .chain(core::iter::once(rescan_stamp))
    .chain(post_widen.iter().copied())
    .collect();
  assert!(
    whole.windows(2).all(|w| w[0] <= w[1]),
    "the whole stamped sequence across the re-point is monotone-nondecreasing"
  );
}

/// Two subscriptions re-pointed onto the SAME new root rebase INDEPENDENTLY, each
/// from its own high-water — so they get different `epoch_base`s and different stamps
/// for the very same raw fs epoch on the shared new root.
#[test]
fn two_subscriptions_onto_one_new_root_rebase_independently() {
  let mut ledger = EpochLedger::new();
  let (s1, s2) = (sub(1), sub(2));

  // Drive the two subscriptions to DIFFERENT high-waters on their own narrow roots.
  let root1 = Fixture::new("/a/b", &[(1, "/a/b")]);
  for raw in 0..5 {
    root1.deliver(&mut ledger, &FakeEvent::change("/a/b/f"), Epoch::new(raw));
  }
  let root2 = Fixture::new("/a/c", &[(2, "/a/c")]);
  for raw in 0..2 {
    root2.deliver(&mut ledger, &FakeEvent::change("/a/c/f"), Epoch::new(raw));
  }

  // Widen both onto the shared new root /a. s1 (high-water 4) rebases to 5; s2
  // (high-water 1) rebases to 2 — independently.
  let r1 = ledger.repoint(s1);
  let r2 = ledger.repoint(s2);
  assert_eq!(
    r1,
    Epoch::new(5),
    "s1's Rescan is one past its own high-water 4"
  );
  assert_eq!(
    r2,
    Epoch::new(2),
    "s2's Rescan is one past its own high-water 1"
  );

  // The SAME raw fs epoch 0 on the shared new root /a stamps DIFFERENTLY for each,
  // because each carries its own rebased base.
  let shared = Fixture::new("/a", &[(1, "/a"), (2, "/a")]);
  let delivered = shared.deliver(&mut ledger, &FakeEvent::change("/a/x"), Epoch::new(0));
  let stamp_of = |who: Subscription| {
    delivered
      .iter()
      .find(|(s, _)| *s == who)
      .map(|(_, e)| *e)
      .expect("both subs are covered by /a")
  };
  assert_eq!(
    stamp_of(s1),
    Epoch::new(5),
    "s1 rebases raw 0 onto its base 5 (independent of s2)"
  );
  assert_eq!(
    stamp_of(s2),
    Epoch::new(2),
    "s2 rebases raw 0 onto its base 2 (independent of s1)"
  );
  // Neither post-widen event is dominated by its own subscription's widen Rescan.
  assert!(stamp_of(s1) >= r1 && stamp_of(s2) >= r2);
}

/// A `Rescan` fs itself reports is stamped and fanned out to EVERY subscriber of the
/// root (coverage bypassed), and its umbrella stamp dominates each subscriber's prior
/// stream — the same dominance the synthetic widen Rescan gives, but for an
/// fs-sourced one.
#[test]
fn fs_rescan_is_stamped_and_dominates_prior_stream() {
  let mut ledger = EpochLedger::new();
  // Root /a serves /a and the narrower /a/b/deep (which a plain event at /a/x would
  // NOT cover — but a Rescan reaches it anyway).
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b/deep")]);
  let (s1, s2) = (sub(1), sub(2));

  // Give /a a couple of prior events so its high-water is non-trivial.
  fx.deliver(&mut ledger, &FakeEvent::change("/a/x"), Epoch::new(0));
  let prior = fx.deliver(&mut ledger, &FakeEvent::change("/a/x"), Epoch::new(1));
  assert_eq!(
    prior,
    vec![(s1, Epoch::new(1))],
    "plain event only covers /a"
  );

  // A Rescan located at /a/x — which /a/b/deep does NOT cover — is delivered to BOTH,
  // stamped in each subscriber's own space (from each one's base START, raw 2 → 2).
  let delivered = fx.deliver(&mut ledger, &FakeEvent::rescan("/a/x"), Epoch::new(2));
  let stamp_of = |who: Subscription| delivered.iter().find(|(s, _)| *s == who).map(|(_, e)| *e);
  assert_eq!(
    stamp_of(s1),
    Some(Epoch::new(2)),
    "the Rescan reaches /a and dominates its prior stamp of 1"
  );
  assert_eq!(
    stamp_of(s2),
    Some(Epoch::new(2)),
    "the Rescan reaches /a/b/deep despite coverage (loss is never narrowed away)"
  );
  assert!(
    stamp_of(s1).unwrap() > Epoch::new(1),
    "the fs Rescan's stamp dominates /a's prior stream"
  );
}

/// Every projection of one raw move carries its subscriber's umbrella stamp (design
/// §5/§8): a move between sibling subs yields a Removed for the source-sub and a
/// Created for the dest-sub, and each is stamped in that subscriber's own epoch space —
/// not the raw fs epoch, and not skipped.
#[test]
fn move_decomposition_stamps_each_projection() {
  let mut ledger = EpochLedger::new();
  let (s1, s2) = (sub(1), sub(2));
  // Two sibling subs on one root, at different high-waters so their stamps differ.
  let fx = Fixture::new("/a", &[(1, "/a/src"), (2, "/a/dst")]);
  fx.deliver(&mut ledger, &FakeEvent::change("/a/src/x"), Epoch::new(3)); // s1 hw = 3
  fx.deliver(&mut ledger, &FakeEvent::change("/a/dst/x"), Epoch::new(1)); // s2 hw = 1

  // A move /a/src/f -> /a/dst/f at raw fs epoch 4: source-sub gets a stamped Removed,
  // dest-sub a stamped Created.
  let out = fx.deliver_projected(
    &mut ledger,
    &FakeEvent::moved("/a/src/f", "/a/dst/f"),
    Epoch::new(4),
  );
  let find = |who: Subscription| out.iter().find(|(s, _, _)| *s == who).copied();

  let (_, p1, e1) = find(s1).expect("the source-sub is served");
  assert_eq!(
    p1,
    Projection::MoveOut,
    "source-sub gets the move-out Removed"
  );
  assert_eq!(e1, Epoch::new(4), "…stamped in s1's space (base 0 + raw 4)");

  let (_, p2, e2) = find(s2).expect("the dest-sub is served");
  assert_eq!(p2, Projection::MoveIn, "dest-sub gets the move-in Created");
  assert_eq!(e2, Epoch::new(4), "…stamped in s2's space (base 0 + raw 4)");
}

/// The overflow shed primitive (design backpressure doc): `shed_rescan` mints a
/// strictly-dominating `Rescan` epoch WITHOUT rebasing the subscription's base (it stays on
/// the same live root). The `Rescan` dominates the whole pre-shed stream. This exercises the
/// case where the raw fs epoch has **advanced** across the shed (a later reconciliation
/// generation — raw 5,6,7): those deltas stamp `base + raw` and so sort at or above the
/// `Rescan`. The complementary case — a later **same-generation** event whose raw has NOT
/// advanced (the common one, since the raw fs epoch is a generation, not a per-event
/// counter), which relies on [`stamp`](EpochLedger::stamp)'s high-water clamp — is covered by
/// [`post_shed_same_generation_event_is_not_dominated_by_the_shed_rescan`]. `repoint`'s
/// base-rebasing is not used for a shed: it is sound only for a widen onto a fresh root.
#[test]
fn shed_rescan_dominates_prior_stream_and_same_root_deltas_sort_at_or_above() {
  let mut ledger = EpochLedger::new();
  let s = sub(1);
  let root = Fixture::new("/a", &[(1, "/a")]);

  // Same-root events at raw fs epochs 0..5 stamp 0..4 (base START), driving high-water to 4.
  let mut pre = Vec::new();
  for raw in 0..5 {
    let delivered = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(raw));
    pre.push(delivered[0].1);
  }
  assert_eq!(
    pre,
    vec![
      Epoch::new(0),
      Epoch::new(1),
      Epoch::new(2),
      Epoch::new(3),
      Epoch::new(4),
    ],
    "pre-shed stamps track the raw fs epochs from base START"
  );

  // Overflow shed: the parked Rescan is minted one past the high-water (strictly dominating
  // the whole pre-shed stream).
  let rescan = ledger.shed_rescan(s);
  assert_eq!(rescan, Epoch::new(5), "shed_rescan = high_water.next()");
  assert!(
    pre.iter().all(|&e| e < rescan),
    "the shed Rescan strictly dominates every pre-shed delivery"
  );

  // The SAME live root keeps delivering — its raw fs epochs keep climbing (5,6,7), NOT
  // restarting at 0 (no re-arm). Because base was NOT rebased, they stamp base + raw =
  // 5,6,7, tying-or-exceeding the Rescan, so a conforming consumer never drops them.
  let mut post = Vec::new();
  for raw in 5..8 {
    let delivered = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(raw));
    post.push(delivered[0].1);
  }
  assert_eq!(
    post,
    vec![Epoch::new(5), Epoch::new(6), Epoch::new(7)],
    "same-root post-shed deltas stamp base + raw (base unchanged)"
  );
  assert!(
    post.iter().all(|&e| e >= rescan),
    "no same-root delta after the shed sorts BELOW the Rescan (the non-rebasing guarantee)"
  );

  // Repeated sheds are monotone/idempotent: a second shed mints strictly above the first
  // and above every same-root stamp since (high-water is now 7).
  let rescan2 = ledger.shed_rescan(s);
  assert_eq!(
    rescan2,
    Epoch::new(8),
    "a second shed mints one past the new high-water (strictly increasing)"
  );
  assert!(rescan2 > rescan, "sheds are monotone");
}

/// Regression (design backpressure doc, no silent loss): the raw fs epoch is a
/// per-scope reconciliation **generation** — constant across ordinary events, advanced only
/// on a `Rescan`/overflow (see `tributary_proto`'s monitor) — NOT a per-event counter. So
/// after an overflow [`shed_rescan`](EpochLedger::shed_rescan) mints a dominating `Rescan` at
/// `high_water.next()`, a later SAME-generation event (same raw) must still not sort below
/// it. [`stamp`](EpochLedger::stamp)'s high-water clamp lifts such an event up to TIE the
/// shed `Rescan` (a tie is not dominated).
///
/// Fail-on-old: without the clamp (`stamp = base + raw`), the post-shed same-generation event
/// stamps `base + 0 = 0`, one BELOW the shed `Rescan` (1) → a dominance-applying consumer
/// drops it → silent loss. This is exactly the class the climbing-raw shed test above (which
/// models raw as a per-event counter) cannot see.
#[test]
fn post_shed_same_generation_event_is_not_dominated_by_the_shed_rescan() {
  let mut ledger = EpochLedger::new();
  let s = sub(1);
  let root = Fixture::new("/a", &[(1, "/a")]);

  // Ordinary events in ONE reconciliation generation all carry the SAME raw fs epoch (0);
  // they stamp base + 0 = 0 and high-water stays 0.
  for _ in 0..3 {
    let delivered = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(0));
    assert_eq!(
      delivered[0].1,
      Epoch::new(0),
      "same-generation events stamp base + 0"
    );
  }

  // Overflow shed: the parked Rescan is minted one past the high-water.
  let rescan = ledger.shed_rescan(s);
  assert_eq!(rescan, Epoch::new(1), "shed_rescan = high_water.next()");

  // A LATER event in the SAME generation still carries raw 0 (no fs re-arm, no generation
  // bump). Its natural stamp base + 0 = 0 would sort BELOW the shed Rescan (1); the clamp
  // lifts it to tie the Rescan (1) instead, so it is never dominated.
  let post = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(0));
  assert_eq!(
    post[0].1,
    Epoch::new(1),
    "the post-shed same-generation event is clamped up to tie the shed Rescan, not base + 0 = 0"
  );
  assert!(
    post[0].1 >= rescan,
    "no post-shed same-generation event sorts below the shed Rescan (no silent loss)"
  );
}

/// Regression (design backpressure doc, no silent loss): a SOURCE-emitted `Rescan`
/// must STRICTLY dominate every prior delivery. The high-water clamp lets an ordinary post-shed
/// same-generation event deliver *at* the shed `Rescan`'s epoch (a tie). If the source then
/// emits its own `Rescan`, the ordinary clamp (`max(base + raw, high_water)`) would only tie
/// that already-delivered event — losing strict dominance and the lower layer's coverage-loss
/// signal. [`stamp_rescan`](EpochLedger::stamp_rescan) (`max(base + raw, high_water.next())`)
/// restores it.
///
/// Fail-on-old: routing the source `Rescan` through the ordinary `stamp` clamp stamps it AT
/// the post-shed event's epoch (a tie, not strictly above) → the assertion FAILS.
#[test]
fn source_rescan_strictly_dominates_a_post_shed_same_generation_event() {
  let mut ledger = EpochLedger::new();
  let s = sub(1);
  let root = Fixture::new("/a", &[(1, "/a")]);

  // One generation of ordinary events (raw 0): stamp base + 0 = 0, high-water 0.
  root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(0));

  // Overflow shed → dominating Rescan at 1.
  let shed = ledger.shed_rescan(s);
  assert_eq!(shed, Epoch::new(1), "shed_rescan = high_water.next()");

  // A post-shed SAME-generation ordinary event (raw 0) is clamped up to tie the shed Rescan.
  let post = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(0));
  assert_eq!(
    post[0].1,
    Epoch::new(1),
    "the post-shed ordinary event ties the shed Rescan"
  );

  // Now the SOURCE emits its own `Rescan` in the SAME generation (raw 0). It must STRICTLY
  // dominate the epoch-1 event just delivered — not merely tie it.
  let src_rescan = root.deliver(&mut ledger, &FakeEvent::rescan("/a/f"), Epoch::new(0));
  assert_eq!(
    src_rescan[0].1,
    Epoch::new(2),
    "the source Rescan is stamped strictly above the post-shed event (high_water.next()), not tying it"
  );
  assert!(
    src_rescan[0].1 > post[0].1,
    "a source Rescan strictly dominates every prior delivery (coverage-loss signal preserved)"
  );
}

/// Regression (design §7, no silent perturbation): the filter admission gate runs
/// BEFORE a delivery is stamped, so a filtered-OUT delivery must never advance the subscription's
/// epoch high-water. This is the property that lets a filter be a pure pre-delivery predicate over
/// the change while the epoch space stays owned by admitted deliveries alone (a rejected candidate
/// perturbs nothing) — preserved by the Option-A fix, which keeps stamping strictly after
/// admission.
///
/// Fail-on-old: were the stamp applied before admission, the rejected raw-9 delivery would inflate
/// high-water to 9 and the clamp would then lift the later admitted raw-1 event up to 9.
#[test]
fn a_filtered_out_delivery_does_not_advance_high_water() {
  let mut ledger = EpochLedger::new();
  let s = sub(1);
  let root = Fixture::new("/a", &[(1, "/a")]);

  // An admitted event at raw 0 stamps 0 and drives high-water to 0.
  let d0 = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(0));
  assert_eq!(d0, vec![(s, Epoch::new(0))]);

  // A REJECTED delivery at raw 9: `fan_out` drops it before the map that stamps, so `stamp` never
  // runs for it and high-water must stay 0.
  let rejected = root.deliver_gated(
    &mut ledger,
    &FakeEvent::change("/a/f"),
    Epoch::new(9),
    |_| false,
  );
  assert!(
    rejected.is_empty(),
    "the filtered-out delivery is not delivered"
  );

  // A later admitted event at raw 1 stamps base + 1 = 1 — NOT inflated to 9. If the rejected raw-9
  // delivery had wrongly advanced high-water, the clamp would lift this to 9.
  let d1 = root.deliver(&mut ledger, &FakeEvent::change("/a/f"), Epoch::new(1));
  assert_eq!(
    d1,
    vec![(s, Epoch::new(1))],
    "a rejected delivery did not perturb the subscription's epoch high-water"
  );
}