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
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
//! DRIVING AN ORIGIN: the engine a source's life runs on, and what a launch does when that life
//! ends.
//!
//! A [`Resident`](crate::drive::Resident) is called once per item and returns; a source is STARTED
//! ONCE and runs until it is finished, told to stop, or dies. So an origin does not join the driving
//! matrix — there is no per-item loop to put a mode under — and what a launch owes it is simpler and
//! smaller: an engine to run on, the three seats, and somewhere for its ending to be reported.
//!
//! # BOTH FACES RUN ON A THREAD OF THEIR OWN, and the awaited one is PINNED there
//!
//! | face | how it is driven |
//! |---|---|
//! | [`Source`](crate::Source) | its own OS thread; `run` IS the drive, and there is nothing to wrap |
//! | [`AsyncSource`](crate::AsyncSource) | its own OS thread, its future pinned on it by [`drive_awaited_origin`] |
//!
//! The awaited face is NOT handed to [`Ignition::spawn`](super::Ignition::spawn), and that is the
//! ruling rather than an oversight. That door is the async engine's, and it demands `Send` of what
//! it takes — which would refuse the exact shape [`AsyncSource`](crate::AsyncSource) dropped its own
//! `+ Send` bound to admit: an origin holding a model session, a thread-affine client, a handle that
//! cannot travel. So an origin is driven the way the thread engine already drives an
//! [`AsyncOperator`](crate::AsyncOperator) — through the same [`block_on`], which pins the future on
//! the stack of the one thread that owns it and asks for nothing.
//!
//! The dividend is a compile-level fact rather than a claim: the suite beside this module drives an
//! origin whose future holds an `Rc` across two awaits, and a `+ Send` anywhere on this road would
//! make that declaration itself the error rather than a placement's refusal.
//!
//! # THE ENDING IS REPORTED, and a DEATH is an ending
//!
//! `run` answers `Result<Fin, Self::Error>` — two ordinary endings and one way of not ending at all
//! — and all three reach the arrangement's [`Taps`](crate::drive::Taps) through [`observed`]:
//!
//! | answered | station | what a tap learns |
//! |---|---|---|
//! | `Ok(Fin::Spent)` | `Processed` | the line ran out of its own accord |
//! | `Ok(Fin::Stopped)` | `Processed` | it heard the stop and wound down |
//! | `Err(e)` | `Failed` | it DIED, and the error keeps its own words |
//!
//! The party SETTLES either way, and that is deliberate: a settle says *this body is finished*, and
//! a dead one is finished. A launch that left a died source unsettled would hold a shutdown open on
//! a thread that had already returned.
//!
//! # RESTARTS ARE DEFERRED, and the debtor is recorded here
//!
//! Nothing restarts a died origin. A restart policy is a real design — how many times, how far
//! apart, whether the yield line's position is replayed or resumed, what a downstream that saw a
//! partial run is owed — and every one of those questions is answered differently by a socket loop,
//! a directory walk and a change feed. Shipping a default would be this layer answering them for
//! everybody. What is shipped instead is the FACT: the death is observed, named, and settled, so an
//! application that wants a restart has everything it needs to build one and nothing it has to undo.
//!
//! # MOUNTING IS DECLARATION-DRIVEN, and a caller never names a face
//!
//! An origin states what it is — [`DeclaredOrigin`](crate::DeclaredOrigin) — and the walk reads it:
//!
//! | step | door | what the declaration decides |
//! |---|---|---|
//! | the arrangement | [`Blueprint::origin`](super::Blueprint::origin) | that it is a HEAD, and that its effect is pure |
//! | the engine | [`Ignition::origin_declared`](super::Ignition::origin_declared) | WHICH of the two drivers below runs it |
//!
//! `Mode` is what makes the second row work: *implements one of two traits* is not a predicate
//! stable Rust can spell, so the declaration selects the [`Lived`] row and the row carries the
//! driver. A caller writes one line for either face, cannot pick the wrong one, and a declaration
//! whose word disagrees with its body is `E0277` at the mount.
//!
//! What the walk mints is the THREE LINES; what it hands back is [`Mounted`], which is their far
//! ends. What it does NOT do is build the origin — construction from an `Options` is the create
//! walk's step and runs before this stage — so a caller hands over a value, exactly as it does for
//! a resident.
//!
//! # CONSTRUCTION IS THE FACE'S OWN, and the row is the same one
//!
//! [`Creation::origin`](super::Creation::origin) is that create step, and what it calls is
//! [`Source::build`](crate::Source::build) — the door the author already wrote — reached through
//! [`Lived::open`] under the mode the declaration named. So an origin states its knobs ONCE, in its
//! own face's [`Options`](crate::Source::Options), and the emitted section is written off that seat.
//!
//! It read differently until this round. `build` signed the RUNTIME window — a [`Context`], whose
//! wind-down line is minted at the mount and therefore does not exist at the create stage — so the
//! walk could not reach it, and the macro road detoured origin construction through
//! [`AsyncConstructor`](super::AsyncConstructor) instead. That left every origin on the declared
//! road writing TWO options seats, one of which nothing read. The window is now [`Resources`] on
//! both faces, the detour is retired, and the second seat is gone with it;
//! [`AsyncConstructor`](super::AsyncConstructor) stays where it always belonged, as the RESIDENT
//! construction door.
//!
//! # A SOURCE NOBODY LISTENS TO IS REFUSED AT VALIDATE, and the refusal is not a new one
//!
//! [`Refusal::PureLeaf`](super::Refusal::PureLeaf) already covers it. That check runs over EVERY
//! enabled node — head or interior, no special case for an origin — and refuses one whose effect is
//! pure, which publishes to nobody, polls nothing and answers nobody. A source mounted as a head with
//! no consumer is exactly that shape, so it is refused before anything is ignited, by name, with
//! the fix in the sentence.
//!
//! [`Blueprint::origin`](super::Blueprint::origin) is what makes that true rather than merely
//! available: an origin's effect is the PURE one, because an origin lands nothing — what it produces
//! becomes durable wherever its consumers land it — so the rule that was already there fires on the
//! shape without being told about origins at all.
//!
//! There is no separate orphan-head family, and adding one would be two refusals for one mistake:
//! the vocabulary is named after WHAT IS WRONG rather than after WHO it happened to, so *this
//! computes into nothing* is one word whether the node that computes into nothing has an upstream or
//! is the head of the whole arrangement.
//!
//! # **THE SOURCE→GRAPH BRIDGE**: an origin's feed IS its out-edge
//!
//! An origin's out-edge starts as a fact in the PLAN — the join reads a consumer's declared upstream
//! and records it — and [`Ignition::origin_bridged`](super::Ignition::origin_bridged) is the walk
//! that opens it. What makes the whole thing small is a single decision, and it is the one this
//! section is really about: **the framework hands the origin the edge rather than pumping items into
//! it.**
//!
//! | end | who mints it | who holds it |
//! |---|---|---|
//! | the consumer's inbox | the wiring walk | the consumer's engine |
//! | its far half, an [`Outbox`](crate::Outbox) | the wiring walk | the MOUNT takes it, by value |
//! | the origin's [`Feed`] | the mount, over that outbox | the origin's own body, by value |
//!
//! There is no [`Yielded`] in that table and no pump beside it, which is what a bridged deployment
//! gets in exchange: no second queue, no second bound, no second thread, and a teardown with no
//! ordering to get wrong. [`Mounted`] is still what a LOOSE mount hands back —
//! [`origin_declared`](super::Ignition::origin_declared) is unchanged and is still the door for an
//! origin a deployment drains itself, through [`App::feeder`](super::App::feeder) or otherwise —
//! and [`Bridged`] is the two-seat handle a bridged one hands back instead.
//!
//! ## The four questions the refusal recorded, and what each was answered with
//!
//! - **WHICH WALK OPENS IT.** The MOUNT takes a sending half from the wiring walk, which was the
//!   only one of the two candidates that could be TYPED: at
//!   [`origin_bridged`](super::Ignition::origin_bridged) the origin's `Yield` is still a type rather
//!   than a `TypeId`, so [`Wiring::outbox`](super::Wiring::outbox) answers under that very
//!   projection and a consumer whose input is something else is refused there with both types named.
//! - **WHAT AN ITEM BECOMES.** A [`Delivery`](crate::Delivery) carrying one [`Item`](crate::Item)
//!   under an [`ItemId`](crate::ItemId) this line mints from a counter of its own — the same thing
//!   every other sender in the framework does. The ack window is opened per give and its receiving
//!   half is dropped on the spot, because that is the position an origin is IN: an ack releases
//!   custody upstream, a head has nobody upstream, and a source has no durable position to rewind
//!   to. It is the posture [`App::feeder`](super::App::feeder)'s own callers already take, and
//!   [`Feed::bridging`](crate::Feed::bridging) is where both halves are written down.
//! - **WHOSE BACKPRESSURE WINS.** Neither, because there is only ONE bound. The feed IS the edge, so
//!   what bounds it is the edge's own depth — resolved from the declaration and the deployment's
//!   document like every other edge's — and [`Feed::give`] waits on the consumer's inbox directly.
//!   The question dissolved rather than being ruled on, which is the dividend of not pumping.
//! - **WHAT THE ENDING DOES.** Nothing new, and no `End` was invented: an edge's end has always
//!   been every sender being gone. The feed is taken BY VALUE into [`Lived::live`], and this layer
//!   keeps no second half on the origin's behalf — the outbox is taken from the wiring BY VALUE for
//!   exactly that reason — so `run` returning drops the origin's own. All three endings do it alike,
//!   because what closed it is the body being over rather than which way it was over; which way it
//!   was over is what the [`Taps`] are told, per the section above.
//!
//!   The LAUNCH still holds a half of every edge whose receiver was taken, so that nothing stops
//!   before it starts, and [`Assembly::close`](super::Assembly::close) releases them as the
//!   wind-down's first domino. From that moment a bridged origin is the ONLY thing holding its
//!   consumer's inbox open — which is what makes it a real producer in that wave rather than a
//!   special case in it: the consumer drains and returns when the origin's life ends, and an origin
//!   that never ends holds its consumer open for as long as it runs, which is precisely what an
//!   fs-watch origin means. [`App::until_stopped`](super::App::until_stopped) before the shutdown is
//!   the drain-first door for a FINITE one, unchanged.
//!
//! ## What a bridge cannot serve, and is refused for
//!
//! Two rows at validate, and both are about a DEPLOYMENT rather than an arrangement — the edge is
//! never the mistake, since an origin with a consumer is exactly what keeps it from being a leaf
//! that computes into nothing.
//!
//! | shape | row | the fix in its sentence |
//! |---|---|---|
//! | a consumer listening by `changes`, `poll` or `transient` | [`Refusal::UnbridgedOrigin`](super::Refusal::UnbridgedOrigin) | subscribe over the channel |
//! | two launched consumers of one origin | [`Refusal::SplitOrigin`](super::Refusal::SplitOrigin) | a pass-through operator, and fan out from there |
//!
//! The first is a WORD asking an origin for a store or a door it has not got. The second is one feed
//! being pulled at from two sides: fanning out is copying, the [`Downstream`](crate::Downstream) set
//! that does it demands `T: Clone`, and the origin face declines that bound because a source hands
//! over what it produced once.
//!
//! ## Where a caller still spells the bridge by hand
//!
//! [`GraphBuilder::origin_edge`](crate::GraphBuilder::origin_edge) is the typed door for a
//! hand-written arrangement — a second door beside
//! [`edge`](crate::GraphBuilder::edge) rather than a bound relaxed on it, for
//! [`GraphBuilder::origin`](crate::GraphBuilder::origin)'s own reason: `Driven` and [`Lived`] are two
//! rows and no blanket impl can join them. The DECLARED road needs no new word at all — a
//! declaration names its upstream by type and the join is kind-blind — and `tests/origin_bridge`
//! pins what is still refused through a real compile.

