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 super::super::{ArrangeError, DriverKind, FanoutKind, GraphBuilder};
use crate::{
  Context, Delivery,
  operator::{Emitter, Operator},
};

// The facts a hand-wired node states. The mount predicate is `O: Declared + Driven<O::Mode>`, so a
// node that is not emitted states them too — the blocking mode and nothing else, which is what a
// bare declaration is.
macro_rules! declared {
  ($name:ident) => {
    impl crate::Declared for $name {
      const EFFECT: crate::Effect = crate::Effect::Pure;

      type Channels = crate::Unchanneled;
      type Mode = crate::Block;
      type Options = ();
      type Pair = crate::Buffered;
      type Wires<O> = crate::Downstream<O>;
      type Attribution<O> = ();
    }
  };
}

// Three same-"tier" analyze operators (u8 → u8), so a linear chain is same-typed.
macro_rules! analyze_op {
  ($name:ident) => {
    struct $name;
    declared!($name);
    impl Operator for $name {
      type In = u8;
      type Out = u8;
      type Error = core::convert::Infallible;
      fn accept(
        &mut self,
        _ctx: &Context,
        _delivery: Delivery<Self::In>,
        _emitter: &mut Emitter<Self::Out>,
      ) -> Result<(), Self::Error> {
        Ok(())
      }
    }
  };
}
analyze_op!(A);
analyze_op!(B);
analyze_op!(C);

