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 NESTED term's identity: two names, folded, never joined.
//!
//! A nested order names a column of another record — `cover_keyframe_id.title` — and the leaf name
//! alone does not identify that subject. The load-bearing tests here are the three ways a one-name
//! fingerprint gets a nested order wrong, each of which is a silent wrong page rather than an error:
//! two relations reaching the SAME leaf name would alias, a term reached through a relation would
//! alias with the plain column of that name, and a leaf spelling the joined literal would pose as
//! the pair.
//!
//! The fourth is the one that is not about aliasing at all: the pair costs no allocation and no
//! leak, which is what [`the_pair_is_two_static_borrows_and_builds_in_a_const`] pins — the whole
//! reason the identity is a fold of two parts instead of one joined literal.
//!
//! # …and the same four questions at N HOPS
//!
//! The pin that used to mark the ceiling — *a second relation replaces the first* — is now a
//! statement about [`OrderTerm`] alone, because the identity of a deeper path is the WALK's:
//! [`OrderFold`] folds one length-prefixed segment per hop as it descends. So the second half of this
//! file asks the same questions of two and three hops that the first half asks of one — every depth
//! is its own order, the hops are a path rather than a set, the prefixes separate what the bytes
//! would join, and a leaf spelling the joined literal poses as none of them.

use super::{OrderFold, OrderSignature, OrderTerm, TermName};
use crate::{FieldName, OrderDirection};

/// The two relation positions a shot reaches a keyframe through, and the leaf they both land on.
const COVER: &TermName = TermName::new("cover_keyframe_id");
const HERO: &TermName = TermName::new("hero_keyframe_id");
const TITLE: &TermName = TermName::new("title");

/// The hops and the leaf of a path DEEPER than one — the shape a term cannot spell and the walk can.
const STRIP: &TermName = TermName::new("strip_id");
const REEL: &TermName = TermName::new("reel_id");
const LABEL: &TermName = TermName::new("label");

/// One nested term: the keyframe's `title`, reached through `relation`, as this database spells the
/// leaf column.
fn reached_through(relation: &'static TermName, column: &'static str) -> [OrderTerm; 1] {
  [OrderTerm::new(TITLE, FieldName::new(column), OrderDirection::Asc).through(relation)]
}

/// **The alias a one-name fingerprint would create.** Two relations reaching the same target land on
/// the same leaf, so a signature folding only the leaf calls `cover.title` and `hero.title` one
/// order — and a cursor minted walking covers resumes against heroes, silently.
#[test]
fn two_relations_to_one_leaf_are_two_orders() {
  assert_eq!(
    reached_through(COVER, "title")[0].identity(),
    reached_through(HERO, "title")[0].identity()
  );

  assert_ne!(
    OrderSignature::of(&reached_through(COVER, "title")),
    OrderSignature::of(&reached_through(HERO, "title"))
  );
}

/// A term reached THROUGH a relation is not the plain column of that name. `title` on the shot and
/// `cover_keyframe_id.title` on the keyframe it covers are two subjects, and the row a cursor
/// resumes at is a different row in each.
#[test]
fn a_nested_term_is_not_the_plain_column_of_the_same_name() {
  let plain = [OrderTerm::new(
    TITLE,
    FieldName::new("title"),
    OrderDirection::Asc,
  )];

  assert!(plain[0].relation().is_none());
  assert_eq!(reached_through(COVER, "title")[0].relation(), Some(COVER));

  assert_ne!(
    OrderSignature::of(&plain),
    OrderSignature::of(&reached_through(COVER, "title"))
  );
}

/// **Injectivity against the road not taken.** The rejected shape was ONE minted literal,
/// `"cover_keyframe_id.title"`. A declaration cannot spell that as a Rust field name today, but the
/// identity type validates nothing and the fold must not depend on that — under the joined form the
/// two would be one input, and under the two-part form they are two.
///
/// This is what *at least as injective as folding one* means, measured rather than asserted.
#[test]
fn a_leaf_spelling_the_joined_literal_cannot_pose_as_the_pair() {
  let joined = [OrderTerm::new(
    TermName::new("cover_keyframe_id.title"),
    FieldName::new("title"),
    OrderDirection::Asc,
  )];

  assert_ne!(
    OrderSignature::of(&joined),
    OrderSignature::of(&reached_through(COVER, "title"))
  );
}