use core::future::{Future, ready};

use super::{
  super::{
    NodeName,
    lane::block_on,
    lifecycle::{Failure, Lifecycle, LifecycleTap as _, Taps},
  },
  Resources,
};
use crate::{
  Async, AsyncSource, Block, Commands, Context, Control, DeclaredOrigin, Feed, Fin, MutationNode,
  Source, Stopper, Yielded,
};

#[cfg(test)]
mod bridge_tests;
#[cfg(test)]
mod bridged_tests;
#[cfg(test)]
mod declared_tests;
#[cfg(test)]
mod shutdown_tests;
#[cfg(test)]
mod tests;

/// **ONE DOOR FOR TWO FACES**: whatever a declaration's [`Mode`](DeclaredOrigin::Mode) selected —
/// opened from its options, and driven to its ending on the calling thread.
///
/// [`Driven`](crate::Driven)'s shape for the origin layer, and it is here for the same reason:
/// *implements one of two traits* is not a predicate stable Rust can spell, so the two faces get a
/// blanket row each and a mount binds the row the DECLARATION named. Nothing an author can write
/// fills either row — [`Source`] and [`AsyncSource`] do — so a word that lies about its body asks
/// for a row that does not exist.
///
/// # It mirrors the WHOLE face, not half of it
///
/// [`Source`] carries two verbs and one error currency, and so does this row: `open` is
/// [`Source::build`] under the mode the declaration named, and [`live`](Lived::live) is
/// [`Source::run`] under it. A row that mirrored only the life would have left the framework
/// reaching an origin's construction through some OTHER trait — which is exactly the detour the
/// origin tier used to take, and the one whose cost was a second options seat nothing read.
///
/// That is also why there is no separate `Error` for the opening: an origin refuses a construction
/// and a death in one currency, per [`Source::Error`]'s own law, so [`Died`] names both.
///
/// # The two rows COLLAPSE into one driver, which is the dividend
///
/// Both faces run on a thread of their own and the awaited one is PINNED there, so
/// [`live`](Lived::live) is [`drive_origin`] on one row and [`drive_awaited_origin`] on the other —
/// and every caller above this trait is written once. See the module note for why the awaited face
/// is pinned rather than spawned.
pub trait Lived<M>: Sized {
  /// Whether THIS mode's `run` answers without a future.
  ///
  /// Set by the blanket rows and by nothing else, which is what makes it a proof rather than a
  /// claim — [`Driven::SYNC`](crate::Driven::SYNC)'s own law, one layer over.
  const SYNC: bool;

