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
//! Attribution & fan-out: routing one raw event back to every caller
//! [`Subscription`] that covers it.
//!
//! This is pure logic — no I/O, no clock, no runtime — so it is exhaustively
//! unit-testable over synthetic events and keys alone. The driver performs the O(1)
//! handle → root lookup and hands the matched root's subscriber list here; [`fan_out`]
//! then does the linear-in-subscribers-of-that-root coverage test, generic over the
//! key component `C`.
//!
//! The one thing keeping this module pure is the [`RoutableEvent`] seam: the raw event
//! is consumed through a trait exposing only its endpoint keys, whether it is a
//! [`Rescan`](crate::EventKind::Rescan), and how to mint the retagged output
//! for one subscriber (including the two synthesized single-endpoint projections a
//! move decomposes into). Production plugs in a thin adapter over the source event
//! (whose deliver methods mint a [`crate::Event`]); tests plug in a trivial fake, so
//! the routing decision is checked without constructing any source event at all.
//!
//! # No silent loss
//!
//! For every raw event, the set of subscribers it is delivered to equals exactly
//! the set whose key covers it **and** whose [`Filter`](crate::Filter) admits it
//! (design §5/§7) — with one override that *widens* that set, never narrows it: a
//! [`Rescan`](crate::EventKind::Rescan) is delivered to **every** subscriber of
//! the root, bypassing *both* the coverage test and the filter, because a
//! coverage-loss signal must never be narrowed or filtered away (design §5/§7/§8).
//!
//! The [`Filter`](crate::Filter) is an *additional* admission gate layered on top of
//! coverage: a non-`Rescan` event reaches a subscriber only if the subscriber's key
//! covers it **and** its filter admits the (minted) delivery. The filter runs here, at
//! fan-out — before any coalescing (design §7) — so a settle burst only ever buffers
//! events the caller actually wants.
//!
//! # A [`Moved`](crate::EventKind::Moved) has two endpoints
//!
//! Every other event kind has a single covered key; a move has two — a source `from`
//! and a destination `to` ([`key`](RoutableEvent::key)). Coverage must consider
//! **both**, or a subscription watching only the source silently misses that the file
//! left its tree. So [`fan_out`] decomposes a move **per subscriber** (design §5):
//!
//! - covers **both** endpoints → the full `Moved(from → to)`;
//! - covers **only `from`** (move-out) → a synthesized `Removed(from)` — the file
//! left its tree and it cannot see where it went;
//! - covers **only `to`** (move-in) → a synthesized `Created(to)` — the file arrived
//! from outside its watch;
//! - covers neither → nothing.
//!
//! Each subscriber thus receives **exactly one** event for a move (dedup: a
//! both-covering subscriber gets the `Moved`, never also a `Removed`/`Created`). The
//! synthesized single-endpoint projections are minted as a flat owned
//! [`Event`](crate::Event) in the umbrella's own neutral vocabulary — and every
//! projection of one raw move carries that subscriber's umbrella epoch stamp (assigned
//! downstream, design §8).
use crateSubscription;
/// A raw event, viewed by [`fan_out`] through only what routing needs — its endpoint
/// keys, whether it is a [`Rescan`](crate::EventKind::Rescan), and how to mint
/// the retagged delivery (whole, or one of the two single-endpoint move projections)
/// for one subscriber.
///
/// The seam that keeps [`fan_out`] pure and testable, generic over the key component
/// `C`: production implements it for a thin adapter over the raw
/// [`SourceEvent`](crate::SourceEvent); tests implement it for a fake. `Delivered` is
/// the per-subscriber output — [`crate::Event`] in production.
pub
/// Fans one raw event out to every covering, filter-admitting subscriber of its
/// matched root, retagging each delivered copy with that subscriber's
/// [`Subscription`] and — for a [`Moved`](crate::EventKind::Moved) — projecting
/// it per that subscriber's two-endpoint coverage.
///
/// `subscribers` is the subscriber list of the root the driver resolved from the raw
/// event's handle (the O(1) reverse map, not a radix walk). `canonical_of` resolves
/// each subscriber to its registered key — the ancestor-test anchor of design §4; a
/// subscriber it cannot resolve (concurrently dropped) is skipped.
///
/// `admits` is the subscriber's admission gate (design §5/§7): given a subscriber and
/// the *minted* (already projected) delivery, it returns whether that subscriber
/// accepts it. Production folds **both** the subscription's [`Filter`](crate::Filter)
/// and its [`Interest`](crate::Interest) gate into this closure, checking them
/// against the projected delivery's kind (so a move-out is gated by `removed` interest,
/// a move-in by `created`, a whole `Moved` by `moved`). It is only consulted for
/// non-`Rescan` events, and only after the coverage test has passed — so the closure
/// receives a delivery the subscriber's key already covers. A subscriber whose gate
/// state cannot be resolved (dropped concurrently) is treated as not admitting.
///
/// **Coverage** is the component-wise ancestor test: a subscription covers a key iff
/// its key is an ancestor of (or equal to) it. `<[C]>::starts_with` is component-wise
/// (so `[a, b]` covers `[a, b, c]` but not `[a, bc]`), which is exactly the §4 test. A
/// single-endpoint event tests only `event.key()`; a move tests **both** `from` and
/// `to` (below).
///
/// **Move decomposition (design §5):** for a [`Moved`](crate::EventKind::Moved)
/// (detected by [`move_from`](RoutableEvent::move_from) being `Some`), each subscriber
/// receives **exactly one** projection: the whole `Moved` if it covers both endpoints,
/// a synthesized `Removed(from)` if it covers only the source (move-out), a synthesized
/// `Created(to)` if it covers only the destination (move-in), or nothing. The dedup is
/// structural — the four coverage cases are disjoint — so a both-covering subscriber
/// never also gets a `Removed`/`Created`.
///
/// **Filter / interest** are the additional admission gates (design §5/§7): a
/// non-`Rescan` projection is pushed only if `admits` returns `true` for it — they
/// *narrow* the covered set. They run here, before any coalescing, so a settle burst
/// never buffers a filtered-out or uninteresting event.
///
/// **Rescan override:** if the event is a [`Rescan`](crate::EventKind::Rescan)
/// it is delivered whole to *every* subscriber of the root regardless of coverage
/// **and** regardless of filter/interest — a coverage-loss signal is never narrowed or
/// filtered away (design §5/§7/§8).
pub
/// The single projection `sub` (registered at `canonical`) receives for one event,
/// or `None` if it covers nothing of it. A non-move tests only `to`; a move
/// (`move_from` is `Some`) decomposes per the two-endpoint rule (design §5).