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 interpretation → filter-type map: [`ToGraphqlFilter`], and every row that resolves one.
//!
//! The map is the GRAPHQL AXIS's half of the marker layer, and the split is what keeps the
//! interpretation vocabulary out of one binding's module: [`crate::marker`] says a column is read as
//! an unordered collection of `Tag`, and this file says that reading resolves to
//! [`SetFilter<Tag, …>`](crate::SetFilter). A second wire binding answers the SAME markers with its
//! own filter types through a map beside this one — so the rows belong to the map and the markers to
//! neither.
//!
//! Two rows here are not delegations but the framework's own COLLECTION registrations —
//! `impl ListFilterMarker for Vec<T>` and its set twin — and they are here for the same reason: what
//! they name is a filter type. See [`crate::marker`] for the trait they answer and for why the
//! answer is delegated to the container at all.

use crate::{
  graphql::filter::{ListFilter, Nullable, QuantifiedFilter, SetFilter},
  marker::{
    BoolFilterMarker, BoolMarker, BytesFilterMarker, BytesMarker, CompositeFilterMarker,
    CompositeMarker, DurationFilterMarker, DurationMarker, EnumFilterMarker, EnumMarker,
    ListFilterMarker, ListMarker, Marker, NullableMarker, OptionalMarker, QuantifiedFilterMarker,
    QuantifiedMarker, ScalarFilterMarker, ScalarMarker, SetFilterMarker, SetMarker,
    StringFilterMarker, StringMarker,
  },
  state::{Extracted, Inner, State},
};

/// An INTERPRETATION mapped to the filter types that guard a column read under it. Bound-free — a
/// backend lowering capability is required only where a query is lowered.
///
/// Implemented for the markers in [`crate::marker`] and for nothing else. Keyed on a
/// marker rather than on a field's Rust type because a type does not determine its own reading:
/// `Vec<u8>` is a byte string or a list of small integers, and a trait keyed on the type answers
/// once, for the declarer. A declaration reaches this through
/// [`DefaultMarker`](crate::DefaultMarker), which is what supplies the reading when the
/// declaration names none.
///
/// # TWO faces, because a host kind decides which truth a predicate tells
///
/// A row-holding host asks what its COLUMNS can be compared by; a rowless one asks what the VALUE
/// can be asked about. For every reading in this crate but one the two questions have one answer,
/// and the second row restates the first. The exception is the COMPOSITE reading, where a fragment
/// held by a record publishes the columns it is actually stored in and the same fragment held by an
/// entity publishes every field it declares — *each face tells its own truth*, the 2026-08-22
/// ruling. See [`CompositeFilterMarker`], which is where the two types are named.
///
/// The second row rides THIS trait rather than a parallel one because
/// [`DefaultMarker::Marker`](crate::DefaultMarker) already carries it as an item bound: a projection
/// through [`ColumnFilter`](Self::ColumnFilter) therefore costs no `where` clause at any holder, and
/// the four COMPOSED readings recurse for free, `VM: ToGraphqlFilter` being a bound they already
/// state. A marker a declaring crate owns answers both, which is the honest shape — a reading whose
/// two faces agree says so in one line.
pub trait ToGraphqlFilter {
  /// The filter that guards a column read under this interpretation, at the face a ROWLESS host
  /// publishes — every field the value declares.
  type Filter;
  /// The filter that guards a column read under this interpretation, at the face a ROW-HOLDING host
  /// publishes — the columns the value is actually stored in.
  ///
  /// The same type as [`Filter`](Self::Filter) for every reading but the composite one, and the
  /// restatement is the point: what varies with the host kind is what a fragment stores, and nothing
  /// else in this map has a storage subset to differ in.
  type ColumnFilter;
}

