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
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 core::{future::Future, time::Duration};

use smol_bytes::Utf8Bytes;

use super::{
  NodeName,
  lifecycle::{Failure, Lifecycle, LifecycleTap as _, Taps},
  observe::{self, TracingLevel},
  serve::{AsyncServes, Responding, Serves},
};

/// 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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[non_exhaustive]
pub enum QueryError {
  /// Nothing is listening at the far end of a QUERY door — the query node is not running, or was
  /// never started.
  #[display("the query node is not listening: nothing holds the other end of this door")]
  Unreachable,
  /// Nothing is listening at the far end of a SOURCE's control line — the origin has died, or was
  /// never started.
  ///
  /// The forwarding door's own arm. It is separate from [`Unreachable`](Self::Unreachable) because
  /// the two ask a client for different things: a query that could not run produced NO effect, and
  /// a change that could not be forwarded has ALREADY been made by the handler that answered — so
  /// the second one is a state to reconcile rather than an attempt to repeat.
  ///
  /// # THE ARM IS KEPT, and the reason is that the vocabulary was NAMED before it was built
  ///
  /// Adding an arm to a `#[non_exhaustive]` sum is a widening, and the alternative — pointing
  /// [`Unreachable`](Self::Unreachable) at the forwarding door's word — was close enough to be
  /// worth writing down. Three things decided it:
  ///
  /// - the communication layer's own record names `UNREACHABLE_SOURCE` as the transport's word for
  ///   this door, so the vocabulary was settled before the code existed to raise it;
  /// - [`Unreachable`](Self::Unreachable)'s sentence says *the query node is not listening*, which
  ///   is a lie at the mutation door and would have had to be rewritten into something vaguer to
  ///   serve both;
  /// - and the two facts ask for genuinely different actions, which is
  ///   [`ErrorCode`](crate::ErrorCode)'s own criterion for whether two refusals share a word.
  ///
  /// The cost is that three of the four codes below are minted for arms the mutation door cannot
  /// raise. That is not waste: [`ToErrorCode`](crate::ToErrorCode) must be total over a type that
  /// now reaches the wire, and [`Invokes`](crate::Invokes) and the awaiting door are public roads an
  /// application resolver can spend.
  #[display("the source is not listening: nothing holds the other end of its control line")]
  UnreachableSource,
  /// The reply oneshot was dropped without an answer.
  ///
  /// The honest reading of every failure along the chain: a node that could not answer drops the
  /// reply, and the node that failed says WHY through its own [`LifecycleTap`](super::LifecycleTap)
  /// — where the error keeps its type, which a caller-side rendering could never have.
  #[display("the query was dropped without an answer")]
  Dropped,
  /// The caller's own deadline elapsed first. The query may still be running.
  #[display("the query did not answer within its deadline")]
  TimedOut,
}

impl core::error::Error for QueryError {}

/// 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.
impl crate::ToErrorCode for QueryError {
  fn error_code(&self) -> crate::ErrorCode {
    match self {
      Self::Unreachable => crate::ErrorCode::UnreachableNode,
      Self::UnreachableSource => crate::ErrorCode::UnreachableSource,
      Self::Dropped => crate::ErrorCode::RequestDropped,
      Self::TimedOut => crate::ErrorCode::RequestTimedOut,
    }
  }
}

/// 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`].
#[derive(Debug)]
pub struct Reply<R> {
  tx: flume::Sender<R>,
}

impl<R> Reply<R> {
  /// Answer the query with `result`.
  ///
  /// `false` when the caller has already stopped waiting. That is not an error to handle: a caller
  /// that dropped its [`Awaiting`] has withdrawn the question, and a transient edge keeps nothing
  /// to re-deliver.
  #[inline]
  pub fn answer(self, result: R) -> bool {
    self.tx.send(result).is_ok()
  }

  /// Whether anybody is still waiting for this answer.
  ///
  /// A LOOK and never a gate: a node is free to answer a query nobody wants, and the answer is
  /// simply dropped. It exists for an arm that would rather not spend a model forward pass on one.
  #[inline]
  #[must_use]
  pub fn is_awaited(&self) -> bool {
    !self.tx.is_disconnected()
  }
}

