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 MOUNT SEAM: how a RESOURCE hands a wire road one corpus of itself, and the connection that
//! corpus's verbs borrow.
//!
//! ```text
//! Shared<Ft>  ──corpus(slot)──►  TantivyFulltext  ──branded──►  SlotHandle<TantivyFulltext, Media>
//!     │                                                                    │
//!     └──connection()──►  &TantivyStore  ──────────────────────────────────┴──►  Connected<'_, …>
//! ```
//!
//! # Why a seam of its own, beside the two store faces that already mint handles
//!
//! [`FulltextStore::fulltext`](super::FulltextStore::fulltext) already takes a corpus name and hands
//! a handle back, and so does its awaited twin. What neither can do is be NAMED by an emitted door:
//! a resource's MODE decides which of the two it wears, the mode is a fact of a `#[ingraph::resource]`
//! declaration in some other crate, and an election that points at that resource is expanded without
//! it. So a door written over `FulltextStore` serves half the resources there are and a door written
//! over `AsyncFulltextStore` serves the other half.
//!
//! This is the MODE-BLIND face over both. The resource's own expansion is what writes it — in TWO
//! TEMPLATES, one per mode, each delegating to the store face that mode wears — so the selection
//! happens exactly where the mode is known, which is the declaration, and every door downstream
//! names one trait.
//!
//! # It carries the CONNECTION, and that is the half a wire door could not reach at all
//!
//! A handle minted here is STATELESS: `FulltextRead::search` reaches its index back through
//! [`Connected`](super::Connected), whose first half is `<Handle as FulltextEngine>::Connection` —
//! the manager the store opened. A door holding only a handle has no value of that type and no way
//! to make one, which is why the emitted resolvers built `Connected::new(&(), ())` and were readable
//! only by an engine whose connection was the unit. The mount is what holds the manager, so the
//! mount is what lends it.
//!
//! # What it does NOT do
//!
//! It does not open anything: a mount is already open — it is what
//! [`AsyncResource::build`](crate::AsyncResource) produced and what
//! [`Shared<R>`](crate::Shared) holds — so both verbs here are synchronous and infallible, which is
//! the contract the per-slot factories already keep on both store faces.
//!
//! It also does not wear the READ or WRITE faces. Those belong to the handle, one grain down, for
//! the reason `store::fulltext`'s own note states: a face on a mount would have to bake ONE corpus
//! name into itself, and a mount holds as many corpora as elections point at it.

use smol_bytes::Utf8Bytes;

use super::{FulltextEngine, VectorEngine};

/// A resource a FULL-TEXT election reads through — the mount, mode-blind, minting one corpus at a
/// time.
///
/// # Who implements it
///
/// `#[ingraph::resource(tantivy)]` writes it. A FOREIGN resource's author writes it beside the base
/// and the faces they already write, and the body is two forwards — the open seam's usual cost, and
/// the reason the trait is public rather than sealed.
///
/// # The bound on [`Handle`](Self::Handle) is the BASE and never a face
///
/// [`FulltextEngine`] is what makes [`connection`](Self::connection)'s return type SPELLABLE — the
/// member lives on the base — and it is the same bound `holds_documents` verifies a pointing leg
/// with. Naming a face here would tax a read-only mount with a write obligation, which is the
/// division the eight faces exist for.
pub trait FulltextMount {
  /// The STATELESS per-slot handle this mount mints — the type that wears the read and write faces.
  type Handle: FulltextEngine;

  /// ONE CORPUS of this mount, by durable name.
  ///
  /// The name is the ELECTION's — `<index>__<field>__<label>` — and it arrives as a parameter for
  /// the grain's own reason: a mount holds as many corpora as elections point at it, and a mount
  /// that baked one name in would be a mount read as a corpus.
  ///
  /// Sync and infallible, per both store faces' own contract: a stateless handle needs no I/O to
  /// mint, so a per-corpus open happens lazily behind the manager on first use.
  fn corpus(&self, slot: impl Into<Utf8Bytes>) -> Self::Handle;

  /// The MANAGER this mount opened, borrowed — the first half of every
  /// [`Connected`](super::Connected) a verb against one of its corpora takes.
  fn connection(&self) -> &<Self::Handle as FulltextEngine>::Connection;
}

/// A resource a VECTOR election reads through — [`FulltextMount`]'s twin, one family over.
///
/// It differs in exactly the one parameter the two per-slot factories differ in, and for the
/// factories' own reason: a vector corpus's WIDTH is a fact its storage cannot be shaped without,
/// where a document schema has no such number.
pub trait VectorMount {
  /// The STATELESS per-slot handle this mount mints.
  type Handle: VectorEngine;

  /// ONE CORPUS of this mount, by durable name, holding `dim`-wide embeddings.
  fn corpus(&self, slot: impl Into<Utf8Bytes>, dim: usize) -> Self::Handle;

  /// The MANAGER this mount opened, borrowed.
  fn connection(&self) -> &<Self::Handle as VectorEngine>::Connection;
}