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 descriptor's own facts: what a `const` holds, and what the audits over it refuse.
//!
//! Everything here runs at COMPILE time or reads a `const` — there is no rendering in this module
//! and therefore nothing to put to an engine. The statements a descriptor becomes are asserted where
//! they are rendered, at [`query::sql`](crate::query::sql), and the refusals its constructors give
//! are `compile_fail` blocks beside the constructors themselves, since a refusal in a `const` cannot
//! be caught by a test that has already compiled.

use super::{Column, Describe, EdgeShape, EdgeTable, SideTable, Table, describes};
use crate::{ColumnName, ColumnShape, FieldName, RecordAddress};

/// The database a descriptor in this module is written for. A stand-in, because nothing here
/// renders: [`Describe`]'s parameter is a type and not a driver.
struct Db;

/// A record's home is a [`Table`], stated per target — which is what a stand-in has to say too, the
/// bound being the walk's floor rather than the SQL family's private arrangement.
impl crate::Habitat for Db {
  type Blueprint = Table;
}

/// A root: one key column, one nullable column, one indexed field.
struct Media;

/// A child: a two-column key, a nullable column, and one collection of each shape.
struct Clip;

const MEDIA_COLUMNS: &[ColumnShape] = &[
  ColumnShape::Plain(ColumnName::new("id")),
  ColumnShape::Plain(ColumnName::new("title")),
];

const CLIP_COLUMNS: &[ColumnShape] = &[
  ColumnShape::Plain(ColumnName::new("media_id")),
  ColumnShape::Plain(ColumnName::new("id")),
  ColumnShape::Plain(ColumnName::new("title")),
  ColumnShape::Plain(ColumnName::new("bit_rate")),
];

impl Describe<Db> for Media {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(FieldName::new("media"), &[FieldName::new("id")]),
    &[
      Column::new(FieldName::new("id"), "INTEGER", false),
      Column::new(FieldName::new("title"), "TEXT", true),
    ],
  )
  .with_indexes(&[FieldName::new("title")]);
}

impl Describe<Db> for Clip {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(
      FieldName::new("clip"),
      &[FieldName::new("media_id"), FieldName::new("id")],
    ),
    &[
      Column::new(FieldName::new("media_id"), "INTEGER", false),
      Column::new(FieldName::new("id"), "INTEGER", false),
      Column::new(FieldName::new("title"), "TEXT", true),
      Column::new(FieldName::new("bit_rate"), "INTEGER", false),
    ],
  )
  .with_edges(&[
    EdgeTable::new(&[FieldName::new("tags")], EdgeShape::Sequence, "TEXT"),
    EdgeTable::new(&[FieldName::new("notes")], EdgeShape::Set, "TEXT"),
  ]);
}

/// The AUDIT both descriptors state, in the position an emitted one would: beside the declaration,
/// as a `const`. A column list that drifted from the row's is `E0080` here rather than a
/// `CREATE TABLE` that renders and then fails at the first insert naming the missing column.
const _: () = assert!(describes(
  &<Media as Describe<Db>>::BLUEPRINT,
  MEDIA_COLUMNS
));
const _: () = assert!(describes(&<Clip as Describe<Db>>::BLUEPRINT, CLIP_COLUMNS));

/// The three optional members DEFAULT to absent, which is what makes a record with no collection and
/// no index a two-argument descriptor.
#[test]
fn a_bare_descriptor_carries_no_index_no_edge_and_no_discriminant() {
  let table = <Media as Describe<Db>>::BLUEPRINT;
  assert_eq!(table.edges(), &[]);
  assert_eq!(table.source(), None);

  let clip = <Clip as Describe<Db>>::BLUEPRINT;
  assert_eq!(clip.indexes(), &[] as &[&FieldName]);
}

/// The address is the query layer's own type, PROJECTED — so a descriptor states the table's name
/// and its key columns exactly once, wherever the row states them.
#[test]
fn the_address_is_the_rows_own_and_not_a_second_spelling() {
  let clip = <Clip as Describe<Db>>::BLUEPRINT;
  assert_eq!(clip.address().table(), FieldName::new("clip"));
  assert_eq!(
    clip.address().keys(),
    [FieldName::new("media_id"), FieldName::new("id")]
  );
}

/// A key column's stored type is READ off the table's own columns, which is what an edge table's
/// leading columns are declared at.
#[test]
fn a_key_column_is_typed_by_the_column_list_that_carries_it() {
  let clip = <Clip as Describe<Db>>::BLUEPRINT;
  assert_eq!(clip.stored(FieldName::new("media_id")), "INTEGER");
  assert_eq!(clip.stored(FieldName::new("title")), "TEXT");
}