/// An INTERPRETATION mapped to the wire ORDER TERM one column read under it carries — the ordering
/// axis's half of the same marker layer, and [`ToGraphqlFilter`]'s twin.
///
/// # What it is FOR: turning a kind ASSUMPTION into a type-level fact
///
/// A generated `<T>OrderBy` names one variant per orderable column, and the emitter used to decide
/// which columns those are by reading a MODEL — whether the declaration persisted, whether a column
/// was a collection, which storage form it took. Every one of those is a fact the emitter can see,
/// and none of them is *may this reading be ordered*. This trait is that question, asked of the
/// reading rather than of the tokens, so a column joins the order face by having a row here and a
/// column that has none is not orderable — which is a compile-time fact instead of a branch in a
/// macro.
///
/// # Absence is the refusal, and it is BOUNDED
///
/// A reading with no row here has no order, and the roster below is exactly the readings this
/// framework orders TODAY — every one of them, which is the all-columns admission the emitter
/// already had. So the map's arrival admits nothing new and refuses nothing that worked, and what it
/// buys is the seat: the first reading that genuinely cannot be ordered — one whose column is an
/// expression no dialect can sort, one whose value has no total order — declines by having no row,
/// and the refusal lands at the declaration naming this trait.
///
/// # ONE member, and the payload is the DIRECTION
///
/// Every admitted reading's wire term is a direction and nothing else, because a term is one column
/// AND one way it runs — the pairing the generated enum makes unspellable to get wrong. The member
/// is carried all the same rather than being assumed, for the reason
/// [`ToGraphqlFilter::Filter`](ToGraphqlFilter) is: a reading whose term needs more of a client — a
/// collation, a locale, a null placement the client chooses — says so in one line, and every
/// projection through this member follows it without a caller moving.
///
/// # It names no DATABASE, and that is the wire face's whole shape
///
/// [`ToDatabaseOrderBy<Db>`](crate::ToDatabaseOrderBy) carries the parameter, because what a column's
/// one term LOWERS into is a dialect's answer. What a client WRITES is not: a schema varying with a
/// deployment's storage choice would be a schema no client could hold against two deployments, which
/// is the argument the retired `Orderable` trait made for having no database parameter, and it
/// transfers here whole — this is the face that argument was always about.
pub trait ToGraphqlOrderBy {
  /// What one ordering term over a column read under this interpretation carries.
  ///
  /// [`OrderDirection`](crate::OrderDirection) for every reading below, and the restatement is the
  /// point: what the wire asks for an order is the same question whatever the column holds.
  type OrderBy;
}

impl<T: ScalarFilterMarker> ToGraphqlFilter for ScalarMarker<T> {
  type Filter = <T as ScalarFilterMarker>::Filter;
  type ColumnFilter = <T as ScalarFilterMarker>::Filter;
}

impl<T: StringFilterMarker> ToGraphqlFilter for StringMarker<T> {
  type Filter = <T as StringFilterMarker>::Filter;
  type ColumnFilter = <T as StringFilterMarker>::Filter;
}

impl<T: BytesFilterMarker> ToGraphqlFilter for BytesMarker<T> {
  type Filter = <T as BytesFilterMarker>::Filter;
  type ColumnFilter = <T as BytesFilterMarker>::Filter;
}

impl<T: EnumFilterMarker> ToGraphqlFilter for EnumMarker<T> {
  type Filter = <T as EnumFilterMarker>::Filter;
  type ColumnFilter = <T as EnumFilterMarker>::Filter;
}

// The ONE reading whose two faces can differ, and the whole reason this trait has two rows. A
// fragment activated for both host kinds emits two predicates — the full field set and the stored
// subset — and this is where a holder's projection picks the one its own kind asks for.
impl<T: CompositeFilterMarker> ToGraphqlFilter for CompositeMarker<T> {
  type Filter = <T as CompositeFilterMarker>::Filter;
  type ColumnFilter = <T as CompositeFilterMarker>::ColumnFilter;
}

#[cfg(feature = "flags")]
impl<T: crate::FlagsFilterMarker> ToGraphqlFilter for crate::FlagsMarker<T> {
  type Filter = <T as crate::FlagsFilterMarker>::Filter;
  type ColumnFilter = <T as crate::FlagsFilterMarker>::Filter;
}

impl<T: BoolFilterMarker> ToGraphqlFilter for BoolMarker<T> {
  type Filter = <T as BoolFilterMarker>::Filter;
  type ColumnFilter = <T as BoolFilterMarker>::Filter;
}

impl<T: DurationFilterMarker> ToGraphqlFilter for DurationMarker<T> {
  type Filter = <T as DurationFilterMarker>::Filter;
  type ColumnFilter = <T as DurationFilterMarker>::Filter;
}

