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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
//! **THE AUTONOMOUS SEAT**: what a node that OWNS ITS OWN LOOP is handed, and what drives one.
//!
//! [`resident`](super::resident) drives a buffered body one `accept` at a time and
//! [`stream`](super::stream) drives a streamed one one delivery at a time. This module drives
//! neither: an [`AutonomousOperator`](crate::AutonomousOperator) is STARTED ONCE and runs until its
//! upstreams are spent, it hears the stop, or it dies — so the framework hands it three seats and
//! settles the party on what it answers.
//!
//! | seat | direction | what it carries |
//! |---|---|---|
//! | [`Upstreams<In>`] | graph → node | the node's inbound edges, RAW: one receiving end per edge, in declaration order |
//! | [`Downstream<Out>`](super::Downstream) | node → graph | the same out-edge set every other face publishes through |
//! | [`ShutdownSignal`] | framework → node | *wind down*: the one thing the framework ever says to a body inside `run` |
//!
//! and [`Fin`] is which of the two endings it reached. It is the ORIGIN layer's vocabulary reused
//! verbatim, for the reason [`Fin`]'s own note gives: a life that ENDED either ran out or was told
//! to, and a life that DIED answers `Err` instead.
//!
//! # The seat is a DECOMPOSITION and not a protocol
//!
//! [`Upstreams`] hands out [`Inbox`]es — the very receiving halves the wiring walk opens — and
//! nothing else. The [`Wake`] vocabulary, the [`Delivery`](super::Delivery) it carries, the
//! [`Custody`](super::Custody) token that delivery owes and the [`AckMode`](super::AckMode) the
//! declaration states are all unchanged: the only novelty at this face is WHO answers, which is the
//! node's own code rather than a driver loop. That is why there is no verb surface here — a body
//! that could not reach the receivers could not put a framework edge and a channel of its own into
//! ONE select, which is the whole operational space this kind exists to open.
//!
//! # What the MOUNT fills the seat with, and it is one edge per DECLARED upstream
//!
//! [`Mount::intake`](super::Mount::intake) is the autonomous cell's own door onto
//! [`Wiring::upstreams`](super::Wiring::upstreams), so a MOUNTED node's set is as wide as its
//! declaration: one receiving half per declared upstream, in declaration order, each on a channel of
//! its own. That is what makes a slow upstream's full edge backpressure on itself and on nobody
//! else, and it is why the arm a body selects at and the slot its producer publishes to are ONE
//! number — [`Wiring::source_of`](super::Wiring::source_of) counts the producer's side by the same
//! rule this set is filled by.
//!
//! A declaration that named ONE upstream — or none — gets one edge, and there fan-in is what fan-in
//! always was: several sending halves of that same edge. The arity is the DECLARATION's rather than
//! the deployment's, so an upstream this deployment leaves dark keeps its place and a body armed
//! over edge two is armed over the edge its own declaration named.
//!
//! What this seat still cannot hold is a HETEROGENEOUS container: every edge in it carries the same
//! `In`, so a node whose input is the derive's `<Node>In` sum wants the by-key intake that assembles
//! one, which the driver does not build.

use core::time::Duration;

use super::{
  Context, Downstream, ItemId, NodeName,
  channel::{Inbox, Wake},
  lane::block_on,
};
use crate::{Async, AsyncAutonomousOperator, AutonomousOperator, Block, source::Fin};

#[cfg(test)]
mod tests;

