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
//! WHO RUNS A TICK, AND WHERE: the handler citizens a poll entry mounts, the executors a detached
//! entry runs on, and the cell that keeps a slow clock from piling up.
//!
//! A `poll(…)` entry says WHEN. Everything here answers the other two questions the declaration can
//! ask — WHAT runs and IN WHICH WORLD — and the words that select them live on the entry:
//!
//! * `handler = "app::PromScraper"` MOUNTS a citizen — a value the deployment built and the node
//! never sees — and `light` runs the node's OWN `<Node>Sweeps` method instead. Exactly one of
//! the two on every entry: WHO runs a tick is declared rather than left to a silence.
//! * `block` · `spawn` · `rayon` · `async(inline)` · `async(spawn)` say WHERE. The word is
//! MANDATORY — a role is declared rather than inferred — and it decides which of the two citizen
//! traits the mount's bound demands, so a `block` entry mounting an async-only handler is
//! `E0277` at the word.
//!
//! # TWO CITIZENS, ONE SHAPE — the dual-mode law at this seam
//!
//! [`AsyncTick`] is the async face and [`Tick`] the blocking one, and they differ in exactly one
//! thing: whether the answer is a future. Same receiver, same lent context, same `Info` and `Error`.
//!
//! # THE NAMING AXIS, framework-wide and permanent
//!
//! **`Async*` is the asynchronous face; the BARE name is the blocking one.** There is no
//! `Blocking*` prefix anywhere in this framework — it was retired outright rather than deprecated,
//! because two spellings of one axis is the drift a reader has to hold in their head. The pairs
//! read the same way at every seam: [`AsyncTick`] / [`Tick`] here,
//! [`AsyncLands`](super::AsyncLands) / [`Lands`](super::Lands) one lane over,
//! [`AsyncSpawn`] / [`Spawn`] below, and
//! [`AsyncBlobEngine`](crate::AsyncBlobEngine) / [`BlobEngine`](crate::BlobEngine),
//! [`AsyncLocate`](crate::AsyncLocate) / [`Locate`](crate::Locate),
//! [`AsyncBlobStore`](crate::AsyncBlobStore) / [`BlobStore`](crate::BlobStore) in the store layer.
//!
//! A trait carrying NEITHER prefix nor a twin is a marker or an assoc-only face: it has no mode to
//! carry, so it is not named on this axis at all.
//!
//! # THE ONE EXEMPTION: a framework-internal engine seam, where dual VERBS are the faithful shape
//!
//! The pair-of-traits law governs AUTHOR-IMPLEMENTABLE contract faces — the ones a declaration or a
//! deployment writes an impl for. A FRAMEWORK-INTERNAL seam whose implementor must serve BOTH
//! engines at once is exempt, and the criterion is exactly that: an emitted subscribe container's
//! intake cannot know which engine will drive it, so ONE BODY has to hold TWO ENGINE DOORS. Two
//! verbs on one trait is the faithful spelling of that; a mode PAIR would be two types for one
//! implementor and would push the choice back onto a party that has no way to make it.
//!
//! The exempt family, on the record: [`Intake::park`](super::Intake::park) /
//! [`park_async`](super::Intake::park_async), [`Inbox`](super::Inbox)'s same pair,
//! [`Outbox`](super::Outbox)'s `deliver` / `deliver_async`, and the lane's own `block_on` driver.
//! Nothing else is exempt, and a new `*_async` verb beside a bare one is a claim that has to answer
//! this criterion first.
//!
//! A handler may implement BOTH citizen traits, and nothing here objects: which one is called is
//! decided by the word on the entry, not by what the type happens to offer.
//!
//! # ONE `Info` AND ONE `Error` PER NODE, and that law reaches the citizens
//!
//! A resident has one observation stream and one effect table, which is why `<Node>Sweeps` carries
//! one `Info` and one `Error` for a whole node. A mounted handler joins that same answer: the
//! emitted route states the node's pair and BINDS each INLINE citizen to it, so two handlers that
//! disagree are `E0271` at the deployment naming both types.
//!
//! DETACHED citizens are exempt, and structurally so — their answer never reaches the seat, so
//! there is nothing for it to agree with. See [`Spawn`] for what does happen to it.
//!
//! # THE EXECUTORS ARE A SEAM, AND THE WORDS ARE SUGAR FOR THE SHIPPED ONES
//!
//! [`Spawn`] and [`AsyncSpawn`] are open capability traits; [`Thread`], [`Rayon`] and
//! [`Tasks`] are the citizens this crate ships for them. `spawn` selects [`Thread`], `rayon` selects
//! [`Rayon`], `async(spawn)` selects whatever [`AsyncSpawn`] the deployment installed. A third-party
//! pool implements the seam and is installed into `<Node>Polling` deployment-side, displacing the
//! shipped default — and no vocabulary word is minted per engine, which is the framework-open law
//! read one axis over from the store engines.
//!
//! # WHAT THIS IS NOT: a deployment with no runtime at all
//!
//! `block` runs a sync body on the driver's own thread, and the thread engine already needs no
//! runtime — but the driver itself is still a driver, and a `Seats` seating is still an async call
//! it blocks on. A graph whose every seam is synchronous, with no future anywhere, is a DIFFERENT
//! and larger thing: it is about the shape of every seam in the tree rather than about where one
//! tick runs.
//!
//! It is RECORDED SCOPE rather than a gap here. The dual-mode law is about seam FACES — a blocking
//! twin beside an async one, so a sync body has somewhere to stand — and never about removing the
//! driver. The all-sync deployment is the R-line's own arc, and it opens with an inventory of every
//! execution seam in this crate rather than with a widening of this one.
use Future;
use ;
/// WHAT A MOUNTED CLOCK RUNS — the async citizen a `poll(…)` entry names with `handler = "…"`.
///
/// `Ctx` is what the clock LENDS the tick, and it defaults to `()`: an entry that granted nothing
/// lends nothing, and a handler for it writes `impl AsyncTick for Scraper` with no context named. An
/// entry that wrote `write = "…"` lends its own emitted grants context, so its handler names that
/// type — `impl AsyncTick<ExporterScrapeGrants<Rows>> for Scraper` — and the write sockets it reaches are
/// exactly the grants that entry wrote.
///
/// # Why the citizen is not the operator
///
/// Because a node's clocks and a node's data path are two different concerns wearing one struct. A
/// `light` entry is a method on the operator and stays the road for a sweep that works
/// through the node's own state; a mounted handler is a value the DEPLOYMENT built and handed over,
/// which is what makes a scraper, an exporter or a health probe reusable across declarations and
/// testable without a resident. Both roads stay open, entry by entry, which is what the presence
/// split buys.
///
/// # The answer is a `Send` future, spelled rather than hoped for
///
/// [`AsyncLands::land`](super::AsyncLands)' reason verbatim: a resident is a task on somebody's runtime, so a
/// body it awaits has to cross threads. Writing the bound into the signature makes it part of the
/// contract instead of something each caller discovers.
/// [`AsyncTick`]'s BLOCKING twin — what a `block`, `spawn` or `rayon` entry's mount implements.
///
/// The whole difference is the answer: a `Result` rather than a future. Everything else — the
/// receiver, the lent context and its default, the two associated types — is [`AsyncTick`]'s, because the
/// two faces are one seam seen from two worlds rather than two seams.
///
/// # It is not a lesser face
///
/// A scan over a directory tree, a `rusqlite` sweep, an FFI session's compaction: these are natively
/// blocking, and wrapping them in an async signature to satisfy a seam would put an await point
/// where no yield happens. The word on the entry says which world the body lives in, and the driver
/// spends it accordingly — `block` on its own thread, `spawn`/`rayon` on an executor.
/// WHERE A DETACHED BLOCKING TICK RUNS: the open executor seam behind the `spawn` and `rayon` words.
///
/// # The word is sugar and this is the door
///
/// `spawn` selects [`Thread`] and `rayon` selects [`Rayon`], and both are ordinary implementations
/// of this trait with no privilege the seam does not give them. A deployment holding a pool of its
/// own implements this and installs the value into `<Node>Polling`, displacing the shipped citizen
/// at the field the declaration's word typed — so a third-party executor costs no vocabulary word,
/// which is the framework-open law: the enum-shaped alternative would make every new pool a change
/// to this crate's grammar.
///
/// # It DETACHES, and that is the whole contract
///
/// There is no handle, no join and no answer. A detached tick's `Result` is dropped where it is
/// produced, because the party that could report it — the resident, which holds the taps — has
/// already moved on: the seat answered [`Swept::Dispatched`](super::Swept) the moment the work was
/// handed over. A body whose outcome must be observed writes `block` or `async(inline)`, where the
/// answer travels back through the seat and reaches the taps.
/// The `spawn` word's engine: ONE OS THREAD PER TICK.
///
/// The shipped default, and the ignition door's own precedent — a resident that names no runtime is
/// a thread too. A thread per tick is the honest cost of the plainest detachment: no pool to size,
/// no queue to fill, and a clock whose interval is minutes pays for a thread every minute.
///
/// A cadence fast enough for that to matter is a cadence that wants [`Rayon`] or a pool of the
/// deployment's own, which is why this is a default rather than a policy.
);
/// The `rayon` word's engine: rayon's own global pool.
///
/// A sibling of [`Thread`] rather than a replacement: the pool is sized once for the process and a
/// tick joins the work already queued there, so a fast clock costs a task instead of a thread. What
/// it buys over the plain spawn is what a pool always buys, and what it costs is the dependency —
/// which is why it rides the optional `rayon` feature and nothing else in this crate names it.
);
/// [`Spawn`]'s async twin: WHERE A DETACHED ASYNC TICK RUNS.
///
/// The `async(spawn)` word's seam, and the same layering one world over — the shipped citizen
/// ([`Tasks`]) binds it to whichever runtime a deployment already named, and a third-party executor
/// implements it directly.
///
/// # Why a value at all, when the runtime seam is a TYPE
///
/// [`AsyncSpawner`](agnostic_lite::AsyncSpawner)'s methods are static, so a task could in principle
/// be spawned by naming the type alone. Naming it alone is the problem: the lending is built by the
/// deployment, which would then have to spell the runtime in a turbofish on a constructor whose
/// every other argument is inferred. A value is what makes the executor an ordinary constructor
/// argument, told apart from its neighbours by the type it carries.
///
/// A blanket `impl<S: AsyncSpawner> AsyncSpawn for S` would remove the wrapper and CLOSE the seam:
/// no downstream type could then implement this trait, because coherence cannot rule out that type
/// implementing `AsyncSpawner` later. The wrapper is what keeps the door open.
/// The `async(spawn)` word's shipped engine: the runtime the deployment already named.
///
/// It holds the spawner rather than only its type so that `Tasks::new(TokioSpawner)` infers `R` —
/// the constructor argument's whole reason, argued at [`AsyncSpawn`]. The value costs nothing: an
/// [`AsyncSpawner`](agnostic_lite::AsyncSpawner) is `Copy + Send + Sync + 'static` and every shipped
/// one is a unit struct.
;
// Hand-written so `R` need not be `Debug`. A runtime marker is somebody else's unit struct and
// `AsyncSpawner` asks nothing of it here, so a derive would put a bound on the LENDING's own `Debug`
// — the value this wraps is printed by parties that never spawn anything.
/// AT MOST ONE IN FLIGHT: the cell a detached SYNC clock claims per tick.
///
/// The default posture of `spawn` and `rayon`, and the `concurrent` word is what turns it off. The
/// asymmetry with `async(spawn)` is the ruling's, and it is about what a pile-up COSTS: a task that
/// waits is cheap and a runtime multiplexes them, while a thread that waits is a stack — so an
/// unbounded pile of blocking ticks is the failure mode a default has to stand against.
///
/// # A skip is not a loss and it SPEAKS
///
/// A tick that finds the cell claimed is a tick whose predecessor is still working, and the next
/// interval asks the same question again — which is the same coalescing posture
/// [`Ticker`](super::Ticker)'s own cell spells about the inbox. The seat answers
/// [`Swept::Lapped`](super::Swept) and the resident says
/// [`Observation::Lapped`](super::Observation) at INFO: configured behaviour working, not an alarm.
///
/// # The cell is freed by DROP
///
/// [`InFlight`] is a guard the work owns, so a body that panicked, unwound or was cancelled leaves
/// the cell as it found it. A cell nobody freed is a clock that never ticks again, which is exactly
/// the shape [`Tick`](super::Ticked)'s own `Drop` exists to prevent one layer over.
;
/// One claim on an [`AtMostOne`], released when it drops.
///
/// It carries no method: the whole of what it is for is being alive, and the work it travels with is
/// what keeps it so.
;