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
//! What the hit's wire face PROMISES: the name it publishes, the three fields it publishes them at,
//! the nullability of each, and the label on the score.
//!
//! The SDL is read out of a real schema rather than asserted against a string this file also wrote —
//! async-graphql builds its registry from the schema root, so a type nothing reaches is a type that
//! renders nothing, and a query field naming the hit is the only way to make the assertions be about
//! a served schema.

use async_graphql::{EmptyMutation, EmptySubscription, Object, Schema, SimpleObject};

use super::{Match, matches};
use crate::Ranked;

/// A node with a name of its own, so the computed `<Node>Match` has something to be computed FROM and
/// an assertion about it cannot pass by coincidence.
#[derive(Debug, Clone, PartialEq, SimpleObject)]
struct Segment {
  media: String,
  frame: i64,
}

impl Segment {
  fn new(media: &str, frame: i64) -> Self {
    Self {
      media: media.to_owned(),
      frame,
    }
  }
}

/// The one root that reaches a hit, so the registry holds one.
struct Root;

#[Object]
impl Root {
  /// Three matches with the holes a real pipeline leaves.
  async fn search(&self) -> Vec<Match<Segment, f32>> {
    matches([
      Ranked::new(9.5_f32, 1, Segment::new("reel-a", 12)),
      Ranked::new(4.25_f32, 4, Segment::new("reel-b", 3)),
      Ranked::new(1.5_f32, 9, Segment::new("reel-c", 7)),
    ])
  }
}

fn schema() -> Schema<Root, EmptyMutation, EmptySubscription> {
  Schema::build(Root, EmptyMutation, EmptySubscription).finish()
}

fn sdl() -> String {
  schema().sdl()
}

/// The published name is the NODE's plus `Match` — the `<Node>Connection` mechanism, one type over.
#[test]
fn the_published_name_is_the_node_s_own_plus_match() {
  let sdl = sdl();
  assert!(sdl.contains("type SegmentMatch"), "{sdl}");
  // And the field that returns it says so, which is what proves the name is the one a client reads
  // rather than one that merely exists in the registry.
  assert!(sdl.contains("search: [SegmentMatch!]!"), "{sdl}");
}

/// THE RULED ITEM: score, rank, node — all three NON-NULL, in the ruled order.
///
/// The order is asserted by position rather than by membership: field order is what a client reads
/// in a schema document, and the score comes first because it is the more important of the two
/// numbers.
#[test]
fn the_three_fields_are_non_null_and_in_the_ruled_order() {
  let sdl = sdl();
  let start = sdl
    .find("type SegmentMatch")
    .expect("the match type is published");
  let body = &sdl[start..];
  let end = body.find('}').expect("the type closes");
  let body = &body[..end];

  // `F32!` and not `Float!`: the score seat travels the crossing map, so the row publishes the
  // WIDTH this fixture's currency is measured in. The DOCTRINE is unchanged — the label below is
  // what says the number compares nowhere else — and only the width moved.
  let score = body
    .find("score: f32!")
    .unwrap_or_else(|| panic!("a non-null score at its own width: {body}"));
  assert!(!body.contains("score: Float!"), "{body}");
  let rank = body
    .find("rank: Int!")
    .unwrap_or_else(|| panic!("a non-null rank: {body}"));
  // `node` and NEVER `key`: the 2026-08-18 alignment gives the third row ONE word across the whole
  // Match family, and what a tier decides is which TYPE stands there — here the address.
  let node = body
    .find("node: Segment!")
    .unwrap_or_else(|| panic!("a non-null node: {body}"));
  assert!(!body.contains("key:"), "the retired spelling: {body}");

  assert!(score < rank, "score is written before rank: {body}");
  assert!(rank < node, "rank is written before node: {body}");
}

/// The NON-COMPARABILITY LABEL reaches the schema, because a client that cannot read it will compare
/// two searches' scores.
///
/// It is the field's own description, which is where async-graphql publishes a resolver's rustdoc —
/// so the sentence a Rust reader gets and the sentence a schema explorer gets are the same sentence
/// and cannot drift.
#[test]
fn the_score_carries_its_non_comparability_label() {
  let sdl = sdl();
  assert!(
    sdl.contains("Scores compare INSIDE one result list and nowhere else."),
    "{sdl}"
  );
  // The rank's own honesty rides the same mechanism, and it is the half a client acts on: a rank is
  // not an index into the list it arrived in.
  assert!(sdl.contains("Not its position in this list"), "{sdl}");
}

/// THE DESCRIPTION DISCIPLINE: async-graphql publishes the `#[Object]` impl's rustdoc as the type's
/// SDL description, so what is written there is written to every client.
///
/// The crate's own reasoning lives on the STRUCT for exactly this reason, and this is the assertion
/// that keeps it there — a section moved onto the impl in a later edit turns this red instead of
/// quietly shipping compiler-error names into a published schema.
#[test]
fn the_schema_carries_a_client_s_description_and_none_of_the_crate_s() {
  let sdl = sdl();
  assert!(
    sdl.contains("One result of a search: what matched, how well, and where the engine put it."),
    "{sdl}"
  );
  // The list is the CRATE's own diagnostic vocabulary as the type note actually spells it — both
  // error codes the prefix measurement names, not only the one it used to.
  for internal in [
    "E0592",
    "E0034",
    "duplicate definitions",
    "multiple applicable items",
    "PhantomData",
    "OutputType",
  ] {
    assert!(
      !sdl.contains(internal),
      "`{internal}` reached the published schema: {sdl}"
    );
  }
}

/// The crossing carries the ENGINE's numbers, holes and all — nothing is re-densified on the way to
/// the wire.
#[tokio::test]
async fn the_engine_s_ordinals_cross_unclosed() {
  let answer = schema()
    .execute("{ search { score rank node { media frame } } }")
    .await;
  assert!(answer.errors.is_empty(), "{:?}", answer.errors);

  let rendered = answer.data.to_string();
  // 1, 4, 9 — the raw-stream positions, with the two holes the pipeline left. A face that renumbered
  // its answer would render 1, 2, 3 here.
  assert!(rendered.contains("rank: 1"), "{rendered}");
  assert!(rendered.contains("rank: 4"), "{rendered}");
  assert!(rendered.contains("rank: 9"), "{rendered}");
  assert!(!rendered.contains("rank: 2"), "{rendered}");
  assert!(!rendered.contains("rank: 3"), "{rendered}");
}

/// [`From<Ranked>`] moves the three fields and nothing else, which is what keeps a face from
/// assembling a hit out of two answers.
#[test]
fn the_crossing_is_the_ranked_answer_itself() {
  let ranked = Ranked::new(0.75_f32, 17, Segment::new("reel-z", 42));
  let hit = Match::from(ranked.clone());

  assert_eq!(hit.score_ref(), ranked.score_ref());
  assert_eq!(hit.rank(), ranked.rank());
  assert_eq!(hit.node_ref(), ranked.node_ref());
}

/// The list crossing preserves the ENGINE's order, which is the ranking itself.
#[test]
fn the_list_crossing_keeps_the_engine_s_order() {
  let crossed = matches([
    Ranked::new(3_u32, 1, "a"),
    Ranked::new(2_u32, 5, "b"),
    Ranked::new(1_u32, 6, "c"),
  ]);

  assert_eq!(
    crossed.iter().map(Match::rank).collect::<Vec<_>>(),
    vec![1, 5, 6]
  );
  assert_eq!(
    crossed
      .iter()
      .map(|hit| *hit.node_ref())
      .collect::<Vec<_>>(),
    vec!["a", "b", "c"]
  );
}