/// The receiving half, kept by whoever asked.
#[derive(Debug)]
pub struct Awaiting<R> {
  rx: flume::Receiver<R>,
}

impl<R> Awaiting<R> {
  /// Wait for the answer — the THREAD engine's door.
  ///
  /// # Errors
  ///
  /// [`QueryError::Dropped`] when the chain dropped the reply instead of answering it.
  #[inline]
  pub fn take(self) -> Result<R, QueryError> {
    self.rx.recv().map_err(|_| QueryError::Dropped)
  }

  /// Wait at most `deadline` — the door a resolver with a budget takes.
  ///
  /// The thread half only, for [`Inbox::park`](super::Inbox)'s reason: there is nothing
  /// runtime-neutral to time an await with, and this crate names no async runtime. An async caller
  /// times out with its own runtime's combinator around [`take_async`](Self::take_async).
  ///
  /// # Errors
  ///
  /// [`QueryError::Dropped`] as above, and [`QueryError::TimedOut`] when `deadline` elapses first —
  /// which says nothing about the query, since the chain may still be working on it.
  #[inline]
  pub fn take_within(self, deadline: Duration) -> Result<R, QueryError> {
    self.rx.recv_timeout(deadline).map_err(|error| match error {
      flume::RecvTimeoutError::Timeout => QueryError::TimedOut,
      flume::RecvTimeoutError::Disconnected => QueryError::Dropped,
    })
  }

  /// Wait for the answer — the ASYNC engine's door.
  ///
  /// # Errors
  ///
  /// [`QueryError::Dropped`], as [`take`](Self::take).
  #[inline]
  pub async fn take_async(self) -> Result<R, QueryError> {
    self.rx.recv_async().await.map_err(|_| QueryError::Dropped)
  }
}

/// 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.
#[inline]
#[must_use]
pub fn reply<R>() -> (Reply<R>, Awaiting<R>) {
  let (tx, rx) = flume::bounded(1);
  (Reply { tx }, Awaiting { rx })
}

/// 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.
#[derive(Debug)]
pub struct Invoke<T, R> {
  input: T,
  reply: Reply<R>,
}

impl<T, R> Invoke<T, R> {
  /// The invocation `input`, answered on `reply`.
  #[inline]
  pub const fn new(input: T, reply: Reply<R>) -> Self {
    Self { input, reply }
  }

  /// What this hop was asked.
  #[inline]
  pub const fn input(&self) -> &T {
    &self.input
  }

  /// Split into the input and the reply — what an arm does before answering, since the reply
  /// travels on where the input does not.
  #[inline]
  pub fn into_parts(self) -> (T, Reply<R>) {
    (self.input, self.reply)
  }
}

/// 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.
#[derive(Debug)]
pub struct Door<T, R> {
  tx: flume::Sender<Invoke<T, R>>,
}

impl<T, R> Door<T, R> {
  /// Ask `input`, and hand back what the answer will arrive on — the THREAD engine's door.
  ///
  /// # Errors
  ///
  /// [`QueryError::Unreachable`] when the query node is not listening.
  #[inline]
  pub fn invoke(&self, input: T) -> Result<Awaiting<R>, QueryError> {
    let (reply, awaiting) = reply();
    self
      .tx
      .send(Invoke::new(input, reply))
      .map(|()| awaiting)
      .map_err(|_| QueryError::Unreachable)
  }

  /// [`invoke`](Self::invoke), awaiting room.
  ///
  /// # Errors
  ///
  /// [`QueryError::Unreachable`], as above.
  #[inline]
  pub async fn invoke_async(&self, input: T) -> Result<Awaiting<R>, QueryError> {
    let (reply, awaiting) = reply();
    self
      .tx
      .send_async(Invoke::new(input, reply))
      .await
      .map(|()| awaiting)
      .map_err(|_| QueryError::Unreachable)
  }

