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
//! **WHERE A SCHEMA-ASKED RECIPE FINDS ITS MEMBERS** — the two seams a recipe's emitted resolver
//! reaches one member through, and the one it hydrates an address through.
//!
//! ```text
//! travelSearch(text: "harbour at dusk", first: 10)
//!   │
//!   ├─ <Subs  as FusedEngine>::Engine              WHICH engine a schema asks this member through
//!   ├─ <Subs  as FusedCitizen<_>>::ranked(ctx, …)  that member's ranked keys, citizens and all
//!   ├─ <Shots as FusedCitizen<_>>::ranked(ctx, …)
//!   │
//!   ├─ fuse_weighted(…)                            the framework's own fold, over the same edges
//!   │
//!   ├─ <Root as WireRoot>::address(root)          the KEYS half of the answer pair
//!   └─ <Root as WireRoot>::hydrate(ctx, keys)     the HYDRATED half of it
//! ```
//!
//! # THE WALL THESE THREE EXIST FOR
//!
//! A recipe holds a member's type PATH. What a member is asked THROUGH — a slot handle branded for
//! that declaration, a read scope opened on that mount's manager, the engine's own floor and its own
//! knobs — is written in the MEMBER's declaration, and
//! [`AsyncFusedRead::Ctx`](crate::AsyncFusedRead::Ctx) is the seat that carries it across without a
//! parent ever naming a part of it. That works for a RUST caller, who holds the handles already.
//!
//! A RESOLVER holds none: it has an [`async_graphql::Context`] and a schema somebody handed a
//! [`Shared<R>`](crate::Shared) to, and it cannot be generic — a resolver is a concrete `async fn`
//! on a unit type, and the corpus lookup is a `TypeId` on a concrete pairing. So the engine has to
//! be a type the RECIPE's expansion can spell, and the only declaration that knows one is the
//! member's. That is exactly the shape [`Fusable`](crate::Fusable) and
//! [`AsyncFusedRead`](crate::AsyncFusedRead) already answer for the Rust road, and these are their
//! wire twins.
//!
//! # WHY TWO TRAITS AND NOT ONE
//!
//! The obvious single trait carries `type Engine` beside a verb whose signature mentions
//! `<Self as AsyncFusedRead<Self::Engine>>::…`. It is a supertrait cycle through an associated type,
//! and the road around it needs a higher-ranked associated-type equality over a lifetime, which is
//! not spellable on stable. So the engine is named by one trait and the read parameterised on it,
//! and the recipe writes `<M as FusedCitizen<<M as FusedEngine>::Engine>>::ranked(ctx, …)`.
//!
//! # THEY ARE OPEN, and that is the whole reason they are traits
//!
//! Nothing here is the macro's to own. A third-party member joins a recipe's WIRE road exactly as it
//! joins its Rust one — by writing these impls — and the recipe absorbs it by projection with no
//! edit. The same discipline [`Fusable`](crate::Fusable)'s own note states one layer down.

use core::{future::Future, pin::Pin};

/// **WHICH ENGINE A SCHEMA ASKS THIS MEMBER THROUGH.**
///
/// A member's Rust doors are generic over their engine — that is the heterogeneity the fusion tree
/// is built on — and a RESOLVER cannot be. So a member that publishes a wire road names the one
/// engine a schema asks it through, and the recipe's expansion reads it as a projection.
///
/// # It is the member's answer and not the recipe's
///
/// A recipe lists members; which store each of them is written to is that member's declaration's
/// business, and a recipe that named one would be reaching inside a declaration it cannot see. The
/// same two-clock wall the per-leg floor already sits behind.
#[diagnostic::on_unimplemented(
  message = "`{Self}` names no engine for a schema to ask it through",
  label = "no wire engine",
  note = "a member joins a recipe's WIRE road by naming the engine a resolver asks it through — \
          `impl FusedEngine for {Self} {{ type Engine = MyStore; }}` — because a resolver is a \
          concrete function and cannot be generic over one",
  note = "the RUST road needs none of this: `{Self}`'s own doors stay generic over their engine, \
          and a caller that holds the handles asks them directly"
)]
pub trait FusedEngine {
  /// The engine a schema-asked read of this member runs on.
  ///
  /// # `'static`, and it costs nothing this seat did not already owe
  ///
  /// A resolver finds its citizens by [`TypeId`](core::any::TypeId) —
  /// [`Context::data`](async_graphql::Context::data) is keyed on one — and a `TypeId` exists only for
  /// a `'static` type. So an engine a SCHEMA asks through is `'static` before this bound is written,
  /// and writing it is what lets the recipe's own emission name the type without carrying an
  /// outlives obligation it has nowhere to discharge.
  ///
  /// The RUST road is untouched: a member's own doors stay generic over an unbounded engine, and a
  /// caller holding a borrowed one asks them directly.
  type Engine: 'static;
}