/// One nested term is not two plain ones. The direction byte closes each term, so the pair's two
/// parts stay inside one term's reading — `ORDER BY cover.title` is one subject and
/// `ORDER BY cover_keyframe_id, title` is two, and no cursor may cross between them.
#[test]
fn one_nested_term_is_not_two_plain_terms() {
  let two = [
    OrderTerm::new(COVER, FieldName::new("cover_id"), OrderDirection::Asc),
    OrderTerm::new(TITLE, FieldName::new("title"), OrderDirection::Asc),
  ];

  assert_ne!(
    OrderSignature::of(&two),
    OrderSignature::of(&reached_through(COVER, "title"))
  );
}

/// The length prefix does the same work at the nested level it already did at the flat one:
/// `["ab", "c"]` and `["a", "bc"]` feed the same bytes without it. Written over the PAIR, which is
/// the sequence the prefix rule newly has to separate.
#[test]
fn the_length_prefix_separates_the_pair_the_bytes_would_join() {
  let ab_c = [
    OrderTerm::new(TermName::new("c"), FieldName::new("c"), OrderDirection::Asc)
      .through(TermName::new("ab")),
  ];
  let a_bc = [OrderTerm::new(
    TermName::new("bc"),
    FieldName::new("c"),
    OrderDirection::Asc,
  )
  .through(TermName::new("a"))];

  assert_ne!(OrderSignature::of(&ab_c), OrderSignature::of(&a_bc));
}

/// The head is an IDENTITY, so the rename law reaches it too: `<db>(rename)` moves what the
/// foreign key is SPELLED as and must not move what the written order fingerprints as. Without this,
/// a nested order would be split apart by exactly the rename the flat one already survives.
#[test]
fn a_rename_beneath_a_nested_term_does_not_split_the_order() {
  assert_ne!(
    reached_through(COVER, "title")[0].column(),
    reached_through(COVER, "caption")[0].column()
  );

  assert_eq!(
    OrderSignature::of(&reached_through(COVER, "title")),
    OrderSignature::of(&reached_through(COVER, "caption"))
  );
}

/// **The ceiling was on the TERM, and the walk is where it is lifted.** A second application to one
/// term still REPLACES rather than deepening — there is no place on a `Copy` `'static` value to put
/// a third segment — and that is now a statement about `OrderTerm` alone rather than about what an
/// order can be fingerprinted as.
#[test]
fn a_second_relation_replaces_the_first_on_one_term() {
  let once = reached_through(COVER, "title");
  let twice = [once[0].through(HERO)];

  assert_eq!(twice[0].relation(), Some(HERO));
  assert_eq!(
    OrderSignature::of(&twice),
    OrderSignature::of(&reached_through(HERO, "title"))
  );
}

/// **THE SEAM.** A walk that hops once before a leaf is the same fingerprint as the term built by
/// [`OrderTerm::through`], and a walk that hops NOT AT ALL is the flat signature — so the two halves
/// of one rule agree wherever both can answer, rather than agreeing because somebody kept them in
/// step.
#[test]
fn the_walk_agrees_with_the_flat_fold_wherever_both_can_answer() {
  let plain = OrderTerm::new(TITLE, FieldName::new("title"), OrderDirection::Asc);

  assert_eq!(
    OrderFold::new().leaf(&plain).finish(),
    OrderSignature::of(&[plain]),
    "no hop is the flat order"
  );
  assert_eq!(
    OrderFold::new().hop(COVER).leaf(&plain).finish(),
    OrderSignature::of(&reached_through(COVER, "title")),
    "one hop is what `through` builds"
  );
  assert_eq!(
    OrderFold::new()
      .leaf(&OrderTerm::new(
        COVER,
        FieldName::new("cover_id"),
        OrderDirection::Asc
      ))
      .leaf(&plain)
      .finish(),
    OrderSignature::of(&[
      OrderTerm::new(COVER, FieldName::new("cover_id"), OrderDirection::Asc),
      plain,
    ]),
    "and several leaves are several terms, in the order they run"
  );
}

/// **N HOPS ARE N DISTINCT ORDERS.** `label`, `cover.label`, `cover.strip.label` and
/// `cover.strip.reel.label` are four subjects and four fingerprints — the positive form of what the
/// ceiling pin used to mark the boundary of.
#[test]
fn every_depth_is_its_own_order() {
  let leaf = OrderTerm::new(LABEL, FieldName::new("label"), OrderDirection::Asc);
  let depths = [
    OrderFold::new().leaf(&leaf).finish(),
    OrderFold::new().hop(COVER).leaf(&leaf).finish(),
    OrderFold::new().hop(COVER).hop(STRIP).leaf(&leaf).finish(),
    OrderFold::new()
      .hop(COVER)
      .hop(STRIP)
      .hop(REEL)
      .leaf(&leaf)
      .finish(),
  ];

  for (at, one) in depths.iter().enumerate() {
    for other in &depths[at + 1..] {
      assert_ne!(one, other, "two depths share a fingerprint");
    }
  }
}

