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
//! THE BRIDGE AT VALIDATE: the deployment that now checks out, and the two a bridge cannot serve.
//!
//! A CHANNEL edge from a launched origin to a launched consumer is opened — the mount hands the
//! origin that consumer's own inbox as its feed — so the arrangement this file used to refuse is the
//! arrangement it now passes. What is left to refuse is narrower and is about the deployment rather
//! than about the bridge: a consumer listening by a word an origin cannot be heard through, and two
//! launched consumers pulling at one feed.
//!
//! The shapes beside them are pinned for the same reason they always were — a rule written too wide
//! would swallow them. An origin whose consumer is left dark is the LOOSE arrangement every other
//! origin test in this crate is built on, and a consumer whose origin is dark is the ordinary
//! starved-upstream refusal with a different fix in its sentence.
use crate::Context;

use core::{convert::Infallible, time::Duration};

use crate::{
  Block, Buffered, Control, Declared, DeclaredOrigin, Delivery, Effect, Emitter, Enablement, Feed,
  Fin, LaunchError, Listen, Operator, Refusal, Resources, Source, Unchanneled, Upstream,
};

/// An origin. What it does is beside the point — nothing here ignites — so it is the smallest one
/// that compiles.
struct Ticking;

impl Source for Ticking {
  type Options = ();
  type Yield = u64;
  type Mutation = ();
  type Error = Infallible;