/// **THE INBOUND EDGES, AS A NODE THAT OWNS ITS LOOP HOLDS THEM** — one receiving end apiece, in
/// declaration order.
///
/// [`Downstream`](super::Downstream)'s twin on the other side of a node, and deliberately the same
/// shape: a set built by attaching halves, read back as a slice, with the POSITION as the edge's
/// identity. Declaration order is the contract here exactly as it is for
/// [`Declared::UPSTREAMS`](super::Declared::UPSTREAMS), the channels shelf and the poll clocks — the
/// wiring walk numbers a node's upstreams by position, so an edge's place in this set is the slot
/// its channel was opened at.
///
/// # It hands out the RECEIVERS, and that is the ruling rather than a leak
///
/// A body that owns its loop waits on framework edges AND on channels it opened for itself — a
/// worker return line, a timer, a stop of its own — in ONE select. A select needs the receiving
/// halves, so a seam that hid them would force a thread or a poll where an arm suffices. What this
/// seat therefore is is a decomposition over [`Inbox`], and the select device is
/// [`arm`](super::arm) beside [`select`](super::select) — the same two a body spends over its own
/// [`conduit`](crate::conduit) channels, side by side.
///
/// # What a node does with one
///
/// Takes a [`Wake`] off whichever edge it chooses, in whatever order it chooses; reads
/// [`Wake::Delivered`]'s [`Delivery`](super::Delivery); and answers that delivery's
/// [`Custody`](super::Custody) when IT decides to — immediately, after a batch, or at the end of a
/// whole session. Nothing here answers anything on the node's behalf.
///
/// # Examples
///
/// ```
/// use core::time::Duration;
///
/// use ingraph::{ItemId, Upstreams, Wake, channel};
///
/// let (fast, from_fast) = channel::<ItemId, u64>(4);
/// let (slow, from_slow) = channel::<ItemId, u64>(4);
/// // Declaration order: edge zero is `fast`, edge one is `slow`.
/// let upstreams = Upstreams::from_iter([from_fast, from_slow]);
///
/// assert_eq!(upstreams.len(), 2);
/// assert!(!upstreams.is_spent(), "both senders are alive");
///
/// drop(fast);
/// drop(slow);
/// // A hung-up and drained set is what a body reads as `Fin::Spent`.
/// assert!(upstreams.is_spent());
/// let _ = upstreams.edges()[1].park(Duration::from_millis(0));
/// let _: Option<Wake<ItemId, u64>> = None;
/// ```
pub struct Upstreams<In> {
  edges: Vec<Inbox<ItemId, In>>,
}

impl<In> Upstreams<In> {
  /// No edges yet.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self { edges: Vec::new() }
  }

  /// Take `inbox` as the NEXT edge — the position it lands at is its identity.
  #[inline]
  pub fn attach(&mut self, inbox: Inbox<ItemId, In>) -> &mut Self {
    self.edges.push(inbox);
    self
  }

  /// The receiving ends, in declaration order — what a body arms its select over.
  #[inline]
  #[must_use]
  pub fn edges(&self) -> &[Inbox<ItemId, In>] {
    &self.edges
  }

  /// The edge at `upstream`, or `None` where this node has no such edge.
  ///
  /// `Option` rather than an index panic, because the count is a fact about the ARRANGEMENT: a
  /// hand-wired one attaches whatever halves it opened, so a body that asks about edge two is asking
  /// a question its own arrangement answers rather than making a mistake. A MOUNTED node's set is as
  /// wide as its declaration — see the module note.
  #[inline]
  #[must_use]
  pub fn edge(&self, upstream: usize) -> Option<&Inbox<ItemId, In>> {
    self.edges.get(upstream)
  }

  /// How many edges feed this node.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.edges.len()
  }

  /// Whether none does — a head fed from outside the graph, or a node this deployment wired no
  /// upstream into.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.edges.is_empty()
  }

  /// **NOTHING MORE CAN ARRIVE**: every edge has hung up and every queue is drained.
  ///
  /// The read a body turns into [`Fin::Spent`], and it is two questions rather than one for the
  /// reason [`Inbox::park`] answers `None` only at the end: a disconnected edge with items still on
  /// it has work left, and a body that stopped there would drop deliveries whose senders are
  /// waiting to hear about them.
  ///
  /// A set with NO edges is spent by this reading, which is the honest answer for a node nothing
  /// feeds: there is nothing that could arrive.
  #[must_use]
  pub fn is_spent(&self) -> bool {
    self
      .edges
      .iter()
      .all(|edge| edge.is_disconnected() && edge.is_empty())
  }

  /// How many wakes are queued across every edge.
  #[must_use]
  pub fn queued(&self) -> usize {
    self.edges.iter().map(Inbox::len).sum()
  }

  /// Park on the edge at `upstream` until something arrives or `sweep` elapses — the THREAD
  /// engine's door, at one edge.
  ///
  /// `None` is that edge's own end, or an index this node has no edge at. The distinction is
  /// [`edge`](Self::edge)'s to make, and a body that selects rather than parking on one arm reaches
  /// [`arm`](super::arm) instead.
  #[inline]
  pub fn park(&self, upstream: usize, sweep: Duration) -> Option<Wake<ItemId, In>> {
    self.edge(upstream)?.park(sweep)
  }

  /// Everything already queued on the edge at `upstream`, without waiting — what a body drains
  /// before doing anything else, so one wake serves a whole burst.
  ///
  /// An empty walk where this node has no such edge, which is the same answer an empty queue gives:
  /// there is nothing there to take.
  #[inline]
  pub fn drain(&self, upstream: usize) -> impl Iterator<Item = Wake<ItemId, In>> {
    self.edge(upstream).into_iter().flat_map(Inbox::drain)
  }
}

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

