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
572
573
574
575
576
577
578
579
//! THE WALK BUDGET: the number a deployment gives one question, the clock that measures it, the
//! arithmetic two tiers compose through, and the one place it BITES.
//!
//! ```text
//! TowerDoor::<ClipText>::installed(|| ClipText { … })?
//! .with_budget(WalkBudget::new(clock, SearchBudget::new().with_walk(30.seconds())))
//! │ │ │
//! │ │ └── TIER TWO's number
//! │ └── the DEPLOYMENT's runtime, named once
//! ▼
//! walk_within(seat, asked, tower, ClipText::run(&mut steps, q, opts, asked)).await
//! │
//! ├── nothing named → the walk, awaited, with no wrapper at all
//! └── a number → the walk RACED against the clock → BudgetSpent
//! ```
//!
//! # WHY A CLOCK IS A SEAT AND NOT A DETAIL
//!
//! [`Awaiting::take_within`](crate::Awaiting::take_within) states the wall in as many words: *there
//! is nothing runtime-neutral to time an await with, and this crate names no async runtime*. That
//! sentence is true and it is not an excuse — a budget nothing measures is exactly the defect
//! [`tightened_budget`]'s own classification is about, one law over: **a bound the requester can
//! rewrite binds nothing**, and a bound the framework never checks binds less. So the timer arrives
//! the way every other runtime-shaped decision arrives in this crate — as a seam the DEPLOYMENT
//! fills, beside the number it is measuring. [`WalkClock`] is that seam and it is three lines to
//! implement over any runtime that can sleep.
//!
//! What the framework refuses to do is pick one. [`AsyncQueryExpander`](crate::AsyncQueryExpander)'s
//! missing reverse bridge is the same refusal written at another seat: *driving a future to
//! completion means choosing a runtime — a decision that belongs to the application and never to the
//! framework*.
//!
//! # A BLOCKING WALK HAS NO SEAT HERE, and the refusal is the COMPILER's
//!
//! [`DeclaredTower::ALL_SYNC`](crate::DeclaredTower::ALL_SYNC) is `true` for a tower whose every step
//! is served by a blocking face, and such a tower's
//! [`run`](crate::AssembledTower::run) is a future with no suspension point in it: the walk runs to
//! completion inside the first poll, so a timeout wrapped round it can never fire. Racing one anyway
//! would be a budget that binds nothing while LOOKING like one that binds — the worst of the three
//! outcomes. So [`TowerDoor::with_budget`](crate::TowerDoor::with_budget) reads the const and refuses
//! at the line the deployment wrote. A blocking tower that wants a wall puts one inside its own step,
//! where there is a thread to interrupt.
use ;
use Arc;
use SignedDuration;
/// **THE BUDGET A WIRE REQUEST RUNS UNDER: the ask, TIGHTENED by the deployment's** —
/// `min(request, deployment)`, with an absent side unbounded.
///
/// ```text
/// request: 5s, deployment: 30s → 5s the ask, well inside the wall
/// request: 300s, deployment: 30s → 30s the wall, and no request may raise it
/// request: 5s, deployment: none → 5s the author's informed openness
/// request: none, deployment: 30s → 30s the deployment's, standing alone
/// request: none, deployment: none → none as long as it takes — `NoDeadline`'s law
/// ```
///
/// # THE CLASSIFICATION: a budget is a PROTECTIVE number, so its wire arm may only TIGHTEN
///
/// The one-sentence law is stated at [`route_depth`](crate::route_depth): *protective numbers never
/// cross the wire; preference numbers do.* A budget sits just inside that line rather than outside
/// it — it crosses, but only downward. Tightening is a requester saying *I will not wait that long*,
/// which costs the deployment nothing and is the requester's own business; loosening is a requester
/// rewriting an upper bound on what one question may cost this deployment, and **a bound the
/// requester can rewrite binds nothing**. So the compose is `min` rather than *explicit beats
/// ambient*, and that is the CAPS-not-replaces precedent spent a second time, in time rather than in
/// hits.
///
/// # It is the OPPOSITE compose to [`Deadlines::resolve`](crate::Deadlines::resolve), and the
/// difference is WHO IS ASKING
///
/// [`Deadlines::resolve`](crate::Deadlines::resolve) answers a Rust CALL SITE: it is
/// explicit-beats-ambient, and its own note says *nothing here can shorten a caller's own patience*.
/// That is right for an in-process caller, which is inside the deployment and is trusted with its own
/// time. A WIRE requester is not inside it, and the same two numbers therefore compose the other way
/// round. The two rules are not a disagreement about deadlines; they are the trust boundary, written
/// as arithmetic at each side of it.
///
/// # An absent deployment budget is INFORMED OPENNESS, not a gap
///
/// [`route_depth`](crate::route_depth)'s own reading, and for its reason: a deployment that named no
/// budget is one whose operator decided there is none to name, and the framework does not invent one
/// on their behalf. [`NoDeadline`](crate::NoDeadline) is that answer as a policy, and this function
/// agrees with it.
///
/// # A NEGATIVE budget is a deadline already past, and it is kept rather than repaired
///
/// `min` lets it through unchanged, which is the honest arithmetic: *do not wait* is a sayable
/// request. What a negative one MEANS is settled where a budget is SPENT — see the zero clamp in
/// [`walk_within`], which is this road's one reading of it, and the policy gate's own for the thread
/// road.
///
/// # It is one function because it is one law
///
/// [`route_depth`](crate::route_depth)'s own posture. A tower's walk, a recipe's road and a door's
/// ambient budget all cap the same way, and a chain written out at each of them is a chain that can
/// drift at one of them.
///
/// # BOTH SIDES HAVE A CALLER NOW, and they arrive at the same one
///
/// [`walk_within`] is that caller. The DEPLOYMENT's number comes out of the [`WalkBudget`] a launch
/// installed on the tower's door; the REQUEST's comes off the `options` argument a dressed recipe
/// publishes, read through
/// [`AssembledTower::asked_budget`](crate::AssembledTower::asked_budget) — the projection that turns
/// an opaque `SearchOptions` package into the one row this law is about. The composed value is what
/// the walk is raced against, and it is composed HERE and nowhere else: the census that recorded
/// this function's zero non-test callers is answered by one call site rather than by a second
/// reading of the law.
/// **THE PROTECTIVE NUMBERS ONE SEARCH NAMES** — the framework's own budget package, spoken by BOTH
/// tiers that may name one.
///
/// ```
/// use ingraph::SearchBudget;
/// use jiff::SignedDuration;
///
/// // A deployment's wall, and a request that never mentioned the knob.
/// let deployment = SearchBudget::new().with_walk(SignedDuration::from_secs(30));
/// assert_eq!(deployment.walk(), Some(SignedDuration::from_secs(30)));
/// assert_eq!(SearchBudget::new().walk(), None);
/// ```
///
/// # It is the UNIVERSAL MINIMUM, which is why it is the FRAMEWORK's type and not a tower's
///
/// `<Tower>StepOptions` carries one row per STEP and its rows are the application's — a macro that mints
/// it cannot know which of them are `()`, and a `()` seat has no wire face — so the tower's own
/// options object never crosses. What every tower's future request face can carry is the set of knobs
/// the FRAMEWORK owns, keyed by words the emitter can read, and a budget is the first of them: it
/// means the same thing for every tower ever declared, because it is about the deployment's time
/// rather than about the search.
///
/// # ONE ROW, and it is NAMED for what it bounds
///
/// [`walk`](Self::walk) is *the whole walk must finish inside this*, and the name says WHICH span
/// rather than just *the budget*, because this type is the seat a second protective number joins. A
/// row called `budget` would have made the second one unnameable without renaming the first.
///
/// # DEFAULT-LESS, and that is the three-tier law rather than a missing constant
///
/// There is no `DEFAULT_WALK_BUDGET` and there will not be one. [`ArmWeights`](crate::ArmWeights)
/// has a shipped constant because a weight has a defensible middle; a budget does not — a deployment
/// that named none is one whose operator decided there is none to name, and a framework that invented
/// thirty seconds on their behalf would be capping searches nobody asked to cap. So absence resolves
/// to [`NoDeadline`](crate::NoDeadline)'s road at the end of the chain, and
/// [`tightened_budget`] never defaults on the way through.
///
/// # IT WEARS A WIRE FACE NOW, and the caller that asked for it is the REQUEST door
///
/// The house rule is that a crossing lands with the caller that needs it, and that caller has
/// arrived: an emitted `<Tower>SearchOptions` carries this type as its budget row, so a client names
/// `budget: { walk: "PT5S" }` and [`tightened_budget`] composes it against the deployment's. The face
/// is HAND-WRITTEN rather than derived, for the same reason every emitted package's is — a derive
/// belongs to the type's own declaration, which is written outside the binding gate.
///
/// The operand crosses as the `Duration` scalar this crate mints, which is what the row's landing
/// COST: async-graphql publishes no `SignedDuration` scalar of its own — its `jiff` feature carries
/// five and this is not one — so the carrier that had lived behind the `jiff` VOCABULARY feature now
/// exists wherever the BINDING does. One grammar, one scalar, one spelling, in every build that can
/// be asked a duration at all; see `graphql::filter::duration` for the two grammars it accepts.
///
/// **THE SERDE FACE IS STILL ABSENT**, and its reason is unchanged: nothing asks for one until a
/// deployment names its tier-two number in a config file rather than in Rust.
/// **THE REQUEST'S OWN BUDGET, AS A SCHEMA HOLDS IT** — one nullable row, so the whole object is
/// omissible and an object that names nothing is the request that named nothing.
///
/// Hand-written rather than derived, for the emitted packages' own measured reason: a derive belongs
/// to the type's declaration, which is written outside the binding gate, and a type that existed only
/// where the binding does would vanish from every build without it.
const _: = ;
/// **THE DEPLOYMENT'S OWN TIMER** — what turns a number into a wall.
///
/// A deployment on tokio writes `Box::pin(tokio::time::sleep(budget))` and is done; on smol,
/// `Box::pin(smol::Timer::after(budget))`. The whole seam is one line over whatever the application
/// already runs on, which is the point of it being a seam:
///
/// ```
/// use core::{future::Future, pin::Pin, time::Duration};
///
/// use ingraph::WalkClock;
///
/// /// A clock with no patience at all — every budget is already spent.
/// struct Spent;
///
/// impl WalkClock for Spent {
/// fn elapsed<'a>(&'a self, _budget: Duration) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>> {
/// Box::pin(core::future::ready(()))
/// }
/// }
/// ```
///
/// # It answers a BOXED future, exactly as [`AsyncQueryExpander`](crate::AsyncQueryExpander) does
///
/// The hook law's own shape: a clock is a VALUE a deployment chooses — possibly from configuration,
/// possibly not at all — so it arrives erased, behind a handle, and its future is boxed because a
/// dyn-compatible seat cannot name an opaque one.
///
/// `+ Send` on the future is part of the CONTRACT rather than something a caller hopes for, for the
/// reason every awaited seat in this crate states it: a resolver's own future must cross threads on
/// somebody's runtime, and a timer that could not would take the whole read's `Send`ness with it. The
/// WALK is asked for no such thing — see [`AssembledTower::run`](crate::AssembledTower::run), whose
/// missing bound is measured — so a `!Send` tower keeps its budget.
///
/// # `Send + Sync`, because a clock is SHARED
///
/// One handle is consulted from wherever a question enters, concurrently, so the seat states what
/// that requires instead of leaving each deployment to discover it. It is the same supertrait
/// [`TickPolicy`](crate::TickPolicy) and its three siblings carry.
///
/// # A clock that never fires is a budget that never bites, and that is the DEPLOYMENT's to get right
///
/// Nothing here can check it: a timer is a promise about the future and the framework has no second
/// clock to audit it with. What the framework does promise is that where the clock DOES fire first,
/// the walk is dropped and the refusal is named — see [`walk_within`].
/// **TIER TWO's SEAT**: the budget a launch named for one tower, and the clock that measures it.
///
/// # The two arrive TOGETHER, and that is what makes a toothless budget unspellable
///
/// A number with no clock is a wall nobody watches and a clock with no number has nothing to watch
/// for, so this type is the pair rather than two seats that could be filled one at a time. The
/// failure it forecloses is the quiet one: a deployment that wrote `with_walk(30.seconds())`,
/// forgot the timer, and reads *our searches never time out* months later with the configuration
/// looking correct.
///
/// # The CLOCK is per-DOOR, not per-schema, for [`TowerDoor`](crate::TowerDoor)'s own keying reason
///
/// One door per tower is the grain a recipe already names, and the budget is a fact about how long
/// THIS tower's walk may take. A schema-wide clock would have been one lookup fewer and one way for a
/// deployment to name a budget for a tower whose seat it never filled.
/// Written out because a handle carries no [`Debug`](fmt::Debug), exactly as
/// [`TowerDoor`](crate::TowerDoor)'s own is: what a reader wants from this line is the NUMBERS, and
/// the erased clock has no name to print.
/// **A WALK THAT DID NOT FINISH INSIDE ITS BUDGET** — the named refusal, and never an empty answer.
///
/// [`PageTokenRefusal`](crate::PageTokenRefusal)'s own posture at the walk's grain, and for its
/// reason: *an empty list would tell the same client that it had reached the end of its answer, which
/// is a different fact and leads to a different screen.* A search that ran out of time has no answer
/// at all, and a client told so can retry, narrow, or say what happened; a client handed zero hits
/// learns that the corpus holds nothing.
///
/// # It carries the TOWER and the NUMBER, which are the two facts an operator acts on
///
/// Which road ran long says where to look, and what it was given says whether the wall is the problem
/// or the walk is. Neither is recoverable from the other, and a sentence with one of them is a
/// sentence somebody has to go and correlate.
/// **THE ENFORCEMENT POINT** — one awaited walk, raced against the budget two tiers composed.
///
/// What an emitted search resolver wraps [`AssembledTower::run`](crate::AssembledTower::run) in, and
/// what a hand-written caller wraps its own walk in. `tower` is the name a refusal carries and
/// `request` is tier three's own number, read off the request's package through
/// [`AssembledTower::asked_budget`](crate::AssembledTower::asked_budget) and [`None`] where the
/// request named nothing.
///
/// # ABSENCE IS IDENTITY, and it is identity TWICE
///
/// A door with no [`WalkBudget`] and a pair that composed to [`None`] both take the same road: the
/// walk is awaited, with no clock consulted, no second future built and no race polled. A deployment
/// that named nothing meets not one instruction of this machinery, which is the property the whole
/// seat is measured against.
///
/// # THE WALK IS POLLED FIRST, and the tie goes to the ANSWER
///
/// An answer already computed is not thrown away because a timer became ready in the same wake. The
/// order is the whole of the tie-break and it is the honest one: the budget is a bound on WAITING,
/// and a walk that is ready has stopped waiting.
///
/// # AN EXPIRED BUDGET DROPS THE WALK, which is the only cancellation there is
///
/// The walk's future is dropped where the clock wins, so whatever it held is released at that point.
/// Nothing here can reach INSIDE a step — a backend already blocked on a socket keeps blocking until
/// its own read returns — so what this bounds is the resolver's patience rather than the engine's
/// work. That is the same honesty [`Awaiting::take_within`](crate::Awaiting::take_within) states:
/// an expiry *says nothing about the query, since the chain may still be working on it*.
///
/// # A NEGATIVE budget is ZERO here, which is the one place that reading belongs
///
/// [`tightened_budget`] carries a past deadline through unchanged because composing is not spending.
/// This is the spending, so this is where *do not wait* becomes a duration a clock can take: the
/// clamp is to [`Duration::ZERO`], and the walk still gets its first poll for the paragraph above.
///
/// # Errors
///
/// [`BudgetSpent`], where the clock completed before the walk did.
pub async