  fn build(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> {
    Ok(Self)
  }

  fn run(
    self,
    _ctx: Context,
    _giving: Feed<u64>,
    _eating: Control<Infallible>,
  ) -> Result<Fin, Self::Error> {
    Ok(Fin::Spent)
  }
}

impl DeclaredOrigin for Ticking {
  type Mode = Block;
}

/// The consumer that names it — the far end of the edge the bridge opens.
struct Ledger;

impl Operator for Ledger {
  type Error = Infallible;
  type In = u64;
  type Out = u64;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<u64>,
    _emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Ledger {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  const UPSTREAMS: &'static [Upstream] = &[Upstream::of::<Ticking>("crate::Ticking")];
  type Channels = Unchanneled;
  type Mode = Block;
  type Options = ();
  type Pair = Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// A SECOND consumer of the same origin — what the split row is about.
struct Mirror;

impl Operator for Mirror {
  type Error = Infallible;
  type In = u64;
  type Out = u64;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<u64>,
    _emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Mirror {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  const UPSTREAMS: &'static [Upstream] = &[Upstream::of::<Ticking>("crate::Ticking")];
  type Channels = Unchanneled;
  type Mode = Block;
  type Options = ();
  type Pair = Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// A consumer that POLLS its upstream — the word an origin has no store to answer.
struct Sweeping;

impl Operator for Sweeping {
  type Error = Infallible;
  type In = u64;
  type Out = u64;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<u64>,
    _emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Sweeping {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  const UPSTREAMS: &'static [Upstream] =
    &[Upstream::of::<Ticking>("crate::Ticking").listening(Listen::Poll(Duration::from_secs(60)))];
  type Channels = Unchanneled;
  type Mode = Block;
  type Options = ();
  type Pair = Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// The arrangement most tests below are deployments of: one origin, one consumer, one channel edge.
fn arranged(enablement: Enablement) -> Result<crate::Wired, LaunchError> {
  let mut blueprint = crate::Blueprint::new();
  let _ = blueprint.origin::<Ticking>("ticking");
  let _ = blueprint.node::<Ledger>("ledger");
  blueprint
    .into_plan()
    .expect("the edge joins on the origin's own identity")
    .with_enablement(enablement)
    .validate()
}

/// The rows a refused deployment came back with.
fn refusals(refused: LaunchError) -> Vec<Refusal> {
  let LaunchError::Refused(rows) = refused else {
    panic!("a validate walk refuses with rows: {refused}");
  };
  rows
}

/// **BOTH ENDS LAUNCHED IS THE BRIDGE**, and it is what this deployment now is.
///
/// The row that used to fire here was the whole record of a step no walk performed. The step exists:
/// the mount hands the origin the consumer's own inbox as its feed, so the plan's edge is one the
/// ignition opens and there is nothing left to refuse.
#[test]
fn a_deployment_that_launches_both_ends_of_an_origins_edge_checks_out() {
  let _: crate::Wired = arranged(Enablement::new().launching("ticking").launching("ledger"))
    .expect("the bridge opens that edge");
}

/// **THE ORIGIN ALONE IS THE LOOSE DEPLOYMENT**, and it validates too.
///
/// Both roads are legal and the deployment picks: a consumer left dark is the shape every other
/// origin test in this crate is built on — the edge exists, so the origin is not a leaf that
/// computes into nothing, and the deployment reads the feed itself through the handle
/// `origin_declared` hands back.
#[test]
fn an_origin_whose_consumer_is_dark_is_the_loose_arrangement() {
  let _: crate::Wired =
    arranged(Enablement::new().launching("ticking")).expect("the deployment checks out");
}

/// **THE CONSUMER ALONE IS THE OTHER ROW**, and the two sentences do not converge.
///
/// A dark PRODUCER is `DisabledUpstream`, whose fix is to launch it or to read its store. Nothing
/// about the bridge touches that: the producer here is not running at all.
#[test]
fn a_consumer_whose_origin_is_dark_is_the_starved_upstream_row_instead() {
  let refused =
    arranged(Enablement::new().launching("ledger")).expect_err("its upstream is not launched");

  let rows = refusals(refused);
  assert!(rows.iter().any(Refusal::is_disabled_upstream), "{rows:?}");
  assert!(
    !rows.iter().any(Refusal::is_unbridged_origin),
    "the origin is not launched, so nothing is listening to a running one: {rows:?}"
  );
}

/// **A WORD AN ORIGIN CANNOT BE HEARD THROUGH** is what the narrowed row is now about.
///
/// `poll` asks the producer's STORE to be swept, and an origin's effect is the pure one — it lands
/// nothing, so there is no store. The fix in the sentence is therefore the WORD and not the wiring,
/// which is what separates this row from every deployment-shaped one beside it.
#[test]
fn a_consumer_that_listens_by_a_word_an_origin_cannot_answer_is_refused_by_name() {
  let mut blueprint = crate::Blueprint::new();
  let _ = blueprint.origin::<Ticking>("ticking");
  let _ = blueprint.node::<Sweeping>("sweeping");
  let refused = blueprint
    .into_plan()
    .expect("the edge joins")
    .with_enablement(Enablement::new().launching("ticking").launching("sweeping"))
    .validate()
    .expect_err("an origin has no store to poll");

  let rows = refusals(refused);
  let [Refusal::UnbridgedOrigin(unheard)] = rows.as_slice() else {
    panic!("one row, and it is the unheard word: {rows:?}");
  };
  assert_eq!(unheard.origin_name(), "ticking");
  assert_eq!(unheard.consumer_name(), "sweeping");
  assert_eq!(unheard.listen(), "poll");
  assert_eq!(unheard.origin(), crate::NodeId::new(0));
  assert_eq!(unheard.consumer(), crate::NodeId::new(1));
  assert_eq!(unheard.edge(), crate::EdgeId::new(0));

  // THE SENTENCE, WHOLE — pinned entire rather than by a substring, because what a reader is told is
  // the deliverable: the row's whole reason for existing is that this used to be a silence.
  assert_eq!(
    rows[0].to_string(),
    "node#1 (`sweeping`) listens to the origin node#0 (`ticking`) by `poll`, and an origin has \
     nothing to be heard through that word with: it lands nothing, so there is no store to watch or \
     poll, and it answers nobody, so there is no door to ask; subscribe to `ticking` over the \
     channel, which is what an origin publishes on"
  );
}

/// **ONE FEED, ONE EDGE** — and two launched consumers of one origin are refused by name.
///
/// Fanning out is copying, and the road that copies demands a `Clone` the origin face declines to
/// bound. The row names every consumer rather than counting them, because the fix is about WHICH.
#[test]
fn two_launched_consumers_of_one_origin_are_refused_by_name() {
  let mut blueprint = crate::Blueprint::new();
  let _ = blueprint.origin::<Ticking>("ticking");
  let _ = blueprint.node::<Ledger>("ledger");
  let _ = blueprint.node::<Mirror>("mirror");
  let refused = blueprint
    .into_plan()
    .expect("both edges join")
    .with_enablement(
      Enablement::new()
        .launching("ticking")
        .launching("ledger")
        .launching("mirror"),
    )
    .validate()
    .expect_err("an origin has one feed");

  let rows = refusals(refused);
  let [Refusal::SplitOrigin(split)] = rows.as_slice() else {
    panic!("one row for the whole fan-out: {rows:?}");
  };
  assert_eq!(split.origin_name(), "ticking");
  assert_eq!(split.origin(), crate::NodeId::new(0));
  assert_eq!(split.count(), 2);
  assert_eq!(split.consumers(), ["ledger", "mirror"]);
  assert_eq!(
    rows[0].to_string(),
    "node#0 (`ticking`) is an origin and this deployment launches 2 consumers of it (`ledger`, \
     `mirror`), but an origin has ONE feed and it becomes ONE edge — put a pass-through operator \
     under `ticking` and fan out from there, or launch one of them"
  );
}

/// The split row is about a DEPLOYMENT, exactly as every row beside it is: an arrangement may
/// declare any number of consumers, and launching one of them is an ordinary bridged deployment.
#[test]
fn an_origin_with_two_declared_consumers_and_one_launched_checks_out() {
  let mut blueprint = crate::Blueprint::new();
  let _ = blueprint.origin::<Ticking>("ticking");
  let _ = blueprint.node::<Ledger>("ledger");
  let _ = blueprint.node::<Mirror>("mirror");
  let _: crate::Wired = blueprint
    .into_plan()
    .expect("both edges join")
    .with_enablement(Enablement::new().launching("ticking").launching("ledger"))
    .validate()
    .expect("one launched consumer is one edge");
}

/// **THE HAND-WRITTEN DOOR**: an origin as an edge's producer, spelled with two typed handles.
///
/// The DECLARED road needs no word for this — a consumer names its upstream by type and the join is
/// kind-blind, so `subscribe(upstream(node = "…"))` reaches an origin already. What this door adds
/// is the compiler checking a pair a hand-written arrangement spells for itself, and what it records
/// is an ORDINARY edge: nothing downstream can tell which of the two doors minted one, and nothing
/// downstream needs to.
#[test]
fn the_typed_origin_door_records_an_ordinary_edge() {
  let mut builder = crate::GraphBuilder::new();
  let ticking = builder.origin::<Ticking>("ticking", crate::DriverKind::Thread);
  let ledger = builder.node::<Ledger>("ledger", crate::DriverKind::Thread);
  let edge = builder.origin_edge(&ticking, &ledger, crate::FanoutKind::Direct);
  assert_eq!(edge, crate::EdgeId::new(0));

  let graph = builder
    .validate()
    .expect("one origin, one consumer, one edge");
  assert!(graph.nodes()[0].is_source(), "an origin is a dataflow head");
  assert_eq!(graph.edges()[0].from(), crate::NodeId::new(0));
  assert_eq!(graph.edges()[0].to(), crate::NodeId::new(1));
}

/// The word the whole family hangs off is set by the ORIGIN door and by nothing else — an operator
/// that subscribes to nothing is a head too, and the graph cannot tell the two apart.
#[test]
fn only_the_origin_door_states_the_originating_word() {
  let mut blueprint = crate::Blueprint::new();
  let _ = blueprint.origin::<Ticking>("ticking");
  let _ = blueprint.node::<Ledger>("ledger");
  let plan = blueprint
    .into_plan()
    .expect("the edge joins")
    .with_enablement(Enablement::new().launching("ticking"));
  let wired = plan.validate().expect("the deployment checks out");
  let row = |at| {
    wired
      .node(crate::NodeId::new(at))
      .expect("both are mounted")
      .is_origin()
  };
  assert!(row(0), "the origin says so");
  assert!(!row(1), "an operator does not");
}

/// **THE BRIDGE DOOR ASKS FROM THE PRODUCER'S END**, and hands back the sending half of the one edge
/// the origin's declaration never named.
///
/// `Wiring::outbox` asks from the CONSUMER's end, which is what a walk that already knows who the
/// consumer is spells. This is what an EMITTED launch spells instead: the pairing lives in the
/// consumer's own declaration and is joined into the plan by type identity, so the walk reads the
/// edge off the arrangement and answers under the origin's own yield.
#[test]
fn the_bridge_door_opens_an_origins_one_out_edge_from_its_own_end() {
  let wired = arranged(Enablement::new().launching("ticking").launching("ledger"))
    .expect("the bridge opens that edge");
  let mut wiring = wired.create().wire();

  let opened = wiring
    .bridge::<u64>(crate::NodeId::new(0))
    .expect("nothing to refuse")
    .expect("both ends are launched");
  // The far half is the CONSUMER's own inbox, which is the whole of what a bridge is: asking for it
  // from the other end answers the same edge.
  let inbox = wiring
    .inbox::<u64>(crate::NodeId::new(1))
    .expect("nothing to refuse")
    .expect("the deployment launches the consumer");
  drop(opened);
  drop(inbox);
}

/// **A DARK CONSUMER IS NO FEED**, and it is not a refusal either: presence is enablement at both
/// ends, so an origin with nowhere to send is an origin with nothing to be started for.
///
/// The validate walk's own rows are about the deployments that turn BOTH ends on, and this is the
/// other case — the loose arrangement, where the deployment drains the origin itself.
#[test]
fn an_origin_whose_consumer_is_dark_has_no_edge_to_be_handed() {
  let wired = arranged(Enablement::new().launching("ticking")).expect("the deployment checks out");
  let mut wiring = wired.create().wire();

  assert!(
    wiring
      .bridge::<u64>(crate::NodeId::new(0))
      .expect("nothing to refuse")
      .is_none(),
    "the consumer this edge ends at is not launched"
  );
}

/// **AN ORIGIN THIS DEPLOYMENT DOES NOT LAUNCH HAS NO FEED**, exactly as a node it does not launch
/// has no inbox.
#[test]
fn a_dark_origin_is_handed_nothing() {
  let wired = arranged(Enablement::new().launching("ledger"));
  // The consumer alone is the starved-upstream refusal, so this deployment never reaches a wiring
  // walk at all — which is the honest way to state it: there is no `Wired` to ask.
  assert!(
    wired.is_err(),
    "a launched consumer with a dark producer is refused"
  );

  // The question this test is really about, asked of a deployment that DOES validate: an arrangement
  // where neither end runs.
  let wired = arranged(Enablement::new()).expect("an empty deployment checks out");
  let mut wiring = wired.create().wire();
  assert!(
    wiring
      .bridge::<u64>(crate::NodeId::new(0))
      .expect("nothing to refuse")
      .is_none(),
    "nobody named the origin, so there is no feed to open"
  );
}

/// **A TYPE THE EDGE DOES NOT CARRY IS REFUSED BY NAME**, from this end as from the other: a
/// producer's output and its consumer's input are ONE type, and a walk that spells them differently
/// is naming a topology the declaration does not have.
#[test]
fn a_bridge_asked_for_the_wrong_message_is_refused() {
  let wired = arranged(Enablement::new().launching("ticking").launching("ledger"))
    .expect("the bridge opens that edge");
  let mut wiring = wired.create().wire();

  let _ = wiring
    .inbox::<u64>(crate::NodeId::new(1))
    .expect("nothing to refuse")
    .expect("the deployment launches the consumer");
  let refused = wiring
    .bridge::<String>(crate::NodeId::new(0))
    .expect_err("this edge carries `u64`");

  assert!(matches!(refused, LaunchError::Wiring { .. }), "{refused}");
}