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
// Copyright (c) 2026 Mike Grier
//! Validating a notification stream against this crate's delivery contract.
//!
//! [`ContractChecker`] is the executable form of the *sequencing* rules --
//! ordering, tier-conditioned legality, cross-message continuity, terminality --
//! that a per-value type cannot carry. It exists so those rules have **one**
//! definition that everything binds to: this crate's own integration tests, the
//! example test harness's generator, and a consumer validating its own test
//! doubles or a captured production stream.
//!
//! That single definition is the point. A hand-written second copy of a
//! sequencing rule is not a check of the contract, it is a check of the copy --
//! see [restatement drift](../../../DESIGN-NOTES.md) in the workspace design
//! notes, where five of six findings across three review rounds were corrections
//! that had failed to reach every place stating them.
//!
//! # What it checks, and what it deliberately does not
//!
//! Only rules the contract actually establishes are asserted. Over-constraining
//! is the same defect as under-specifying, and this crate has produced it: the
//! harness generator once excluded a `Desync { QueueFull }` that a coarse watch
//! can legally report. Each rule below cites the decision it comes from.
//!
//! **Checked:**
//!
//! - **Terminality.** Nothing follows `Completion { Cancelled }`,
//! `Completion { Failed }`, or `Desync { Stopped }` for that watch (D-30/D-46,
//! and D-22 for the last).
//! - **Tier-conditioned emission.** Once a tier has been reported, a Coarse watch
//! emits no `Batch` and no `Desync { Overflow }`, and a Detailed watch emits no
//! `Desync { Coarse }` (D-17). Delegated to
//! [`DesyncCause::is_reachable_in`](crate::DesyncCause::is_reachable_in) rather
//! than restated here.
//! - **Volume-change continuity.** A watch's next `VolumeChanged.previous` equals
//! its own prior `.current`, because `install` stores the confirmed identity
//! (D-78).
//! - **Volume-change distinctness.** `previous` and `current` never compare equal,
//! since the notification is only emitted when identity actually differs (D-78)
//! and identity compares by serial alone (D-50).
//!
//! **Deliberately not checked**, because the contract permits them and asserting
//! otherwise would encode a rule the watcher does not keep:
//!
//! - A `Resumed` **without** a preceding `Suspended`. A route coalescing onto an
//! already-faulted watcher joins after `enter_fault` sent its `Suspended`s, so
//! it observes a bracket it never saw open (M14.2).
//! - A `Suspended` closed by `Desync { Stopped }` rather than `Resumed` (M14.2).
//! - `Established` arriving other than first, for that same mid-fault join
//! (M14.2).
//! - A tier that **changes** between establishments: `reopen` re-resolves it every
//! call (D-61), so Detailed then Coarse, or the reverse, is legal.
//! - A `Batch` **inside a fault bracket**. `on_completion` re-arms before it
//! decodes, so a read that completed and then failed to re-arm calls
//! `enter_fault` first and publishes the already-completed batch afterwards.
//! Those changes were in hand and dropping them would be silent loss, so one
//! batch may legally follow a bracket's opening notifications.
//! - A `Desync { QueueFull }` **after that watch's terminator**, once. The latch
//! is synthesized when the queue drains, while a cancellation completion holds
//! a slot reserved since registration (D-45), so a saturated queue delivers
//! the terminator first and the owed loss report after it. Exactly one can be
//! owed -- latching coalesces per watch, and nothing is sent for a watch after
//! its terminator -- so a second is rejected.
//!
//! **Not checkable from the stream alone**, and so not attempted: at most one
//! question is outstanding per subscription (D-28's standing-slot invariant). The
//! answer travels the *request* queue, which never appears here, so a second
//! `RetryQuestion` after the client answered the first is indistinguishable from
//! two outstanding at once.
//!
//! # Scope
//!
//! The checker is per-`WatchId` and order-sensitive, matching the contract:
//! ordering is defined *within* a subscription (D-12/D-26), not across
//! subscriptions, so interleaving between watches is never a violation.
use HashMap;
use crateVolumeIdentity;
use crateDesyncCause;
use crate;
use crateWatchMode;
/// Why a notification stream violated the delivery contract.
/// How a watch ended.
/// Whether `notification` is an owed loss report, which may legally arrive
/// *after* that watch's terminator.
///
/// A latched `Desync { QueueFull }` is not in the queue -- it is synthesized
/// once the queue drains -- while a subscription's cancellation completion has
/// held a reserved slot since registration (D-45). So when saturation latches a
/// loss and the watch is then cancelled, `Reservation::send` flushes the latch
/// *while its own reservation is still counted*, finds no free slot, and
/// appends `Cancelled` anyway. The receiver drains the queue before
/// synthesizing latches, so it observes `Cancelled` and only then the owed
/// `Desync { QueueFull }`.
///
/// That is real, legal output, and it is the one thing that may follow a
/// terminator. Rejecting it would be over-constraining -- the same defect as
/// under-specifying, and the reason this checker has as many
/// must-accept tests as must-reject ones.
/// One subscription's position in the contract.
/// Validates a notification stream against the delivery contract.
///
/// Feed every notification, in arrival order, to [`ContractChecker::observe`].
/// Notifications for different watches may interleave freely.
///
/// ```
/// use windows_file_watcher::{
/// ContractChecker, DesyncCause, Notification, Outcome, WatchId,
/// };
///
/// let mut checker = ContractChecker::new();
/// let watch = WatchId::from_raw(1);
///
/// checker
/// .observe(&Notification::Completion { watch, outcome: Outcome::Subscribed })
/// .expect("a registration outcome is legal");
/// checker
/// .observe(&Notification::Desync { watch, cause: DesyncCause::Stopped })
/// .expect("a terminal desync is legal");
///
/// // Nothing may follow a terminator for that watch.
/// let after = checker.observe(&Notification::Desync {
/// watch,
/// cause: DesyncCause::Overflow,
/// });
/// assert!(after.is_err());
/// ```