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 SET hit's wire face PROMISES: the names it publishes, the rows it publishes them at,
//! the NULLABILITY of the slot list — which is the one shape claim this family makes that its
//! single-vector sibling does not — and the absence of any answer-wide rank.
//!
//! The SDL is read out of a real schema rather than asserted against a string this file also wrote,
//! on [`matches`](super::super::matches)' own reason: async-graphql builds its registry from the
//! schema root, so a type nothing reaches renders nothing.

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

use super::{FoldedMatch, folded_matches};
use crate::retrieve::{Folded, StreamBest};

/// A node with a name of its own, so the computed `<Node>FoldedMatch` 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 HYDRATED TIER'S NODE, and a SECOND type on purpose: both tiers compute `<N>FoldedMatch`, so
/// mounting them over one node in one schema would be two Rust types at one SDL name — the collision
/// the type's own note says a declaration can only reach by publishing an entity as its own address.
/// Two nodes is what a real declaration has, the address object and the entity object being two.
#[derive(Debug, Clone, PartialEq, SimpleObject)]
struct SegmentEntity {
  media: String,
  frame: i64,
  caption: String,
}

/// A THREE-STREAM answer with one absent slot — the shape every claim below is read off.
///
/// Streams 0 and 2 saw the entity, at ordinals 1 and 7; stream 1 did not. `Sum` of the two present
/// bests is the folded score, which is what makes the entries explain the number they made.
fn walked() -> Folded<Segment, f32> {
  Folded::new(
    9.0_f32,
    Box::new([
      Some(StreamBest::new(6.5_f32, 1)),
      None,
      Some(StreamBest::new(2.5_f32, 7)),
    ]),
    Segment::new("reel-a", 12),
  )
}

/// The one root that reaches both tiers, so the registry holds both.
struct Root;

#[Object]
impl Root {
  async fn set_search(&self) -> Vec<FoldedMatch<Segment, f32>> {
    folded_matches([walked()])
  }

  async fn hydrated_set_search(&self) -> Vec<FoldedMatch<SegmentEntity, f32>> {
    folded_matches([walked().map_node(SegmentEntity {
      media: "reel-a".to_owned(),
      frame: 12,
      caption: "a caption the address does not carry".to_owned(),
    })])
  }
}

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

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

/// The body of one published type, so a claim about a ROW is not answered by a row of a neighbour.
///
/// The close is `"\n}"` and not the first `}`, which is a MEASUREMENT rather than a preference: these
/// types carry descriptions, the descriptions carry GraphQL selection sets (`streams { score }`), and
/// a scan for the first brace ends inside the prose of the first field.
fn body(sdl: &str, ty: &str) -> String {
  let start = sdl
    .find(ty)
    .unwrap_or_else(|| panic!("`{ty}` is published: {sdl}"));
  let rest = &sdl[start..];
  let end = rest.find("\n}").expect("the type closes on its own line");
  rest[..end].to_owned()
}

/// The published name is the NODE's plus `FoldedMatch` — the `<Node>Match` mechanism at the set arity.
#[test]
fn the_published_name_is_the_node_s_own_plus_folded_match() {
  let sdl = sdl();
  assert!(sdl.contains("type SegmentFoldedMatch"), "{sdl}");
  assert!(sdl.contains("setSearch: [SegmentFoldedMatch!]!"), "{sdl}");
}

/// **THE RULED ROWS: score, streams, node** — in that order, and no `rank` anywhere.
///
/// The absent row is the assertion that matters: an answer-wide ordinal is the one number this
/// family refuses to mint, so a face that grew one would be publishing a position the fold authored
/// as if an engine had.
#[test]
fn the_three_rows_are_the_ruled_ones_and_there_is_no_answer_wide_rank() {
  let sdl = sdl();
  let body = body(&sdl, "type SegmentFoldedMatch");

  // `F32!` and not `Float!`: the folded score crosses at the fold's own currency, which is the
  // engine's — `FoldSemantics` being `S → S` — so both grains publish one width.
  let score = body
    .find("score: f32!")
    .unwrap_or_else(|| panic!("a non-null folded score at its own width: {body}"));
  assert!(!body.contains("score: Float!"), "{body}");
  let streams = body
    .find("streams: [SegmentStreamSighting]!")
    .unwrap_or_else(|| panic!("a non-null list of nullable slots: {body}"));
  // `node` and NEVER `key`: the 2026-08-18 alignment gives the third row ONE word across the whole
  // Match family, at the set grain as at the single-vector one.
  let node = body
    .find("node: Segment!")
    .unwrap_or_else(|| panic!("a non-null node: {body}"));

  assert!(score < streams, "score is written before streams: {body}");
  assert!(streams < node, "streams is written before node: {body}");
  // `rank:` and not `rank`, the field's own prose being where the missing row is EXPLAINED.
  assert!(!body.contains("rank:"), "an answer-wide rank: {body}");
  assert!(!body.contains("key:"), "the retired spelling: {body}");
}

/// **THE SLOT LIST IS NON-NULL AND ITS ELEMENTS ARE NULLABLE**, which is the whole positional
/// contract: `[T]!` and never `[T!]!`.
///
/// A non-null element type would force a face to drop the streams that saw nothing, and a position
/// in the list would stop being the query vector's own ordinal.
#[test]
fn the_slot_list_is_positional_and_its_elements_are_nullable() {
  let sdl = sdl();
  let body = body(&sdl, "type SegmentFoldedMatch");
  assert!(body.contains("streams: [SegmentStreamSighting]!"), "{body}");
  assert!(
    !body.contains("[SegmentStreamSighting!]!"),
    "a stream that saw nothing would have no slot: {body}"
  );
}

