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 family's own rows, and the two claims a reader would otherwise have to take on trust: that
//! the projections answer with the DECLARATION's facts, and that a set's members come back in the
//! order its ordinals are minted from.

use std::sync::Arc;

use super::{ElectsOne, ElectsSet, EmbeddingMarker, EmbeddingShape, One, Set};
use crate::{Anon, Embedding};

/// A space, spelled the way the canonical example spells one.
struct Clip(());

/// The ALIAS the whole rework exists for: a token peel reads `ClipFrames` and finds no `Vec`, and a
/// bound resolves it to the type it denotes.
type ClipFrames = Vec<Embedding<f32, 4, Clip>>;

/// A DOWNSTREAM carrier over a `Vec`-like — the third-party vantage, inside the crate's own test so
/// the type-level half is pinned beside the rows it joins.
struct Keyframes(Vec<Embedding<f32, 4, Clip>>);

impl EmbeddingMarker for Keyframes {
  type Item = Embedding<f32, 4, Clip>;
  type Multiplicity = Set;

  fn members(&self) -> impl Iterator<Item = &Self::Item> {
    self.0.iter()
  }
}

/// The multiplicity assertion, as a bound rather than as a value: the answer is a TYPE, so the
/// compiler is what checks it.
fn holds_one<F: EmbeddingMarker<Multiplicity = One>>() {}

/// [`holds_one`]'s twin.
fn holds_a_set<F: EmbeddingMarker<Multiplicity = Set>>() {}

/// The audits, instantiated exactly as an expansion instantiates them.
fn labelled_embedding<F>()
where
  F: EmbeddingMarker,
  <F as EmbeddingMarker>::Multiplicity: ElectsOne<F>,
{
}

fn labelled_list_of_embedding<F>()
where
  F: EmbeddingMarker,
  <F as EmbeddingMarker>::Multiplicity: ElectsSet<F>,
{
}

fn coordinates(fill: f32) -> Arc<[f32]> {
  Arc::from(vec![fill; 4])
}

fn tagged(fill: f32) -> Embedding<f32, 4, Clip> {
  Embedding::new(coordinates(fill)).expect("the fixture is this type's width")
}

/// The single row: one embedding is its own item, and it is [`One`].
#[test]
fn an_embedding_holds_one_of_itself() {
  holds_one::<Embedding<f32, 4>>();
  holds_one::<Embedding<f32, 4, Clip>>();
  labelled_embedding::<Embedding<f32, 4, Clip>>();

  let embedding = tagged(0.5);
  let members: Vec<_> = embedding.members().collect();
  assert_eq!(members.len(), 1);
  assert_eq!(members[0].coordinates(), &[0.5; 4]);
}

/// The set row, through the framework's own carrier.
#[test]
fn a_vec_of_embeddings_holds_a_set() {
  holds_a_set::<Vec<Embedding<f32, 4>>>();
  holds_a_set::<Vec<Embedding<f32, 4, Clip>>>();
  labelled_list_of_embedding::<Vec<Embedding<f32, 4, Clip>>>();
}

/// **THE ALIAS.** `ClipFrames` names no `Vec` at its own spelling and denotes one; a bound reads the
/// denotation, which is the whole of why the facts go through this family and not through the tokens
/// a macro holds.
#[test]
fn an_alias_answers_as_the_type_it_denotes() {
  holds_a_set::<ClipFrames>();
  labelled_list_of_embedding::<ClipFrames>();

  // And every projected fact is the aliased type's own.
  assert_eq!(
    <<ClipFrames as EmbeddingMarker>::Item as EmbeddingShape>::WIDTH,
    4
  );
  let width: usize = <<ClipFrames as EmbeddingMarker>::Item as EmbeddingShape>::WIDTH;
  let element: <<ClipFrames as EmbeddingMarker>::Item as EmbeddingShape>::Element = 0.5f32;
  let _space: Option<<<ClipFrames as EmbeddingMarker>::Item as EmbeddingShape>::Space> = None;
  assert_eq!(width, 4);
  assert!((element - 0.5).abs() < f32::EPSILON);
}

/// **THE NEWTYPE.** A carrier this framework never heard of joins by writing one impl, and answers
/// every question the framework's own rows answer.
#[test]
fn a_downstream_carrier_joins_by_one_impl() {
  holds_a_set::<Keyframes>();
  labelled_list_of_embedding::<Keyframes>();

  let frames = Keyframes(vec![tagged(0.25), tagged(0.75)]);
  let members: Vec<_> = frames.members().map(EmbeddingShape::coordinates).collect();
  assert_eq!(members, vec![&[0.25; 4][..], &[0.75; 4][..]]);
}

/// **THE ORDER CONTRACT.** Ordinals are minted by walking [`EmbeddingMarker::members`], so the walk
/// IS the ordinal order — a set of keyframe embeddings comes back in keyframe order because the
/// carrier yields them in it.
#[test]
fn the_order_members_yields_is_the_ordinal_order() {
  let held = vec![tagged(0.1), tagged(0.2), tagged(0.3)];
  let ordinals: Vec<(u32, f32)> = (0u32..)
    .zip(held.members())
    .map(|(at, member)| (at, EmbeddingShape::coordinates(member)[0]))
    .collect();

  assert_eq!(ordinals.len(), 3);
  assert_eq!(ordinals[0].0, 0);
  assert!((ordinals[0].1 - 0.1).abs() < f32::EPSILON);
  assert_eq!(ordinals[2].0, 2);
  assert!((ordinals[2].1 - 0.3).abs() < f32::EPSILON);
}

/// An EMPTY set is a legal value: it yields no members, so a knn over its column never reaches the
/// entity and no refusal is involved.
#[test]
fn an_empty_set_yields_no_members() {
  let empty: Vec<Embedding<f32, 4, Clip>> = Vec::new();
  assert_eq!(empty.members().count(), 0);
}

/// The SPACE is projected rather than spelled, so a field that named none answers [`Anon`] and one
/// that named a space answers the space — with no *absent* state in between for an emission to have
/// to handle.
#[test]
fn the_space_is_a_projection_and_an_unnamed_one_is_anon() {
  fn anonymous<F>()
  where
    F: EmbeddingMarker,
    F::Item: EmbeddingShape<Space = Anon>,
  {
  }

  fn clip<F>()
  where
    F: EmbeddingMarker,
    F::Item: EmbeddingShape<Space = Clip>,
  {
  }

  anonymous::<Embedding<f32, 4>>();
  anonymous::<Vec<Embedding<f32, 4>>>();
  clip::<Embedding<f32, 4, Clip>>();
  clip::<ClipFrames>();
}