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
//! DETECT: what an analyzer says it FOUND — the word, the confidence, and the two shapes a finding
//! comes in.
//!
//! # It is a FAMILY, and it is the SECOND here that is domain-neutral
//!
//! [`geometry`](super::geometry) arrived as one because a point, a rectangle and a quadrilateral are
//! one geometry read at three arities. This house arrives as one for a narrower reason: a
//! classification is a WORD and a NUMBER, and the only thing that varies between its members is
//! whether the finding also has a place. Three types, one subject.
//!
//! **Nothing here knows what a label is a label OF.** An image classifier's tag, a sound event, a
//! zero-shot query hit, a barcode's symbology and a document region's kind are five callers with one
//! `(word, confidence)` pair between them, and the vision-specific PAYLOADS that pair one of these
//! with a pose, a mask or a set of landmarks are NOT this module's — they belong to the crate that
//! has the poses, consuming 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
//! classified regions, which have no camera anywhere near them.
//!
//! # THE MODULE IS CALLED `detect`, and that is a census verdict
//!
//! The alternative was a `classify`-class name, and the word this house is built from decided it:
//! the types are [`Detection`] and [`LocatedDetection<T>`], so a module named `classify` would put a
//! reader through one translation on every path they ever wrote. The word is also the RULING's own —
//! the seal that sent this cluster here names it, and it names an `assess` house beside it for the
//! frame-level measurements that carry no label at all, so `detect` is one half of a pair rather
//! than a name chosen alone.
//!
//! The producer this framework has met calls the pair a classification and the type a detection in
//! one breath — *a labelled, scored classification with no geometry of its own* — so no name here
//! could have satisfied both words. The one that matches the types is the one that landed.
//!
//! # THE MEMBERS, in two clusters
//!
//! | type | holds | for |
//! |---|---|---|
//! | [`Label`] | a non-empty word | the vocabulary half of the two below it |
//! | [`Detection`] | a label and a [`Score`](crate::Score) | a WHOLE-FRAME classification — no geometry |
//! | [`LocatedDetection<T>`] | a detection and a [`BoundingBox<T>`](crate::BoundingBox) | a finding WITH a place — box REQUIRED |
//! | [`TextDetection<T>`] | words, a score and a box | what a RECOGNISER read out of a region |
//! | [`Symbology`] | a barcode standard, open | the vocabulary half of the row below |
//! | [`BarcodeDetection<T>`] | a payload, a symbology, a score and a box | what a DECODER read |
//! | [`DocumentSegment<T>`] | a [`Quad<T>`](crate::Quad) and a score | a four-cornered region a detector found |
//!
//! # THE PAYLOAD TRIO IS A SECOND CLUSTER, and what separates it is what a WORD IS
//!
//! The first three are built out of a [`Label`] — a CLASS a model chose from its own vocabulary. The
//! last four carry a PAYLOAD instead: a recognised string and a decoded code are the picture's own
//! content read back, and they name nothing. Putting either in a `label` field would call one thing
//! by the other's name in every schema that published it, so the two clusters have the same SHAPE
//! and different subjects — and a shape is not a reason to share a type.
//!
//! The division is visible at the doors. [`Label::new`] refuses the empty word, because a
//! classification of nothing is not one; [`TextDetection::new`] and [`BarcodeDetection::new`] refuse
//! nothing at all, because a recogniser that found a region and no characters in it has made an
//! observation and the region is what a caller is asking about.
//!
//! **[`Symbology`] is the one closed-ish VOCABULARY here, and it is open anyway.** Twenty-four named
//! standards read out of a documentation page, plus an escape carrying the folded word — so it takes
//! the ENUM filter's four membership operators where a payload takes the text family's twenty. See
//! that type, where the roster, the fold and the wire scalar are argued.
//!
//! **[`DocumentSegment<T>`] is the only member that holds a [`Quad<T>`](crate::Quad)**, and it is
//! therefore the only one whose columns are ALL VALUE — see below, where the derived leaf the other
//! two inherit is accounted for.
//!
//! **There is no `Option<BoundingBox<T>>` anywhere in this house.** One type with an optional box
//! would make *a classification that never had a location* and *a located finding whose box went
//! missing* the same value; two types make the second unrepresentable. That is the ruling this house
//! was built to state, and every face below inherits it — there is no null box in a column, none in
//! a filter and none on the wire.
//!
//! # WHERE AN INVARIANT LIVES: on the leaf, and nowhere else
//!
//! A rule about ONE WORD is [`Label::new`]'s — non-empty, and nothing about case. A rule about one
//! number is [`Confidence`](crate::Confidence)'s and [`NormCoord`](crate::NormCoord)'s, each in its
//! own house. **Neither composite here checks anything at all**, and that is not laziness: a label
//! says nothing about what a confidence may be, and neither says anything about where a rectangle
//! may sit. Both constructors are total and `const`, which is what building out of validated parts
//! buys — see [`avanalyze`'s own contract](https://github.com/findit-studio/avanalyze), whose
//! subject-detection constructor is infallible for exactly this reason.
//!
//! # THE ENGINE OWNS NORMALISATION
//!
//! Stated once here because it decides the shape of [`Label`] and therefore of everything above it:
//! *the engine lowercases and trims image-classification labels but passes animal labels through
//! verbatim, and uses the literal `"person"` for human subjects — the label vocabulary is Apple's,
//! not this crate's*. So `Cat` and `cat` are two labels, the type folds nothing, and a caller that
//! wants them to be one asks with the `nocase` half of a text filter's affix slots. See [`Label`],
//! where the division is argued at the constructor that keeps it.
//!
//! # THE GATE: none, on the geometry house's own precedent
//!
//! Every vocabulary door in this crate is named for the DEPENDENCY it admits. **This house admits
//! none**: [`Label`] is text over the crate's own carrier, [`Score`](crate::Score) is the crate's
//! own confidence, and the geometry it composes is ungated beside it.
//!
//! It needs no TIER either, and that is a measurement rather than a preference. The
//! `#[ingraph(composed)]` derive takes a CONCRETE struct — which is why
//! [`lang`](super::lang) rides `derive` for a filter this house's sibling declares — and
//! [`LocatedDetectionFilter<CF>`] is generic over its component's filter, so it could not be
//! declared through that word whatever this module wanted. Declaring ONE of the two and
//! hand-writing the other would have bought a `derive` gate for half a house. Both are hand-written
//! on [`TimeRangedFilter`](crate::TimeRangedFilter)'s 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, decodes and lowerings, `mongo` for the documents, `async-graphql` for the wire.
//!
//! # The three layers, and the crossings between them
//!
//! ```text
//!   domain                  crossing            storage
//!   Label                   identity            text
//!   Symbology               CANONICALISING      text
//!   Detection               per half            (text, f32)
//!   LocatedDetection<T>     per half            (text, f32) + the box's FIVE
//!   TextDetection<T>        per half            (text, f32) + the box's FIVE
//!   BarcodeDetection<T>     per half            (text, text, f32) + the box's FIVE
//!   DocumentSegment<T>      per half            the quad's EIGHT + f32
//! ```
//!
//! Every crossing is a HALF's, applied per column, and ONE of them canonicalises: [`Symbology`]
//! folds ASCII case and three separators at its door, so `DATA-MATRIX` and `data_matrix` are one
//! value and a stored slug reads back as the named member. That is a vocabulary's business and not a
//! payload's — [`Label`], a recognised string and a decoded payload each rewrite NOTHING, so a value
//! this crate wrote reads back byte for byte at every door.
//!
//! **The located finding INHERITS a derived leaf, and it is the geometry house's.**
//! [`BoundingBox<T>`](crate::BoundingBox) stores an `area` beside the four numbers it holds, so a
//! `subject: LocatedDetection<NormCoord>` spans SEVEN columns of which SIX are the value. This house
//! computes nothing — the fifth box column is the box's own bind — and what it owes is the
//! CONSEQUENCE: a holder of a citizen with a derived leaf owes an order of its own, because a wide
//! term does not know that one of the columns beneath it is an index. See
//! [`LocatedDetection<T>`]'s `ORDER`, where six levels are named over seven leaves.
//!
//! # What a DECODE re-proves, and it is everything
//!
//! A read goes through each half's own constructor, so an empty stored label is refused at the
//! column that held it and a confidence outside `[0.0, 1.0]` at its own. Unlike the geometry house
//! one door over, **there is no cross-column rule to lose**: a detection's two columns are
//! independent and a located detection's six are its parts', so the composites promise nothing at
//! construction that a decode cannot re-establish. The recorded gap in the sibling family — a sum
//! rule no `Assemble` can re-check — has no analogue here.
//!
//! # WHAT IS REFUSED, BY NAME
//!
//! **No whole-value operator, at either arity.** No `eq`, `ne`, `in` or ordering over a whole
//! detection: the leaf tuple IS the conjunction of the facets and is reachable as one, a whole-value
//! `ne` over a composite is a disjunction, a per-column `in` is the cartesian product, and an order
//! composed of a word's and a float's is an order over the storage that would read like a ranking.
//! See [`DetectionFilter`], where each clause is argued.
//!
//! **No FIXED-WIDTH cursor**, and this house frames its members instead. The composites' keyset
//! positions are written with [`write_member`](crate::cursor::write_member) and read with
//! [`read_member`](crate::cursor::read_member) — the crate's one authority for *several values in
//! one buffer*, four bytes of big-endian length a member — where the geometry family divides its
//! payload by a constant. **The division is unavailable here**: a label is variable-width and it is
//! FIRST in segment order, so there is no constant split point from either end. See [`Detection`]'s
//! own cursor row, where the choice is argued; what four bytes a member buys is a read that refuses
//! a frame this type did not write.
//!
//! **No `Vec<Label>`**, which is [`Utf8Bytes`](smol_bytes::Utf8Bytes)' own position inherited: the
//! crate's text carrier is not a [`CollectionElement`](crate::CollectionElement) on any backend, and
//! neither are the [`lang`](super::lang) subtags. A list of words is a
//! `Vec<Detection>` in every declaration this framework has met — a bare tag has no confidence to
//! rank it by — and THAT is admitted, along with `Vec<LocatedDetection<T>>`.
//!
//! **No MONGO face on the four citizens that hold GEOMETRY**, and it is a RECORDED GAP rather than a
//! refusal.
//! [`Label`], [`Detection`] and [`Symbology`] all have their document forms, but a located finding,
//! a reading, a decoded code or a segment would need [`BoundingBox<T>`](crate::BoundingBox) or
//! [`Quad<T>`](crate::Quad) to have a [`MongoCarrier`](crate::MongoCarrier), and the geometry house
//! publishes none for any of its three holders. Writing one here would put the geometry family's
//! BSON shape in the detect family's file, decided by the house that consumes it rather than the
//! house that owns it. So the door is named and left at the type that has to open it.
//!
//! # THE DERIVED LEAF FOUR OF THESE INHERIT, and the sequence each of them owes
//!
//! [`BoundingBox<T>`](crate::BoundingBox) stores an `area` beside the four numbers it holds — a
//! DERIVED leaf, computed by the write and read by no decode. Nothing in this house computes
//! anything; what it inherits is an OBLIGATION, and it is worth stating once for all four:
//!
//! > A holder of a citizen with a derived leaf owes a sequence of its own.
//!
//! A composite that states no [`ORDER`](crate::ColumnKind::ORDER) keeps a WIDE term whose keyset row
//! value is its whole width — so a finding, a reading or a decoded code wearing the non-reordering
//! word would put `…_bbox_area` inside a pagination cursor, which is the 2026-08-29 law's own
//! prohibition. So [`LocatedDetection<T>`], [`TextDetection<T>`] and [`BarcodeDetection<T>`] each
//! state a sequence and publish a leaf vocabulary, and each of those sequences is the DECLARATION
//! order minus the box's derived leaf: the point is the EXPANSION, not a claim about how findings
//! sort.
//!
//! [`DocumentSegment<T>`] states none and needs none, and the contrast is what makes the rule
//! legible: a quad is four positions and a position is two components, so nothing beneath it
//! derives anything and every one of its nine columns holds the value.