  /// Pass `invoke` on with the reply it already carries — one hop of a chain.
  ///
  /// `Err` gives the invocation back, and the honest thing to do with it is to DROP it: the reply
  /// goes with it, so the caller learns [`QueryError::Dropped`] rather than waiting on a chain that
  /// no longer exists.
  #[inline]
  pub fn forward(&self, invoke: Invoke<T, R>) -> Result<(), Invoke<T, R>> {
    self.tx.send(invoke).map_err(|e| e.0)
  }

  /// [`forward`](Self::forward), awaiting room.
  #[inline]
  pub async fn forward_async(&self, invoke: Invoke<T, R>) -> Result<(), Invoke<T, R>>
  where
    T: Send,
    R: Send,
  {
    self.tx.send_async(invoke).await.map_err(|e| e.0)
  }

  /// Whether the query node has hung up.
  #[inline]
  #[must_use]
  pub fn is_closed(&self) -> bool {
    self.tx.is_disconnected()
  }
}

// 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.
impl<T, R> Clone for Door<T, R> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      tx: self.tx.clone(),
    }
  }
}

/// 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.
#[derive(Debug)]
pub struct Invokes<T, R> {
  rx: flume::Receiver<Invoke<T, R>>,
}

impl<T, R> Invokes<T, R> {
  /// Park until a query arrives — the THREAD engine's door.
  ///
  /// `None` is shutdown: every door is gone, so nothing can arrive again.
  #[inline]
  pub fn park(&self) -> Option<Invoke<T, R>> {
    self.rx.recv().ok()
  }

  /// Park until a query arrives — the ASYNC engine's door. `None` is shutdown, as above.
  #[inline]
  pub async fn park_async(&self) -> Option<Invoke<T, R>> {
    self.rx.recv_async().await.ok()
  }

  /// How many queries are queued.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.rx.len()
  }

  /// Whether none is.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.rx.is_empty()
  }

  /// Whether every door is gone.
  #[inline]
  #[must_use]
  pub fn is_disconnected(&self) -> bool {
    self.rx.is_disconnected()
  }
}

/// A transient edge of `capacity` queries.
///
/// Zero is legal and means a rendezvous: the caller waits until the query node takes it.
#[inline]
#[must_use]
pub fn door<T, R>(capacity: usize) -> (Door<T, R>, Invokes<T, R>) {
  let (tx, rx) = flume::bounded(capacity);
  (Door { tx }, Invokes { rx })
}

/// 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.
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no BLOCKING `on_invoke`",
  label = "this face is not the one this responder wears",
  note = "a responder implements exactly ONE of `Answers` (the blocking face) and `AsyncAnswers` \
          (the awaited one), and the arm's verb is what selects: `QueryArm::run` drives this face \
          and `QueryArm::run_async` drives the other",
  note = "either give the body an `Answers` impl, or run the arm through `run_async`"
)]
pub trait Answers<In> {
  /// What this hop produces: the NEXT hop's input, or the chain's answer where this hop is the last.
  type Output;

  /// This responder's per-query failure.
  ///
  /// Bound-free here, per [`Operator::Error`](crate::Operator::Error)'s discipline: the arm bounds
  /// it at its own call site, where the erasure a tap needs is paid for.
  type Error;

  /// Answer one query, on THIS thread.
  ///
  /// It keeps the BARE name that [`AsyncAnswers::on_invoke`] also carries, for
  /// [`Lands::land`](crate::Lands::land)'s measured reason: a body that imports one face calls
  /// `on_invoke` with no ceremony, and a type wearing BOTH is `E0034` naming the two candidates and
  /// offering the disambiguating spelling.
  fn on_invoke(&mut self, input: In) -> Result<Self::Output, Self::Error>;
}

/// [`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.
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no AWAITED `on_invoke`",
  label = "this face is not the one this responder wears",
  note = "a responder implements exactly ONE of `AsyncAnswers` (the awaited face) and `Answers` \
          (the blocking one), and the arm's verb is what selects: `QueryArm::run_async` drives this \
          face and `QueryArm::run` drives the other",
  note = "either give the body an `AsyncAnswers` impl, or run the arm through `run`"
)]
pub trait AsyncAnswers<In> {
  /// What this hop produces: the NEXT hop's input, or the chain's answer where this hop is the last.
  type Output;

