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 seam and the verb, implemented BY HAND — which is the whole claim: a third-party member joins
//! a root's fused query with no edit to the root and no derive at all.
//!
//! Beside [`AsyncFusedRead`] since 2026-08-19, where these lived under the two modality markers that
//! retired that day. Nothing about the acceptance moved with them: what a third party writes is
//! [`Fusable`] and [`AsyncFusedRead`], and every claim below was always about those two.

use core::{
  convert::Infallible,
  future::Future,
  num::NonZeroUsize,
  pin::pin,
  task::{Context, Poll, Waker},
};

use crate::retrieve::{AsyncFusedRead, Fusable, Rooted};

/// Drive a future to its value without a runtime — every future here is already-ready.
fn block_on<F: Future>(future: F) -> F::Output {
  let mut future = pin!(future);
  let mut cx = Context::from_waker(Waker::noop());
  loop {
    if let Poll::Ready(value) = future.as_mut().poll(&mut cx) {
      return value;
    }
  }
}

/// The depth every call below asks a member at — minted rather than written, because the seam's
/// currency admits no zero.
fn depth(n: usize) -> NonZeroUsize {
  NonZeroUsize::new(n).expect("the fixture depths are not zero")
}

/// A third-party VECTOR member, written out.
struct Shots;

/// Its package pair, opaque to every parent.
struct ShotsOptions;
struct ShotsQuestion;

impl Fusable for Shots {
  type Options = ShotsOptions;
  type Question = ShotsQuestion;
}

impl<E> AsyncFusedRead<E> for Shots {
  type Ctx<'a>
    = &'a [(u32, u64)]
  where
    E: 'a;
  type Error = Infallible;
  type Evidence = f32;
  type Root = u32;

  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,
  {
    let rows = ctx
      .iter()
      .take(limit.get())
      .map(|&(root, rank)| Rooted::new(root, rank, 1.0_f32))
      .collect();
    core::future::ready(Ok(rows))
  }
}

/// A third-party FULL-TEXT member over the SAME root, which is what makes the two fusable together.
struct Captions;

struct CaptionsOptions;
struct CaptionsQuestion;

impl Fusable for Captions {
  type Options = CaptionsOptions;
  type Question = CaptionsQuestion;
}

impl<E> AsyncFusedRead<E> for Captions {
  type Ctx<'a>
    = &'a [(u32, u64)]
  where
    E: 'a;
  type Error = Infallible;
  type Evidence = f32;
  type Root = u32;

  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,
  {
    let rows = ctx
      .iter()
      .take(limit.get())
      .map(|&(root, rank)| Rooted::new(root, rank, 2.0_f32))
      .collect();
    core::future::ready(Ok(rows))
  }
}

/// A member that RANKS NOTHING — no [`AsyncFusedRead`] impl and no [`Fusable`] one. The absence is
/// the assertion a root's `E0277` reports.
struct Journal;

/// **A PARENT NAMES NOTHING OF A MEMBER'S** — it projects, and the compiler resolves the meeting.
///
/// Written as a generic function because that IS the root door's shape: every type it touches is a
/// projection off the member, so a member whose shapes it has never seen still fits.
fn ask_vector<M, E>(
  ctx: M::Ctx<'_>,
  options: &M::Options,
  question: &M::Question,
) -> Vec<Rooted<u32, f32>>
where
  M: Fusable + AsyncFusedRead<E, Root = u32, Evidence = f32, Error = Infallible>,
{
  block_on(M::keys(ctx, Some(options), question, depth(10)))
    .expect("the fixture member refuses nothing")
}

/// **THE VERB IS CALLABLE THROUGH THE PROJECTION**, with no `&self` anywhere: the member's type is a
/// brand and the state arrived through `Ctx`.
#[test]
fn a_hand_written_vector_member_answers_through_the_projection() {
  let rows = ask_vector::<Shots, ()>(&[(7, 1), (9, 2)], &ShotsOptions, &ShotsQuestion);

  assert_eq!(rows.len(), 2);
  assert_eq!(rows[0].root_ref(), &7);
  assert_eq!(rows[0].rank(), 1);
}

/// **THE ROAD IS UNIFORM ACROSS MODALITIES** — one `AsyncFusedRead` impl per member whatever its
/// kind, which is what lets a root's MIXED door ask every member through one projection without
/// seeing any member's kind. Uniform is the whole of it now: the two markers that let a consumer
/// demand ONE modality retired on 2026-08-19 with no caller having ever written the bound.
///
/// The two members fuse together because their `Root` types agree, which is the equality bound a
/// parent writes rather than a runtime check.
#[test]
fn two_modalities_travel_one_road_and_fuse_over_one_root() {
  let vector = block_on(<Shots as AsyncFusedRead<()>>::keys(
    &[(7, 1), (9, 2)],
    Some(&ShotsOptions),
    &ShotsQuestion,
    depth(10),
  ))
  .expect("the fixture refuses nothing");
  let fulltext = block_on(<Captions as AsyncFusedRead<()>>::keys(
    &[(9, 1), (11, 2)],
    Some(&CaptionsOptions),
    &CaptionsQuestion,
    depth(10),
  ))
  .expect("the fixture refuses nothing");

  let fused = crate::retrieve::fuse_weighted::<u32, f32, crate::retrieve::HashJoin<u32>>(
    vec![(1.0, vector), (1.0, fulltext)],
    crate::retrieve::Fusion::default(),
  );

  assert_eq!(
    fused[0].root(),
    9,
    "the root both modalities agreed about did not lead: {fused:?}",
  );
  assert_eq!(
    fused[0].evidence().len(),
    2,
    "the nested provenance lost a member: {fused:?}",
  );
}

/// **THE SEAM IS THE DEMAND**, which is what makes a fusion package a projection rather than a
/// registry: a parent names `<M as Fusable>::Options` and the compiler resolves the meeting, so a
/// member that has no package is `E0277` at the parent's own field.
///
/// `Journal` is that member, and it is spent rather than merely declared — an unspent fixture is a
/// negative claim nothing checks.
#[test]
fn the_seam_is_the_demand_and_a_member_without_one_has_no_package() {
  const fn has_a_package<M: Fusable>() {}

  has_a_package::<Shots>();
  has_a_package::<Captions>();

  // MUTATION: add `impl Fusable for Journal` and the line below compiles, which is the whole of what
  // this fixture's absence asserts.
  //
  // has_a_package::<Journal>();
  let _ = Journal;
}