/// The SLOT publishes the engine's own currency and an ordinal, and nothing else — no contribution,
/// no weight, no re-derived rank.
#[test]
fn the_slot_publishes_the_pre_fold_score_and_the_stream_s_own_ordinal() {
  let sdl = sdl();
  let body = body(&sdl, "type SegmentStreamSighting");
  assert!(body.contains("score: f32!"), "{body}");
  assert!(!body.contains("score: Float!"), "{body}");
  assert!(body.contains("ordinal: Int!"), "{body}");
  assert!(!body.contains("contribution"), "{body}");
}

/// **THE HYDRATED TWIN SPELLS THE THIRD ROW THE SAME AND TYPES IT DIFFERENTLY** — which is the whole
/// of what the two tiers differ in, and it is the NODE PARAMETER that carries it.
#[test]
fn the_hydrated_twin_differs_in_one_row() {
  let sdl = sdl();
  assert!(
    sdl.contains("hydratedSetSearch: [SegmentEntityFoldedMatch!]!"),
    "{sdl}"
  );
  let body = body(&sdl, "type SegmentEntityFoldedMatch");
  // The same WORD over the ENTITY type, and neither retired spelling beside it. ONE `#[Object]`
  // impl published both bodies — this twin and the one above are `FoldedMatch` at two
  // instantiations — so the row's TYPE is the tier's node and nothing else moved.
  assert!(body.contains("node: SegmentEntity!"), "{body}");
  assert!(!body.contains("node: Segment!"), "{body}");
  assert!(!body.contains("key:"), "{body}");
  assert!(!body.contains("entity:"), "the retired spelling: {body}");
  // Everything else is shared, down to the slot list's own shape and the score's own width.
  assert!(body.contains("score: f32!"), "{body}");
  assert!(
    body.contains("streams: [SegmentEntityStreamSighting]!"),
    "{body}"
  );
}

/// THE NON-COMPARABILITY LABELS reach the schema at BOTH grains, because a client that cannot read
/// them will compare a folded score against a floor.
#[test]
fn both_scores_carry_their_own_reading() {
  let sdl = sdl();
  assert!(
    sdl.contains("This list's order is this number's order, and the number compares nowhere else."),
    "{sdl}"
  );
  assert!(
    sdl.contains("The number BEFORE any folding"),
    "the slot's pre-fold reading is missing: {sdl}"
  );
  assert!(
    sdl.contains("There is no rank for the result as a whole"),
    "the missing-rank law is not published: {sdl}"
  );
}

/// THE DESCRIPTION DISCIPLINE: the crate's own reasoning stays on the STRUCT, so no compiler-error
/// name reaches a published schema.
#[test]
fn the_schema_carries_a_client_s_description_and_none_of_the_crate_s() {
  let sdl = sdl();
  for internal in ["E0592", "E0034", "PhantomData", "OutputType", "MEASURED"] {
    assert!(
      !sdl.contains(internal),
      "`{internal}` reached the published schema: {sdl}"
    );
  }
}

/// **THE ENTRIES EXPLAIN THE SCORE THEY MADE**, executed: the two present slots carry the numbers a
/// `Sum` fold added, and the absent one renders `null` in its own position.
#[tokio::test]
async fn the_slots_render_in_asked_order_with_the_absent_one_null() {
  let answer = schema()
    .execute("{ setSearch { score streams { score ordinal } node { frame } } }")
    .await;
  assert!(answer.errors.is_empty(), "{:?}", answer.errors);

  let rendered = answer.data.to_string();
  assert!(rendered.contains("score: 6.5"), "{rendered}");
  assert!(rendered.contains("ordinal: 1"), "{rendered}");
  assert!(rendered.contains("score: 2.5"), "{rendered}");
  assert!(rendered.contains("ordinal: 7"), "{rendered}");
  // THE HOLE: the stream that saw nothing keeps its position rather than being dropped, so the
  // second slot is `null` and the third is still the third.
  assert!(
    rendered.contains("null"),
    "the absent stream was dropped: {rendered}"
  );
  // 6.5 + 2.5 — the entries add up to the score they made.
  assert!(rendered.contains("score: 9"), "{rendered}");
}

/// [`From<Folded>`] moves the score, every slot and the node, and adds nothing — the provenance lock
/// read as an equality.
#[test]
fn the_crossing_is_the_folded_answer_itself() {
  let folded = walked();
  let hit = FoldedMatch::from(folded.clone());

  assert_eq!(hit.score_ref(), folded.score_ref());
  assert_eq!(hit.node_ref(), folded.node_ref());
  assert_eq!(hit.streams().len(), folded.streams().len());
  for (crossed, slot) in hit.streams().iter().zip(folded.streams()) {
    match (crossed, slot) {
      (Some(crossed), Some(slot)) => {
        assert_eq!(crossed.score_ref(), slot.score_ref());
        assert_eq!(crossed.ordinal(), slot.ordinal());
      }
      (None, None) => {}
      _ => panic!("a slot changed presence across the crossing"),
    }
  }
}