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
//! The per-storage-type binding: [`MongoCarrier`], and the BSON this crate stores each type as.
//!
//! It is `Carrier`'s twin with one axis removed. The SQL table is
//! keyed on (storage type × dialect), because `u64` binds natively on MySQL and needs a blob
//! elsewhere; there is one MongoDB, so this is a list.
//!
//! # The table
//!
//! | storage type | stored as | why |
//! |---|---|---|
//! | `bool` | `Boolean` | |
//! | `i8`, `i16`, `i32` | `Int32` | BSON's narrower integer is 32 bits, so three widths share it |
//! | `u8`, `u16` | `Int32` | both fit, and BSON has no unsigned type to widen into |
//! | `u32` | `Int64` | it does not fit `Int32` |
//! | `i64` | `Int64` | |
//! | `f32`, `f64` | `Double` | BSON's only binary float is 64-bit |
//! | `String` | `String` | |
//! | [`smol_bytes::Utf8Bytes`] | `String` | the same text, on `String`'s own terms |
//! | `Vec<u8>` | `Binary`, subtype 0 | the generic subtype, which is what a blob column is |
//! | [`Score`](crate::Score) | `Double` | the `[0.0, 1.0]` invariant is the domain's, not the column's |
//! | [`Confidence<f64>`](crate::Confidence) | `Double` | the same, at the width BSON's float already is |
//! | [`BeU64`](crate::BeU64) | `Binary`, subtype 0, 8 bytes | the escape a `u64` declares, and its bytes are the carrier's own |
//! | [`BeU128`](crate::BeU128), [`BeI128`](crate::BeI128) | `Binary`, subtype 0, 16 bytes | the same, for the width BSON has no integer for at all |
//! | [`uuid::Uuid`] | `Binary`, **subtype 4**, 16 bytes | BSON has a subtype that MEANS uuid — see the note below |
//! | `regex::Regex` (behind `regex`) | `String` | the PATTERN, on `String`'s terms — **never BSON's own `Regex`**, see the row's own note |
//! | [`Count`](crate::Count) | `Int64` | a cardinality is bounded by the store, so the narrowing crosses nothing — see the type's own row |
//! | [`Timestamp`](crate::Timestamp) | a sub-document of `secs` (`Int64`) and `nanos` (`Int32`) | two flat integers, both of which BSON holds exactly |
//! | `Language`, `ScriptSubtag`, `Region` ‡ | `String` | one canonical subtag is one word |
//! | `LanguageId` ‡ | a sub-document of `language`, `script`, `region`, `rest` — the last three `String` or `Null` | the four columns a table spans, nested rather than joined |
//! | `DetectedLanguage` ‡ | those four keys and `confidence` (`Double`), at ONE level | the identity's entry lends no name, so it has no key to nest under |
//!
//! ‡ **The language family's five rows ride the `derive` FEATURE**, which the family itself rides:
//! two of its types are DECLARED through `#[derive(ingraph::Filter)]`, so a build declining the
//! declaration tier has no such type to store. Each row is written beside that type's own SQL bind
//! rather than in the table below, which is where the family keeps every face it owes — see
//! `primitives::lang`, and `primitives::lang::id::storage`, where the composite's document shape is
//! decided and the reasoning recorded.
//!
//! # Every row matches what the DOCUMENT's own serializer writes, and one of them had to be measured
//!
//! A record's field of the same type is stored by serde through bson's serializer — the emitter
//! derives that pair, see `ingraph-codegen`'s `emit::mongo` — so a filter operand and the value it
//! is compared against reach BSON by two different routes. Where the two routes disagree about the
//! BSON TYPE, the disagreement is invisible in the filter document and visible in an index scan.
//!
//! Measured against bson 3.1: `Serializer::serialize_u32` is `Bson::Int64` unconditionally, while
//! `impl From<u32> for Bson` NARROWS to `Int32` when the value fits. So the obvious spelling —
//! `Bson::from(*self)` — would give a small `u32` a different BSON type in the filter than in the
//! stored document. `$eq` still matches, since MongoDB compares numerics across `Int32`/`Int64`
//! by value, but nothing else about the two documents agrees. The rows below write the arm rather
//! than delegating to [`From`], and `tests` pins the `u32` case.
//!
//! # What has NO row, and what a declaration does about it
//!
//! `u64`, `u128` and `i128` are absent because BSON has no unsigned 64-bit and no 128-bit integer.
//! That is the same shape they have on SQLite and Postgres, and it is deliberate on all three: a
//! type whose bytes a backend cannot hold has no row, and the declaration names a storage type that
//! fits. Here as there that type is [`BeU64`](crate::BeU64) or one of its two siblings, and the
//! escape is the same one because the carriers are the CRATE's rather than the SQL family's — the
//! split that made them nameable from a build with no `sqlx` in it is what this row set is the
//! consumer of.
//!
//! [`Count`](crate::Count) sits on the other side of that line, and it sits there for the SQL
//! family's own reason: a cardinality counts rows that EXIST, so it is bounded by the physical store
//! and its `Int64` is the whole value rather than a narrowing anybody pays for. The row calls
//! [`Count::to_signed`](crate::Count::to_signed) — the type's own codec, exactly as the three blob
//! rows call `to_blob` — so the value a MongoDB filter compares and the value a SQLite column holds
//! are produced by one function.
//!
//! **The bytes are the same bytes.** Each row calls the carrier's own
//! [`to_blob`](crate::BeU64::to_blob), which is the single authority for the encoding, so a `BeU64`
//! column holds one eight-byte big-endian blob whichever backend wrote it. A row spelling
//! `to_be_bytes` itself would agree today and be free to stop, and a shared name with two encodings
//! is worse than two names.
//!
//! MongoDB compares `BinData` by LENGTH, then SUBTYPE, then bytes. Every value of one carrier shares
//! the first two, so the comparison reduces to the bytewise one the big-endian encoding makes
//! numeric — which is the property that lets `$gt` and `$lt` answer over such a column. That is read
//! from MongoDB's documented BSON order rather than measured against a live server here, and
//! `legacy/ingraph`'s own `store::encode` states it the same way, from the same position above both
//! families. What IS pinned below is the half this crate owns: that the bytes are the carrier's.
//!
//! Legacy's two `BinData` rows are these rows for `u128` and `i128`, through those same shared
//! codecs. Its `u64` is where the two diverge, and the divergence is PR #74's ruling rather than
//! this change's: legacy binds `Int64` and refuses at RUNTIME past `i64::MAX`, where a missing row
//! moves the same no to the declaration.
//!
//! # THE UUID IS THE ONE ROW THAT IS NOT SUBTYPE 0, and the subtype is the whole of what it says
//!
//! Every other `BinData` above is `Generic` because the value is opaque bytes and BSON has nothing
//! more specific to call it. A uuid is the case BSON DID name: subtype **4** is *this binary is a
//! UUID*, and writing it is what makes a stored value legible to `mongosh`, to a driver's own uuid
//! reader and to an index the same way the other three backends' native forms are. It is the
//! 2026-08-29 ruling read on this backend — each backend's own best form — and it is what
//! [`id`](crate::TypedId)'s admission matrix has said a uuid key is stored as since that table was
//! written.
//!
//! The subtype is reachable with no bson feature at all: `BinarySubtype::Uuid` is an ungated variant
//! of the spec enum, and the `Binary` is built from `as_bytes` directly. bson's `uuid-1` feature buys
//! only the `From<uuid::Uuid>` conveniences, and this crate does not ask for it — the same posture
//! it takes to `bson/serde`.
//!
//! **Ordering is unaffected by the subtype being different, and that is worth stating** because
//! BSON's order puts SUBTYPE ahead of bytes: every uuid shares length 16 and subtype 4, so the
//! comparison reduces to the bytewise one exactly as it does for the three `Generic` rows above. It
//! reduces to the SAME bytewise order the other three backends use, which is what lets one cursor
//! page a uuid column on any of the four — see `column::stored`, where that argument is made across
//! all four backends at once.
//!
//! ## THE DOCUMENT SIDE HAS TO BE WRITTEN THROUGH `bson::Uuid`, and this is the row that says so
//!
//! This module's standing rule is that every row matches what the DOCUMENT's own serializer writes,
//! and this row is the one where that takes a deliberate act by the declaration. Measured against
//! bson 3.1: the serializer's uuid special case keys on the **newtype name** `bson::Uuid` mints, so a
//! `bson::Uuid` field serializes to `Binary`/subtype 4 and agrees with this row exactly. A bare
//! `uuid::Uuid` does not reach that case — it would serialize through `uuid`'s own `serde` rows,
//! which write a STRING under a human-readable serializer (`bson::Serializer` defaults to human
//! readable) and generic bytes under a raw one, so neither matches subtype 4.
//!
//! Nothing here can go wrong SILENTLY today, and the reason is the same one [`Timestamp`] gives
//! two rows down: this crate takes `uuid` with `default-features = false`, so `uuid::Uuid` has no
//! `serde::Serialize` in this graph at all and a `mongo(…)` declaration naming a bare one is `E0277`
//! at the declaration rather than a document that disagrees with its own filter. The escape is the
//! one that row names — a `type = "…"` naming [`bson::Uuid`], which is already a member of the id
//! vocabulary for exactly this reason and whose sixteen bytes are these sixteen bytes.
//!
//! It is recorded here so that a build which DOES unify `uuid/serde` in — a declarer's own
//! dependency can — meets the hazard as a written sentence rather than as an index scan that finds
//! nothing.
//!
//! # The `jiff` types are nameable here and still have no row, which is a different answer
//!
//! Their storage form is `Temporal<T>`, and it moved with the big-endian carriers, so this family
//! can spell it. What it cannot yet do is store one, and the reason is MongoDB's rather than a
//! module boundary's:
//!
//! - `Temporal<time::OffsetDateTime>` would carry as BSON's `UtcDateTime`, which is an `i64` of
//! MILLISECONDS. The crossing preserves nanoseconds — measured, in `comparison::temporal` — so a
//! row would drop six digits in silence, which is the failure this crate refuses for a duration on
//! MySQL through `MySqlDuration` rather than rounds.
//! - `Temporal<time::Date>`, `Temporal<time::Time>` and `Temporal<time::PrimitiveDateTime>` have no
//! BSON type at all: there is no date-only, no time-only and no zoneless-datetime value in the
//! format.
//! - `Temporal<i32>` — the ZONE OFFSET's storage form — is the one that could carry, an `i32` being
//! an ordinary BSON `Int32`. It has no row anyway, and deliberately: a row would be this wrapper
//! deciding a question the four above leave open, and it would put a bare number in a document with
//! nothing beside it to say what the number is. The house that needs one is
//! [`LocalTimestamp`](crate::LocalTimestamp), and it writes its own — see below.
//!
//! So the temporal question here is a real one about what a MongoDB column should hold, and it
//! arrives with the kind that needs it rather than being settled by whichever encoding was easiest
//! to write beside the rows above.
//!
//! # …and the two the FRAMEWORK owns do have rows, which is not a reversal of that
//!
//! [`Timestamp`](crate::Timestamp) is stored as two flat integers and no BSON date type is involved,
//! so the millisecond truncation that refuses `Temporal<time::OffsetDateTime>` has nothing to
//! truncate: the pair crosses exactly. [`LocalTimestamp`](crate::LocalTimestamp) is the same licence
//! at a composite: its own row writes a sub-document of a STRING, an `Int32` and a `Boolean`, none of
//! which is a BSON temporal type and none of which can lose a digit. The answers are about
//! encodings rather than about types, and the sentence above is the licence for both.
use ;
use crate::;
/// One storage type's BSON value.
///
/// Public, and deliberately so, for the reason `Carrier` is: this is
/// the surface a downstream scalar or enum joins the comparison vocabulary through, and a type with
/// a row here needs nothing else from this crate to be filtered on.
///
/// # Why it RETURNS where the SQL twin pushes
///
/// `Carrier::push_bind` is a method rather than an associated type so that a row can render more
/// than a placeholder — a cast, a function call — without the trait changing shape. There is no
/// such position here: a BSON operand IS a value, and the document has no text for a row to
/// contribute to. So the value comes back and the caller places it.
///
/// # It cannot fail, and that is the crossing's doing
///
/// A comparison already holds STORAGE values, chosen by the declaration and converted once at the
/// crossing, so by the time one reaches this trait there is nothing left to reject — see the
/// absent rows above for what a type that BSON cannot hold does instead, which is to have no row
/// and be refused at the declaration. `legacy/ingraph`'s twin returns a `Result` and its only
/// non-`Ok` path is a `u64` past `i64::MAX`, which is exactly the case a missing row covers here.
/// A borrowed operand carries exactly as the owned one does, which is what makes
/// `MongoScalarComparison<&'a i64>` a real type rather than an aspiration — the same property the
/// SQL family's blanket gives, and it matters most for the identity crossing, which otherwise
/// rebuilds a whole `Box<[V]>` to change nothing.
/// **ABSENCE is `null`**, which is MongoDB's own conflation of *written as null* and *never written*
/// rather than this crate's choice: `{f: {$eq: null}}` matches both, and `$sort` orders a missing
/// field exactly where it orders a null.
///
/// It is the exact mirror of [`MongoExtract for Option<T>`](crate::query::mongo::MongoExtract), which
/// is the invariant this table lives by — that one is *this read backwards, row for row*. A nullable
/// column is a storage type like any other, so a table missing its row would be one a document could
/// be read out of and not written back into.
///
/// # It writes the key rather than omitting it, and that is the RULED half
///
/// A document could say *this field is absent* by carrying no key at all, and the two are
/// indistinguishable to every predicate this backend renders — so the choice is free at the filter
/// and NOT free at the document. `replace_one` swaps the whole document, so a field the replacement
/// omitted is a field the stored document loses; writing the key is what makes a record whose optional
/// field went from `Some` to `None` come back holding `null` rather than come back missing the key. The
/// two read the same to a query today, and only because BSON says so — an `$exists` tells them apart,
/// and so does anything that walks the raw document.
///
/// [`query::mongo`](crate::query::mongo)'s own `operand` reads through this rather than matching, so
/// the keyset arm, the address predicate and the stored document cannot come to three answers about
/// what an absent value is.
/// The rows, each naming the BSON arm rather than delegating to [`From`] — see the module note for
/// the `u32` measurement that decides it.
carriers!
// **THE PATTERN AS A `String`, AND EXPLICITLY NOT `Bson::RegularExpression`** — the one row in
// this table whose obvious BSON arm is the wrong one.
//
// BSON HAS a regex type, and reaching for it here would mean something this column does not: a
// `RegularExpression` is an OPERATOR — MongoDB matches a stored string against it, exactly as
// `$regex` does — so a document written with one would turn every predicate over this field into a
// pattern MATCH against the other side. This column holds a pattern as a VALUE; a query asking
// `eq` about it is asking whether two patterns are the same text, not whether one matches the
// other. `String` is the arm that says that, and it is the same arm
// `smol_bytes::Utf8Bytes` takes for the same reason: one kind of text, one
// BSON shape.
//
// It also keeps the four backends telling ONE story. Every SQL dialect stores the pattern text in a
// `TEXT` column and compares it as text; a BSON `RegularExpression` would have made mongo the one
// backend where `eq` meant something else, which is a difference no declaration asked for and none
// could see.
//
// The flags a BSON regex carries are the second half of the refusal. A `RegularExpression` is a
// pattern AND an options string, and `regex::Regex` has no such field — its case-insensitivity and
// its multi-line reading are written INSIDE the pattern as `(?i)` and `(?m)`. So a crossing into
// that arm would have had to invent an options value, and inventing one is exactly what a carrier
// must not do.
carriers!
/// **A confidence is whatever BSON its WIDTH crosses as** — a `Double` at both widths that have a
/// column, since BSON's only binary float is 64 bits and both narrow widths widen into it exactly.
///
/// The bound is the membership rule: a confidence has a row here exactly where the width it measures
/// in has one. `[0.0, 1.0]` is the DOMAIN's invariant and not the column's, so nothing about it is
/// encoded — the constructor on the way back is what re-establishes it.
/// **The framework's own instant, as the two flat integers it is** — a sub-document holding `secs`
/// as an `Int64` and `nanos` as an `Int32`, under the same two names the SQL family's columns take.
///
/// # The `Temporal` refusal above does not reach it, and the licence is one sentence
///
/// That refusal is about BSON's DATE type: `UtcDateTime` is an `i64` of milliseconds, so a row for
/// a nanosecond-carrying instant would drop six digits in silence. **No BSON date type is involved
/// here** — the value is two integers, both of which BSON holds exactly — so nothing is lost and
/// the refusal has nothing to say about this row.
///
/// A sub-document rather than two fields spliced into the holder, which is the same asymmetry the
/// `flatten` refusal on this backend already states: a composite is FLATTENED into columns wherever
/// a table stores it and stays nested wherever a document does. So the two names are the segment
/// names unjoined, and a filter reaches them as `at.secs` and `at.nanos` where SQL reaches
/// `at_secs` and `at_nanos`.
///
/// BSON's own comparison order compares two sub-documents field by field, in the order they were
/// written, so a pair written by this row compares by seconds and then by nanoseconds — which IS
/// the instant's order, jiff's signs being matched between the two halves. That is read from
/// MongoDB's documented BSON order rather than measured against a live server here, the same
/// posture this module takes for `BinData`; the sort itself is not built.
///
/// # What a DOCUMENT can hold is a narrower question, and the answer today is measured
///
/// This row is what a FILTER operand and — since the write half landed — what a STORED DOCUMENT is
/// written through: [`MongoWrite::document`](crate::query::mongo::MongoWrite::document) walks this
/// table exactly as [`from_document`](crate::query::mongo::MongoQuery::from_document) walks
/// [`MongoExtract`](crate::query::mongo::MongoExtract)'s. So nothing about this type stops it being
/// stored by the lane.
///
/// What still narrows it is the EMITTED row's own derives: `ingraph-codegen`'s mongo family derives
/// serde's pair on the document struct, and no storage type this crate ships carries a serde row — so
/// a declaration naming a bare `Timestamp` column under `mongo(…)` is `E0277` at the declaration,
/// *the trait bound `Timestamp: serde::Serialize` is not satisfied*. That is the same answer a
/// `BeU64` column gets there and the same escape applies: the declaration names a `type = "…"` with
/// its own conversions, which is what the derive corpus's `StoredTrack` already does for exactly this
/// reason.
///
/// The two halves no longer agree about WHY, and the gap is recorded rather than closed here: the
/// derive is kept for a consumer's own `bson::to_document`/`from_document` — see `emit::mongo`, which
/// says so — and it is now the only party asking for serde, the framework's own read and write both
/// going through this crate's two tables. Removing it would widen what a mongo row may hold to
/// exactly what those tables cover, and that is the emitter's change rather than this file's.
/// The generic-subtype `BinData` a big-endian carrier stores as.
///
/// One function for the three rows so that the SUBTYPE is decided once: a `Vec<u8>` column and a
/// carrier's blob are the same kind of value to MongoDB, and BSON's comparison order puts subtype
/// ahead of bytes — so three rows free to pick their own would be three orderings.