/// A column the table does not carry has no type to answer with, and asking is the CALLER's error —
/// [`Table::new`] has already refused the one caller that must never ask.
#[test]
#[should_panic(expected = "this table carries no such column")]
fn a_column_the_table_does_not_carry_has_no_stored_type() {
  let _ = <Media as Describe<Db>>::BLUEPRINT.stored(FieldName::new("bit_rate"));
}

/// The audit is an ORDERED comparison rather than a set one: a `CREATE TABLE` declares columns in
/// the order the descriptor lists them and a decode reads them in the order the row's own list
/// names, so two lists holding the same names in different orders are two different tables.
#[test]
fn the_audit_reads_the_column_order_and_not_only_the_names() {
  const SWAPPED: &[ColumnShape] = &[
    ColumnShape::Plain(ColumnName::new("title")),
    ColumnShape::Plain(ColumnName::new("id")),
  ];
  assert!(!describes(&<Media as Describe<Db>>::BLUEPRINT, SWAPPED));
  assert!(describes(
    &<Media as Describe<Db>>::BLUEPRINT,
    MEDIA_COLUMNS
  ));
}

/// A shorter or longer list is a drift, which is the half a per-column loop alone would miss.
#[test]
fn the_audit_reads_the_width() {
  assert!(!describes(
    &<Clip as Describe<Db>>::BLUEPRINT,
    &[ColumnShape::Plain(ColumnName::new("media_id"))]
  ));
}

/// The two shapes differ in exactly one fact, and it is the one that decides how many columns an
/// edge row has.
#[test]
fn a_sequence_carries_an_ordinal_and_a_set_does_not() {
  assert!(EdgeShape::Sequence.ordered());
  assert!(!EdgeShape::Set.ordered());
}

/// A fan-in's descriptor: the discriminant is one of the table's own columns, and the provenance
/// table holds that variant's ancestors and not the id it is keyed on.
const SPLIT: Table = Table::new(
  RecordAddress::new(FieldName::new("caption"), &[FieldName::new("id")]),
  &[
    Column::new(FieldName::new("id"), "INTEGER", false),
    Column::new(FieldName::new("__ig_source__"), "TEXT", false),
  ],
)
.with_provenance(
  FieldName::new("__ig_source__"),
  &[SideTable::new(
    FieldName::new("caption_frame"),
    &[Column::new(FieldName::new("media_id"), "INTEGER", false)],
  )],
);

/// The SPLIT LAYOUT arrives in one call, and both halves are read back through the names it was
/// given — the discriminant among the table's own columns, and one provenance table per upstream.
#[test]
fn the_split_layout_is_read_back_through_the_names_it_was_declared_with() {
  assert_eq!(SPLIT.source(), Some(FieldName::new("__ig_source__")));
  assert_eq!(
    SPLIT
      .sides()
      .iter()
      .map(|side| side.table().as_str())
      .collect::<Vec<_>>(),
    ["caption_frame"]
  );
  assert_eq!(<Media as Describe<Db>>::BLUEPRINT.source(), None);
  assert!(<Media as Describe<Db>>::BLUEPRINT.sides().is_empty());
}

/// The discriminant is among the table's own columns, so the audit a descriptor states against its
/// row's `SELECT` list carries it — which is what makes it a column the write binds and the read
/// selects rather than one only the DDL knows about.
#[test]
fn the_discriminant_is_one_of_the_tables_own_columns() {
  assert!(describes(
    &SPLIT,
    &[
      ColumnShape::Plain(ColumnName::new("id")),
      ColumnShape::Plain(ColumnName::new("__ig_source__"))
    ]
  ));
}

/// The id a provenance row points back at is the key's LAST column, and the whole key where that is
/// its only one — which is what makes the foreign key legal in both shapes.
#[test]
fn the_id_a_provenance_row_points_at_is_the_keys_last_column() {
  assert_eq!(SPLIT.id(), FieldName::new("id"));
  assert_eq!(<Clip as Describe<Db>>::BLUEPRINT.id(), FieldName::new("id"));
  assert_eq!(
    <Media as Describe<Db>>::BLUEPRINT.id(),
    FieldName::new("id")
  );
}

