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 SEARCH ROAD's front door: where an emitted search resolver finds the RESOURCE its election
//! points at, and mints the one corpus of it that election owns.
//!
//! ```text
//! Schema::build(root, …).data(Shared::<Ft>::new(ft))          // the deployment, once per resource
//!         │
//!         ▼
//! ctx.data::<Shared<Ft>>()  →  Ft::corpus(MediaTitleLexical::SLOT)  →  SlotHandle<TantivyFulltext, Media>
//!                           └► Ft::connection()                     →  Connected<'_, TantivyStore, ()>
//! ```
//!
//! # THE CITIZEN IS THE RESOURCE, and that is the whole of the re-axis
//!
//! A `SearchDoor<E, T>` used to be the citizen: a per-(engine × declaration) type an application
//! installed, holding an ENGINE and handing out a handle branded for the declaration. Under the
//! resource axis a leg no longer names an engine — it POINTS at a `#[ingraph::resource]` declaration
//! — so the type an emitted resolver can name is that resource, and the citizen it looks up is the
//! [`Shared<R>`](crate::Shared) a launch already built. What that retires is a whole installation
//! step: a deployment that declared its resources has already handed them over, and a second door
//! type per pairing was a second spelling of a binding the declaration made.
//!
//! Two resources of ONE KIND are two TYPES and therefore two `TypeId`s, which is what keeps the
//! lookup unambiguous where a shared engine word could not have.
//!
//! # A SLOT IS A CORPUS, so the mint takes the election's own name
//!
//! A resource is the MOUNT. The corpus one election writes is named `<index>__<field>__<label>` and
//! is minted per read through [`FulltextMount::corpus`] — so two elections pointing at one resource
//! are two corpora with two universes of BM25 statistics, and the brand
//! ([`SlotHandle`]) is what carries the pairing from here to the engine call.
//!
//! # WHY THE CONNECTION COMES BACK BESIDE THE HANDLE
//!
//! A minted handle is STATELESS: its verbs reach the index back through
//! [`Connected`](crate::Connected), whose first half is the manager the mount opened. A resolver
//! holding a handle alone has no value of that type and no way to make one — which is why the
//! emitted bodies used to build `Connected::new(&(), ())` and were readable only by an engine whose
//! connection was the unit. Both halves come out of ONE lookup here, so the handle and the manager
//! it reaches back through cannot be taken from two different mounts.
//!
//! # It hands out an OWNED handle, per read
//!
//! [`SlotHandle::search`] and [`SlotHandle::knn`] take `&mut self` and
//! [`Context::data`](async_graphql::Context::data) lends `&T`, so a shared borrow cannot answer.
//! Minting per read is what turns a shared citizen into an exclusive borrow without a lock, and —
//! the measurement that decides the shape — no guard is held across an `await`. A
//! `Mutex<SlotHandle<…>>` would have been the literal reading of *behind interior mutability*, and
//! `std::sync::MutexGuard` is not `Send`, so a resolver future holding one is refused by
//! async-graphql's own `Send` bound on every resolver.
//!
//! # The OPENNESS lives in the MOUNT SEAM
//!
//! An application whose store is held inside a larger handle, behind its own accessor, or beside a
//! tenant's routing table implements [`FulltextMount`] / [`VectorMount`] for its own resource type
//! and mints a corpus whichever way it likes. That is the seam a `SearchSource` used to be, moved
//! one layer down to where the resource axis puts it.

use crate::{
  resource::{AsyncResource, Shared},
  slot::SlotName,
  store::{FulltextEngine, FulltextMount, SlotHandle, VectorEngine, VectorMount},
};

/// The refusal a resolver reads when the deployment installed no such resource.
///
/// A sentence of this seam's own rather than the library's, for
/// [`artifact_store`](crate::artifact_store)'s reason: async-graphql's message would name the
/// citizen type and stop. What a deployment reading this one is told is WHICH FIELD went looking,
/// for WHICH CORPUS, and through WHICH RESOURCE — and those three are what turn *a citizen is
/// missing* into *this `.data(…)` line is missing*.
fn unmounted<R>(word: &str, slot: &SlotName) -> async_graphql::Error {
  async_graphql::Error::new(format!(
    "`{word}` searches the `{slot}` corpus of `{resource}`, and no such resource is installed on \
     this schema. A deployment builds it once and hands it over: \
     `builder.data(::ingraph::Shared::<{resource}>::new(resource))`",
    slot = slot.as_ref(),
    resource = core::any::type_name::<R>(),
  ))
}

/// THE FULL-TEXT CORPUS one emitted resolver reads through — the branded handle, and the manager it
/// reaches back through.
///
/// `data_opt` and a refusal of this seam's own; see [`unmounted`].
///
/// # Errors
///
/// Where no [`Shared<R>`](crate::Shared) is installed on the schema.
#[expect(
  clippy::type_complexity,
  reason = "the pair IS what a resolver needs and both halves are projections off the mount seam — \
            an alias would name a tuple no caller ever holds by name"
)]
pub fn search_slot<'a, R, T>(
  ctx: &'a async_graphql::Context<'_>,
  word: &str,
  slot: &'static SlotName,
) -> async_graphql::Result<(
  SlotHandle<<R as FulltextMount>::Handle, T>,
  &'a <<R as FulltextMount>::Handle as FulltextEngine>::Connection,
)>
where
  R: AsyncResource + FulltextMount + 'static,
  T: ?Sized + Send + Sync + 'static,
{
  let mount = async_graphql::Context::data_opt::<Shared<R>>(ctx)
    .map(Shared::get)
    .ok_or_else(|| unmounted::<R>(word, slot))?;
  Ok((
    SlotHandle::mint(FulltextMount::corpus(mount, slot.as_ref())),
    FulltextMount::connection(mount),
  ))
}

/// THE VECTOR CORPUS one emitted resolver reads through — [`search_slot`]'s twin, one family over.
///
/// It differs in the one parameter the two mount seams differ in: a vector corpus's WIDTH, which is
/// the election's own geometry and is spelled at the call.
///
/// # Errors
///
/// Where no [`Shared<R>`](crate::Shared) is installed on the schema.
#[expect(
  clippy::type_complexity,
  reason = "[`search_slot`]'s pair one mount seam over, and its note holds here word for word"
)]
pub fn vector_slot<'a, R, T>(
  ctx: &'a async_graphql::Context<'_>,
  word: &str,
  slot: &'static SlotName,
  dim: usize,
) -> async_graphql::Result<(
  SlotHandle<<R as VectorMount>::Handle, T>,
  &'a <<R as VectorMount>::Handle as VectorEngine>::Connection,
)>
where
  R: AsyncResource + VectorMount + 'static,
  T: ?Sized + Send + Sync + 'static,
{
  let mount = async_graphql::Context::data_opt::<Shared<R>>(ctx)
    .map(Shared::get)
    .ok_or_else(|| unmounted::<R>(word, slot))?;
  Ok((
    SlotHandle::mint(VectorMount::corpus(mount, slot.as_ref(), dim)),
    VectorMount::connection(mount),
  ))
}

#[cfg(test)]
mod tests;