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
//! GEOMETRY: the shapes an analyzer reports a FINDING'S LOCATION as, and the one coordinate this
//! crate names to measure them in.
//!
//! # It is a FAMILY, and it is the first here that is DOMAIN-NEUTRAL
//!
//! [`lang`](super::lang) arrived as a family because a STANDARD does not come one type at a time,
//! and [`mediatime`](super::mediatime) because a tick count is not a time until a timebase says what
//! a tick is. This house arrives as one for a third reason: a point, a rectangle and a quadrilateral
//! are ONE geometry read at three arities, they share a component and an origin convention, and a
//! caller that has any of them has the others within a frame.
//!
//! Nothing here knows what a box is a box OF. A face detection, a text line, a saliency region, a
//! table cell on a scanned page and a subject mask's extent are five callers with one rectangle
//! between them, and the composite that pairs one of these with a label and a confidence is NOT this
//! module's — it is [`detect`](super::detect)'s, one door over, which consumes these. That split is
//! what makes the house domain-neutral rather than a vision library with the vision taken out: the
//! types below would be the same types for a PDF's glyph boxes, which have no detector and no score
//! anywhere near them.
//!
//! **The pairing landed BESIDE this house rather than downstream of it**, and the sentence that
//! stood here said otherwise — *they belong to the crate that has the labels*. The ruling that sent
//! the geometry cluster here sent the classification trio after it on the same ground: a label and a
//! confidence are no more a camera's than a rectangle is. What stayed downstream is the layer above
//! both — the poses, the masks and the landmark contours, which are a producer's vocabulary rather
//! than a shape. See [`detect`](super::detect), where that line is drawn from the other side.
//!
//! # GENERIC over the component, and the parameter is the ruling
//!
//! [`Point2<T>`], [`BoundingBox<T>`] and [`Quad<T>`] are DUMB HOLDERS over whatever a declaration
//! measures in. **Not everyone wants a normalized coordinate** — a metric pipeline measures in
//! `f64` metres, a raster one in `u32` pixels, a quantised model in a half-width float — and a
//! holder that admitted one of those and refused the rest would be a holder with an opinion about a
//! unit it was never told.
//!
//! [`NormCoord`] is the ONE instantiation this crate names, and it is named because the normalized
//! frame is the one world with a rule that is not the caller's: a coordinate in `[0.0, 1.0]` is a
//! fraction of a frame whatever the frame is. Every other `T` a caller brings is admitted without
//! being enumerated — the openness is the holders', and a roster of blessed widths would be exactly
//! the closed surface this framework does not build.
//!
//! # WHERE AN INVARIANT LIVES: on the component, or on ONE instantiation's impl block
//!
//! The rule this house is arranged by, and it is worth stating once because it decides every
//! question below it:
//!
//! - **A rule about ONE NUMBER lives on the component.** Finite, and inside `[0.0, 1.0]` — that is
//!   [`NormCoord::new`], and every holder gets it for free by holding one. An invalid value dies at
//!   the component's constructor and never reaches a shape.
//! - **A rule about a SHAPE IN A UNIT FRAME lives on that shape's `BoundingBox<NormCoord>` impl
//!   block, and nowhere else.** A strictly positive extent, and an edge that does not run past
//!   `1.0`, are true of a normalized rectangle and meaningless for a metric or a pixel one. So
//!   [`BoundingBox::try_unit`] is where they are checked, and `BoundingBox::new` — the generic
//!   constructor — checks nothing at all.
//!
//! A generic *is this degenerate* helper was considered and declined. It would need `T: PartialOrd`
//! plus a ZERO, and the zero is what still refuses it: a bound naming a distinguished value is a
//! numeric vocabulary this crate does not own, where a bound naming an OPERATOR is std's. When in
//! doubt the check stays on the specific impl, which is where it is true.
//!
//! # THE READINGS, and the arithmetic bound each one costs
//!
//! Two methods here compute rather than return, and each states its own bound at its own signature —
//! the arrangement [`rust-bound-minimization`'s fixpoint asks for][area] and the one every accessor
//! in this house already takes.
//!
//! | reading | bound | who is in |
//! |---|---|---|
//! | [`BoundingBox::area`] | `T: Copy + Mul<Output = T>` | [`NormCoord`], `f32`, `f64`, integer widths, any component with the operator |
//! | [`Quad::bounds`] | `T: Copy + PartialOrd + Sub<Output = T>` | `f32`, `f64`, integer widths — and NOT [`NormCoord`] |
//!
//! **The asymmetry is a census verdict rather than an oversight.** The closed unit interval is
//! closed under MULTIPLICATION — a product of two values in `[0, 1]` is in `[0, 1]` at every width —
//! and it is NOT closed under subtraction, `0.2 - 0.8` being `-0.6`. So the coordinate publishes the
//! one operator that is total on it and not the one that is not, and the box a normalized quad
//! reduces to is out of bounds rather than refused: closing it would mean an operator that
//! saturates, clamps or panics on the values its own domain excludes, which is the *value quietly
//! minted around the hole* the decode below refuses.
//!
//! [area]: BoundingBox::area
//!
//! # TOP-LEFT ORIGIN, and `xywh`
//!
//! `y` grows DOWNWARD and a rectangle is its top-left corner plus two extents. `avanalyze` — the
//! producer this framework has actually met — flips Vision's bottom-left normalized rectangles onto
//! that convention before a value is ever built, and states that bounding boxes, 2-D pose joints,
//! face landmarks and document quads all share it. A second convention here would be a translation
//! layer standing between this crate and every caller it has.
//!
//! A [`Quad`]'s corners are in PERIMETER WINDING ORDER — top-left, top-right, bottom-right,
//! bottom-left. That is the same producer's `DocumentSegment` contract, whose own note says what
//! reading them as `(TL, TR, BL, BR)` costs: *an implementation that reads them as `(TL, TR, BL,
//! BR)` builds a bow-tie out of every real document*. The order is pinned by a test here for the
//! same reason it is pinned by a conformance suite there.
//!
//! # A SECOND, INDEPENDENT CITIZEN: [`Radians<T>`](Radians)
//!
//! Everything above is the POSITION half of this house — a point, a rectangle, a quadrilateral, and
//! the one coordinate they are generic over. [`Radians<T>`](Radians) is the other neutral quantity a
//! producer's geometry needs and names nothing about a place: a face's roll, yaw and pitch, a
//! horizon's tilt. It shares this module for [`NormCoord`]'s own reason — a producer that has a
//! normalized frame typically has an angle beside it, and neither is anyone's business but this
//! crate's own numbers — and it is GENERIC over its carrier for the same reason
//! [`BoundingBox<T>`](BoundingBox) is: not everyone measures an angle in the same width, and a holder
//! with an opinion about one is a holder that was never asked.
//!
//! It is not a fourth arity of [`Point2`]/[`BoundingBox`]/[`Quad`]'s shared parameter — it holds ONE
//! `T` rather than fanning one out into several columns, so it carries none of their fixed-arity
//! machinery — and it carries no interval the way [`NormCoord`] does; see the type's own note for the
//! census that keeps the two apart. Its faces are FULLER than [`NormCoord`]'s own — a mongo carrier
//! and a GraphQL filter under its own name — because it is reachable as a bare, top-level column a
//! declaration names directly (a face's `roll: Option<Radians<f32>>`), where every holder's own
//! component today is reached only nested inside one of the three shapes above.
//!
//! # THE GATE: none, and the reason is the dependency law read where it runs out
//!
//! Every other vocabulary door in this crate is named for the DEPENDENCY it admits — `mediatime`
//! for the crate whose four types that family wraps, `half` for a width somebody else ships. **This
//! house has no dependency at all**: the types are this crate's own, over Rust's own numbers, and
//! the whole module is arithmetic and column names.
//!
//! So it is UNGATED, and the precedent is exact rather than argued from silence.
//! [`TimeRange`](crate::TimeRange) and [`TimeRanged<T>`](crate::TimeRanged) are a dependency-free,
//! GENERIC primitives family whose filter is HAND-WRITTEN, and they carry no word of their own;
//! [`Confidence`](crate::Confidence), [`Count`](crate::Count) and [`Timestamp`](crate::Timestamp)
//! are ungated beside them. The one dep-free family that DOES ride a word is
//! [`lang`](super::lang), and it rides `derive` because two of its five filters are DECLARED — a
//! tier it needs rather than a dependency it admits.
//!
//! **This house needs no tier either**, and that is a measurement rather than a preference: the
//! `#[ingraph(composed)]` derive takes a CONCRETE struct, so the three filters below — every one of
//! them generic over the component's filter — could not be declared through it whatever this module
//! wanted. They are hand-written on [`TimeRangedFilter`](crate::TimeRangedFilter)'s own road, and a
//! build that declines the declaration tier keeps every one of them.
//!
//! Each FACE beneath the family carries its own cross-gate, as every family here does: `sqlx` for
//! the binds and decodes, `async-graphql` for the wire.
//!
//! # The three layers, and the one crossing between them
//!
//! ```text
//!   domain                 crossing        storage
//!   NormCoord              identity        f32
//!   Point2<T>              per component   (T, T)
//!   BoundingBox<T>         per component   (T, T, T, T) + a DERIVED T
//!   Quad<T>                per component   (T, T) × 4
//! ```
//!
//! Every crossing is the COMPONENT's, applied per column, and no VALUE here is reduced or
//! canonicalised — which is why none of these types has an `exact` facet: a value that crosses
//! unchanged has one identity, and the leaf tuple is it.
//!
//! **ONE type carries a fifth column that is not part of its value.** `BoundingBox<T>` stores its
//! `area` — `width × height`, written by the bind and read by no decode — because *how much of the
//! picture is this* is the one question about a rectangle that is a single ordered number, and
//! asking it over the stored pair is an expression no index can serve. It is a DERIVED LEAF in the
//! sense [`ColumnShape`](crate::ColumnShape) rules: it serves the semantic filter alone, and every
//! structural judgment in the crate — the decode, an optional box's `None` test, a row-value
//! equality, a cursor — walks the four value leaves and never it. See [`BoundingBox`]'s own segment
//! note, where the whole ledger is written out, and its `ORDER`, where the derived leaf is
//! deliberately in no level at all.
//!
//! # What a DECODE can and cannot re-prove
//!
//! A read goes through the COMPONENT's constructor, so a stored number outside `[0.0, 1.0]` in a
//! `NormCoord` column is refused at the column that held it. That is the whole of what the type
//! system can re-establish from four independent columns.
//!
//! **The SUM rule is not re-checked on the way in, and the gap is recorded rather than papered
//! over.** A hand-written `UPDATE` can leave `x = 0.9, width = 0.5` — two valid coordinates whose
//! sum leaves the frame — and the decode will hand back a `BoundingBox<NormCoord>` that
//! [`try_unit`](BoundingBox::try_unit) would have refused. Closing it means a refusal in
//! [`Assemble`](crate::Assemble) for ONE instantiation of a generic row, which stable Rust cannot
//! spell — a specialised impl is what it would take — so the honest posture is to say where the
//! promise stops. `try_unit` is a CONSTRUCTOR's guarantee, not a column constraint, and a database
//! that wants one writes a `CHECK` this crate does not emit.
//!
//! # The wire faces
//!
//! Behind `async-graphql`: the three holders as GraphQL OBJECTS whose names COMPOSE from the
//! component's own — `BoundingBoxF32`, `Point2F32`, `QuadF32` for the normalized world, since a
//! coordinate publishes its width's roster scalar — and one input object per filter beside them.
//! The composition is not decoration: GraphQL keeps ONE FLAT NAMESPACE, so a schema holding a
//! metric box and a normalized one needs two names, and a single `BoundingBox` would be a name
//! async-graphql resolves in silence.
//!
//! There is no operand SCALAR anywhere in this house. A holder publishes an object and takes no
//! whole-value operand — see [`BoundingBoxFilter`], where the absence is argued — and
//! [`NormCoord`] publishes `f32`'s own roster scalar rather than a named one, on the ruling that
//! retired [`Score`](crate::Score)'s: a named scalar has to say something the roster does not, and
//! what a `NormCoord` scalar would have said is the INTERVAL, which is a constructor's promise
//! rather than a grammar.

