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
//! [`Connected`] — the per-call resource bundle every store-handle op receives: a borrow of the
//! shared connection-manager (the `*Store` that was opened once) plus the per-call scope. ONE
//! lifetime by design — see the type doc.

/// The per-call resources a store handle operates against: a borrow of the shared `Connection` (the
/// connection-manager a `*Store` opened once and now hands to every op, so nothing reconnects per
/// call) plus the per-call `scope` — owned here, being whatever the handle's `ReadContext<'_>` /
/// `WriteContext<'_>` GAT resolved to (search knobs, or a borrowed `&mut Transaction`).
///
/// ONE lifetime: `'a` is the connection borrow. Any borrow the scope itself needs rides a lifetime
/// baked INSIDE `X` (the `WriteContext<'s>` / `ReadContext<'s>` GAT), so the scope's borrow is
/// already decoupled from `'a` — a second wrapper lifetime is provably redundant. `C: ?Sized` so an
/// unsized / `dyn` manager can still be borrowed.
pub struct Connected<'a, C: ?Sized, X> {
  connection: &'a C,
  scope: X,
}

impl<'a, C: ?Sized, X> Connected<'a, C, X> {
  /// Bundle a connection borrow with a per-call scope.
  #[inline]
  pub const fn new(connection: &'a C, scope: X) -> Self {
    Self { connection, scope }
  }

  /// The shared connection-manager — where a read reaches its searcher / pool / table (reads
  /// resolve committed state through it; the scope stays the owned knobs). Reborrowed to `&self`.
  #[inline]
  pub const fn connection(&self) -> &C {
    self.connection
  }

  /// The per-call scope, by reference.
  #[inline]
  pub const fn scope(&self) -> &X {
    &self.scope
  }

  /// Take the owned scope, dropping the connection borrow — for an op whose scope (a transaction) is
  /// all it still needs.
  #[inline]
  pub fn into_scope(self) -> X {
    self.scope
  }

  /// Split into the connection at the FULL `'a` (not the transient `&self` reborrow) and the owned
  /// scope. This is what lets an impl HOLD the connection borrow across an `.await` while also using
  /// the scope — `let (conn, tx) = ctx.into_parts();` then `conn.…().await` and `tx.…().await`.
  #[inline]
  pub fn into_parts(self) -> (&'a C, X) {
    (self.connection, self.scope)
  }
}

/// Written rather than derived, because `#[derive(Clone)]` would bound `C: Clone` — and the
/// connection is BORROWED here, so a shared manager that is not cloneable (which is most of them: a
/// pool, an open index, a cached table set) would lose the impl for a bound nothing spends.
///
/// # What a clone IS, and why the bound sits on the SCOPE alone
///
/// A copy of the connection borrow beside a clone of the per-call scope. That is the whole of it,
/// and it exists for ONE caller: the multi-vector road runs the engine once per query vector, and
/// [`VectorRead::knn`](crate::VectorRead::knn) takes its scope BY VALUE — so `m` calls need `m`
/// scopes, and cloning the knobs is the honest way to get them. Read knobs are what a scope holds on
/// that path (`k`, a probe count, a metric, a prefilter), and they are per-call by nature.
///
/// A read scope that must NOT be duplicated — a lease with an identity, a cursor — simply does not
/// implement [`Clone`], and its engine is then absent from the set road at COMPILE time rather than
/// misused at run time. That is the seam doing its job: the capability is asked for where it is
/// spent, and an engine answers by having it or not having it.
impl<C: ?Sized, X: Clone> Clone for Connected<'_, C, X> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      connection: self.connection,
      scope: self.scope.clone(),
    }
  }
}

#[cfg(test)]
mod tests;