/// **HOW A SCHEMA ASKS ONE MEMBER FOR ITS RANKED KEYS** — the wire twin of
/// [`AsyncFusedRead::keys`](crate::AsyncFusedRead::keys), with the citizen lookup inside it.
///
/// The read seam takes the asking position as a parameter, because a RUST caller already holds the
/// handles. A resolver holds an [`async_graphql::Context`] and nothing else, so this verb mints the
/// position out of the schema's own citizens and spends it in one move — and the recipe's wire face
/// never names a slot, a scope, a floor or a knob of any member's.
///
/// # THE FUTURE IS BOXED, and that is measured rather than a matter of taste
///
/// The obvious signature returns `impl Future<…> + Send + 'a`. It does not survive contact with a
/// resolver: a recipe's members are asked through `Ctx<'a>` GATs carrying `where E: 'a`, and an
/// opaque future over those cannot be produced inside another `async fn` at all —
/// rust-lang/rust#100013, reported as *lifetime bound not satisfied* at the attribute that emitted
/// the caller, with no span a reader could act on and no note naming a type. A `Pin<Box<dyn …>>` is
/// a CONCRETE type with no hidden regions, so the limitation has nothing to bite. The cost is one
/// allocation per member per request, paid where a store round trip is about to be.
///
/// The `Send` is the IMPLEMENTOR's promise rather than the seam's demand on anybody: a member knows
/// its own engine, where [`AsyncFusedRead`](crate::AsyncFusedRead) — which is total over engines it
/// has never seen — deliberately promises nothing. A resolver's future must be `Send`, so this is
/// where that obligation lands and the only place it can.
///
/// # The shipped road for a declared member
///
/// [`vector_slot`](super::vector_slot) / [`search_slot`](super::search_slot) mint the branded handle
/// and the manager it reaches back through, off the [`Shared<R>`](crate::Shared) a launch installed;
/// the body then hands both to this member's own `keys`. A member whose store is held somewhere else
/// mints its position whichever way it likes — the openness the resource axis already put one layer
/// down.
#[diagnostic::on_unimplemented(
  message = "`{Self}` cannot be asked for a fused read by a schema",
  label = "no schema-side read",
  note = "a member joins a recipe's WIRE road by minting its own asking position from the schema's \
          citizens — the slot handle, the read scope, the floor and the engine's knobs — and \
          spending it on its own `AsyncFusedRead::keys`",
  note = "`ingraph::vector_slot` / `ingraph::search_slot` are the shipped road: they look up the \
          `Shared<R>` a launch installed and hand back the branded handle beside its manager"
)]
pub trait FusedCitizen<E>: crate::AsyncFusedRead<E> {
  /// This member's ranked keys for one request, asked out of the schema's own citizens.
  ///
  /// `limit` is the depth the RECIPE resolved for this member's edge — already this edge's own
  /// number, exactly as [`AsyncFusedRead::keys`](crate::AsyncFusedRead::keys) takes it.
  ///
  /// # Errors
  /// Where the deployment installed no citizen this member's read needs, where a request left a
  /// value the engine demands unstated, or where the read itself refused — all three shaped as the
  /// wire's own refusal, because a client reads one error vocabulary.
  #[expect(
    clippy::type_complexity,
    reason = "the BOX is the point and every layer under it is a projection: an implementor reads \
              the erasure, the `Send` bound and the two associated types off this line, and an \
              alias would hide the one row a wrong impl gets `E0053` on"
  )]
  fn ranked<'a>(
    ctx: &'a async_graphql::Context<'_>,
    options: Option<&'a <Self as crate::Fusable>::Options>,
    question: &'a <Self as crate::Fusable>::Question,
    limit: core::num::NonZeroUsize,
  ) -> Pin<
    Box<
      dyn Future<
          Output = async_graphql::Result<
            Vec<
              crate::Rooted<
                <Self as crate::AsyncFusedRead<E>>::Root,
                <Self as crate::AsyncFusedRead<E>>::Evidence,
              >,
            >,
          >,
        > + Send
        + 'a,
    >,
  >;
}