impl<In> FromIterator<Inbox<ItemId, In>> for Upstreams<In> {
  #[inline]
  fn from_iter<I: IntoIterator<Item = Inbox<ItemId, In>>>(edges: I) -> Self {
    Self {
      edges: edges.into_iter().collect(),
    }
  }
}

impl<In> core::fmt::Debug for Upstreams<In> {
  /// The ARITY and what is waiting — never the messages. `In` is the author's own type and
  /// demanding a [`Debug`](core::fmt::Debug) of it would bound every autonomous node for the
  /// benefit of this line, which is [`Feed`](crate::Feed)'s own reason one layer down.
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("Upstreams")
      .field("edges", &self.edges.len())
      .field("queued", &self.queued())
      .finish()
  }
}

/// **THE AUTONOMOUS ROW** of the face table: what one node's whole life IS, at each of the two
/// faces.
///
/// [`Driven`](crate::Driven)'s shape at a third seam, and it exists for that trait's own reason: the
/// two faces carry the same three associated types under different trait names, and every door that
/// spends them would otherwise be written twice. [`Block`] selects
/// [`AutonomousOperator`](crate::AutonomousOperator) and [`Async`] selects
/// [`AsyncAutonomousOperator`](crate::AsyncAutonomousOperator), so a bound written over this row
/// serves both.
///
/// # THE TWO ROWS COLLAPSE INTO ONE DRIVER, which is the dividend
///
/// [`Lived`](super::Lived)'s arrangement one kind over, and for its reason: a whole-life body runs
/// on a thread of its own and the awaited one is PINNED there, so [`drive`](Self::drive) is the
/// author's `run` on one row and the same `run` driven by this layer's own `block_on` on the other.
/// Every caller above this trait is written once — see
/// [`Ignition::autonomous_declared`](super::Ignition::autonomous_declared), which is the one that
/// matters.
///
/// The awaited face is NOT handed to [`Ignition::spawn`](super::Ignition::spawn), and that is the
/// origin layer's ruling read at this kind: that door demands `Send`, which would refuse the exact
/// shape [`AsyncAutonomousOperator`](crate::AsyncAutonomousOperator) declines to bound — a node
/// holding a model session, a device context, an FFI handle across its own awaits.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not an AUTONOMOUS node in the `{M}` mode",
  label = "no `run` of this mode's shape",
  note = "an autonomous node implements exactly ONE of `AutonomousOperator` (the blocking face, \
          mode `Block`) and `AsyncAutonomousOperator` (the awaited face, mode `Async`), and \
          implementing either IS implementing this trait's row for it",
  note = "where a declaration is mounted, the mode is the one its own word selected and its \
          `Declared::Mode` states: `autonomous` alone asks for `Block` and `autonomous, async` asks \
          for `Async`, so a body whose face differs from its word is refused here",
  note = "if `{Self}` wears the BUFFERED pair instead, it is mounted through `Blueprint::node` and \
          `Wiring::resident`; the STREAMING pair is `Blueprint::stream` and `Wiring::lane_mount` — \
          this door is the autonomous one, and the `autonomous` word is what sends a declaration to \
          it"
)]
pub trait Runs<M>: Sized {
  /// Whether THIS mode's `run` answers without a future.
  ///
  /// [`Driven::SYNC`](crate::Driven::SYNC) verbatim, one kind over: a graph root folds an
  /// `ALL_SYNC` over every mount it carries, and an autonomous mount has no [`Driven`](crate::Driven)
  /// row for the emission to read one off. Set by the two blanket rows below and by nothing an
  /// author can write, so it PROVES rather than claims.
  const SYNC: bool;