// =================================================================================================
// `same_shapes`' 3×3 TRUTH TABLE — one row per LEAF WORD against one column per leaf word
// =================================================================================================
//
// The audit's shaped arm compares *same word, same name*, and until the arm roster was completed the
// only word it could say yes about was `Plain`. Two identical `Nullable` leaves, and two identical
// `Derived` ones, fell to the cross-variant `_ => false` — so `describes` reported drift about a
// descriptor built from the very list its row publishes, for every row carrying a derived leaf.
//
// A TABLE and not three examples, because the two halves of the law are only one law when both are
// stated: the DIAGONAL must hold (a word compares equal to itself) and the six OFF-DIAGONAL cells
// must not (three words that render one column under one name are three different facts about it —
// whether it is part of the value, and whether its own arithmetic may decline). Six of the nine
// cells were already the right answer for the WRONG reason; the three on the diagonal are what
// changed, and a table is what tells those apart.
//
// `const` throughout, which is the only vantage that matters: `describes` is called from a `const _:
// () = assert!(…)` beside a declaration, so a cell that regressed would be a compile error rather
// than a test run.

/// One leaf apiece, under ONE name — so the only thing that can separate them is the WORD.
const AT_PLAIN: &[ColumnShape] = &[ColumnShape::Plain(ColumnName::new("at"))];
const AT_NULLABLE: &[ColumnShape] = &[ColumnShape::Nullable(ColumnName::new("at"))];
const AT_DERIVED: &[ColumnShape] = &[ColumnShape::Derived(ColumnName::new("at"))];

// THE DIAGONAL — a word compares equal to itself. All three were `false` before the arms landed
// except the first.
const _: () = assert!(super::same_shapes(AT_PLAIN, AT_PLAIN));
const _: () = assert!(super::same_shapes(AT_NULLABLE, AT_NULLABLE));
const _: () = assert!(super::same_shapes(AT_DERIVED, AT_DERIVED));

// THE SIX OFF-DIAGONAL CELLS — one column, one name, three different facts, and no two of them are
// one shape. Both directions of each pair, because the comparison walks a pair and an arm roster
// that answered one way round and not the other would be a defect this table exists to see.
const _: () = assert!(!super::same_shapes(AT_PLAIN, AT_NULLABLE));
const _: () = assert!(!super::same_shapes(AT_NULLABLE, AT_PLAIN));
const _: () = assert!(!super::same_shapes(AT_PLAIN, AT_DERIVED));
const _: () = assert!(!super::same_shapes(AT_DERIVED, AT_PLAIN));
const _: () = assert!(!super::same_shapes(AT_NULLABLE, AT_DERIVED));
const _: () = assert!(!super::same_shapes(AT_DERIVED, AT_NULLABLE));

/// The NAME half survives the new arms, said at each of the two words that gained one — an arm that
/// matched on the word and forgot to compare the name would pass every cell of the table above.
const ON_PLAIN: &[ColumnShape] = &[ColumnShape::Nullable(ColumnName::new("on"))];
const ON_DERIVED: &[ColumnShape] = &[ColumnShape::Derived(ColumnName::new("on"))];
const _: () = assert!(!super::same_shapes(AT_NULLABLE, ON_PLAIN));
const _: () = assert!(!super::same_shapes(AT_DERIVED, ON_DERIVED));

/// A ROW THAT CARRIES BOTH DERIVED WORDS, described through the PUBLIC road — which is where the
/// defect was actually reachable from. `MediaTimestamp`'s shape is the shipped case: value columns
/// and a derived position beside them, one of which may decline.
///
/// One word list per FIELD and one optionality per FIELD, which is [`Table::shaped`]'s own
/// agreement — a leaf's own nullability is on its segment and is not counted there.
const STAMPED_COLUMNS: &[ColumnShape] = &[
  ColumnShape::Plain(ColumnName::new("id")),
  ColumnShape::Nullable(ColumnName::new("at_nanos")),
  ColumnShape::Derived(ColumnName::new("area")),
];
const STAMPED: Table = Table::shaped(
  RecordAddress::new(FieldName::new("stamped"), &[FieldName::new("id")]),
  STAMPED_COLUMNS,
  &[&["INTEGER"], &["INTEGER"], &["INTEGER"]],
  &[false, false, false],
);
const _: () = assert!(describes(&STAMPED, STAMPED_COLUMNS));
const _: () = assert!(!describes(
  &STAMPED,
  &[
    ColumnShape::Plain(ColumnName::new("id")),
    ColumnShape::Plain(ColumnName::new("at_nanos")),
    ColumnShape::Plain(ColumnName::new("area")),
  ]
));