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 crate::{ColumnKind, CursorValue, DialectCursor, dialect};

use super::*;
use crate::primitives::mediatime::tests::rate;

/// The bytes the RETIRED hand kit minted for `30000/1001`, written out rather than computed.
///
/// This is the byte-continuity pin's anchor: a literal, so it cannot drift with the code that used
/// to produce it. Two big-endian `i32`s — `30000 = 0x7530`, `1001 = 0x03E9` — and no length prefix
/// anywhere, the framed default for these two members being sixteen bytes rather than eight.
const NTSC_TOKEN: [u8; 8] = [0, 0, 117, 48, 0, 0, 3, 233];

/// One value's cursor bytes at one dialect, through the framework's own seam.
fn at<Db>(value: &Rate) -> Vec<u8>
where
  Rate: DialectCursor<Db>,
{
  let mut bytes = Vec::new();
  value.write_cursor_at(&mut bytes);
  bytes
}

/// The width is TWO, and the two are the segments every other half of the crossing reads.
#[test]
fn a_rate_spans_the_two_columns_it_is_bound_and_read_through() {
  let names: Vec<_> = <Rate as ColumnKind>::SEGMENTS
    .iter()
    .map(|shape| {
      shape
        .field()
        .expect("a plain segment names its column")
        .declared()
        .as_str()
    })
    .collect();

  assert_eq!(names, ["num", "den"]);
}

/// **THE MOUNT DID NOT CHANGE THE BYTE FORM** — a token the retired hand kit minted still decodes,
/// and the codec still mints exactly it.
///
/// This is the whole proof obligation of the migration. A page token is a string a client is holding
/// right now; the seat replaced WHO writes the bytes and not WHICH bytes, so an outstanding token
/// resumes across the change. Sixteen bytes would be the framed default having quietly taken over,
/// which is the one way this mount could fail silently — a frame round-trips perfectly whether or
/// not the codec was ever reached.
#[test]
fn an_old_kit_token_decodes_through_the_mounted_seat() {
  assert_eq!(
    <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(&NTSC_TOKEN),
    Some(rate(30_000, 1001)),
    "the token the hand kit wrote is still this seat's encoding"
  );
  assert_eq!(
    at::<dialect::Sqlite>(&rate(30_000, 1001)),
    NTSC_TOKEN,
    "and the seat mints the identical bytes back"
  );
  assert_eq!(
    NTSC_TOKEN.len(),
    2 * size_of::<i32>(),
    "eight flat bytes, not the framed sixteen"
  );
}

/// **ONE CODEC, THREE DIALECTS** — the byte form does not vary per store, and every declared dialect
/// mounts it.
///
/// The all-mounted state is load-bearing rather than tidy: the fallible construction protocol is
/// admitted only while no declared dialect is left riding the framed default, so a dialect dropping
/// off this list would bring back a refusal at `builder(entry = "checked_fps", fallible)`.
#[test]
fn every_declared_dialect_walks_the_same_bytes() {
  let held = rate(30_000, 1001);

  assert_eq!(at::<dialect::Sqlite>(&held), NTSC_TOKEN);
  assert_eq!(at::<dialect::Postgres>(&held), NTSC_TOKEN);
  assert_eq!(at::<dialect::Mysql>(&held), NTSC_TOKEN);

  for bytes in [
    <Rate as DialectCursor<dialect::Postgres>>::read_cursor_at(&NTSC_TOKEN),
    <Rate as DialectCursor<dialect::Mysql>>::read_cursor_at(&NTSC_TOKEN),
  ] {
    assert_eq!(bytes, Some(held), "each dialect reads its own minting");
  }
}

/// **The columns hold the RATE's reading and not its reciprocal**, which is the one convention this
/// citizen has to state rather than inherit — asserted on the bytes a cursor writes, since those are
/// the same two values a bind pushes.
///
/// The timebase side still rides its own hand `CursorValue`: that household has not taken the
/// declaration yet, and reading it through the row it actually has is what keeps this a claim about
/// the two citizens rather than about one of them twice.
#[test]
fn the_stored_pair_is_the_rate_and_not_its_timebase() {
  let mut reciprocal = Vec::new();
  crate::primitives::mediatime::tests::timebase(1001, 30_000).write_cursor(&mut reciprocal);

  assert_ne!(
    at::<dialect::Sqlite>(&rate(30_000, 1001)),
    reciprocal,
    "a rate column and a timebase column of one value hold different pairs"
  );
  assert_eq!(
    <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(&NTSC_TOKEN)
      .expect("its own bytes")
      .get()
      .num(),
    30_000
  );
}

/// The cursor carries the pair a COLUMN holds — the reduced one — so two spellings of one rate are
/// one boundary.
#[test]
fn the_cursor_writes_the_pair_a_column_holds() {
  assert_eq!(
    at::<dialect::Sqlite>(&rate(60_000, 2002)),
    at::<dialect::Sqlite>(&rate(30_000, 1001))
  );
  assert_eq!(
    at::<dialect::Sqlite>(&rate(60_000, 2002)).len(),
    2 * size_of::<i32>()
  );
}

/// Round trip, with the DECLARED pair coming back reduced — equality-preserving, `mediatime`
/// comparing by value.
#[test]
fn a_written_cursor_reads_back_as_the_stored_value() {
  for (num, den) in [(0, 1), (30, 1), (60_000, 2002), (30_000, 1001)] {
    let written = rate(num, den);
    let bytes = at::<dialect::Sqlite>(&written);

    let read =
      <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(&bytes).expect("its own bytes");

    assert_eq!(read, written, "{num}/{den} survives the round trip");
    assert_eq!(read.reduced(), written.reduced());
  }
}

/// A forged cursor is refused rather than read — the wrong WIDTH, and the right width holding a pair
/// no `Rate` can exist as.
///
/// The domain half is the codec's own judgement and not the protocol's: a mounted read never reaches
/// the construction protocol, so a pair the remote would reject has to be folded into this codec's
/// [`None`] or it is admitted. Both refusals are asserted through the SEAT, which is the road a page
/// walk actually takes.
#[test]
fn a_forged_cursor_is_refused_rather_than_read() {
  for forged in [[0u8; 0].as_slice(), &[0; 4], &[0; 7], &[0; 9], &[0; 16]] {
    assert_eq!(
      <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(forged),
      None,
      "{forged:?}"
    );
  }

  let zero_denominator = [0, 0, 0, 30, 0, 0, 0, 0];
  assert_eq!(
    <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(&zero_denominator),
    None
  );

  let negative_numerator = [255, 255, 255, 255, 0, 0, 0, 1];
  assert_eq!(
    <Rate as DialectCursor<dialect::Sqlite>>::read_cursor_at(&negative_numerator),
    None
  );
}

/// The two column invariants are refused by the shared reader, which the decode and the cursor both
/// go through — so a database and a page token cannot come to admit different values.
#[test]
fn the_column_reader_states_which_invariant_a_pair_broke() {
  assert_eq!(assembled(30, 0), Err(RateColumnError::ZeroDenominator));
  assert_eq!(assembled(-1, 1), Err(RateColumnError::NegativeHalf));
  assert_eq!(assembled(1, -2), Err(RateColumnError::NegativeHalf));
  assert_eq!(assembled(0, 1), Ok(rate(0, 1)));

  // Unreduced is not an error: a column holds whatever was written to it.
  assert_eq!(assembled(60_000, 2002), Ok(rate(30_000, 1001)));

  assert_eq!(
    RateColumnError::ZeroDenominator.to_string(),
    "the stored denominator must not be zero"
  );
}