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
//! The framework's own instant: [`Timestamp`], and the two columns it occupies.
use ;
use SystemTime;
use crate::;
/// The WHOLE SECONDS column, named as the ruling names it.
pub const SECOND: &FieldName = new;
/// The FRACTION column, in nanoseconds.
pub const NANOSECOND: &FieldName = new;
/// **The two columns an instant occupies, and the ONE authority every lane reads them from.**
///
/// A width for [`ColumnKind`](crate::ColumnKind), a pair of binds for
/// [`Carrier`](crate::Carrier), a pair of reads for [`Assemble`](crate::Assemble), and two
/// sub-document keys for the MongoDB family — five rows in four modules, and a rename here moves
/// all of them together. That is the arrangement a DECLARED composite already has (the derive
/// corpus's `Timebase` keeps one `const SEGMENTS` its predicate and its row both read); what is new
/// is that the composite is the FRAMEWORK's, so the authority sits with the type rather than in a
/// declarer's module.
///
/// The names are unprefixed here because a segment is named BENEATH its field: a field called `at`
/// renders `at_secs` and `at_nanos`, and the join is the renderer's — see
/// [`ColumnShape`](crate::ColumnShape), where the prefixing rule is stated once for every
/// composite.
/// **BOTH leaves are the VALUE, and the census is worth stating because the name invites the other
/// reading.** `nanos` here is the SUBSECOND component of the instant — half of what
/// [`from_parts`](Timestamp::from_parts) rebuilds it from, read by the decode, and exact for every
/// instant in the range. It is not the `nanos` the media-time citizens carry, which is a DERIVED
/// position on a timeline and is [`Nullable`](ColumnShape::Nullable) for it.
///
/// So this type declares no self-nullable leaf: a required `at: Timestamp` renders both of its
/// columns `NOT NULL`, and an optional one is absent in both or in neither. There is nothing here
/// the write path can fail to place.
pub const SEGMENTS: & = &;
/// An instant on the UTC timeline, to the NANOSECOND, from `-9999-01-02T01:59:59Z` to
/// `9999-12-30T22:00:00.999999999Z`.
///
/// The framework's own temporal citizen, present in EVERY build: [`jiff`] is a required dependency
/// here rather than a vocabulary feature, so a record the FRAMEWORK ships can stamp a time without
/// the build having asked for a temporal vocabulary first.
///
/// `Temporal<T>` is the other temporal name in this crate and answers the other question — it is the
/// storage WRAPPER a user-declared jiff or `time` value crosses into, behind the `jiff` and `time`
/// features, where this type is the framework's own instant and stands whatever the features say.
///
/// # Why a newtype and not `jiff::Timestamp` itself
///
/// The orphan rule, at the one place it actually bites. A filter registration would not have needed
/// this — `to_filter!`'s two traits are local, so jiff's own types are registered here already — but
/// the WIRE FACE cannot be written for a foreign type: `impl async_graphql::ScalarType for
/// jiff::Timestamp` is `E0117`, both halves foreign, which is the same wall `graphql::filter::
/// duration` hit and answered with a newtype of its own. A citizen this crate is going to give a
/// scalar, a comparison and a storage shape to has to be a type this crate owns.
///
/// It is also what keeps the SHAPE the framework's decision rather than jiff's: the range and the
/// precision above are promises made here, and the columns an instant occupies are chosen here.
///
/// # The range, and what refuses
///
/// [`MIN`](Self::MIN) and [`MAX`](Self::MAX) are jiff's own bounds and they are not the `i64`
/// nanosecond ceiling a Unix timestamp usually carries: there is no 2262 problem here, and no
/// 1677 one either. What they ARE is ±9999 years, chosen by jiff so that either bound combined with
/// any legal zone offset still lands on a representable civil date.
///
/// So the one lossy direction is a [`SystemTime`] from outside that span, and it REFUSES —
/// [`TryFrom`] rather than a saturating [`From`], because an instant substituted for the one a
/// caller handed over is a wrong answer reported as a right one. Nothing else about that crossing is
/// lossy: nanoseconds survive it in both directions.
///
/// # Ordering, equality and hashing are the INSTANT's
///
/// All three are derived, and on a one-field newtype a derive IS the delegation. What makes it the
/// right delegation is that an instant has nothing to normalise: this type holds no zone and no
/// offset, so two spellings of one moment — `2026-08-09T21:14:03+09:00` and
/// `2026-08-09T12:14:03Z` — parse to one value that compares, hashes and renders as one.
;
/// Why a stored `(secs, nanos)` pair is not an instant.
///
/// Both variants are REFUSALS of a stored value rather than of a caller's arithmetic, which is what
/// puts them on a decode path: [`Assemble`](crate::Assemble) turns one into
/// [`sqlx::Error::ColumnDecode`] naming the `nanos` column, and the MongoDB family turns it into
/// [`MongoTypeError::Range`](crate::query::mongo::MongoTypeError::Range). A column pair this type
/// cannot hold is the same situation as a blob of the wrong width or an integer past its type, and
/// it is answered the same way — loudly, at the row that holds it.
///
/// No [`PartialEq`], deliberately: [`jiff::Error`] has none, so an equality here would either
/// compare rendered text — which is jiff's to change — or ignore the half that carries the reason.
/// A test asserts on the VARIANT and on the pair, which is what a caller can act on.
/// Legal though [`jiff::Timestamp`] is foreign and [`From`] is: the trait's PARAMETER is this
/// crate's type, which is what the orphan rule asks for.
/// Fallible in this direction alone, and by RANGE rather than by precision — see the type's note.
/// jiff's own crossing has the same shape and the same reason, so this is a delegation rather than a
/// second policy.
/// [`From`] and not [`TryFrom`], because jiff's own crossing is a [`From`] and this delegates to it
/// rather than inventing a second policy. What that impl assumes is a platform time wide enough for
/// the whole span, which is true where this crate runs — a `timespec`'s `i64` seconds hold ±9999
/// years many times over — and is not a universal fact: a `FILETIME`-based [`SystemTime`] begins at
/// 1601, and an instant before it would panic inside jiff. Recorded rather than guarded, since a
/// guard here would be this crate answering for a conversion it does not own.
/// RFC 3339, with the fewest fractional digits that render the value exactly — `2026-08-09T21:14:03Z`
/// for a whole second, `2026-08-09T21:14:03.123456789Z` for one carrying nanoseconds. Never a bare
/// integer, which is the form a client cannot read.
///
/// A NEGATIVE year has no RFC 3339 spelling and takes ISO 8601's expanded form instead
/// (`-009999-01-02T01:59:59Z`, which is [`MIN`](Self::MIN)); every instant from the epoch onwards is
/// RFC 3339 exactly.
///
/// The [`Formatter`](fmt::Formatter) is PASSED THROUGH rather than written into, so jiff's own
/// precision option survives the newtype: `{:.3}` still asks for milliseconds and `{:.0}` still
/// truncates the fraction away. A `write!(f, "{}", …)` here would drop both in silence.
/// The inverse of [`Display`](fmt::Display), and jiff's parser rather than a second one: an offset
/// spelling is accepted and NORMALISED to the instant it names, and a string with no offset at all is
/// refused — a civil datetime is not an instant, and guessing UTC for it would invent the one fact it
/// is missing.
///
/// The error is jiff's own, kept rather than re-worded: it names the component it refused and where
/// in the input, which is more than a wrapper of this crate's would say.
/// The WALL-CLOCK reading of the same house — an instant's local twin, and the first citizen here
/// whose value may decline to name an instant at all.
///
/// Gated on `time` because its wall-clock leaf reaches a column through
/// [`Temporal<time::PrimitiveDateTime>`](crate::Temporal), and on `derive` because its filter is
/// DECLARED through `#[ingraph(composed)]` as the media-time house's five are. Neither is the
/// framework's own instant's situation, which is why that type stands in every build and this one
/// stands where a build has asked for a date library.
pub use ;
pub use SqlLocalTimestampComparison;