  /// What OPENING one takes — [`Source::Options`] under the mode the declaration named.
  ///
  /// The ONE options seat an origin has, and the seat the emitted spine writes its
  /// `[<mount>]` section off — see [`Tuned`], which is this projection written once.
  type Options;

  /// What this origin produces.
  type Yield: 'static;
  /// Its command face — the node whose fields are the vocabulary it is controlled through.
  type Mutation: MutationNode;
  /// What a refused OPENING and a life that DIED both refuse with — one currency, per
  /// [`Source::Error`].
  type Error;

  /// Open this origin from `options`, reaching whatever it shares through `ctx` — the CREATE walk's
  /// step, [`Creation::origin`](super::Creation::origin).
  ///
  /// # It answers a FUTURE on both rows, and the blocking one is already resolved
  ///
  /// [`Source::build`] is synchronous and stays so — an author writes the face their body has. What
  /// this row unifies is the CALLER's side: the create walk is an `async` walk, so a door it can
  /// spell once has to be awaitable, and the blocking row answers a [`ready`] future rather than
  /// making the walk hold two arms. It is the opposite trade to [`live`](Self::live), which is
  /// synchronous on both rows because its caller is the origin's own thread — see the module note.
  ///
  /// # Errors
  ///
  /// Whatever this origin's own construction refuses with. The walk wraps it into a start-up refusal
  /// naming the mount.
  fn open(
    ctx: &Resources,
    options: Self::Options,
  ) -> impl Future<Output = Result<Self, Self::Error>>;

