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
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
//! The TRANSIENT edge: the second edge kind, on the first edge's transport.
//!
//! A query travels DECLARED EDGES. It is not an RPC surface bolted onto the graph — the index node
//! a search reaches is a true FAN-IN, subscribing both to the indexing side's embeddings and to the
//! query side's — so what a query needs is not a second topology but a second EDGE KIND on the one
//! already here.
//!
//! # Same transport, different semantics
//!
//! | | durable edge ([`channel`](super::channel)) | TRANSIENT edge (this module) |
//! |---|---|---|
//! | transport | one bounded `flume` + a paired oneshot | the same two |
//! | the oneshot carries | an [`Ack`](super::Ack) — which keys the sender may forget | the RESULT |
//! | ack window | [`Outbound`](super::Outbound), watermarks, re-delivery | NONE |
//! | durable position | [`Positions`](super::Positions) | NONE |
//! | journal | `(root, node)` rows | NONE |
//! | a dropped oneshot means | held: the sender re-delivers | [`QueryError::Dropped`] at the caller |
//!
//! The row that matters most is the last: a durable edge is built so a lost answer costs LATENCY,
//! and a transient one is built so it costs the QUERY. A query nobody is waiting for any more is
//! work with no destination, and re-delivering it would be answering a question that was withdrawn.
//!
//! # Multi-hop, because the reply threads through
//!
//! `R` — what the caller is waiting for — is fixed for the whole chain, and only the INPUT type
//! changes per hop. So a node in the middle takes the [`Reply`] out of the invoke it received and
//! puts it in the invoke it sends, and the answer travels back to the original caller from however
//! deep the chain went. Nothing accumulates on the way: the lineage machinery a durable fan-out
//! needs has nothing to pay for here, because there is exactly one obligation and it is already
//! addressed to whoever asked.
//!
//! # A query node's inbox carries ONLY invokes
//!
//! [`Invokes`] is a channel of its own and never the node's data [`Inbox`](super::Inbox). That is
//! the whole mechanism behind the read-path law: an indexing batch cannot sit ahead of a query,
//! because the two are not in one queue. At a node that both indexes and answers, the query side is
//! a SECOND ARM — its own receiver, its own loop, its own reader value — which is what tantivy's
//! `Searcher`-beside-`IndexWriter` and lancedb's equivalent already give, and what the framework
//! must not take away.
//!
//! # WHICH HOPS COME HERE — the division, stated so this column is not read as an unspent road
//!
//! A search TOWER WALK does NOT travel this edge. A question resolves its own steps IN-PROCESS at
//! the search grain — inline, on the caller's stack, no channel in the walk at all — and that is
//! the road the search layer takes by default. A [`Reply`] between two steps of one question would
//! buy a hop, a copy and a second failure mode, and buy nothing back.
//!
//! What arrives here is a STEP OR HOP THAT ALREADY LIVES IN A GRAPH RESIDENT. The test is
//! residency, not what the step computes: a hop whose body is a plain function is a call; a hop
//! whose body is a node of this graph is reached over that node's declared edge, because a second
//! way to address one resident is a second thing to keep true.
//!
//! The case that makes the column load-bearing is QUERY-TIME COMPUTE OVER AN EXCLUSIVE MODEL. A
//! value that is `&mut`-only or `!Send` — an embedding model, a tokenizer holding a scratch arena,
//! a device context — is reachable only from the one resident that owns it. Where that same value
//! serves the INDEXING flow and the QUESTION flow both, the resident has two callers: the indexing
//! side arrives over a durable edge, the question side over this one, and the exclusive value is
//! still entered from exactly one place. The arm split above is what keeps the question from
//! queueing behind the batch.
//!
//! ENGINE-RESIDENT DATA does not come here and keeps the door-holds-slots road: a question needing
//! only rows out of a store goes through the branded slot door, which is shareable and concurrent,
//! and putting it behind a resident would add a queue in front of a reader that never needed one.
use ;
use Utf8Bytes;
use ;
/// Why a message this framework carried did not get where it was going.
///
/// # The family, and the two doors it now serves
///
/// It is the TRANSPORT's error contract, and every variant is a fact about the DOOR rather than
/// about the work: what an operator refused with is its own error and reaches a
/// [`LifecycleTap`](super::LifecycleTap), because only the arm that ran it can name its type.
///
/// It began as the query lane's alone, and the second door is the one the origin layer opened: a
/// declared exchange's handler answers, and the framework then hands the change to the source's
/// [`Control`](crate::Control) line — where the far end can be gone. That is
/// [`UnreachableSource`](Self::UnreachableSource), and it is a different fact from
/// [`Unreachable`](Self::Unreachable) rather than a second spelling of it: the party is different,
/// and so is what a client does about it.
///
/// # The wire codes have landed
///
/// This doc used to say *the wire code a resolver renders one of these as attaches when the wire
/// face lands*. It has: [`ToErrorCode`](crate::ToErrorCode) is implemented below, one word per arm,
/// so a resolver hands over the refusal it holds and the code goes with it. The type stays
/// `#[non_exhaustive]` so a later door adds to it rather than replacing it.
/// THE WIRE WORDS of the transport's own refusals — one per arm, because the four ask a client for
/// four different things.
///
/// [`PageError`](crate::PageError)'s reading of the derivation rule, applied one family over: a sum
/// whose arms want ONE fix answers with one word, and a sum whose arms want different fixes is worth
/// a word each. These do:
///
/// | arm | the client's own fix |
/// |---|---|
/// | [`Unreachable`](QueryError::Unreachable) | none: the node is not running, so tell whoever owns the deployment |
/// | [`UnreachableSource`](QueryError::UnreachableSource) | none: the change was MADE and not applied, so reconcile rather than repeat |
/// | [`Dropped`](QueryError::Dropped) | retry: something along the chain gave up without answering |
/// | [`TimedOut`](QueryError::TimedOut) | retry with a longer deadline, or poll — the work may still be running |
///
/// Written HERE rather than in a table beside the code vocabulary, which is
/// [`ToErrorCode`](crate::ToErrorCode)'s own law: the fact belongs to the type that has it, so an
/// arm added later cannot leave a mapping somewhere else out of date.
/// The sending half of ONE query's reply oneshot.
///
/// [`answer`](Self::answer) takes `self` BY VALUE, which is what makes it a oneshot rather than a
/// channel used once — [`AckSender`](super::AckSender)'s construction, for its reason. Dropping it
/// unanswered is the other legal outcome, and it is the one that reaches the caller as
/// [`QueryError::Dropped`].
/// The receiving half, kept by whoever asked.
/// One query's reply oneshot.
///
/// A bounded channel of capacity one, exactly as [`ack_channel`](super::ack_channel) is and for its
/// reason: `flume` is already this layer's transport, so a oneshot is a shape of it rather than a
/// second dependency.
/// ONE invocation as the transient edge moves it: the input, and the oneshot the RESULT threads
/// back on.
///
/// `T` is this hop's input and `R` is the whole chain's answer — see the module note for why only
/// the first of them changes from hop to hop.
/// The SENDING half of a transient edge — the INVOKE DOOR.
///
/// One shape serves both of its callers, which is the ruling's own point: a resolver outside the
/// graph holding a door is doing exactly what an upstream query node holding one does, so there is
/// no separate RPC surface to describe. [`invoke`](Self::invoke) is the door as an entry point —
/// mint a reply, send, hand back the receiver — and [`forward`](Self::forward) is the door as a
/// HOP, passing a reply that already exists.
///
/// BOUNDED and BLOCKING, as [`Outbox`](super::Outbox) is: a full door waits for room rather than
/// dropping, so a burst of queries becomes backpressure on whoever is issuing them.
// Hand-written so `T`/`R` need not be `Clone`: a door is a handle, and cloning one is what several
// resolvers reaching one query node IS.
/// The RECEIVING half — a query node's transient inbox.
///
/// It carries invokes and NOTHING else, which is the read-path law's mechanism rather than a
/// convention: there is no variant here for a delivery, a sweep or a tick, so an indexing batch has
/// no way to be queued in front of a query.
///
/// There is no sweep, and its absence is not an omission. A sweep exists to heal a stuck WATERMARK,
/// and a transient edge has none: an invocation that nobody answers ends at the caller, in one
/// [`QueryError`], with nothing left outstanding anywhere.
/// A transient edge of `capacity` queries.
///
/// Zero is legal and means a rendezvous: the caller waits until the query node takes it.
/// What a node does on its TRANSIENT arm — [`Operator`](crate::Operator)'s query-side twin.
///
/// A separate trait and a separate VALUE, and both halves of that are the read-path law. The
/// operator holds the write side (an `IndexWriter`, a staging buffer, a connection with a
/// transaction on it); the responder holds the read side (a `Searcher`, a snapshot, a pooled read
/// handle). They share whatever the engine gives them to share — a [`Shared`](crate::Shared)
/// resource, an engine handle — and they run at the same time, which is what every engine here
/// already supports and what the framework must not un-support.
///
/// # It emits ONE answer and cannot skip
///
/// [`Operator`](crate::Operator) buffers emissions through an [`Emitter`](crate::Emitter) because one
/// input may fan out to many; a query has exactly one destination, so the answer is the return
/// value. An intentional refusal has nowhere to be recorded either: a skip is a gap in a STREAM, and
/// a query that refuses simply answers — with an empty result, or with `Err`, which drops the reply
/// and reaches the caller as [`QueryError::Dropped`].
///
/// # TWO MODES, one per face, and this trait is the BLOCKING one
///
/// [`AsyncAnswers`] is the other, which is the framework's naming axis read at the query seam —
/// `Async*` is the asynchronous face, the BARE name is the blocking one, exactly as
/// [`Operator`](crate::Operator) / [`AsyncOperator`](crate::AsyncOperator) read one arm over and
/// [`Lands`](crate::Lands) / [`AsyncLands`](crate::AsyncLands) one layer down. An author implements
/// EXACTLY ONE, and the BOUND is what says which: [`QueryArm::run`] asks for this face and
/// [`QueryArm::run_async`] asks for the other.
///
/// The split is the same measurement that split the compute seam. `on_invoke` was an RPITIT that
/// every responder paid and a responder answering out of a held reader — a searcher, a snapshot, a
/// row map — never spent, so the thread engine's arm was buying a `block_on` per query to unwrap a
/// future that was ready on creation. On this face it does not: the arm CALLS the body and takes the
/// answer, minting nothing to poll.
///
/// The framework-internal exemption that lets [`Intake`](super::Intake) carry two verbs on one trait
/// does not reach here, and the criterion is why: an intake's implementor must serve BOTH engines at
/// once and cannot know which will drive it, where a responder's body is written one way and knows.
///
/// # `&mut self`
///
/// The arm owns its responder, so the exclusive borrow costs nothing and lets a reader hold mutable
/// state (a cursor cache, a scratch buffer).
///
/// # It is the ROLE; [`Serves`] is the SEAM under it
///
/// The arm does not call this trait — it calls [`Serves`], and a responder reaches it through the
/// [`Responding`] wrapper that seats it. So a node's author still writes exactly this and names
/// nothing else, while the arm's own half is generic over anything that answers: the shipped
/// engine-backed lane, and whatever a third party wraps it in. The seating is per FACE — this one
/// seats under [`Serves`] and [`AsyncAnswers`] seats under [`AsyncServes`](super::AsyncServes) — so
/// no responder reaches a face its body does not have.
/// [`Answers`]' ASYNCHRONOUS face — the same query role, for a responder that has an `.await` to
/// spend.
///
/// Everything [`Answers`] states holds here verbatim: the same one-answer-and-no-skip contract, the
/// same `&mut self`, the same bound-free error. THE ONLY DIFFERENCE IS THAT THE ANSWER IS A FUTURE.
///
/// # The future is `Send`
///
/// An arm may be a task on somebody's runtime, and [`QueryArm::run_async`] awaits this future inside
/// its own — so a responder whose future were not `Send` would take the arm's `Send`ness with it. It
/// is spelled as `impl Future + Send` rather than as `async fn` so the bound is part of the CONTRACT
/// instead of something each caller has to hope for.
/// Where an arm's answer GOES: on to the next hop, or back to the caller.
///
/// The absence of a next hop is spelled as a TYPE — `()` — which is
/// [`AsyncLands for ()`](super::AsyncLands)' construction one lane over, and it is what keeps the arm's loop
/// one body: a terminal arm and a forwarding one differ in this type and in nothing else.
///
/// The two impls cannot overlap, and the reason is the shape of the terminal case: answering the
/// caller is only possible when this hop's output IS the chain's answer, so `()` implements
/// `Onward<R, R>` alone.
/// The TERMINAL arm: this hop's output is the answer, so it goes back on the reply.
/// A FORWARDING arm: this hop's output is the next hop's input, and the reply travels with it.
/// What one run of a query arm did.
/// ONE node's TRANSIENT arm: a SERVER, a transient inbox, and where its answers go.
///
/// It is the second arm at a node that also indexes, and the WHOLE of a query-only node. Beside a
/// [`Resident`](super::Resident) rather than inside it, and the separation is the read-path law
/// made structural: two receivers, two loops, two values, so a query cannot queue behind a write
/// batch even in principle.
///
/// # `Q` is a [`Serves`] and not an [`Answers`]
///
/// The arm's answering half goes through the read lane's capability seam, so what it holds is
/// whatever serves: a node's [`Answers`] responder seated by [`new`](Self::new), the shipped
/// [`SlotLane`](super::SlotLane) taken by [`serving`](Self::serving), or a third party's cache,
/// telemetry or shadow-read lane wrapped around either. The arm cannot tell how deep the stack
/// under it goes, which is what lets a lane change what answering costs without the arm or the
/// engine changing at all.
///
/// # What it does NOT have, and why each absence is the edge kind
///
/// | absent | because |
/// |---|---|
/// | an ack window | the oneshot carries the RESULT; there is nothing to release |
/// | a durable position | a query is not replayed, so there is nothing to resume from |
/// | a journal | a `(root, node)` row certifies a completion, and a query completes at its caller |
/// | a write lane | a query READS; a node that writes does it on the other arm |
/// | a sweep | a sweep heals a stuck watermark, and there is none to stick |
///
/// # The onward destination is a TYPE
///
/// `D` is `()` for a terminal arm and a [`Door`] for a forwarding one, so
/// [`forwarding_to`](Self::forwarding_to) is what changes the type — [`Resident`](super::Resident)'s
/// own trade with its write lane, one arm over, and it means a caller never names the parameter and
/// inference never has to guess it.
/// # The bounds are on the METHODS, and `A` is what forced that
///
/// The arm's answering half goes through [`Serves<In, A>`](Serves), which carries the answer as a
/// PARAMETER where [`Answers`] carried it as an associated type — so `A` is named by neither the
/// struct nor the trait ref, and an impl block declaring it would be `E0207`. Putting the whole
/// clause on `run`/`run_async` keeps the loop ONE body, which is the property the
/// [`Onward`] type trade exists to buy, and a caller never spells `A`: `D` is concrete at the call
/// and each [`Onward`] impl determines it — `()` answers `A = R`, a [`Door<Out, R>`](Door) answers
/// `A = Out`.