// The three COMPOSED readings, and the bound they share is the whole of what composition costs:
// what the container holds and what the inner marker marks have to be the same type. Each is stated
// as an equality on the projection rather than as two separate bounds, so a mismatch is `E0271` at
// the site that wrote the marker — see [`ListMarker`] for the pair that pins it.
impl<T, VM> ToGraphqlFilter for ListMarker<T, VM>
where
  VM: ToGraphqlFilter + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked> + ListFilterMarker,
{
  type Filter = <T as ListFilterMarker>::Filter<<VM as ToGraphqlFilter>::Filter>;
  type ColumnFilter = <T as ListFilterMarker>::Filter<<VM as ToGraphqlFilter>::ColumnFilter>;
}

impl<T, VM> ToGraphqlFilter for SetMarker<T, VM>
where
  VM: ToGraphqlFilter + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked> + SetFilterMarker,
{
  type Filter = <T as SetFilterMarker>::Filter<<VM as ToGraphqlFilter>::Filter>;
  type ColumnFilter = <T as SetFilterMarker>::Filter<<VM as ToGraphqlFilter>::ColumnFilter>;
}

// The third collection reading, resolving through its own family trait and carrying the same
// agreement bound: a quantified collection whose inner marker reads something the container does not
// hold names a reading of nothing, exactly as a mismatched sequence does.
impl<T, VM> ToGraphqlFilter for QuantifiedMarker<T, VM>
where
  VM: ToGraphqlFilter + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked> + QuantifiedFilterMarker,
{
  type Filter = <T as QuantifiedFilterMarker>::Filter<<VM as ToGraphqlFilter>::Filter>;
  type ColumnFilter = <T as QuantifiedFilterMarker>::Filter<<VM as ToGraphqlFilter>::ColumnFilter>;
}

// No `NullableFilterMarker` beside the two above, for the reason the type's own note gives: there is
// one wrapper and no per-container variation for a trait to carry.
impl<T, VM> ToGraphqlFilter for NullableMarker<T, VM>
where
  VM: ToGraphqlFilter + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type Filter = Nullable<<VM as ToGraphqlFilter>::Filter>;
  type ColumnFilter = Nullable<<VM as ToGraphqlFilter>::ColumnFilter>;
}

// The fourth composed reading, and the only one that adds NOTHING: the filter is the inner marker's,
// so `T` appears in the bound and nowhere in the answer. That is what makes the `Option`
// TRANSPARENT — the coherence half is still stated, because an optional reading whose inner marker
// reads something `T` does not hold names a reading of nothing exactly as a mismatched list does.
impl<T, VM> ToGraphqlFilter for OptionalMarker<T, VM>
where
  VM: ToGraphqlFilter + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type Filter = <VM as ToGraphqlFilter>::Filter;
  type ColumnFilter = <VM as ToGraphqlFilter>::ColumnFilter;
}

// THE ORDER ROSTER — one row per reading this framework orders, which is every reading it has. It
// is a CENSUS of what the emitter already admitted rather than a new policy: a generated `<T>OrderBy`
// names one variant per stored column whatever that column's kind, so admitting anything less here
// would be this map deciding a question the emission had already answered the other way.
//
// Each row is bound by NOTHING beyond the composition bounds its marker needs. A wire term is a
// direction, and asking a reading's family trait for permission to carry one would be a bound with
// nothing behind it — the flat readings' rows say so by having no clause at all.
impl<T> ToGraphqlOrderBy for ScalarMarker<T> {
  type OrderBy = crate::OrderDirection;
}

impl<T> ToGraphqlOrderBy for StringMarker<T> {
  type OrderBy = crate::OrderDirection;
}

impl<T> ToGraphqlOrderBy for BytesMarker<T> {
  type OrderBy = crate::OrderDirection;
}

impl<T> ToGraphqlOrderBy for EnumMarker<T> {
  type OrderBy = crate::OrderDirection;
}

impl<T> ToGraphqlOrderBy for BoolMarker<T> {
  type OrderBy = crate::OrderDirection;
}