  /// This responder's per-query failure. Bound-free, per [`Answers::Error`]'s discipline.
  type Error;

  /// [`Answers::on_invoke`], answering a future the arm awaits.
  fn on_invoke(
    &mut self,
    input: In,
  ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send;
}

/// 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.
pub trait Onward<Out, R> {
  /// Hand `out` on, carrying `reply`. `false` when the destination is gone — a caller that stopped
  /// waiting, or a next hop that hung up.
  fn pass(&self, out: Out, reply: Reply<R>) -> bool;

  /// [`pass`](Self::pass), awaiting room where the destination is a door.
  fn pass_async(&self, out: Out, reply: Reply<R>) -> impl Future<Output = bool> + Send;
}

/// The TERMINAL arm: this hop's output is the answer, so it goes back on the reply.
impl<R> Onward<R, R> for ()
where
  R: Send,
{
  #[inline]
  fn pass(&self, out: R, reply: Reply<R>) -> bool {
    reply.answer(out)
  }

  #[inline]
  async fn pass_async(&self, out: R, reply: Reply<R>) -> bool {
    reply.answer(out)
  }
}

/// A FORWARDING arm: this hop's output is the next hop's input, and the reply travels with it.
impl<Out, R> Onward<Out, R> for Door<Out, R>
where
  Out: Send,
  R: Send,
{
  #[inline]
  fn pass(&self, out: Out, reply: Reply<R>) -> bool {
    // A refused forward DROPS the invocation, reply and all — see `forward`. The caller learns
    // `Dropped`, which is the honest answer: the chain it was travelling no longer exists.
    self.forward(Invoke::new(out, reply)).is_ok()
  }

  #[inline]
  async fn pass_async(&self, out: Out, reply: Reply<R>) -> bool {
    self.forward_async(Invoke::new(out, reply)).await.is_ok()
  }
}

/// What one run of a query arm did.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Served {
  invokes: usize,
  passed: usize,
  abandoned: usize,
  failed: usize,
}

impl Served {
  /// Queries taken off the transient inbox.
  #[inline]
  #[must_use]
  pub const fn invokes(&self) -> usize {
    self.invokes
  }

  /// Answers handed on — replied to the caller at a terminal arm, forwarded at a hop.
  #[inline]
  #[must_use]
  pub const fn passed(&self) -> usize {
    self.passed
  }

  /// Answers that reached nobody, the destination having gone. A withdrawn question rather than a
  /// failure: nothing is held and nothing is retried.
  #[inline]
  #[must_use]
  pub const fn abandoned(&self) -> usize {
    self.abandoned
  }

  /// Queries whose responder returned `Err`. Each dropped its reply, so each reached its caller as
  /// [`QueryError::Dropped`].
  #[inline]
  #[must_use]
  pub const fn failed(&self) -> usize {
    self.failed
  }
}

/// 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.
#[derive(Debug)]
pub struct QueryArm<Q, In, R, D = ()> {
  name: Utf8Bytes,
  responder: Q,
  invokes: Invokes<In, R>,
  onward: D,
  taps: Taps,
  // The level this arm's door span opens at — the node's own `tracing(level = …)` word. Held in
  // every build, for the reason `Resident`'s copy is: the level is what a declaration said, and a
  // field that came and went with a feature would put a `#[cfg]` in both engines' loops.
  tracing: TracingLevel,
}

impl<Q, In, R> QueryArm<Responding<Q>, In, R> {
  /// An arm for `responder`, reading `invokes`, ANSWERING its caller directly.
  ///
  /// The terminal shape, which is the ordinary one: most chains are one hop, and the last hop of
  /// every chain is this.
  ///
  /// The responder is SEATED under the seam on the way in — [`Responding`] is what the arm actually
  /// holds — so a node's author writes [`Answers`] and names nothing else while the arm's own half
  /// stays generic over [`Serves`]. Take a lane that already serves through
  /// [`serving`](QueryArm::serving) instead.
  #[must_use]
  pub fn new(name: impl Into<Utf8Bytes>, responder: Q, invokes: Invokes<In, R>) -> Self {
    Self::serving(name, Responding::new(responder), invokes)
  }
}

