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
use core::num::NonZeroUsize;

use super::SlotHandle;
use crate::{AsyncFulltextWrite, AsyncVectorRead, Connected, FulltextSubset, VectorColumn};

/// The `k` every branded read below hands the verb.
const K: NonZeroUsize = NonZeroUsize::new(10).expect("10 is not zero");

/// Two declarations sharing one engine TYPE — which is the whole hazard: every slot's handle is the
/// same `TantivyFulltext`, so nothing but the brand tells one from another.
struct Transcript;
struct Caption;

/// Drive an already-ready future to its value without a runtime.
fn poll<F: Future>(future: F) -> F::Output {
  use core::{
    pin::pin,
    task::{Context, Poll, Waker},
  };
  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 brand is a TYPE fact and carries no value, so two handles over one engine differ in nothing a
/// runtime check could see — which is why the check is the compiler's.
#[test]
fn the_brand_carries_no_value() {
  let transcripts: SlotHandle<(), Transcript> = SlotHandle::mint(());
  let captions: SlotHandle<(), Caption> = SlotHandle::mint(());

  assert_eq!(
    core::mem::size_of_val(&transcripts),
    core::mem::size_of::<()>()
  );
  assert_eq!(transcripts.engine(), captions.engine());
  // And the engine comes back out unchanged — the brand wraps, it does not transform.
  let () = transcripts.into_engine();
}

/// A CLONE keeps the brand: `T` is unchanged, so the second handle is the same slot's and nothing
/// about the guarantee moved. It is what a concurrent reader takes, the branded verbs being `&mut`.
#[test]
fn a_clone_keeps_the_brand() {
  let one: SlotHandle<u8, Transcript> = SlotHandle::mint(7);
  let two = one.clone();

  // Both are `SlotHandle<u8, Transcript>`, so the annotation type-checks — a clone branded `Caption`
  // would be `E0308`, and that half is the trybuild fixture's.
  let same: SlotHandle<u8, Transcript> = two;
  assert_eq!(one.engine(), same.engine());
}

/// The auto-traits are the ENGINE's, not the declaration's — `PhantomData<fn() -> T>` earning its
/// spelling. A declaration that is neither `Send` nor `Sync` must not cost the write seam its
/// `+ Send` future, since it reaches no byte of the handle.
#[test]
fn the_brand_does_not_borrow_the_declarations_auto_traits() {
  /// Neither `Send` nor `Sync`, and never constructed — it is only ever NAMED.
  struct Unsendable(#[allow(dead_code)] *const u8);

  const fn is_send<T: Send + Sync>() {}
  const _: () = is_send::<SlotHandle<u8, Unsendable>>();

  assert_eq!(
    core::mem::size_of::<SlotHandle<u8, Unsendable>>(),
    core::mem::size_of::<u8>(),
    "and the marker costs no bytes either",
  );
}

/// The branded doors turn on the unused faces — every verb resolves through the brand and forwards.
#[test]
fn the_branded_doors_forward_to_the_engine() {
  let mut fulltext: SlotHandle<(), Transcript> = SlotHandle::mint(());
  assert_eq!(
    poll(fulltext.upsert_document(Connected::new(&(), ()), ())),
    Ok(())
  );
  assert_eq!(
    poll(fulltext.search(Connected::new(&(), ()), FulltextSubset::All, "car", K, None)),
    Ok(Vec::new())
  );

  let mut vector: SlotHandle<(), Caption> = SlotHandle::mint(());
  assert_eq!(
    poll(vector.upsert_vector(Connected::new(&(), ()), ())),
    Ok(())
  );
  // The BRAND and the COLUMN are two facts at two grains, and neither substitutes for the other: the
  // type says which declaration's slot this is, the argument says which of that declaration's
  // elected embeddings answers.
  assert_eq!(
    poll(vector.knn(
      Connected::new(&(), ()),
      VectorColumn::new("image_embedding"),
      &[],
      K,
      None
    )),
    Ok(Vec::new())
  );

  // The seams themselves are untouched: the unused faces are still reachable UNBRANDED, which is the
  // proof that the brand added no impl row and no bound to either engine trait.
  assert_eq!(
    poll(AsyncFulltextWrite::upsert(&(), Connected::new(&(), ()), ())),
    Ok(())
  );
  assert_eq!(
    poll(AsyncVectorRead::knn(
      &(),
      Connected::new(&(), ()),
      VectorColumn::new("image_embedding"),
      &[],
      K,
      None
    )),
    Ok(Vec::new())
  );
}