  /// The message this node consumes.
  type In;
  /// The message it publishes.
  type Out: 'static;
  /// What a life that DIED refuses with.
  type Error;

  /// Take the three seats and run to an ending, ON THE CALLING THREAD.
  ///
  /// It takes `self` BY VALUE because the faces do: a node of this kind is started once and there
  /// is nothing after it, so the value MOVES into the call — see
  /// [`AutonomousOperator`](crate::AutonomousOperator)'s lifecycle table, which is where that
  /// sentence and its consequences are written.
  ///
  /// # Errors
  ///
  /// Whatever this node's own life refuses with — a body that DIED rather than reaching either
  /// ending. Both endings are `Ok`.
  fn drive(
    self,
    ctx: Context,
    upstreams: Upstreams<Self::In>,
    downstream: Downstream<Self::Out>,
  ) -> Result<Fin, Self::Error>;
}

/// The BLOCKING row: implementing [`AutonomousOperator`](crate::AutonomousOperator) is implementing
/// this, and `run` IS the drive.
impl<O> Runs<Block> for O
where
  O: AutonomousOperator,
{
  const SYNC: bool = true;

  type Error = <O as AutonomousOperator>::Error;
  type In = <O as AutonomousOperator>::In;
  type Out = <O as AutonomousOperator>::Out;

  #[inline]
  fn drive(
    self,
    ctx: Context,
    upstreams: Upstreams<Self::In>,
    downstream: Downstream<Self::Out>,
  ) -> Result<Fin, Self::Error> {
    AutonomousOperator::run(self, ctx, upstreams, downstream)
  }
}

/// The AWAITED row: implementing [`AsyncAutonomousOperator`](crate::AsyncAutonomousOperator) is
/// implementing this, and the future is PINNED on the calling thread rather than spawned — see the
/// trait's own note for why.
impl<O> Runs<Async> for O
where
  O: AsyncAutonomousOperator,
{
  const SYNC: bool = false;

  type Error = <O as AsyncAutonomousOperator>::Error;
  type In = <O as AsyncAutonomousOperator>::In;
  type Out = <O as AsyncAutonomousOperator>::Out;

  #[inline]
  fn drive(
    self,
    ctx: Context,
    upstreams: Upstreams<Self::In>,
    downstream: Downstream<Self::Out>,
  ) -> Result<Fin, Self::Error> {
    block_on(AsyncAutonomousOperator::run(
      self, ctx, upstreams, downstream,
    ))
  }
}

/// **THE WHEEL, AND EVERYTHING A HAND ON IT REACHES** — one autonomous node with its three seats
/// filled, waiting for an engine.
///
/// What [`Wiring::autonomous`](super::Wiring::autonomous) hands back and
/// [`Ignition::autonomous_declared`](super::Ignition::autonomous_declared) spends. It is
/// [`LaneMount`](super::LaneMount)'s counterpart at this kind and it holds the same kind of thing —
/// the parts a party that has not started yet will be given — with one difference that matters: a
/// lane is handed OUT to whoever asks for it, and this is started by the launch, because an
/// autonomous body's loop is its own rather than a cycle somebody outside has to drive.
///
/// # The STOPPER is not in here, and that is the shutdown's doing
///
/// The launch keeps it. A body inside `run` for its whole life never reads the party announcement
/// [`App::shutdown`](super::App::shutdown) broadcasts, so the wind-down reaches it on the one road
/// it listens to — its [`ShutdownSignal`] — and the far half of that road has to stay with the world rather
/// than travel onto the engine with the value. That is
/// [`Ignition::origin_declared`](super::Ignition::origin_declared)'s arrangement exactly.
///
/// # The TAPS are not in here either, and for the same shape of reason
///
/// An ending is reported by the party that STARTED the body, through the deployment's own composite
/// — [`Ignition::autonomous_declared`](super::Ignition::autonomous_declared), which is where
/// [`observed`](super::Lived) is called. A seat here would be a second authority for one fact, and
/// a hand-built value that forgot to fill it would report into nothing. The origin layer's
/// arrangement, unchanged.
pub struct Helm<O, M = Block>
where
  O: Runs<M>,
{
  /// The node's own WINDOW — the deployment's resources, this node's wind-down line and its name,
  /// which is why no separate name field sits beside it: one fact, one home.
  ctx: Context,
  operator: O,
  upstreams: Upstreams<<O as Runs<M>>::In>,
  downstream: Downstream<<O as Runs<M>>::Out>,
}