  /// Drive this origin to its ending, on the calling thread.
  ///
  /// # Errors
  ///
  /// Whatever this origin's own life refuses with — a line that DIED rather than reaching either
  /// ending. Both endings are `Ok`.
  fn live(
    self,
    ctx: Context,
    giving: Feed<Self::Yield>,
    eating: Control<<Self::Mutation as MutationNode>::Command>,
  ) -> Result<Fin, Self::Error>;
}

/// The BLOCKING row: implementing [`Source`] is implementing this.
impl<T> Lived<Block> for T
where
  T: Source,
{
  const SYNC: bool = true;

  type Options = <T as Source>::Options;
  type Yield = <T as Source>::Yield;
  type Mutation = <T as Source>::Mutation;
  type Error = <T as Source>::Error;

  #[inline]
  fn open(
    ctx: &Resources,
    options: Self::Options,
  ) -> impl Future<Output = Result<Self, Self::Error>> {
    // ALREADY RESOLVED: the blocking face's construction is over by the time this future exists, so
    // the walk's `.await` costs one poll and nothing waits. See the trait's own note.
    ready(<T as Source>::build(ctx, options))
  }

  #[inline]
  fn live(
    self,
    ctx: Context,
    giving: Feed<Self::Yield>,
    eating: Control<<Self::Mutation as MutationNode>::Command>,
  ) -> Result<Fin, Self::Error> {
    drive_origin(self, ctx, giving, eating)
  }
}