mod bbox;
// The SQL side for all three, in ONE file for the wire faces' reason: three comparisons that are
// one lowering shape at three arities, read side by side.
#[cfg(feature = "sqlx")]
mod comparison;
mod coord;
// The wire faces for all three holders and all three filters in ONE file, where every other family
// here splits them per citizen. The shape is the reason: the three faces are one pattern at three
// arities — a composed name, an object of components, an input object of facets — and reading them
// side by side is what makes a divergence between them visible.
#[cfg(feature = "async-graphql")]
mod graphql;
mod point;
mod quad;
// The house's SECOND independent citizen, beside `coord` rather than under it: an angle shares this
// module's dependency-free, tier-free gate for the same reason `NormCoord` does — the type is this
// crate's own, over Rust's own numbers, with every face self-contained in its own file on this
// family's own convention. See the type's own note for why it carries no interval, why its faces are
// fuller than `NormCoord`'s own (a mongo carrier and a named filter, which no holder here has needed
// yet), and why — unlike the three composites above — it needs no leaf guard to stay honest about a
// generic carrier.
mod radians;

#[cfg(test)]
mod tests;

pub use bbox::{BoundingBox, BoundingBoxFilter, BoundingBoxLeaf, RefusedBox};
#[cfg(feature = "sqlx")]
pub use comparison::{SqlBoundingBoxComparison, SqlPoint2Comparison, SqlQuadComparison};
pub use coord::{NormCoord, OutsideTheUnitInterval};
pub use point::{Point2, Point2Filter};
pub use quad::{Quad, QuadFilter};
pub use radians::{RadianMath, Radians};