mod barcode;
mod detection;
mod label;
mod located;
mod payload_kind;
mod segment;
mod symbology;
mod text;

// The SQL side for both composites, in ONE file: two comparisons that are one lowering shape at two
// arities, read side by side.
#[cfg(feature = "sqlx")]
mod comparison;
// The wire faces for both composites and both filters in ONE file, where the two citizen files hold
// everything else. The COMPOSITION is the reason: the located face's field list, render and parse
// are each built by calling the detection face's, so the two have to be written where they can see
// each other or the flattening becomes two lists that can drift.
#[cfg(feature = "async-graphql")]
mod graphql;

#[cfg(test)]
mod tests;

pub use barcode::{BarcodeDetection, BarcodeDetectionFilter, BarcodeDetectionLeaf};
#[cfg(feature = "sqlx")]
pub use comparison::{
  SqlBarcodeDetectionComparison, SqlDetectionComparison, SqlDocumentSegmentComparison,
  SqlLocatedDetectionComparison, SqlTextDetectionComparison,
};
pub use detection::{Detection, DetectionFilter};
pub use label::{EmptyLabel, Label, LabelWire};
pub use located::{LocatedDetection, LocatedDetectionFilter, LocatedDetectionLeaf};
pub use payload_kind::BarcodePayloadKind;
pub use segment::{DocumentSegment, DocumentSegmentFilter};
pub use symbology::Symbology;
pub use text::{TextDetection, TextDetectionFilter, TextDetectionLeaf};