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
//! [`AsyncFusedRead`] — the one verb a parent asks a fusable member through, and the four seats that make
//! it total over members whose shapes the parent has never seen.

use core::{future::Future, num::NonZeroUsize};

use super::{Fusable, Rooted};

#[cfg(test)]
mod tests;

/// HOW a parent asks a member for its ranked keys.
///
/// [`Fusable`] says a member has a fusion package; this says how to spend one. It is ONE trait for
/// both modalities, and that is load-bearing: a ROOT holds a member's type PATH and cannot see which
/// kind its declaration is, so a mixed door has to reach every member through one projection.
///
/// There is no second trait carrying the MODALITY, and there was one until 2026-08-19: two markers
/// a consumer could write to demand ONE modality at a field. The word that demanded them — a graph
/// root's `fuse(vector)` / `fuse(fulltext)` trim — retired with the root's own typed doors, and in
/// the rounds after it nothing wrote the bound. A stated capability nobody states is a name in a
/// prelude, so it went; a consumer that wants a modality checked writes its own marker over the
/// members it holds, which is the same one line without this crate carrying it.
///
/// # NO `&self`, and the index type is why
///
/// A declaration's type is a BRAND — `Shots` is not a value anybody holds, it is the name a slot
/// handle is branded with. So the verb is ASSOCIATED, and the state it needs arrives through
/// [`Ctx`](Self::Ctx) exactly as a queries unit's resolvers take theirs from a context rather than
/// from a receiver.
///
/// # `Ctx` is the MEMBER's own, and that is what keeps a root from naming a slot
///
/// A member's own doors take slot handles, read scopes and floors — types written in the member's
/// declaration, generic over the engine, and unspellable at a root that holds a type path. So the
/// member names them INSIDE its own impl and a parent names `<M as AsyncFusedRead<E>>::Ctx<'_>`. The
/// root's door is therefore total over members whose shapes it has never seen, which is the same
/// projection seam [`Fusable`] draws for the packages.
///
/// # The engine is a PARAMETER, and the member's own heterogeneity is not lost
///
/// One engine per MEMBER at this seat: a root's routes are its members, so the root grain's currency
/// law is one engine parameter per route exactly as the index grain's is. A member whose own routes
/// are held by DIFFERENT engines is still reachable — through that member's own `vector_fuse`, which
/// takes one engine per route — and what this seat offers is the member asked through one of them.
/// Widening it would mean a root naming a member's route count, which is the wall this seam exists
/// to keep.
///
/// # The engine parameter is UNBOUNDED, and that is what lets one road carry two modalities
///
/// A vector member is asked through a `VectorEngine` and a full-text one through a
/// `FulltextEngine`, and there is no trait both are. Naming either here would have split this seam
/// in two and put the root's mixed door back where it started — picking a modality per member it
/// cannot see. So the parameter is a NAME: whichever engine the member's own doors take, carried
/// through to `Ctx` and read by nobody in between.
#[diagnostic::on_unimplemented(
  message = "`{Self}` cannot be asked for a fused read",
  label = "this member answers no retrieve, so a root's fused door cannot route to it",
  note = "a `AsyncFusedRead` impl is emitted for a `#[ingraph::fulltext(…)]` or `#[ingraph::vector(…)]` \
          declaration; records, operators, journals and artifact families do not rank and do not \
          implement it",
  note = "a vector declaration whose ONLY election is a `list(embedding)` does not implement it \
          either — a set election is no route of its own tier, so there is no ordinal a parent's \
          fold could read",
  note = "a THIRD-PARTY member joins by implementing `AsyncFusedRead` — the root's door reaches it by \
          projection, with no edit to the root"
)]
pub trait AsyncFusedRead<E>: Fusable {
  /// The key this member's rankings are ABOUT — the root a parent joins on.
  ///
  /// A parent requires every fused member's to be one type, and says so with an equality bound: two
  /// members answering two key types have no root to be fused at, and that is `E0271` at the
  /// parent's own call rather than a runtime mismatch.
  type Root;

  /// This member's OWN provenance, carried out of the fold untouched.
  ///
  /// Whatever the member's grain minted: its `<Index>FusedEvidence` where it fuses several routes,
  /// its engine's own `Score` where it has one. A parent asks NOTHING of the type — it nests it in
  /// its own evidence enum and hands it to the client, which is what *aggregating by projection*
  /// means.
  type Evidence;

  /// This member's own refusal, carried whole.
  type Error;

  /// WHERE the state a fused read needs arrives from — the handles, scopes and floors this member's
  /// own doors take, named by the member and never by a parent.
  ///
  /// The ONE outlives clause is what a borrowed context COSTS, declared here rather than left to
  /// each impl — a where-clause an impl may not add is a where-clause the trait has to own. The
  /// further clauses a borrowed scope needs (`E::Connection: 'a`, `E::ReadContext<'a>: 'a`) follow
  /// from it by rustc's projection-outlives rule, which is why one clause is enough over a parameter
  /// this trait deliberately does not bound.
  type Ctx<'a>
  where
    E: 'a;

  /// This member's hits for one question, each wearing the ordinal a parent's fold reads.
  ///
  /// # `limit` is the DEPTH the parent asked this member at, and it cannot be nothing
  ///
  /// A root resolves each member's [`Route::depth`](super::Route::depth) against its own budget
  /// before it calls, so the number arriving here is already this edge's own — see
  /// [`route_depth`](super::route_depth). It is a [`NonZeroUsize`] because the door family's whole
  /// currency is: an ask for nothing is not a search with an empty answer, and the type is what makes
  /// it unrepresentable rather than a fork every implementor has to remember to write. The member's
  /// OWN legs read the member's own declaration against this number, which is the fractal one level
  /// down.
  ///
  /// It is a CEILING and never a promise. A member holding fewer hits, or whose floor cuts its tail,
  /// answers shorter — and a parent's fold reads what came back.
  ///
  /// # NO `Send` PROMISE, and that is a measurement rather than an oversight
  ///
  /// [`AsyncVectorRead::knn`](crate::AsyncVectorRead::knn) returns `impl Future + Send`, and every
  /// door
  /// this verb reaches is a plain `async fn` that does not. A member's future holds its own floor,
  /// its own read scope and its own key across an await, and none of those is `Send` by any bound
  /// the emission can state without pushing the whole set onto every engine that ever joins a root.
  /// So the seam promises what its doors promise, and a deployment that needs the future to cross
  /// threads gets it from the concrete types it actually named, where the auto trait is inferred
  /// rather than demanded.
  ///
  /// # Errors
  ///
  /// This member's own — whatever its engine or its own doors refuse.
  #[expect(
    clippy::type_complexity,
    reason = "every layer of the return is one of this seam's four projections — the answer, the \
              root, the evidence and the refusal — so the shape a third party implements against \
              is the shape written here"
  )]
  fn keys<'a>(
    ctx: Self::Ctx<'a>,
    options: Option<&Self::Options>,
    question: &Self::Question,
    limit: NonZeroUsize,
  ) -> impl Future<Output = Result<Vec<Rooted<Self::Root, Self::Evidence>>, Self::Error>>
  where
    E: 'a;
}