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
//! The second citizen: [`TimeRanged<T>`], a payload beside the stretch of timeline it occupies, and
//! the filter that guards one.
use fmt;
use crate::;
use ;
/// A `T` and WHEN it was — the shape a timed analysis emits, with the timing held once and the
/// payload left alone.
///
/// ```text
/// Vec<TimeRanged<DetectedLanguage>> which language was spoken, span by span
/// Vec<TimeRanged<()>> where the speech was, and nothing about it
/// ```
///
/// # The RANGE is a [`TimeRange`] and not two instants, which is the whole point of the pair
///
/// A payload with `start` and `end` fields of its own carries the invariant nowhere: nothing stops
/// the two being written in the wrong order, and every reader has to decide again what to do about
/// it. Holding a [`TimeRange`] makes `start <= end` a property of the value rather than a rule about
/// it, and it makes the four columns, the sub-document, the cursor and the three interval words the
/// range's own rather than this type's.
///
/// # `T` IS THE PARAMETER, and this type asks nothing of it
///
/// No bound on the struct. What a payload owes is asked at each FACE and nowhere else — a stored one
/// owes [`ColumnKind`](crate::ColumnKind) and its carriers, a crossed one owes the wire rows, a
/// filtered one owes a default marker — so a `TimeRanged<T>` over a payload with none of them is
/// still a value a caller can build, hold and match on. That is the same posture
/// [`Confidence<S>`](crate::Confidence) takes with a difference worth naming: a confidence's width
/// vocabulary is SEALED because each member is a measurement, and a payload vocabulary is OPEN
/// because a payload is whatever a declaration holds.
///
/// # Equality is the PAIR's, and there is NO order
///
/// [`Eq`] and [`Hash`] are derived and compose the two halves. [`Ord`] is NOT, and the reason is
/// [`TimeRange`]'s: that type declines it because a stretch has three candidate orders and no
/// single one to derive, so a pair holding one cannot manufacture the order its half refuses. The
/// KEYSET's order is a storage fact stated at [`CursorValue`](crate::CursorValue)'s row in this
/// house's `storage` module, where a page's need for *an* order does not become a claim about
/// *the* order.
///
/// # Examples
///
/// ```
/// use ingraph::{TimeRange, TimeRanged, Timestamp};
///
/// let start: Timestamp = "2026-08-28T09:00:00Z".parse().unwrap();
/// let end: Timestamp = "2026-08-28T09:01:00Z".parse().unwrap();
/// let minute = TimeRange::new(start, end).unwrap();
///
/// let spoken = TimeRanged::new(minute, "zh");
/// assert_eq!(spoken.range().start(), start);
/// assert_eq!(*spoken.data(), "zh");
///
/// // The payload moves without the timing being rebuilt.
/// let upper = spoken.map(str::to_uppercase);
/// assert_eq!(upper.range(), &minute);
/// ```
/// The payload, then its stretch in brackets — `zh (2026-08-28T09:00:00Z/2026-08-28T09:01:00Z)`.
///
/// A RENDERING rather than a round trip, exactly as
/// [`DetectedLanguage`](crate::DetectedLanguage)'s is and for its reason: the pair has no spelling
/// any standard defines.
/// What guards a [`TimeRanged<T>`] column: the RANGE's own filter, and the PAYLOAD's own filter.
///
/// | facet | slot | operand | asks about |
/// |---|---|---|---|
/// | RANGE | `range` | [`TimeRangeFilter`] | the stretch — three interval words and two ends |
/// | PAYLOAD | `data` | `T`'s own filter | whatever the payload's own family asks |
///
/// # The two guard ONE value, and that is why they share a filter
///
/// It is [`DetectedLanguageFilter`](crate::DetectedLanguageFilter)'s argument at a different pair. A
/// track carries several timed detections; asked separately, *Chinese* and *in the first minute*
/// would be answered by a track speaking English in the first minute and Chinese in the tenth — each
/// half true of a different span. Holding both in one filter over ONE span makes that
/// unrepresentable rather than merely wrong, and the quantified reading below is what carries it to a
/// collection.
///
/// # NEITHER facet flattens, and the reason is that `T` is a PARAMETER
///
/// [`DetectedLanguageFilter`] splices its identity because it knows what that identity's slots are
/// called. This face cannot know: `TF`'s slot names are the payload family's, so a splice would put
/// two independent field sets in one namespace with nothing able to say whether they collide. Both
/// facets therefore keep their names, on the wire and — for the payload — in the columns as well.
///
/// The RANGE's columns are the one place the two answers differ, and the argument is made where the
/// segments are: see this house's `storage` module.
///
/// # `TF` rather than `T`, and the alias that resolves one from the other
///
/// The parameter is the payload's FILTER because that is what this struct holds, which is
/// [`ListFilter`](crate::ListFilter)'s own shape. A caller naming the payload instead spells
/// [`PayloadFilter<T>`](super::PayloadFilter), which is the path the marker rows below take.
/// The bound's row: [`is_empty`](TimeRangedFilter::is_empty), reached where the kind is a parameter
/// rather than a spelling.
// `Debug`, `Clone` and `PartialEq` are written out rather than derived, for the reason
// `ScalarFilter`'s are: a derive puts its bound on EVERY parameter, and here that is the same bound
// this file wants — but writing them out keeps the three consistent with the rest of the filter
// family and leaves the door open for a parameter that carries no such row.
/// What guards a [`TimeRanged<T>`] column — its own filter at both seats, the same reading
/// [`TimeRange`]'s row takes.
///
/// The payload's filter is resolved through [`PayloadFilter<T>`](super::PayloadFilter) rather than
/// listed, which is what keeps this row FRAMEWORK-OPEN: a payload type declared in a downstream
/// crate reaches this filter by having a default marker, which every column type already has.
/// The interpretation a [`TimeRanged<T>`] field is read under — the COMPOSITE reading, for
/// [`TimeRange`]'s reason: the value occupies columns of its own, all of which can be absent
/// together.
///
/// The bound is the PAYLOAD's own default, and it is the membership rule spelled as a bound exactly
/// as [`Confidence<S>`](crate::Confidence)'s width rows spell theirs: a timed payload has a default
/// interpretation wherever its payload has one. A payload with none reaches `E0277` naming ITSELF,
/// which is the sentence a declaration's author can act on — where a row without the bound would
/// have named this wrapper and left them to work out which half was missing.
/// **A COLLECTION of timed payloads is asked through the QUANTIFIERS alone** — [`TimeRange`]'s row,
/// and its argument holds here with one clause added.
///
/// `any` carries the whole [`TimeRangedFilter`], so *some Chinese was spoken in the first minute* is
/// one element question: `any: { range: { overlaps: … }, data: { language: { eq: "zh" } } }`. That
/// is the shape this whole house was ruled for, and the seven operators a list reading would add
/// each hold a WHOLE timed payload — an operand pairing an exact nanosecond span with an exact
/// payload value, which is a row a caller can seldom spell and never means as a question.