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 arrangement layer: the composable unit-DAG expressed as data.
//!
//! The **pure model** owns the graph as data — opaque [`NodeId`]/[`EdgeId`], a
//! typed [`GraphBuilder`] whose `edge` bound is the compile-time guard, and a
//! [`validate`](GraphBuilder::validate) that topo-sorts the declared edges into
//! *derived* layers (as many as the topology implies, no fixed tiers).
//!
//! Declaring a topology and checking it is the whole of what happens here.
//! Nothing in this module opens a channel, spawns a driver or observes a fate —
//! the execution engine that does is not in this crate — which is why the layer
//! names no async runtime and carries no feature.
//!
//! # What this layer does NOT yet carry — the large-stream prerequisites
//!
//! The wiring here is proven for pipelines whose units process a whole item per call and buffer
//! their emissions. A pipeline over long media streams (a two-hour mp4 demuxed to packets) needs
//! four things that are named and OPEN, not built. They are listed so nobody reads the shipped
//! machinery as readiness for that shape:
//!
//! 1. **A streaming execution contract — the FACES and the LANE are built; the WORD is not.**
//!    Demux/decode cannot ride the buffered [`Emitter`](crate::Emitter) / `Dispatch` shape: one call
//!    producing millions of packets holds all of them before the driver drains. What replaces it
//!    shipped as [`StreamOperator`](crate::StreamOperator) /
//!    [`AsyncStreamOperator`](crate::AsyncStreamOperator) — one delivery's whole life, streamed
//!    through a bounded [`Feed`](crate::Feed) — and [`StreamLane`](crate::StreamLane) is what drives
//!    them: a run per delivery, the node's in-flight count bounded, the fed items projected into the
//!    downstream set. What is still open is the DECLARATION WORD that would mount one, so a
//!    deployment reaches the lane by building it. It is orthogonal to subscription — a source's
//!    options and a unit's execution contract are different axes — so subscription sits on both
//!    shapes unchanged.
//! 2. **A typed fork out of one unit — OPEN, with a recorded candidate and no commitment.** A
//!    demuxer emits five differently-typed track kinds (video, audio, subtitle, data, attachment)
//!    from ONE input file, so the fork is inside the pipeline and cannot be expressed by
//!    subscribing twice: a single file is one subscription and one content root. Today an edge
//!    carries exactly one message type, so no edge kind and no `SubscribeOptions` value can spell
//!    this. The recorded candidate is a typed PORT — the subscribe shape one level down:
//!
//!    ```text
//!    trait Emits<Port> { type Item; type SubscribeOptions; }
//!    ```
//!
//!    with the compiler tying a consumer's input to `<U as Emits<P>>::Item` exactly as `subscribe`
//!    ties it to `S::Output`. It is written down as a candidate and nothing more. The one open
//!    variable is the COST of the alternatives — a broadcast sum sends every packet down all five
//!    arms and discards four fifths of them on the hottest path there is — and that is measurable
//!    only against a real demuxer, so the decision belongs with the first one, not here.
//! 3. **A seek-capable reader is the pipeline's to name.** Nothing in this crate names a reader,
//!    a byte source, or a decoder at all, so a media pipeline puts `Seek` on ITS own reader type
//!    at ITS own units (moov-at-end needs it). Free today precisely because there is no framework
//!    reader to compose with.
//! 4. **One-shot streams are the SOURCE's to spool.** A non-re-openable stream (an upload body, a
//!    pipe) must be spooled by the source before it emits, because nothing downstream can rewind
//!    it.

mod builder;
mod error;
mod graph;

pub use builder::{Edge, GraphBuilder, Node, NodeHandle};
pub use error::{ArrangeError, CycleError, DirectFanoutError, EdgeEndpointError};
pub use graph::ChannelGraph;

/// An opaque handle to a declared node (its index in declaration order).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display)]
#[display("node#{_0}")]
pub struct NodeId(usize);

impl NodeId {
  #[inline]
  pub(crate) const fn new(index: usize) -> Self {
    Self(index)
  }

  /// This node's index in declaration order.
  #[inline]
  pub const fn index(&self) -> usize {
    self.0
  }
}

/// An opaque handle to a declared edge (its index in declaration order).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display)]
#[display("edge#{_0}")]
pub struct EdgeId(usize);

impl EdgeId {
  #[inline]
  pub(crate) const fn new(index: usize) -> Self {
    Self(index)
  }

  /// This edge's index in declaration order.
  #[inline]
  pub const fn index(&self) -> usize {
    self.0
  }
}

/// Which driver runs a node.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum DriverKind {
  /// A `tokio` task (the operator must be `Send`).
  Async,
  /// A dedicated OS thread (the operator is built on the worker thread, so it may
  /// be `!Send`).
  Thread,
}

impl DriverKind {
  /// A stable name for logs.
  #[inline]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Async => "async",
      Self::Thread => "thread",
    }
  }
}

/// How a producer's output edge reaches its consumer(s). Semantic, per-edge data — the
/// runtime derives delivery from it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum FanoutKind {
  /// Exclusive single consumer (a zero-copy move). Must be a node's sole out-edge.
  Direct,
  /// Every consumer of this output (fan-out by clone).
  Broadcast,
  /// Every member of a manifest search group (labeled fan-out).
  Group,
}

impl FanoutKind {
  /// A stable name for logs.
  #[inline]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Direct => "direct",
      Self::Broadcast => "broadcast",
      Self::Group => "group",
    }
  }
}

#[cfg(test)]
mod tests;