// A source head whose Output feeds the analyze chain.
struct Head;
declared!(Head);
impl Operator for Head {
  type In = ();
  type Out = u8;
  type Error = core::convert::Infallible;
  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<Self::In>,
    _emitter: &mut Emitter<Self::Out>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

#[test]
fn issue_100_same_tier_chain_derives_distinct_layers() {
  // The #100 acceptance in the PURE model: a linear chain of same-"tier" analyze
  // operators A→B→C validates and derives three layers, so B→C (which the fixed
  // legacy tiers rejected as a same-layer edge) is legal — an edge change, not an
  // architecture change.
  let mut g = GraphBuilder::new();
  let a = g.source::<A>("a", DriverKind::Async);
  let b = g.node::<B>("b", DriverKind::Async);
  let c = g.node::<C>("c", DriverKind::Async);
  g.edge(&a, &b, FanoutKind::Direct);
  g.edge(&b, &c, FanoutKind::Direct);

  let graph = g.validate().expect("chain validates");
  assert_eq!(graph.layers().len(), 3);
  assert_eq!(graph.layers()[0], vec![a.id()]);
  assert_eq!(graph.layers()[1], vec![b.id()]);
  assert_eq!(graph.layers()[2], vec![c.id()]);
  assert!(graph.orphans().is_empty());
}

#[test]
fn broadcast_fanout_shares_a_layer() {
  let mut g = GraphBuilder::new();
  let h = g.source::<Head>("head", DriverKind::Async);
  let b = g.node::<A>("b", DriverKind::Async);
  let c = g.node::<B>("c", DriverKind::Async);
  g.edge(&h, &b, FanoutKind::Broadcast);
  g.edge(&h, &c, FanoutKind::Broadcast);

  let graph = g.validate().expect("valid");
  assert_eq!(graph.layers().len(), 2);
  assert_eq!(graph.layers()[1], vec![b.id(), c.id()]); // sorted, same layer
}

#[test]
fn cycle_is_rejected() {
  let mut g = GraphBuilder::new();
  let a = g.node::<A>("a", DriverKind::Async);
  let b = g.node::<B>("b", DriverKind::Async);
  // A→B and B→A: both u8→u8, so both edges type-check but form a cycle.
  g.edge(&a, &b, FanoutKind::Direct);
  g.edge(&b, &a, FanoutKind::Direct);
  let err = g.validate().expect_err("cycle rejected");
  assert!(err.is_cycle());
}

#[test]
fn cycle_error_names_a_cycle_member_not_a_downstream_node() {
  // Kahn's stall leaves BOTH cycle members and their downstream nodes unplaced.
  // With `d` declared first (lowest index) strictly downstream of the a→b→c→a
  // cycle, naming "the first unplaced node" would blame d — a node provably NOT
  // on any cycle. The error must name a genuine cycle member.
  let mut g = GraphBuilder::new();
  let d = g.node::<A>("d", DriverKind::Async); // downstream only, declared first
  let a = g.node::<B>("a", DriverKind::Async);
  let b = g.node::<C>("b", DriverKind::Async);
  let c = g.node::<A>("c", DriverKind::Async);
  g.edge(&a, &b, FanoutKind::Direct);
  g.edge(&b, &c, FanoutKind::Direct);
  // c fans out to the cycle AND to d, so both its edges must be Broadcast.
  g.edge(&c, &a, FanoutKind::Broadcast);
  g.edge(&c, &d, FanoutKind::Broadcast);

  let err = g.validate().expect_err("cycle rejected");
  let ArrangeError::Cycle(cycle) = err else {
    panic!("expected Cycle, got {err:?}");
  };
  let node = cycle.node();
  assert!(
    [a.id(), b.id(), c.id()].contains(&node),
    "culprit {node} is not on the a→b→c→a cycle"
  );
}

#[test]
fn diamond_with_skip_edge_layers_by_longest_path() {
  // a→b, a→c, b→d, c→d plus the skip edge a→d: d must layer at 1 + MAX of its
  // producers' layers (layer 2), not where the skip edge first reaches it.
  let mut g = GraphBuilder::new();
  let a = g.source::<Head>("a", DriverKind::Async);
  let b = g.node::<A>("b", DriverKind::Async);
  let c = g.node::<B>("c", DriverKind::Async);
  let d = g.node::<C>("d", DriverKind::Async);
  g.edge(&a, &b, FanoutKind::Broadcast);
  g.edge(&a, &c, FanoutKind::Broadcast);
  g.edge(&a, &d, FanoutKind::Broadcast);
  g.edge(&b, &d, FanoutKind::Broadcast);
  g.edge(&c, &d, FanoutKind::Broadcast);

  let graph = g.validate().expect("diamond validates");
  assert_eq!(
    graph.layers(),
    &[vec![a.id()], vec![b.id(), c.id()], vec![d.id()]]
  );
  assert!(graph.orphans().is_empty());
}

#[test]
fn direct_edge_cannot_fan_out() {
  let mut g = GraphBuilder::new();
  let h = g.source::<Head>("head", DriverKind::Async);
  let b = g.node::<A>("b", DriverKind::Async);
  let c = g.node::<B>("c", DriverKind::Async);
  g.edge(&h, &b, FanoutKind::Direct);
  g.edge(&h, &c, FanoutKind::Broadcast); // second out-edge, one of them Direct
  let err = g.validate().expect_err("direct-fanout rejected");
  assert!(err.is_direct_fanout());
}

#[test]
fn orphan_without_source_is_data_not_error() {
  // No node marked source ⇒ every node is an orphan, but the graph still validates.
  let mut g = GraphBuilder::new();
  let a = g.node::<A>("a", DriverKind::Async);
  let b = g.node::<B>("b", DriverKind::Async);
  g.edge(&a, &b, FanoutKind::Direct);
  let graph = g.validate().expect("valid even with orphans");
  assert_eq!(graph.orphans(), &[a.id(), b.id()]);
  // Layering is decoupled from orphan-ness: orphans still layer by topology
  // (`a` in the root layer), they are just additionally reported.
  assert_eq!(graph.layers(), &[vec![a.id()], vec![b.id()]]);
}

#[test]
fn cross_builder_handle_is_out_of_range_not_panic() {
  // A NodeHandle carries no builder brand, so a handle minted by a *different*
  // builder can be passed to `g.edge` and smuggle an out-of-range NodeId. validate()
  // must reject it with a typed error rather than panic on the out-of-bounds index.
  let mut g = GraphBuilder::new();
  let a = g.source::<A>("a", DriverKind::Async); // g's only node: id #0

  let mut other = GraphBuilder::new();
  let _first = other.node::<A>("first", DriverKind::Async); // id #0 in `other`
  let foreign = other.node::<B>("foreign", DriverKind::Async); // id #1 in `other`

  // `foreign` (id #1) is out of range for `g`, which declared a single node.
  g.edge(&a, &foreign, FanoutKind::Broadcast);

  let err = g.validate().expect_err("out-of-range endpoint rejected");
  assert!(err.is_edge_endpoint_out_of_range());
}

#[test]
fn node_lookup_is_total_over_unbranded_ids() {
  // Same smuggling class as the edge-endpoint check: a NodeId minted by another
  // graph may index past this graph's node set, so `node()` must be total.
  let mut g = GraphBuilder::new();
  let a = g.source::<A>("a", DriverKind::Async);
  let graph = g.validate().expect("valid");
  assert_eq!(graph.node(a.id()).expect("declared node").name(), "a");

  let mut other = GraphBuilder::new();
  let _x = other.node::<A>("x", DriverKind::Async);
  let foreign = other.node::<B>("foreign", DriverKind::Async); // id #1
  assert!(graph.node(foreign.id()).is_none());
}