/// The AWAITED row: implementing [`AsyncSource`] is implementing this — and the future is PINNED on
/// the calling thread rather than spawned, per the module note.
impl<T> Lived<Async> for T
where
  T: AsyncSource,
{
  const SYNC: bool = false;

  type Options = <T as AsyncSource>::Options;
  type Yield = <T as AsyncSource>::Yield;
  type Mutation = <T as AsyncSource>::Mutation;
  type Error = <T as AsyncSource>::Error;

  #[inline]
  fn open(
    ctx: &Resources,
    options: Self::Options,
  ) -> impl Future<Output = Result<Self, Self::Error>> {
    // The awaited face's own future, handed on unchanged — the create walk awaits it where it
    // stands, which is the whole reason this face exists.
    <T as AsyncSource>::build(ctx, options)
  }

  #[inline]
  fn live(
    self,
    ctx: Context,
    giving: Feed<Self::Yield>,
    eating: Control<<Self::Mutation as MutationNode>::Command>,
  ) -> Result<Fin, Self::Error> {
    drive_awaited_origin(self, ctx, giving, eating)
  }
}

/// What OPENING an origin of type `S` takes, through the row its declaration named — its author's
/// own [`Source::Options`], and the type an emitted `[<mount>]` section holds.
///
/// It is the seat a deployment fills. An origin used to carry a SECOND one — the
/// [`AsyncConstructor`](super::AsyncConstructor) the create walk read instead of the face's own
/// `build` — and retiring that detour is what left exactly one.
pub type Tuned<S> = <S as Lived<<S as DeclaredOrigin>::Mode>>::Options;

/// What an origin of type `S` PRODUCES, through the row its declaration named — the projection every
/// door here spells, written once so a signature does not have to.
pub type Produced<S> = <S as Lived<<S as DeclaredOrigin>::Mode>>::Yield;

/// What it is TOLD, the same way.
pub type Ordered<S> =
  <<S as Lived<<S as DeclaredOrigin>::Mode>>::Mutation as MutationNode>::Command;