impl<O, M> Helm<O, M>
where
  O: Runs<M>,
{
  /// The node this `ctx` names, with its seats.
  ///
  /// `ctx` LEADS, as it does at every face of this crate: it is the window the run is spent
  /// through, and the name it carries is this value's own name too.
  #[must_use]
  pub fn new(
    ctx: Context,
    operator: O,
    upstreams: Upstreams<<O as Runs<M>>::In>,
    downstream: Downstream<<O as Runs<M>>::Out>,
  ) -> Self {
    Self {
      ctx,
      operator,
      upstreams,
      downstream,
    }
  }

  /// This node's declared name — the [`Context`]'s own, since the window carries it.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &NodeName {
    self.ctx.node()
  }

  /// How many inbound edges the seat was filled with.
  #[inline]
  #[must_use]
  pub fn upstreams(&self) -> usize {
    self.upstreams.len()
  }

  /// The node's own value, taken back — what a REFUSED launch stages the goodbye of.
  ///
  /// [`LaneMount::into_instances`](super::LaneMount::into_instances)'s door one kind over, and it
  /// takes the same road for the same reason: a pre-ignition unwind has to be able to say a
  /// `teardown` word's goodbye, and a value swallowed by a closure would be one the unwind could
  /// only drop.
  ///
  /// It is safe to spend for a reason the FACE states rather than this type: an autonomous node's
  /// construction is PURE DATA, so a value that has been built and never ignited holds no thread,
  /// no channel and no worker — dropping one in its slot is a no-op, and taking it back to say a
  /// goodbye is the whole of what the unwind could want. Everything live starts in `run`'s
  /// prologue, which is a call this value has not made.
  #[inline]
  #[must_use]
  pub fn into_operator(self) -> O {
    self.operator
  }

  /// **RUN IT** — the whole life, on the calling thread.
  ///
  /// The node's value is CONSUMED, and nothing comes back but the ending. That is the face's own
  /// by-value contract cashed: the run took `self`, its prologue moved `self`'s parts into workers
  /// of its own, and its epilogue wound them down — so there is no husk for a caller to be handed,
  /// and a respawn is a factory rebuild rather than a reuse. See
  /// [`AutonomousOperator`](crate::AutonomousOperator)'s lifecycle table.
  ///
  /// [`Ended`](super::Ended) one kind over hands the instance back BECAUSE there is a next delivery
  /// for it to be warm for. Here there is no next.
  ///
  /// # Errors
  ///
  /// Whatever the node's own life refuses with — a body that DIED rather than reaching either
  /// ending. Both endings are `Ok`.
  pub fn run(self) -> Result<Fin, <O as Runs<M>>::Error> {
    let Self {
      ctx,
      operator,
      upstreams,
      downstream,
    } = self;
    Runs::drive(operator, ctx, upstreams, downstream)
  }
}

impl<O, M> core::fmt::Debug for Helm<O, M>
where
  O: Runs<M>,
{
  /// The node and its arity — never the body and never the messages, for
  /// [`StreamLane`](super::StreamLane)'s reason: `O` is the author's own type and demanding a
  /// [`Debug`](core::fmt::Debug) of it would bound every autonomous node for the benefit of this
  /// line.
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("Helm")
      .field("node", &self.ctx.node().as_str())
      .field("upstreams", &self.upstreams.len())
      .finish_non_exhaustive()
  }
}