/// **The hops are ORDERED, and the order is the subject's.** `cover.strip.label` and
/// `strip.cover.label` reach two different rows, so a fold that treated the chain as a set would
/// page one under the other's cursor.
#[test]
fn the_hops_are_a_path_rather_than_a_set() {
  let leaf = OrderTerm::new(LABEL, FieldName::new("label"), OrderDirection::Asc);

  assert_ne!(
    OrderFold::new().hop(COVER).hop(STRIP).leaf(&leaf).finish(),
    OrderFold::new().hop(STRIP).hop(COVER).leaf(&leaf).finish(),
  );
}

/// **Alias-proof BY THE PREFIXES, at every depth.** The length prefix is what separates `["ab", "c"]`
/// from `["a", "bc"]` at one hop, and it does the same work at three — the rule does not weaken as
/// the path grows, which is the whole reason the segments are folded rather than joined.
#[test]
fn the_length_prefix_separates_a_deep_path_the_bytes_would_join() {
  let leaf = OrderTerm::new(LABEL, FieldName::new("label"), OrderDirection::Asc);
  let ab_c = OrderFold::new()
    .hop(TermName::new("ab"))
    .hop(TermName::new("c"))
    .leaf(&leaf)
    .finish();
  let a_bc = OrderFold::new()
    .hop(TermName::new("a"))
    .hop(TermName::new("bc"))
    .leaf(&leaf)
    .finish();
  let joined = OrderFold::new()
    .hop(TermName::new("abc"))
    .leaf(&leaf)
    .finish();

  assert_ne!(ab_c, a_bc);
  assert_ne!(ab_c, joined);
  assert_ne!(a_bc, joined);
}

/// A deep path cannot be posed by a LEAF spelling the joined literal either — the same injectivity
/// the one-hop pin measures, at the depth that has no term to be built from.
#[test]
fn a_leaf_spelling_a_deep_joined_literal_cannot_pose_as_the_path() {
  let joined = [OrderTerm::new(
    TermName::new("cover.strip.label"),
    FieldName::new("label"),
    OrderDirection::Asc,
  )];
  let leaf = OrderTerm::new(LABEL, FieldName::new("label"), OrderDirection::Asc);

  assert_ne!(
    OrderSignature::of(&joined),
    OrderFold::new().hop(COVER).hop(STRIP).leaf(&leaf).finish(),
  );
}

/// A DEEP path survives a rename beneath it, exactly as the one-hop one does: every hop is an
/// identity, and `<db>(rename)` moves none of them.
#[test]
fn a_rename_beneath_a_deep_path_does_not_split_the_order() {
  let title = OrderTerm::new(LABEL, FieldName::new("label"), OrderDirection::Asc);
  let renamed = OrderTerm::new(LABEL, FieldName::new("caption"), OrderDirection::Asc);

  assert_ne!(title.column(), renamed.column());
  assert_eq!(
    OrderFold::new().hop(COVER).hop(STRIP).leaf(&title).finish(),
    OrderFold::new()
      .hop(COVER)
      .hop(STRIP)
      .leaf(&renamed)
      .finish(),
  );
}

/// The pair is TWO `&'static` borrows and nothing is built from them, which is what lets the whole
/// composition happen in a constant. A joined literal could not: `const` concatenation is not a
/// language feature, and doing it at runtime would leak a `String` that has to outlive every page.
///
/// A `const` ITEM rather than a `const { … }` block, for the reason the emitter's own subject paths
/// are items: the block does not make a borrow inside it `'static` either.
#[test]
fn the_pair_is_two_static_borrows_and_builds_in_a_const() {
  const NESTED: OrderTerm =
    OrderTerm::new(TITLE, FieldName::new("title"), OrderDirection::Asc).through(COVER);

  assert_eq!(NESTED.relation(), Some(COVER));
  assert_eq!(NESTED.identity(), TITLE);
  assert_eq!(
    OrderSignature::of(&[NESTED]),
    OrderSignature::of(&reached_through(COVER, "title"))
  );
}