/// What a refused OPENING and a death are both reported as — one currency, per [`Source::Error`], so
/// the launch's construction refusal and its taps name the same type.
pub type Died<S> = <S as Lived<<S as DeclaredOrigin>::Mode>>::Error;

/// **THE THREE ENDS OF A MOUNTED ORIGIN** — what the launch walk hands back once the origin is on
/// its engine.
///
/// The walk mints the three lines and keeps the origin's halves; these are the framework's, and a
/// deployment holds them to say things to the origin, to read what it produces, and to stop it.
///
/// # DROPPING IT STOPS THE ORIGIN, and so does the world's own wind-down
///
/// A [`Stopper`] says the stop as it goes, so a deployment that lets this handle go has told the
/// origin to wind down — the same *whoever can still reach it decides it is finished* rule the rest
/// of this stage runs on. A deployment that wants to keep the origin running keeps the handle.
///
/// KEEPING IT IS NOT A WAY TO OUTLIVE THE SHUTDOWN. The mount joins a second half of the same line
/// to the launch, and [`App::shutdown`](super::App::shutdown) says the stop through it — so an
/// infinite origin winds down when the world does, whoever is still holding this. See
/// [`Ignition::origin_declared`](super::Ignition::origin_declared), where the join is made, and
/// [`App::until_stopped`](super::App::until_stopped) for the wait a deployment takes when it wants
/// a finite origin's last item rather than its earliest honest ending.
#[derive(Debug)]
pub struct Mounted<C, Y> {
  commands: Commands<C>,
  yielded: Yielded<Y>,
  stopper: Stopper,
}

impl<C, Y> Mounted<C, Y> {
  /// The line an app says things to this origin down.
  ///
  /// Borrowed rather than moved, because [`Commands`] is `Clone` and a deployment usually installs
  /// a copy somewhere — a schema's data map, a handler's context — while keeping one of its own.
  #[inline]
  #[must_use]
  pub const fn commands(&self) -> &Commands<C> {
    &self.commands
  }

  /// What the origin has produced.
  #[inline]
  #[must_use]
  pub const fn yielded(&self) -> &Yielded<Y> {
    &self.yielded
  }

  /// The handle that says *wind down* — see the type's note on what dropping it does.
  #[inline]
  #[must_use]
  pub const fn stopper(&self) -> &Stopper {
    &self.stopper
  }

  /// The three ends, taken apart — for a deployment that stores them separately.
  #[inline]
  #[must_use]
  pub fn into_parts(self) -> (Commands<C>, Yielded<Y>, Stopper) {
    (self.commands, self.yielded, self.stopper)
  }

  /// The three ends, as the walk assembles them.
  pub(super) const fn new(commands: Commands<C>, yielded: Yielded<Y>, stopper: Stopper) -> Self {
    Self {
      commands,
      yielded,
      stopper,
    }
  }
}

/// **THE TWO ENDS OF A BRIDGED ORIGIN** — what the launch walk hands back once an origin is on its
/// engine AND its feed is a graph edge.
///
/// [`Mounted`] minus the one seat a bridge spends: there is no [`Yielded`] here because the feed's
/// far end is a CONSUMER'S INBOX rather than a line a deployment drains. A separate type rather than
/// an optional field, because the absence is a fact about the arrangement rather than a value a
/// caller might or might not find — a handle whose `yielded()` answered `None` would make every
/// bridged deployment write the arm that cannot happen.
///
/// # DROPPING IT STOPS THE ORIGIN, exactly as [`Mounted`]'s note says
///
/// The [`Stopper`] rule is unchanged and the join to the wind-down is unchanged. What changes is
/// what a stopped origin's ending DOES: its feed is the edge, so the ending that drops the feed is
/// the ending that closes the consumer's stream — see [`Feed::bridging`](crate::Feed::bridging).
#[derive(Debug)]
pub struct Bridged<C> {
  commands: Commands<C>,
  stopper: Stopper,
}