impl<Q, In, R> QueryArm<Q, In, R> {
  /// An arm for `server` — a lane that already implements [`Serves`].
  ///
  /// [`new`](QueryArm::new)'s twin for the OTHER kind of answering half: the shipped
  /// [`SlotLane`](super::SlotLane), and whatever a third party wrapped it in. It is the same arm and
  /// the same loop — what differs is only that the seam is reached without a node behind it.
  #[must_use]
  pub fn serving(name: impl Into<Utf8Bytes>, server: Q, invokes: Invokes<In, R>) -> Self {
    Self {
      name: name.into(),
      responder: server,
      invokes,
      onward: (),
      taps: Taps::new(),
      tracing: TracingLevel::Info,
    }
  }
}

impl<Q, In, R, D> QueryArm<Q, In, R, D> {
  /// Pass this arm's answers on through `door` instead of replying — the MIDDLE of a chain.
  #[must_use]
  pub fn forwarding_to<X>(self, door: X) -> QueryArm<Q, In, R, X> {
    QueryArm {
      name: self.name,
      responder: self.responder,
      invokes: self.invokes,
      onward: door,
      taps: self.taps,
      tracing: self.tracing,
    }
  }

  /// Observe through `taps`.
  #[inline]
  #[must_use]
  pub fn with_taps(mut self, taps: Taps) -> Self {
    self.set_taps(taps);
    self
  }

  /// [`with_taps`](Self::with_taps), in place.
  #[inline]
  pub fn set_taps(&mut self, taps: Taps) -> &mut Self {
    self.taps = taps;
    self
  }

  /// Open its door span at `level` — the node's own `tracing(level = …)` word.
  ///
  /// [`Resident::with_tracing_level`](super::Resident::with_tracing_level)'s twin, and it is spelled
  /// here rather than wired by the launch for one reason: an arm is built by whoever holds the
  /// responder, and the launch walk does not build one yet. When it does, this is the door it calls.
  #[inline]
  #[must_use]
  pub const fn with_tracing_level(mut self, level: TracingLevel) -> Self {
    self.tracing = level;
    self
  }

  /// The level its door span opens at.
  #[inline]
  #[must_use]
  pub const fn tracing_level(&self) -> TracingLevel {
    self.tracing
  }

  /// This node's name.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &NodeName {
    NodeName::new(&self.name)
  }

  /// The server this arm runs — a [`Responding`] wrapper where a responder was seated, the lane
  /// itself where one was handed over.
  #[inline]
  #[must_use]
  pub const fn responder(&self) -> &Q {
    &self.responder
  }

  /// The taps it observes through.
  #[inline]
  #[must_use]
  pub const fn taps(&self) -> &Taps {
    &self.taps
  }

  /// Where its answers go, or `()` where they go back to the caller.
  #[inline]
  #[must_use]
  pub const fn onward(&self) -> &D {
    &self.onward
  }

  /// How many queries are queued at this arm.
  #[inline]
  #[must_use]
  pub fn queued(&self) -> usize {
    self.invokes.len()
  }
}

