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
//! THE CRON SEAM, runtime side: when is a calendar expression next due?
//!
//! # The seam existed because the implementation was temporary — and it has been replaced
//!
//! The ruling that put cron in v1 said what rides underneath it: a third-party crate FIRST, and the
//! user's own implementation later. The later has arrived. What changed is what this module calls;
//! what did not change is a single word an author writes, a single variant of
//! [`Recurrence`](super::Recurrence), or a single engine — which is what the seam was built to make
//! possible, and this swap is the measurement that it did.
//!
//! Its twin is `ingraph-codegen`'s `cron`, which refuses a garbage expression AT EXPANSION. Two
//! halves rather than one because the build order forbids one: this crate expands THROUGH the
//! derive, which is built on that one, so it cannot reach it. A swap touches both, and the
//! FIVE-FIELD rule is stated in both for the same reason.
//!
//! # What the crate does, and what THIS MODULE does
//!
//! `cronp` PARSES and does not evaluate. It reads an expression into a bitset per field, takes its
//! dialect as a type parameter, and answers *does this field admit this value* — and, for the two
//! day fields, whose combination is a rule of the dialect rather than an `and`, *does this calendar
//! match this civil datetime*. There is still no next-occurrence call to make, and that is the point
//! rather than a shortfall: **the walk from a civil datetime to an instant is where every DST
//! decision lives**, so a seam that owns the walk owns the decisions, where one that delegated it
//! could only record whatever the delegate chose.
//!
//! The DIALECT is `Vixie`, and its own constants are the pins this framework used to state by hand:
//! five fields, no seconds field, no year field, and day-of-month against day-of-week the classic
//! `Union` — `0 3 1 * MON` fires on the first AND on every Monday. The five-field count is still
//! checked here, because the useful sentence is not *that parses as six fields* but *a timezone is
//! not a sixth field, there is a word for it*.
//!
//! # THE TWO RULED DST PINS ARE HONOURED
//!
//! They were recorded as deviations while the evaluator belonged to somebody else. They are law now,
//! and each is one arm of `Calendar::instant_of`:
//!
//! * a NONEXISTENT local time — the spring-forward gap — FIRES ONCE, AT THE GAP'S END. `30 2 * *
//! *` in `America/New_York` has no 02:30 on 2026-03-08, and the schedule fires at 03:00-04:00,
//! the first instant that exists after the gap. Every civil minute inside the gap maps to that
//! same instant, so a schedule naming several of them still fires once: the walk answers
//! strictly after what it was given, and an instant already passed is not offered twice.
//! * a REPEATED local time — the fall-back fold — FIRES ONCE, AT THE FIRST OCCURRENCE. The same
//! schedule at `30 1 * * *` fires at 01:30-04:00 on 2026-11-01 and not again at 01:30-05:00.
//! Which of the two is *the* one is the ruled half; what makes it structural rather than a
//! filter is that the walk enumerates CIVIL times and maps each to exactly one instant, so the
//! second pass of a repeated hour is never a candidate at all.
//!
//! The second pin has a consequence worth meeting here rather than in production: a schedule firing
//! several times inside a repeated hour — `*/15 * * * *` — loses that hour's second pass, four
//! firings once a year. That is what *a repeated local time fires once* MEANS, and the poll
//! doctrine's own requirement that a sweep be idempotent is what makes it affordable.
//!
//! # The zone is the RUNNING machine's, never the building machine's
//!
//! `tz = "<IANA>"` names a zone and the absence of it means the system's, and both are resolved
//! HERE — expansion happens wherever the build happens, and a schedule that meant three in the
//! morning meant it where the program runs.
use Duration;
use Arc;
use ;
use ;
/// How many fields a cron expression has here: the classic five — minute, hour, day of month,
/// month, day of week.
///
/// Checked by THIS framework even though the dialect now states it too, and the reason is the
/// SENTENCE rather than the rule: `Vixie` would refuse a sixth field as a parse error, and what a
/// reader needs to be told is that a timezone is not a sixth field because there is a word for it.
/// Stated in `ingraph-codegen`'s half of the seam as well, since the build order gives the two no
/// way to share it.
const FIELDS: usize = 5;
/// How far ahead a walk looks before it answers *never*.
///
/// FOUR YEARS, which is the leap cycle: `0 0 29 2 *` is the sparsest expression this dialect can
/// write, and four years is what it takes to be sure one exists. An expression that names no day in
/// four years — `0 0 30 2 *`, February the thirtieth — names none ever, and a clock told *never*
/// stops asking instead of waking forever on a schedule that will not fire.
const HORIZON_DAYS: i32 = 366 * 4;
/// ONE calendar expression, read, with the zone it is evaluated in.
///
/// Constructed once at wiring time and asked for its next due date forever after, which is why the
/// parse is fallible and the asking is not.
///
/// BEHIND A POINTER, and that is about the two things holding one: a
/// [`Recurrence`](super::Recurrence) is an enum whose other arm is a [`Duration`], and a schedule is
/// CLONED once per entry to mint its cadences. A parsed expression and a time zone are neither small
/// nor cheap to copy, so they are shared instead — the value is immutable once read, which is what
/// makes sharing it indistinguishable from owning it.
/// A calendar's contents, behind the pointer.
/// Whether this DATE is one the expression names — ASKED OF THE DIALECT rather than spelled here.
///
/// The dom/dow rule used to be written out in this function, off four accessors the dialect no
/// longer offers. That it is applied inside the dialect now is a correction and not only a tidying:
/// the hand-spelling could not see WHERE the wildcard sat, and Vixie's union rule turns on exactly
/// that. `10,*` and `*,10` name one set of days — every one of them — and land on opposite sides of
/// the rule, while the restricted-flags the old arm read share one value across the pair, so both
/// spellings could only ever be given one answer here. `wildcard.rs` beside this module is where the
/// two are pinned apart.
///
/// # ONE probe answers the whole day
///
/// [`cronp::Calendar::matches`] asks a civil datetime where this asks a date, so the day question is
/// put to it at [`Read::probe`] — a time the expression admits. Every term `matches` adds beyond the
/// date is then either passed by that construction (hour, minute, second) or is a test this walk
/// wanted anyway (year, month), so the answer belongs to the day rather than to the clock it was
/// asked at, and a day still costs a fixed handful of bitset reads.
///
/// A date `cronp` cannot NAME is not a day. Its calendar runs year 1 to 9999 where jiff's runs -9999
/// to 9999, so the LOW end is the only one a walk can reach, and a walk that has left the range
/// answers *never* — the same answer [`Calendar::instant_of`] gives where the arithmetic leaves what
/// an instant can hold.
/// A parse refusal with the expression under it and a caret on the offending run.
///
/// The TWIN of `ingraph-codegen`'s `cron::caret`, written out twice because the build order gives
/// the two crates no way to share one — the reason [`FIELDS`] is stated twice. Kept identical by
/// `the_two_halves_render_one_caret` in the suite beside this module.
///
/// The caret is at least one column wide, because an empty span is a real answer: a parser that ran
/// out of input points AT the end, and a marker with no width would point at nothing.
/// Why a calendar expression could not be read.
///
/// It carries TEXT rather than a taxonomy, and that is the seam's doing rather than laziness: the
/// categories a cron parser refuses in are the implementation's, so a typed error here would be the
/// one part of this module a swap could not replace without changing a public type. What the text
/// is, is the implementation's own sentence with the expression under it and a caret on the run that
/// broke.
;