ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! 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 bson::{Binary, Bson, spec::BinarySubtype};

use crate::{BeI128, BeU64, BeU128, Count};

/// 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.
pub trait MongoCarrier {
  /// This value as the BSON this crate stores it as.
  fn to_bson(&self) -> Bson;
}

/// 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.
impl<T: MongoCarrier> MongoCarrier for &T {
  #[inline]
  fn to_bson(&self) -> Bson {
    T::to_bson(self)
  }
}

/// **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.
impl<T: MongoCarrier> MongoCarrier for Option<T> {
  #[inline]
  fn to_bson(&self) -> Bson {
    match self {
      Some(value) => value.to_bson(),
      None => Bson::Null,
    }
  }
}

/// The rows, each naming the BSON arm rather than delegating to [`From`] — see the module note for
/// the `u32` measurement that decides it.
macro_rules! carriers {
  ($( $ty:ty => |$value:ident| $bson:expr ),+ $(,)?) => {
    $(
      impl MongoCarrier for $ty {
        #[inline]
        fn to_bson(&self) -> Bson {
          let $value = self;
          $bson
        }
      }
    )+
  };
}

carriers! {
  bool => |v| Bson::Boolean(*v),
  i8 => |v| Bson::Int32(i32::from(*v)),
  i16 => |v| Bson::Int32(i32::from(*v)),
  i32 => |v| Bson::Int32(*v),
  i64 => |v| Bson::Int64(*v),
  u8 => |v| Bson::Int32(i32::from(*v)),
  u16 => |v| Bson::Int32(i32::from(*v)),
  u32 => |v| Bson::Int64(i64::from(*v)),
  f32 => |v| Bson::Double(f64::from(*v)),
  f64 => |v| Bson::Double(*v),
  String => |v| Bson::String(v.clone()),
  // The house's own text carrier, on `String`'s own terms: the same `Bson::String`, no second BSON
  // shape for one kind of text.
  smol_bytes::Utf8Bytes => |v| Bson::String(v.as_str().to_owned()),
  Vec<u8> => |v| Bson::Binary(Binary {
    subtype: BinarySubtype::Generic,
    bytes: v.clone(),
  }),
  BeU64 => |v| blob(v.to_blob()),
  BeU128 => |v| blob(v.to_blob()),
  BeI128 => |v| blob(v.to_blob()),
  Count => |v| Bson::Int64(v.to_signed()),
  // The ONE row in this table with a subtype of its own — see the uuid note above for why `Uuid`
  // and not `Generic`, and for what a DOCUMENT has to be written through for the two to agree.
  uuid::Uuid => |v| Bson::Binary(Binary {
    subtype: BinarySubtype::Uuid,
    bytes: v.as_bytes().to_vec(),
  }),
}

// **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.
#[cfg(feature = "regex")]
carriers! {
  regex::Regex => |v| Bson::String(v.as_str().to_owned()),
}

/// **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.
impl<S: crate::ConfidenceCarrier + MongoCarrier> MongoCarrier for crate::Confidence<S> {
  #[inline]
  fn to_bson(&self) -> Bson {
    self.get().to_bson()
  }
}

/// **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.
impl MongoCarrier for crate::Timestamp {
  fn to_bson(&self) -> Bson {
    let mut instant = bson::Document::new();
    instant.insert(
      crate::primitives::timestamp::SECOND.as_str(),
      Bson::Int64(self.as_second()),
    );
    instant.insert(
      crate::primitives::timestamp::NANOSECOND.as_str(),
      Bson::Int32(self.subsec_nanosecond()),
    );
    Bson::Document(instant)
  }
}

/// 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.
fn blob<const N: usize>(bytes: [u8; N]) -> Bson {
  Bson::Binary(Binary {
    subtype: BinarySubtype::Generic,
    bytes: bytes.to_vec(),
  })
}

#[cfg(test)]
mod tests;