impl<C> Bridged<C> {
  /// The line an app says things to this origin down.
  ///
  /// Borrowed rather than moved, for [`Mounted::commands`]'s reason.
  #[inline]
  #[must_use]
  pub const fn commands(&self) -> &Commands<C> {
    &self.commands
  }

  /// The handle that says *wind down* — see the type's note on what dropping it does.
  #[inline]
  #[must_use]
  pub const fn stopper(&self) -> &Stopper {
    &self.stopper
  }

  /// The two ends, taken apart — for a deployment that stores them separately.
  #[inline]
  #[must_use]
  pub fn into_parts(self) -> (Commands<C>, Stopper) {
    (self.commands, self.stopper)
  }

  /// The two ends, as the walk assembles them.
  pub(super) const fn new(commands: Commands<C>, stopper: Stopper) -> Self {
    Self { commands, stopper }
  }
}

/// The command line an origin of type `S` eats — the projection every seat here spells, written once
/// so a signature does not have to.
type Commanded<S> = Control<<<S as AsyncSource>::Mutation as MutationNode>::Command>;

/// The same, for the blocking face.
type Told<S> = Control<<<S as Source>::Mutation as MutationNode>::Command>;

/// Drive an AWAITED origin to its ending, PINNED on the calling thread.
///
/// The awaited face's whole driver, and the blocking face has none: [`Source::run`] IS the drive,
/// so a wrapper around it would be a second name for one call. See the module note for why the
/// future is pinned here rather than spawned.
///
/// It BLOCKS the calling thread until the origin answers, which is what makes it the thread engine's
/// door rather than the async engine's. A caller that already has a runtime awaits `run` directly.
///
/// # Errors
///
/// Whatever this origin's own life refuses with — a line that DIED rather than reaching either
/// ending. Both endings are `Ok`.
pub fn drive_awaited_origin<S>(
  source: S,
  ctx: Context,
  giving: Feed<S::Yield>,
  eating: Commanded<S>,
) -> Result<Fin, S::Error>
where
  S: AsyncSource,
{
  block_on(source.run(ctx, giving, eating))
}

/// Drive a BLOCKING origin to its ending on the calling thread — [`Source::run`], named.
///
/// It exists for the SYMMETRY of the two launch doors and for nothing else: a reader who found
/// [`drive_awaited_origin`] alone would reasonably ask where its twin is, and the honest answer — *the
/// blocking face needs no driver* — is worth a function's doc rather than a comment nobody lands on.
///
/// # Errors
///
/// [`drive_awaited_origin`]'s, unchanged.
#[inline]
pub fn drive_origin<S>(
  source: S,
  ctx: Context,
  giving: Feed<S::Yield>,
  eating: Told<S>,
) -> Result<Fin, S::Error>
where
  S: Source,
{
  source.run(ctx, giving, eating)
}

/// Report one origin's ENDING to the arrangement's taps — the death path, and the ordinary one, in
/// one function because they are one fact.
///
/// `Fin` is the info type for BOTH stations, so a tap asks for one thing whichever way the line
/// ended and a `Failed` observation is not a differently-shaped record.
pub(super) fn observed<E>(taps: &Taps, name: &NodeName, ended: Result<Fin, E>)
where
  E: core::error::Error + Send + Sync + 'static,
{
  let observation = match ended {
    // NOT `Persisted`, and the distinction is the station vocabulary's own: an origin lands nothing
    // — what it produced is durable wherever its consumers landed it — so the station a finished
    // line reaches is the pure one.
    Ok(fin) => Lifecycle::<Fin>::Processed(fin).erase(),
    // The error keeps its own words all the way to the tap, which is what `Failure` is for: only the
    // party that ran the body can name its type, so the boxing happens here and the rendering
    // happens wherever somebody knows what to do with it.
    Err(error) => Lifecycle::<Fin>::Failed(Failure::new(error)).erase(),
  };
  taps.observe(name, &observation);
}