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
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
//! [`LocatedDetection<T>`](LocatedDetection): a classification bound to the rectangle it was found
//! in, with the box REQUIRED.
use fmt;
use crate::;
use ;
/// **A CLASSIFICATION AND ITS PLACE** — what was found, how sure the finder was, and WHERE.
///
/// ```text
/// ┌─ bbox ───────────┐
/// │ │ detection: "person" @ 0.94
/// │ ● │
/// └──────────────────┘
/// ```
///
/// # THE BOX IS REQUIRED, and that is the ruling this type exists to state
///
/// There is no `Option` here and there will be none. A located detection whose box went missing is
/// not a located detection — it is a [`Detection`], which is a type this house already has. One
/// shape with an optional box would make *a whole-frame classification* and *a subject detection
/// whose geometry was lost* the same value, so every consumer reading a location would carry a
/// branch that says nothing, and no query could tell the two populations apart.
///
/// So the pairing is `avanalyze`'s own, whose contract calls it *a classification bound to a
/// bounding box: the shape used for both human and animal subjects*, and whose constructor is
/// INFALLIBLE for the reason this one is — *both halves have already been validated by their own
/// constructors*.
///
/// # GENERIC over the GEOMETRY component, and over nothing else
///
/// `T` is what the box is measured in, exactly as it is for [`BoundingBox<T>`] — a normalized frame
/// writes `LocatedDetection<NormCoord>`, a raster pipeline `LocatedDetection<u32>`, a metric one
/// `LocatedDetection<f64>`. The openness is the geometry family's and this type inherits it whole:
/// nothing here has an opinion about a unit it was never told.
///
/// **There is no second parameter for the confidence's width**, and the reason is
/// [`Detection`]'s own: the half that holds the confidence names [`Score`](crate::Score) rather than
/// taking a width, so this type has one axis to be generic over and it is the geometry's. See
/// [`Detection`], where the door that a second parameter would come through is named.
///
/// **NO DEFAULT TYPE PARAMETER.** `LocatedDetection` bare does not compile, on the ruling
/// [`Confidence<S>`](crate::Confidence) set and [`BoundingBox<T>`] kept: a default would make one
/// world the silent reading of a type whose whole subject is that the world is the caller's to name.
///
/// # Examples
///
/// ```
/// use ingraph::{BoundingBox, Detection, Label, LocatedDetection, Score};
///
/// let subject = LocatedDetection::new(
/// Detection::new(Label::new("person").unwrap(), Score::new(0.94).unwrap()),
/// BoundingBox::try_unit(0.1, 0.2, 0.3, 0.6).unwrap(),
/// );
///
/// assert_eq!(subject.label().as_str(), "person");
/// assert_eq!(subject.bbox().width().get(), 0.3);
///
/// // The same shape in a raster world, measured in pixels.
/// let pixels = LocatedDetection::new(
/// Detection::new(Label::new("cat").unwrap(), Score::new(0.5).unwrap()),
/// BoundingBox::new(12_u32, 40, 200, 150),
/// );
/// assert_eq!(pixels.bbox().height(), 150);
/// ```
// NOT `Copy`, where the geometry half is: a finding carries a [`Label`], a label carries text, and
// text is not a register move. The box's own `Copy` is untouched and reaching one through
// [`bbox`](LocatedDetection::bbox) still costs nothing.
/// The geometry half's segment.
///
/// `bbox` rather than `box`, and the reason is Rust rather than taste: `box` is a reserved word, so
/// a field a declaration might one day want to name after this column could not be spelled. The
/// producers this framework has met use the same four letters.
pub const BBOX: &FieldName = new;
/// **The SIX columns a located detection spans**: the detection's two, FLATTENED, then the box's
/// four under their own name.
///
/// # The classification FLATTENS and the geometry does not, and neither side chose that
///
/// The detection's entry is [`flattened`], which lends no name, so a located detection at `subject`
/// reaches `subject_label` and `subject_confidence` — the same two columns a bare [`Detection`] at
/// `subject` occupies. Naming it would have given `subject_detection_label`, which says one word
/// twice and buys nothing: this type holds exactly one classification, so there is nothing for that
/// segment to disambiguate. That is
/// [`DetectedLanguage`](crate::primitives::lang::DetectedLanguage)'s own arrangement, in the other
/// family's spelling.
///
/// The box KEEPS its name for [`TimeRanged<T>`](crate::TimeRanged)'s reason, and it is the stronger
/// of the two: `BoundingBox<T>`'s own segments are `x`, `y`, `width`, `height`, and a splice would
/// put four independent names into the holder's namespace beside a `label` and a `confidence`. Here
/// nothing collides today — but the `bbox` segment is what makes a collision UNREPRESENTABLE rather
/// than merely absent, and it costs one segment.
///
/// # The LEAF GUARD is inherited rather than restated
///
/// `BoundingBox<T>`'s own `SEGMENTS` asserts that its component spans one column, and this row reads
/// that const — so a composite component meets the box's own `E0080`, naming the box's rule, at the
/// place a reader would go looking for it. A second assertion here would be a second sentence about
/// one fact.
///
/// ```compile_fail,E0080
/// use ingraph::{ColumnKind, LocatedDetection, TimeRange};
///
/// const _: usize = <LocatedDetection<TimeRange> as ColumnKind>::SEGMENTS.len();
/// ```
/// A located detection is one column value when its classification and its region both are — the
/// classification through its own row, so the box's derived area plays no part in what the box
/// itself compares equal.
/// **The order those SEVEN columns mean, and the box's derived leaf is in NO level of it.**
///
/// Six levels over seven leaves: `label`, `confidence`, then the rectangle's four value leaves in
/// the sequence the box declares them. The seventh leaf is the box's `area` — see
/// [`BoundingBox`]'s own `ORDER`, where the argument is made — and it is absent here for the same
/// reason it is absent there.
///
/// # THE SEQUENCE IS THE DECLARATION'S, and stating it is still not redundant
///
/// Every level is where it was, so this const claims nothing about how findings sort. What it does
/// is make the term EXPAND: a composite that leaves this at its default keeps a WIDE term whose
/// keyset row value is its whole width, and this type's whole width now contains a derived leaf it
/// inherited from the box. Stating the sequence turns one seven-column row value into six
/// one-column levels, which is the 2026-08-29 law's structural half — *every structural judgment
/// walks value leaves only* — executed by a citizen that acquired its index leaf from a COMPONENT
/// rather than by computing one.
///
/// That inheritance is the general rule this type is the first case of: **a holder of a citizen with
/// a derived leaf owes a sequence of its own**, because a wide term does not know that one of the
/// columns beneath it is an index. `MediaTimeRange` is the same sentence one house over, holding two
/// instants.
pub const ORDER: & = &;
/// **The VALUE one of a located finding's six levels compares** — the per-leaf vocabulary this
/// citizen publishes beside its sequence.
///
/// The classification's two members carry their own types and the geometry's carry the box's own
/// leaf vocabulary rather than restating it, which is the same nesting the SEGMENTS take: a rename
/// or a widening in the geometry house moves this face too, and there is no second list to drift
/// from.
///
/// The numbering is the LEAF numbering — `label` is `0`, `confidence` is `1`, and the box's four
/// value leaves are `2` through `5`. Leaf `6` is the box's derived area, and there is no member for
/// it.
/// One leaf is the same as another leaf when it is the SAME leaf holding the same value — never
/// across kinds, so a label is never equal to a confidence even where both compare true against
/// another value of their own kind.
/// **The six VALUE leaves, the geometry's four delegated, and [`None`] for the derived seventh.**
/// **The KEYSET position of ONE leaf**: which leaf, then that leaf's own bytes — the geometry's
/// members carrying the box's own tag beneath this one.
/// **ONE BIND OUT**, through the row the leaf's own type already had.
/// **The DECLARED half — SEVEN words**, the detection's two and the box's five, each read off the
/// half that owns it.
///
/// The arity is FIXED at seven, and both halves are why: a [`Detection`] is two leaves by
/// construction, and a [`BoundingBox<T>`] is five — four it holds and one it derives — because its
/// own leaf guard says so. That is what puts this type on the side of the boundary
/// [`TimeRanged<T>`](crate::TimeRanged) records rather than under it — a generic PAYLOAD has a word
/// count no length position can name, and a generic COMPONENT under a leaf guard has one the impl
/// can write down.
///
/// The FIFTH box word is the derived area's, read off the box's own row like the other four. This
/// type states nothing about it and could not: what a derived column is stored as is the house that
/// derives it's answer.
/// **THE ADMISSION**, and it DELEGATES to the geometry half: a located detection is one element of a
/// collection exactly where its box is.
///
/// `Vec<LocatedDetection<NormCoord>>` is what a detection pass produces — every face in a frame,
/// every subject in a photo — so this row is the one an edge table of findings needs. The
/// classification half is admitted unconditionally ([`Detection`]'s own row), so the box is the only
/// half with a question left to ask.
/// **SEVEN BINDS OUT** — the detection's two, then the box's five, with the one comma this level
/// owns between them.
///
/// Each half writes its own internal commas, which is the arrangement [`Carrier`](crate::Carrier)
/// documents: how many columns a value spans is the value's own answer, so a composite pushes
/// several placeholders with its own separators and the caller counts FIELDS. The derived column is
/// the box's own fifth push and nothing here computes it.
///
/// **AND SIX FOR A STRUCTURAL JUDGMENT**, which is this row's half of the 2026-08-30 pairing: the
/// value bind DELEGATES to each half's, so the box leaves its index leaf out where it always does
/// and the classification — which has none — binds the same two either way. A holder that took the
/// default here would bind seven placeholders under a six-column row value, which is a statement no
/// engine parses.
/// **AND ITS COLUMNS BACK IN** — the classification flat under the address it was given, then the
/// box beneath its own seat.
///
/// [`assembled_flattened`](crate::assembled_flattened) is what makes the first half read at the
/// holder's own level, which is the read side of [`flattened`] and the same pairing every spliced
/// part in this crate has. Every refusal this row can produce is a half's own — an empty label, a
/// confidence outside the interval, a coordinate outside the frame — each naming the column that
/// held it.
/// **THE KEYSET POSITION** — the classification, then the box, each behind its own four-byte length.
///
/// [`Detection`]'s row one file over carries the argument, and it is unchanged one level up: this
/// holder's first member is variable-width, so there is no constant split point and the framing is
/// the framework's own [`write_member`](crate::cursor::write_member) pair rather than a delimiter
/// invented here. The box RIDES that framing unchanged whatever its component's width is — it is
/// handed exactly the bytes it wrote, which is the contract its own division already depends on.
///
/// The ORDER the bytes encode is the columns' and not a claim about findings, for the reason neither
/// this type nor either of its halves publishes an [`Ord`].
/// What guards a [`LocatedDetection<T>`] column — its own filter at both seats.
///
/// The component's filter is resolved through [`PayloadFilter<T>`](crate::PayloadFilter) rather than
/// listed, which is what keeps this row FRAMEWORK-OPEN: a geometry component declared in a
/// downstream crate reaches this filter by having a default marker, which every column type already
/// has. That is [`BoundingBox<T>`]'s own row, read one level up, and it reads the same alias rather
/// than writing a second.
/// The interpretation a [`LocatedDetection<T>`] field is read under — the COMPOSITE reading, because
/// the value occupies columns of its own and all six can be absent together.
/// **A COLLECTION of located detections is asked through the QUANTIFIERS alone** — [`Detection`]'s
/// own ruling, which this type inherits along with the float that makes it.
///
/// `any` carries the whole [`LocatedDetectionFilter`], so *a person was detected confidently in the
/// top-left quadrant* is ONE element question — which is the shape that matters here and the one a
/// per-column reading could never state: asked of the collection separately, the label, the
/// confidence and the box would each be answered by a different finding.
/// The filter that guards a [`LocatedDetection<T>`] column: the CLASSIFICATION axis flattened, and
/// the GEOMETRY beside it.
///
/// ```text
/// input LocatedDetectionF32Filter {
/// label: LabelFilter confidence: ConfidenceFilter
/// bbox: BoundingBoxF32Filter
/// }
/// ```
///
/// # The classification axis FLATTENS on the wire exactly as it does in the columns
///
/// A client writes `{ label: { eq: "person" }, confidence: { gte: 0.8 }, bbox: { … } }` — three
/// names at one level, which is the same shape the six columns take. The nesting the Rust struct has
/// is an authority rather than a wire fact: this type holds a whole [`DetectionFilter`], so a slot
/// added to that filter appears on this face with it and nothing here can drift out of step. That is
/// [`DetectedLanguageFilter`](crate::primitives::lang::DetectedLanguageFilter)'s
/// `#[ingraph(flatten)]`, hand-written because this filter is GENERIC and that word takes a concrete
/// struct.
///
/// The box does NOT flatten, for the reason the storage row gives: its four facets are `x`, `y`,
/// `width` and `height`, and a splice would put them in a namespace beside `label` and `confidence`
/// with nothing able to say whether a future facet collides.
///
/// # The THREE guard ONE finding, and that is why they share a filter
///
/// A frame carries several findings. Were the questions asked of the frame separately, *a person,
/// confidently, in the top-left* would be answered by a frame holding a person at `0.2` in the
/// bottom-right and a bicycle at `0.9` in the top-left — each clause true of a different finding.
/// Holding all three in one filter over one finding makes that unrepresentable rather than merely
/// wrong.
///
/// # NO WHOLE-FINDING OPERATOR
///
/// None of `eq`, `ne`, `in` or an ordering, on the two houses' shared terms: the leaf tuple IS the
/// conjunction of the facets, a whole-value `ne` over a composite is a disjunction, a per-column
/// `in` is the cartesian product, and six numbers-and-a-word have no total order. See
/// [`DetectionFilter`] and [`BoundingBoxFilter`](crate::BoundingBoxFilter), where each half argues
/// its own.
///
/// SPATIAL PREDICATES are the door the geometry half leaves open, and this type inherits it: the day
/// `contains`/`intersects`/`within` arrive at [`BoundingBoxFilter`](crate::BoundingBoxFilter), the
/// `bbox` facet here carries them with no line of this file changing.
// The four are written out rather than derived, for `BoundingBoxFilter`'s reason: a derive would
// bound `CF` on the whole type, where each of these needs it on itself alone — a filter over a
// component family that publishes no `Debug` is still a filter a caller can build and clone.