impl<T> ToGraphqlOrderBy for DurationMarker<T> {
  type OrderBy = crate::OrderDirection;
}

// The COMPOSITE reading, which is ONE word on the wire however many columns it is stored in. That is
// the full-form law at the ordering seam: a client orders by an instant, not by the four columns an
// instant occupies, and the expansion into those columns happens at the storage crossing — see
// [`ToDatabaseOrderBy`](crate::ToDatabaseOrderBy), which is the map that owns it.
impl<T> ToGraphqlOrderBy for CompositeMarker<T> {
  type OrderBy = crate::OrderDirection;
}

#[cfg(feature = "flags")]
impl<T> ToGraphqlOrderBy for crate::FlagsMarker<T> {
  type OrderBy = crate::OrderDirection;
}

// The three COLLECTION readings. A collection IS orderable on the wire — the emitted enum has always
// named one variant per collection column — and whether a given DIALECT can honour it is a different
// question, asked one layer down by that backend's own
// [`OrderCapability`](crate::query::OrderCapability) row and refused BY NAME at `SqlOrder::new`. So
// the wire admits the word and the storage decides, which is the split the whole face is built on:
// a schema states the DECLARATION's truth, and what a deployment can do with it is the deployment's.
impl<T, VM> ToGraphqlOrderBy for ListMarker<T, VM>
where
  VM: Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type OrderBy = crate::OrderDirection;
}

impl<T, VM> ToGraphqlOrderBy for SetMarker<T, VM>
where
  VM: Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type OrderBy = crate::OrderDirection;
}

impl<T, VM> ToGraphqlOrderBy for QuantifiedMarker<T, VM>
where
  VM: Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type OrderBy = crate::OrderDirection;
}

// The two TRANSPARENT readings, which forward their inner reading's term rather than restating it.
// An optional column is ordered exactly as a required one is — what the wrapper adds is a `NULL`
// group, whose position is the framework's pin rather than anything a client writes — so a wrapper
// that answered on its own would be a second opinion about a question its inner reading has already
// settled.
impl<T, VM> ToGraphqlOrderBy for NullableMarker<T, VM>
where
  VM: ToGraphqlOrderBy + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type OrderBy = <VM as ToGraphqlOrderBy>::OrderBy;
}

impl<T, VM> ToGraphqlOrderBy for OptionalMarker<T, VM>
where
  VM: ToGraphqlOrderBy + Marker,
  T: State<Extracted<Inner>, Output = VM::Marked>,
{
  type OrderBy = <VM as ToGraphqlOrderBy>::OrderBy;
}

// The framework's collection rows, ONE each over every element type — which is the orphan hole
// closing. A downstream cannot write `impl ToGraphqlFilter for Vec<ItsOwnType>` (`Vec` is foreign,
// the trait is foreign to it, and `Vec` is not fundamental: `E0117`), and under markers it does not
// need to, because these two impls already cover every element including its own.
//
// `ListFilter<T>` here is `ListFilter<T, <<T as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>`
// — the filter type's own DEFAULT, which is where the inference is written rather than at each of
// these two rows. That default is what put the bound here: a collection filter now holds a filter
// for ONE element (see [`ListFilter`]), and an element's filter is the one its own reading carries.
//
// A DECLARED collection is unaffected — every element type this crate registers has a
// [`DefaultMarker`](crate::DefaultMarker) row, and a downstream element type joins by writing one,
// which is the same row it already writes to say whether its `Vec` is a list or a set. What loses a
// collection filter is `Vec<T>` for a `T` answering no family at all, and such a `T` had one whose
// element questions nothing could ask.
impl<T> ListFilterMarker for Vec<T> {
  type Filter<VF> = ListFilter<T, VF>;
}

impl<T> SetFilterMarker for Vec<T> {
  type Filter<VF> = SetFilter<T, VF>;
}

// The third row, and the one whose bound is the loosest of the three: nothing about `T` is asked
// here or in the filter it names, which is what lets an element type with no wire form at all reach
// a schema through a `Vec` of itself. The other two rows are equally bound-free at THIS level and
// spend their demand at the wire face; this one has none to spend.
impl<T> QuantifiedFilterMarker for Vec<T> {
  type Filter<VF> = QuantifiedFilter<T, VF>;
}