/// # 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`.
impl<Q, In, R, D> QueryArm<Q, In, R, D> {
  /// Serve queries on THIS thread until every door is gone — the thread engine, over a BLOCKING
  /// server.
  ///
  /// It parks in a blocking receive with no timeout, which is the difference from a resident's park
  /// and the transient edge's own: there is no sweep to time, so an idle arm costs a reserved stack
  /// and nothing else.
  ///
  /// # The `block_on` this verb used to spend is GONE, and the bound is what deleted it
  ///
  /// While [`Serves`] was a single async face, the thread arm had to drive a future it had no
  /// runtime for — `block_on(self.responder.serve(input))` — to unwrap an answer that, for every
  /// server in this tree, was ready the moment it was made. The face pair makes that unnecessary
  /// rather than merely cheaper: this verb bounds the BLOCKING face, so the call IS the answer.
  /// [`run_async`](Self::run_async) bounds [`AsyncServes`](super::AsyncServes) and awaits, and the
  /// two cells are the whole matrix an arm has.
  ///
  /// A server that only awaits is therefore refused HERE, at the bound, naming the two roads —
  /// rather than silently block-on'd by an arm that chose on its behalf.
  pub fn run<A>(&mut self) -> Served
  where
    Q: Serves<In, A>,
    Q::Error: core::error::Error + Send + Sync + 'static,
    D: Onward<A, R>,
  {
    let mut report = Served::default();
    while let Some(invoke) = self.invokes.park() {
      report.invokes += 1;
      let (input, reply) = invoke.into_parts();
      // THE DOOR SPAN, over the serve alone — see `drive::observe::door` for why the handoff after
      // it is outside, and why both engines wrap the same call.
      let door = observe::door(self.tracing, self.name(), report.invokes);
      // CALLED, and that is this cell's whole difference from the async one: no future is minted,
      // so there is nothing to drive and no runtime to want.
      let answer = {
        let _entered = door.entered();
        // NO KNOBS FROM THE ARM, and that is where the seat's holder is rather than an omission: an
        // arm is handed questions off a channel and holds no options value of its own, so what a
        // question is served under travels with the question. A held options value is the TOWER
        // walk's, which hands each step its own field.
        self.responder.serve(input, None)
      };
      match answer {
        Ok(out) => self.landed(self.onward.pass(out, reply), &mut report),
        Err(error) => self.refused(error, reply, &mut report),
      }
    }
    report
  }

  /// [`run`](Self::run) as a task, over an AWAITED server — the async engine.
  ///
  /// The one difference is the park and the server's own await; there is no write to order
  /// against and no room to wait for beyond the next door's, so the two bodies are as close as the
  /// two engines get anywhere in this layer.
  pub async fn run_async<A>(&mut self) -> Served
  where
    Q: AsyncServes<In, A>,
    Q::Error: core::error::Error + Send + Sync + 'static,
    D: Onward<A, R>,
  {
    let mut report = Served::default();
    while let Some(invoke) = self.invokes.park_async().await {
      report.invokes += 1;
      let (input, reply) = invoke.into_parts();
      let door = observe::door(self.tracing, self.name(), report.invokes);
      match door.over(self.responder.serve(input, None)).await {
        Ok(out) => {
          let reached = self.onward.pass_async(out, reply).await;
          self.landed(reached, &mut report);
        }
        Err(error) => self.refused(error, reply, &mut report),
      }
    }
    report
  }

  /// Count a passed answer and OBSERVE it.
  ///
  /// The station is [`Processed`](super::Station::Processed) and never
  /// [`Persisted`](super::Station::Persisted), whatever the node's [`Effect`](super::Effect) says: a
  /// query READS, so this arm reached no durability and must not claim to have. That observation is
  /// also the honest content of the pure-leaf exemption a query-only node is granted — its work
  /// leaves a trace by construction, and this is the trace.
  fn landed(&self, reached: bool, report: &mut Served) {
    if reached {
      report.passed += 1;
    } else {
      report.abandoned += 1;
    }
    let observation = Lifecycle::<()>::Processed(()).erase();
    self.taps.observe(NodeName::new(&self.name), &observation);
  }

  /// A refused query: DROP the reply, and observe the failure where its type still exists.
  ///
  /// Dropping is the answer rather than a fallback. The chain's answer type is the caller's, so this
  /// arm has no way to spell a failure in it — and putting the error on the wire would mean erasing
  /// it to a string at exactly the layer that still knows what it is. So the caller learns
  /// [`QueryError::Dropped`], and the tap learns the error itself.
  ///
  /// Generic over the error rather than projecting the server's, because the server's projection
  /// needs `A` and this helper does not: what it does with the error is erase it into a
  /// [`Failure`], which asks for the bound and nothing else.
  fn refused<E>(&self, error: E, reply: Reply<R>, report: &mut Served)
  where
    E: core::error::Error + Send + Sync + 'static,
  {
    report.failed += 1;
    drop(reply);
    let observation = Lifecycle::<()>::Failed(Failure::new(error)).erase();
    self.taps.observe(NodeName::new(&self.name), &observation);
  }
}

#[cfg(test)]
mod tests;