/// **WHAT A RECIPE'S ROOT IS ON THE WIRE** — the address a client reads, and the row that address
/// points at.
///
/// A recipe answers in a ROOT: one key type every member agrees about. The KEYS tier publishes the
/// address and the HYDRATED tier publishes what it points at, and both are facts about the KEY — so
/// they arrive as one capability ON the key rather than as a mechanism this crate picked, and two
/// recipes over one root answer the same way by construction.
///
/// # The ADDRESS is a projection of the key's columns, not the key
///
/// [`GraphqlOutput::Key`](crate::GraphqlOutput::Key)'s own statement one family over: a key holds
/// the declaration's own types and an address holds what a schema can name. An entity that publishes
/// a wire face already mints the projection and the `From` that reaches it, so the shipped impl is
/// one line.
///
/// # HYDRATION IS POSITIONAL, and a hole is an answer
///
/// [`hydrate`](Self::hydrate) answers one entry per key IN THE ORDER THEY WERE ASKED, and [`None`]
/// where the row is gone. That is the emitted hydrated road's own law one grain down: a lost row
/// leaves a hole rather than shifting every row after it, so the two halves of the answer pair can
/// be read side by side.
///
/// # It is a RECIPE's demand and never a member's
///
/// A member's own roads publish their own addresses through their own upstream's face. This is what
/// a RECIPE needs, whose root is a type it never names — every member's
/// [`Root`](crate::AsyncFusedRead::Root) is bound to one parameter — so the capability belongs where
/// the type is.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a wire-facing root",
  label = "no address and no hydrated form",
  note = "a recipe answers in ONE key every member agrees about, and publishes it in two tiers — \
          the address as a schema can name it, and the row that address points at. Both are facts \
          about the key: `impl WireRoot for {Self} {{ type Address = …; type Entity = …; … }}`",
  note = "an entity wearing `graphql(async_graphql)` already mints the address projection and the \
          `From` that reaches it, so `fn address(self) -> Self::Address {{ self.into() }}` is the \
          whole of that half"
)]
pub trait WireRoot: Sized {
  /// The ADDRESS a client reads — a projection of this key's columns, in a shape a schema can name.
  type Address: async_graphql::OutputType + Send + Sync;

  /// What one address points at, in the shape a client reads.
  type Entity: async_graphql::OutputType + Send + Sync;

  /// This key, as the wire names it.
  fn address(self) -> Self::Address;

  /// The rows these addresses point at — one entry each, in order, [`None`] for a row that is gone.
  ///
  /// # Errors
  /// Whatever the read refuses with, already shaped as the wire's own refusal.
  #[expect(
    clippy::type_complexity,
    reason = "the erasure and its `Send` bound are what an implementor has to match — see `ranked`, \
              whose note holds here word for word"
  )]
  fn hydrate<'a>(
    ctx: &'a async_graphql::Context<'_>,
    keys: Vec<Self>,
  ) -> ::core::pin::Pin<
    ::std::boxed::Box<
      dyn Future<Output = async_graphql::Result<Vec<Option<Self::Entity>>>> + Send + 'a,
    >,
  >;
}

#[cfg(test)]
mod tests;