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 Duration;
use ;
use crate::;
/// **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;
/// ```
/// **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.
/// The BLOCKING row: implementing [`AutonomousOperator`](crate::AutonomousOperator) is implementing
/// this, and `run` IS the drive.
/// 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.
/// **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.