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 SEAT THE EMITTED ROOT PROJECTION LANDS ON.
//!
//! [`Attributes`](crate::Attributes) has always been the seam a node's root projection arrives
//! through, and its own note has always said where the projection comes from: *a field access on
//! the record's declared key, which an emitted wrapper writes*. This is that wrapper.
//!
//! # The wrapper is the FRAMEWORK's and the impl is the RECORD's
//!
//! A record declaration is the only place that knows a record's root — the key is `lineage ⊕ id`,
//! flat and root-first, so the root is the key's FIRST column and the derive has it. But the
//! `Attributes` trait is this crate's, so an impl of it has to name something local to the crate
//! that writes it. [`RootProjection<T>`] is what makes the pair legal: the emitted impl is
//! `impl Attributes<Keyframe> for RootProjection<Keyframe>`, whose self type carries the local
//! record, so a declaring crate may write it without owning either the trait or the wrapper.
//!
//! ```ignore
//! // emitted beside a record's other impls, from its own `lineage(…)` declaration:
//! impl ::ingraph::Attributes<Keyframe> for ::ingraph::RootProjection<Keyframe> {
//!   const FAMILY: &'static str = "media";
//!   type Root = MediaId;
//!   fn root(&self, record: &Keyframe) -> MediaId { ::core::clone::Clone::clone(&record.media) }
//!   fn observe(&self, _: &MediaId, _: &::ingraph::NodeName, _: &::ingraph::Arrival) {}
//! }
//! ```
//!
//! # IT CARRIES NOTHING, and that is the design rather than an omission
//!
//! A projection is a COMPILE-TIME fact — which column of which type a record descends from — so the
//! value has nothing to hold and is zero-sized. The registry the counts go to is the RESIDENT's,
//! reached through [`Resident::registries`](crate::Resident::registries), and joining the two is
//! the counting knife's act: this one only has to make the root nameable.
//!
//! `observe` is therefore the empty program here. That is not a stub standing in for a call — it is
//! the honest state of a projection whose counting has not been wired yet, and it is the same empty
//! program [`Attributes for ()`](crate::Attributes) already ships.
//!
//! # WHAT INSTALLS IT, and where the word for it lives
//!
//! [`Declared::Attribution`](crate::Declared::Attribution) — a seat on the NODE's own declaration,
//! written by the `attributed` word — and [`Wiring::resident`](crate::Wiring::resident) is what
//! spends it, on every buffered node it wires and with no branch of its own.
//!
//! It had to be the declaration's, and the reason is worth keeping because it is what the shape
//! answers. A per-node install written by the GRAPH expansion cannot work: that expansion sees a
//! node's output only as the TYPE `<Cell<N> as Mount<N>>::Out` and cannot ask whether that type is
//! a declared record at all — there is no specialization to branch on and an autoref probe dies on
//! an associated-type projection — while a great many nodes' outputs are not records (a `String`, a
//! `u64`, a `()`), so an unconditional `.attributing(RootProjection::<Out>::new())` written THERE
//! would refuse to compile for every one of them. The party that knows is the node's own
//! declaration, which is the party the word is written on; the seat is how the answer crosses to a
//! root that cannot read those tokens, exactly as [`Declared::Pair`](crate::Declared::Pair) and
//! [`Declared::Wires`](crate::Declared::Wires) already do for their own facts.
//!
//! So the install is unconditional and the BRANCH is the seat: `attributed` seats
//! `RootProjection<O>` and silence seats `()`, whose [`Attributes`](crate::Attributes) impl is the
//! empty program and whose value is zero-sized. A word written over an output no record declared is
//! `E0277` at the mount, naming the payload.
//!
//! [`Resident::attributing`](crate::Resident::attributing) stays public beside it, and it is the
//! road for the attribution that carries STATE — a journal writer, a queue, a handle — which no
//! walk can mint from a type. Such a deployment seats `()` and attaches its own, replacing what the
//! seat installed.
//!
//! # WHAT IS STILL NOT HERE, and it is a ward rather than a line
//!
//! Nothing refuses a node that **lands record rows and wears no attribution**. Such a declaration
//! is legal and silent: its rows reach a store, its observations stay counter-grade, and no
//! sentence anywhere says the two facts disagree. The launch floor is where that check would live —
//! it already refuses the node that claims durability and performs none
//! ([`Refusal::LandsNowhere`](crate::Refusal::LandsNowhere)) — and this would be its sibling, read
//! off [`Declared::EFFECT`](crate::Declared::EFFECT) beside the seat. It is a candidate for a later
//! knife rather than an omission from this one: whether an unattributed landing is a MISTAKE or an
//! ordinary posture is a ruling, and a refusal shipped before that ruling would refuse deployments
//! that are working.

use core::marker::PhantomData;

/// The value an emitted root projection is written on — zero-sized, and see the
/// [module note](self) for why.
pub struct RootProjection<T>(PhantomData<fn(&T)>);

impl<T> RootProjection<T> {
  /// The projection for records of type `T`.
  ///
  /// It takes nothing because it holds nothing. What makes one projection differ from another is
  /// its `T` and the emitted impl that `T` carries, both of which are decided before this is
  /// called.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self(PhantomData)
  }
}

impl<T> Default for RootProjection<T> {
  #[inline]
  fn default() -> Self {
    Self::new()
  }
}

/// Written rather than derived, for the reason [`Registry`](super::Registry)'s is: a derived one
/// would carry `T: Debug`, and `T` is a NAME here rather than a value — the marker is
/// `PhantomData<fn(&T)>`, which owns nothing and prints nothing.
impl<T> core::fmt::Debug for RootProjection<T> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.write_str("RootProjection")
  }
}

/// `fn(&T)` is what makes both derivable without a bound on `T`, and it is chosen for that: the
/// marker carries no ownership, no drop obligation and none of `T`'s own auto traits, exactly as
/// [`App`](crate::App)'s own root marker does.
impl<T> Clone for RootProjection<T> {
  #[inline]
  fn clone(&self) -> Self {
    *self
  }
}

impl<T> Copy for RootProjection<T> {}

impl<T> PartialEq for RootProjection<T> {
  #[inline]
  fn eq(&self, _other: &Self) -> bool {
    true
  }
}

impl<T> Eq for RootProjection<T> {}