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
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
//! What a channel edge moves, and what comes back on the oneshot paired with it.
//!
//! # The custody family
//!
//! [`Delivery`] carries a [`Custody`]: one [`AckSender`] off the wire, or — for a delivery the
//! intake assembled out of a keyed group — the [`Share`]s of the member deliveries that went into
//! it. A member's obligation is an [`Owing`], shared because one delivery's items can join several
//! groups and its token is still one. The protocol beneath is unchanged: every delivery is answered
//! exactly once, on its own token, releasing only keys its own sender minted.

use core::{any::Any, hash::Hash, time::Duration};

use std::{
  collections::{HashMap, HashSet},
  sync::{Arc, Mutex},
};

use smol_bytes::Utf8Bytes;

use crate::operator::Receipts;

use super::{
  ItemId, NodeName,
  fate::Fate,
  lifecycle::{Lifecycle, Observation},
  window::Owed,
};

/// **THE PER-ITEM RECEIPTS ONE ACK CARRIES** — absent unless a consumer actually stated one.
///
/// An `Option<Box<…>>` rather than a bare map, and the shape is what keeps the receipt free for
/// everyone who does not spend it. Two measurements decide it:
///
/// - a consumer that states nothing carries EIGHT BYTES here instead of a map header, and that is
///   every consumer written before this slot existed;
/// - [`Answer`] is returned BY VALUE from every poll of every outstanding delivery on every harvest
///   pass, so [`Settled`]'s width is a cost the idle path pays. An inline map put it over
///   `clippy::large_enum_variant`'s own threshold, which is that lint doing exactly its job.
///
/// The allocation happens where a receipt does, which is the one place it is worth anything.
///
/// # Why `ReceiptMap` and not `Receipts`
///
/// The plural is the DECLARATION's — [`Receipts`](crate::Receipts) is the trait a node states its
/// receipt type on, and two items of one crate cannot both hold that name. The tie is broken toward
/// the trait rather than toward this alias because the trait is the word an AUTHOR writes and this
/// is a shape the transport carries: what the alias names is a MAP, keyed by the item, so saying so
/// costs a reader nothing they did not already need to know.
pub type ReceiptMap<K> = Option<Box<HashMap<K, Box<dyn Any + Send + Sync>>>>;

/// The five halves of a [`Settled`], as [`into_parts`](Settled::into_parts) hands them over: the
/// released set, the worker's name, the observation, a fate's extra message, and the consumer's own
/// receipts.
pub type SettledParts<K> = (
  HashSet<K>,
  Utf8Bytes,
  Observation,
  Option<Box<dyn Any + Send + Sync>>,
  ReceiptMap<K>,
);

/// One item as the transport moves it: the key the ack window releases by, and the declared struct.
///
/// The key is BESIDE the value rather than inside it. That is the whole of what survives of the
/// envelope this layer's design removed — an edge moves the app's own type, an operator's `accept`
/// is handed exactly that type, and the transport's own identity never reaches the operator at all.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Item<T, K = ItemId> {
  key: K,
  value: T,
}

impl<T, K> Item<T, K> {
  /// The item `value`, released by `key`.
  #[inline]
  pub const fn new(key: K, value: T) -> Self {
    Self { key, value }
  }

  /// The key this item is released by.
  #[inline]
  pub const fn key(&self) -> &K {
    &self.key
  }

  /// The declared struct.
  #[inline]
  pub const fn value(&self) -> &T {
    &self.value
  }

  /// Split into the key and the value — what a drive loop does before it hands the item on.
  #[inline]
  pub fn into_parts(self) -> (K, T) {
    (self.key, self.value)
  }

  /// The declared struct alone, taken — the door an operator walking its delivery reaches for,
  /// since the transport's own key is the driver's business and never the operator's.
  #[inline]
  pub fn into_value(self) -> T {
    self.value
  }
}

/// What ONE delivery carries: a single item, or a batch of them.
///
/// The two are one enum rather than a `Vec` that happens to hold one, because the single case is
/// the common one and a `Vec` for it is an allocation per item on the hottest path there is. A
/// batch is what a source produces from one page of a pull, and its ack is per-item — 250 of 256
/// released and 6 held is an ordinary answer, not an error path.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Payload<T, K = ItemId> {
  /// Exactly one item.
  One(Item<T, K>),
  /// A page of items, in the order the sender produced them.
  Batch(Vec<Item<T, K>>),
}

impl<T, K> Payload<T, K> {
  /// How many items this delivery carries.
  #[inline]
  pub fn len(&self) -> usize {
    match self {
      Self::One(_) => 1,
      Self::Batch(items) => items.len(),
    }
  }

  /// Whether it carries none — possible only as an empty [`Batch`](Self::Batch).
  #[inline]
  pub fn is_empty(&self) -> bool {
    self.len() == 0
  }

  /// The keys this delivery's items are released by, in send order.
  #[inline]
  pub fn keys(&self) -> impl Iterator<Item = &K> {
    // Two iterator shapes behind one `impl Trait`, which is what the slice view buys: `One` is a
    // one-element slice of the item it holds, so neither arm needs an enum of iterators.
    match self {
      Self::One(item) => core::slice::from_ref(item),
      Self::Batch(items) => items.as_slice(),
    }
    .iter()
    .map(Item::key)
  }
}

impl<T, K> Payload<T, K> {
  /// The same items carrying `map`'s answer instead of their own value, keys untouched.
  ///
  /// What a fan-in intake spends on a STRAIGHT source: the message arrived as itself and the
  /// operator's input is the node's own sum, so the wrapping is a map and the transport's keys —
  /// which are the sender's, and what its window releases by — pass through unchanged. The shape is
  /// preserved too: a `One` stays a `One`, so the single case still allocates nothing.
  pub fn map<U>(self, mut map: impl FnMut(T) -> U) -> Payload<U, K> {
    match self {
      Self::One(item) => {
        let (key, value) = item.into_parts();
        Payload::One(Item::new(key, map(value)))
      }
      Self::Batch(items) => Payload::Batch(
        items
          .into_iter()
          .map(|item| {
            let (key, value) = item.into_parts();
            Item::new(key, map(value))
          })
          .collect(),
      ),
    }
  }
}

impl<T, K> IntoIterator for Payload<T, K> {
  type IntoIter = PayloadIter<T, K>;
  type Item = Item<T, K>;

  #[inline]
  fn into_iter(self) -> Self::IntoIter {
    match self {
      Self::One(item) => PayloadIter::One(Some(item)),
      Self::Batch(items) => PayloadIter::Batch(items.into_iter()),
    }
  }
}

/// [`Payload`]'s owning iterator. Two arms rather than one `Vec` walk, so the single case still
/// allocates nothing.
#[derive(Debug)]
pub enum PayloadIter<T, K = ItemId> {
  /// The single item, until it is taken.
  One(Option<Item<T, K>>),
  /// The batch's own walk.
  Batch(std::vec::IntoIter<Item<T, K>>),
}

impl<T, K> Iterator for PayloadIter<T, K> {
  type Item = Item<T, K>;

  #[inline]
  fn next(&mut self) -> Option<Self::Item> {
    match self {
      Self::One(item) => item.take(),
      Self::Batch(items) => items.next(),
    }
  }

  #[inline]
  fn size_hint(&self) -> (usize, Option<usize>) {
    match self {
      Self::One(item) => {
        let n = usize::from(item.is_some());
        (n, Some(n))
      }
      Self::Batch(items) => items.size_hint(),
    }
  }
}

impl<T, K> ExactSizeIterator for PayloadIter<T, K> {}

/// One delivery: the payload, and the oneshot its consumer answers on.
///
/// The pairing is the protocol. A consumer that answers releases the sender's window; a consumer
/// that DROPS the sender — because it died, or because it never answered — disconnects the oneshot,
/// which the sender reads as "held" and re-delivers from its durable position. There is no third
/// outcome, and that is what makes a lost ack cost latency rather than correctness.
///
/// # The message leads
///
/// `Delivery<T>` — the declared struct first, the transport's key defaulted to [`ItemId`] — because
/// this is the type [`Operator::accept`](crate::Operator::accept) names, and what an operator has
/// to spell there is the message it consumes. Every wired edge in this crate is keyed by [`ItemId`]
/// already ([`Wiring`](crate::Wiring) opens them all), so the parameter is a seam rather than a
/// choice a deployment makes.
///
/// # The custody token, and why it is an [`Option`]
///
/// The oneshot is this delivery's CUSTODY TOKEN: whoever holds it owes the answer. On the wire it
/// is always there — [`new`](Self::new) is what an [`Outbox`](super::Outbox) sender builds through.
/// The driver TAKES it when it opens the obligation, and the delivery it then walks item by item
/// carries none: the release protocol is the driver's, so the token is not in two places at once.
/// [`in_custody`](Self::in_custody) is that second shape, and its name is the answer to "who owes
/// the ack?".
///
/// # A JOINED delivery owes SEVERAL, and the wire never mints one
///
/// A keyed group's delivery is assembled by the intake out of messages that arrived on different
/// edges, so its answer is owed on each of their tokens. That is [`Custody`], and
/// [`joined`](Self::joined) is the constructor the intake builds one through. Nothing on the wire
/// makes one: an [`Outbox`](super::Outbox) hands over exactly one oneshot, so a member delivery is
/// always [`Custody::Sole`] and a composition never nests.
#[derive(Debug)]
pub struct Delivery<T, K = ItemId> {
  payload: Payload<T, K>,
  ack: Option<Custody<K>>,
}

impl<T, K> Delivery<T, K> {
  /// Pair `payload` with `ack` — the WIRE's constructor, and the only one that carries a token.
  #[inline]
  pub const fn new(payload: Payload<T, K>, ack: AckSender<K>) -> Self {
    Self {
      payload,
      ack: Some(Custody::sole(ack)),
    }
  }

  /// Pair `payload` with the composed `custody` a JOIN assembled — the intake's constructor.
  ///
  /// The counterpart of [`new`](Self::new) for the keyed group: the members arrived under their own
  /// tokens and the pair is processed as one input, so the delivery that carries it owes all of
  /// them one outcome. See [`Custody`] for how that outcome is fanned out.
  #[inline]
  pub const fn joined(payload: Payload<T, K>, custody: Custody<K>) -> Self {
    Self {
      payload,
      ack: Some(custody),
    }
  }

  /// `payload` alone, its answer owed by whoever already holds the token.
  ///
  /// What a driver hands an operator: the obligation was opened for the whole inbound delivery
  /// before the walk began, so the item's own delivery carries the message and not the promise.
  #[inline]
  pub const fn in_custody(payload: Payload<T, K>) -> Self {
    Self { payload, ack: None }
  }

  /// What this delivery carries.
  #[inline]
  pub const fn payload(&self) -> &Payload<T, K> {
    &self.payload
  }

  /// Walk the items this delivery carries, owned — what an operator's `accept` body spends.
  ///
  /// The custody token, where there was one, is DROPPED with the rest of the delivery, and dropping
  /// it unsent is the protocol's own second outcome: the sender reads a disconnected oneshot as
  /// held and re-delivers. An operator that means to answer takes the token through
  /// [`into_parts`](Self::into_parts) instead.
  #[inline]
  pub fn into_items(self) -> PayloadIter<T, K> {
    self.payload.into_iter()
  }

  /// The same delivery carrying `map`'s answer, CUSTODY AND KEYS INTACT.
  ///
  /// The straight source's whole runtime: a message from an independent flow is wrapped into the
  /// node's own input sum and passed through the moment it arrives, owing exactly what it owed
  /// before. Nothing waits, because an independent flow has nothing to wait for.
  #[inline]
  pub fn map<U>(self, map: impl FnMut(T) -> U) -> Delivery<U, K> {
    Delivery {
      payload: self.payload.map(map),
      ack: self.ack,
    }
  }

  /// Split into the payload and the token — what a consumer does before processing, since the
  /// answer is owed after the whole payload has been walked.
  ///
  /// `None` where the token is already somewhere else — see the type's own note.
  #[inline]
  pub fn into_parts(self) -> (Payload<T, K>, Option<Custody<K>>) {
    (self.payload, self.ack)
  }
}

/// A consumer's answer to one delivery: WHICH items it released, WHO did the work, and where it
/// says they got to.
///
/// The three fields carry different weight, and the difference is the protocol's:
///
/// - `released` is LOAD-BEARING. It is the set of keys the sender may now forget — persisted or
///   intentionally skipped — and the window clears exactly it, item by item. A positive set errs
///   toward holding: what is not named stays outstanding, so a consumer that reports nothing costs
///   a re-delivery and never a loss.
/// - `worker` is the node whose work this answer DESCRIBES, and it is the consumer's own name. It
///   travels with the answer because nothing downstream of here could reconstruct it: a sender
///   harvesting its window holds an observation its own name has nothing to do with, and a run
///   record keyed `(root, node)` keyed by the sender would name the wrong node for every row.
/// - `lifecycle` is OBSERVATIONAL. It is the station this answer reached and the consumer's own
///   detail, and nothing in the window reads it. It exists to be TAPPED.
///
/// A failure therefore holds the window by construction rather than by a rule: a consumer that
/// failed names the failed keys nowhere in `released`, and there is no way to spell an answer that
/// reports [`Failed`](Lifecycle::Failed) and releases the item it failed on in the same breath.
///
/// `I` takes no bound here — see [`Lifecycle`] for where the bound arrives and why it arrives
/// exactly there.
///
/// # The RECEIPT rides beside the three, and it is PER ITEM
///
/// A consumer may answer with a VALUE as well as with a station — the durable id a seat minted or
/// found, which its producer then stamps onto everything descended from that item. That is
/// [`receipting`](Self::receipting), and three facts about it are the design rather than the mechanics:
///
/// - it is keyed by the ITEM, exactly as `released` is, because the grain of everything else in this
///   answer is the item: one delivery carries a page, one ack answers the page, and a receipt that had
///   to be one per DELIVERY would make a batch arbitrate between its items' answers.
/// - it is EMPTY by construction — [`new`](Self::new) and [`holding`](Self::holding) build no map
///   entry and a `HashMap::new` allocates nothing — so a consumer that never receipts pays for this
///   slot exactly what it paid before it existed.
/// - it ERASES at the wire and is read back typed, which is [`Settled`]'s own law: the framework
///   never names an app's type, and one edge's consumers each name their own.
#[derive(Debug)]
pub struct Ack<K, I> {
  released: HashSet<K>,
  worker: Utf8Bytes,
  lifecycle: Lifecycle<I>,
  receipts: ReceiptMap<K>,
}

impl<K, I> Ack<K, I> {
  /// An answer from `worker` that releases NOTHING and states `lifecycle` — the shape a failure
  /// takes.
  #[inline]
  pub fn holding(worker: impl Into<Utf8Bytes>, lifecycle: Lifecycle<I>) -> Self {
    Self {
      released: HashSet::new(),
      worker: worker.into(),
      lifecycle,
      receipts: None,
    }
  }

  /// An answer from `worker` releasing `released` and stating `lifecycle`.
  #[inline]
  pub fn new(released: HashSet<K>, worker: impl Into<Utf8Bytes>, lifecycle: Lifecycle<I>) -> Self {
    Self {
      released,
      worker: worker.into(),
      lifecycle,
      receipts: None,
    }
  }

  /// The keys the sender may forget.
  #[inline]
  pub const fn released(&self) -> &HashSet<K> {
    &self.released
  }

  /// The node that did the work this answer describes.
  #[inline]
  pub fn worker(&self) -> &NodeName {
    NodeName::new(&self.worker)
  }

  /// The station this answer reached, and the consumer's own detail.
  #[inline]
  pub const fn lifecycle(&self) -> &Lifecycle<I> {
    &self.lifecycle
  }

  /// Release `key` too.
  #[inline]
  #[must_use]
  pub fn releasing(mut self, key: K) -> Self
  where
    K: Eq + Hash,
  {
    self.released.insert(key);
    self
  }

  /// Answer the item keyed `key` with `receipt` as well — the durable value its producer is waiting
  /// for.
  ///
  /// [`releasing`](Self::releasing)'s shape one fact over, and the two compose: an answer that
  /// releases an item AND says what the item became is the ordinary landing case, written as
  /// `Ack::new(…).releasing(key).receipting(key, id)`.
  ///
  /// Receipting does NOT release. The two are independent on purpose — a consumer that computed an
  /// answer but could not make it durable states the receipt and holds the key, and the sender
  /// re-delivers exactly as it would have — so nothing here can make a held item look settled.
  ///
  /// A second receipt for one key REPLACES the first, which is the map's own behaviour and the honest
  /// one: an answer is stated once per item, and the last word a consumer says about an item before
  /// it settles is what it means.
  #[inline]
  #[must_use]
  pub fn receipting<R>(mut self, key: K, receipt: R) -> Self
  where
    K: Eq + Hash,
    R: Any + Send + Sync,
  {
    self
      .receipts
      .get_or_insert_with(Box::default)
      .insert(key, Box::new(receipt));
    self
  }

  /// [`receipting`](Self::receipting) AT THE TYPE THE MESSAGE DECLARED — the transport's door with
  /// teeth.
  ///
  /// [`Emitter::receipt_of`](crate::Emitter::receipt_of)'s twin one layer down, and it is here
  /// rather than only there because the BUFFERED face is not the only consumer that answers: a
  /// [`StreamOperator`](crate::StreamOperator) body is handed its delivery's custody and builds this
  /// answer itself, so a door only `Emitter` had would have left the streamed half of the framework
  /// with no way to be checked at all.
  ///
  /// `ack.receipting_of::<SceneOpen>(key, id)` names the MESSAGE this key is an item of; the type is
  /// `<SceneOpen as Receipts>::Receipt` and a value of any other type is `E0308` at the argument. An
  /// [`Ack<K>`](Ack) is keyed and carries no message type of its own, so the turbofish stays here —
  /// [`Acked::receipt`](crate::Acked::receipt) is the door where it does not.
  #[inline]
  #[must_use]
  pub fn receipting_of<M>(self, key: K, receipt: M::Receipt) -> Self
  where
    K: Eq + Hash,
    M: Receipts,
    M::Receipt: Any + Send + Sync,
  {
    self.receipting(key, receipt)
  }

  /// The receipt stated for `key`, as `R` — `None` where none was stated, and `None` where `R` is not
  /// the type the consumer stated.
  #[inline]
  pub fn receipt<R: Any>(&self, key: &K) -> Option<&R>
  where
    K: Eq + Hash,
  {
    self
      .receipts
      .as_ref()?
      .get(key)
      .and_then(|receipt| receipt.downcast_ref())
  }

  /// The receipts this answer carries, ALREADY BOXED — what an obligation that collected them per
  /// item hands over in one move.
  ///
  /// `pub(crate)`: the public door is [`receipting`](Self::receipting), which is where the boxing and the
  /// bound are written down. This one exists so [`Owed::receipt`](super::Owed::receipt) does not box a
  /// second time on the settle path.
  #[inline]
  #[must_use]
  pub(crate) fn carrying(mut self, receipts: ReceiptMap<K>) -> Self {
    self.receipts = receipts;
    self
  }
}

/// An [`Ack`] AS THE TRANSPORT CARRIES IT: the released set verbatim, the worker's name, and the
/// lifecycle erased.
///
/// The erasure happens here rather than at the tap, and it is what makes fan-out expressible at
/// all. One edge may reach several consumers and each names its OWN info type; a transport typed in
/// that type could hold one of them. So the oneshot's message drops the parameter and the
/// [`Observation`] keeps the content — the same split [`SkipReason::Custom`](crate::SkipReason)
/// makes for the same reason, with the typing at the ends and the erasure in the middle.
///
/// The worker's name does NOT erase, and it is the one thing here that is neither the window's nor
/// the tap's: it is the answer's own attribution, and it crosses because the far end has no way to
/// compute it.
///
/// # The fate's extra message rides BESIDE the observation
///
/// A [`Fate`] answered on this oneshot states its terminal through the same [`Observation`] a tap is
/// shown, and carries whatever the party that ended the delivery had to add in a slot of its own.
/// It is not folded into the observation because the arms a tap already had are not widened for it,
/// and a terminal that reached the tap stream with a payload the arm could not name would be the
/// second wording this design exists to refuse. It erases exactly as
/// [`Arrival`](super::Arrival)'s info does, for the same reason: one sender's window is harvested by
/// code that knows nothing about the type, and the typing belongs at the ends.
///
/// # The CONSUMER'S RECEIPT rides in a slot of its own, for the same reason
///
/// A consumer that answered with a value as well as with a station — see [`Ack::receipting`] — carries
/// it here, keyed by the item it is about. It is a THIRD slot rather than a widened observation for
/// the reason the fate's message is a second one: the arms a tap already had are not widened for it,
/// and a tap has no business reading an answer addressed to one sender. It is also not folded into
/// the fate's slot, because the two are filled by opposite parties on opposite paths — a fate is the
/// answer of a party that ENDED the delivery before any consumer saw it, and a receipt is the answer
/// of the consumer that ran — and one slot serving both would make "which happened?" a downcast
/// rather than a read.
#[derive(Debug)]
pub struct Settled<K> {
  released: HashSet<K>,
  worker: Utf8Bytes,
  observation: Observation,
  message: Option<Box<dyn Any + Send + Sync>>,
  receipts: ReceiptMap<K>,
}

impl<K> Settled<K> {
  /// The keys the sender may forget.
  #[inline]
  pub const fn released(&self) -> &HashSet<K> {
    &self.released
  }

  /// The node that did the work this answer describes — the CONSUMER, never the sender reading it.
  #[inline]
  pub fn worker(&self) -> &NodeName {
    NodeName::new(&self.worker)
  }

  /// What a tap is shown.
  #[inline]
  pub const fn observation(&self) -> &Observation {
    &self.observation
  }

  /// A [`Fate`]'s extra message, as `M` — `None` on an ordinary arrival, and `None` where `M` is not
  /// the type the answering party sent.
  #[inline]
  pub fn message<M: Any>(&self) -> Option<&M> {
    self
      .message
      .as_ref()
      .and_then(|message| message.downcast_ref())
  }

  /// [`receipt`](Self::receipt) AT THE TYPE THE MESSAGE DECLARED — the whole-answer door with
  /// teeth.
  ///
  /// [`Acked::receipt`](crate::Acked::receipt)'s read for a sender that takes the whole [`Settled`]
  /// rather than waiting on the value alone: same read, same box, and the type taken off the
  /// MESSAGE's own `Receipts` impl instead of a turbofish this caller invented.
  ///
  /// The turbofish stays because a [`Settled<K>`](Settled) is keyed and speaks for a whole
  /// delivery — its keys may be items of several messages, so there is no ONE message type for it to
  /// carry. The producer's own door has exactly one and therefore needs no name at all.
  ///
  /// # Errors
  ///
  /// [`receipt`](Self::receipt)'s, unchanged.
  #[inline]
  pub fn receipt_of<M>(&self, key: &K) -> Result<&M::Receipt, Unreceipted>
  where
    K: Eq + Hash,
    M: Receipts,
    M::Receipt: Any,
  {
    self.receipt::<M::Receipt>(key)
  }

  /// The consumer's RECEIPT for the item keyed `key`, as `R`.
  ///
  /// # Errors
  ///
  /// [`Unreceipted::Silent`] where the consumer answered and stated nothing for this item, and
  /// [`Unreceipted::Mismatched`] where it stated a receipt of another type. The two are separated
  /// because they are different mistakes: the first is a consumer that does not receipt at all, and
  /// the second is two ends of one edge disagreeing about the receipt's type.
  ///
  /// A borrow rather than a value, for [`message`](Self::message)'s reason: the answer is read where
  /// it lands and nothing here knows whether `R` can be cloned. [`take_receipt`](Self::take_receipt) is
  /// the owning door.
  #[inline]
  pub fn receipt<R: Any>(&self, key: &K) -> Result<&R, Unreceipted>
  where
    K: Eq + Hash,
  {
    let receipt = self
      .receipts
      .as_ref()
      .and_then(|receipts| receipts.get(key))
      .ok_or(Unreceipted::Silent)?;
    receipt.downcast_ref().ok_or(Unreceipted::Mismatched)
  }

  /// The consumer's receipt for `key`, TAKEN — the owning half of [`receipt`](Self::receipt).
  ///
  /// What a producer awaiting one delivery's answer spends: the value is what it asked for and the
  /// rest of the answer is the window's, so the receipt is moved out rather than borrowed out of a
  /// value the caller is about to drop.
  ///
  /// # Errors
  ///
  /// [`receipt`](Self::receipt)'s, unchanged. A [`Mismatched`](Unreceipted::Mismatched) receipt is left
  /// where it was — the box is put back — so a caller that guessed the type wrong can guess again.
  pub fn take_receipt<R: Any>(&mut self, key: &K) -> Result<R, Unreceipted>
  where
    K: Eq + Hash,
  {
    let Some(receipts) = self.receipts.as_mut() else {
      return Err(Unreceipted::Silent);
    };
    // `remove_entry` and not `remove`, so putting a mismatched receipt back costs no `K: Clone`: the
    // owned key comes out with it and goes back in with it.
    let Some((key, receipt)) = receipts.remove_entry(key) else {
      return Err(Unreceipted::Silent);
    };
    match receipt.downcast::<R>() {
      Ok(receipt) => Ok(*receipt),
      Err(receipt) => {
        receipts.insert(key, receipt);
        Err(Unreceipted::Mismatched)
      }
    }
  }

  /// Whether this answer carries a receipt for `key` at all, WHATEVER its type — the read that tells
  /// [`Silent`](Unreceipted::Silent) from [`Mismatched`](Unreceipted::Mismatched) without naming a type.
  #[inline]
  #[must_use]
  pub fn has_receipt(&self, key: &K) -> bool
  where
    K: Eq + Hash,
  {
    self
      .receipts
      .as_ref()
      .is_some_and(|receipts| receipts.contains_key(key))
  }

  /// Split into the five halves — the window takes the first, a journal the second and third, the
  /// fourth is the fate's own extra where there was one, and the fifth is the consumer's receipts.
  #[inline]
  pub fn into_parts(self) -> SettledParts<K> {
    (
      self.released,
      self.worker,
      self.observation,
      self.message,
      self.receipts,
    )
  }
}

/// WHY A RECEIPT DID NOT COME BACK — the acked give's refusal roster, and every arm is a different
/// mistake.
///
/// Two of the four are about the ANSWER never arriving and two are about the answer arriving without
/// the receipt, which is the division a caller acts on: the first pair may be worth waiting longer or
/// re-delivering for, and the second pair is a wiring fact that more waiting cannot change.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
pub enum Unreceipted {
  /// The consumer dropped the token without answering — it wound down, it died, or it is a consumer
  /// that never answers at all.
  ///
  /// The protocol's own second outcome read at this door: the delivery stays HELD and its sender
  /// re-delivers, so an acked give that ends here has lost latency and never the item.
  #[display("the consumer hung up without answering")]
  HungUp,
  /// The wait's own budget elapsed first. The consumer may still be working, and the answer may
  /// still arrive — at a token this caller no longer holds.
  #[display("the consumer did not answer within the deadline")]
  TimedOut,
  /// The consumer ANSWERED and stated no receipt for this item.
  ///
  /// The refusal for the misuse the ruling names: an acked give on an edge whose consumer never
  /// receipts. It is stated rather than silent, and it is not a hang — the ack arrived, and what it
  /// did not carry is the value.
  #[display("the consumer answered and stated no receipt for this item")]
  Silent,
  /// The consumer stated a receipt of ANOTHER type — the two ends of one edge disagree about what the
  /// answer is.
  #[display("the consumer's receipt is not of the type this caller asked for")]
  Mismatched,
}

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

impl From<Unsettled> for Unreceipted {
  /// The two ways the ANSWER itself never came, widened into the four-arm roster.
  #[inline]
  fn from(unsettled: Unsettled) -> Self {
    match unsettled {
      Unsettled::HungUp => Self::HungUp,
      Unsettled::TimedOut => Self::TimedOut,
    }
  }
}

/// WHY A DELIVERY'S ANSWER NEVER CAME — the two terminal outcomes of a wait on one ack.
///
/// [`Answer`]'s two non-settled readings with the non-terminal one removed: a caller that WAITS has
/// nothing to do with [`Waiting`](Answer::Waiting), because waiting is what it is doing. It is a
/// type of its own rather than [`Unreceipted`] narrowed, for that vocabulary's own reason — the arms a
/// door can raise are the arms its type has.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
pub enum Unsettled {
  /// The consumer dropped the token without answering. [`Unreceipted::HungUp`]'s fact.
  #[display("the consumer hung up without answering")]
  HungUp,
  /// The wait's own budget elapsed first. [`Unreceipted::TimedOut`]'s fact.
  #[display("the consumer did not answer within the deadline")]
  TimedOut,
}

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

/// WHO owes a delivery's answer: one token, or the tokens a JOIN composed.
///
/// # The composed arm, and what it is for
///
/// A keyed group's delivery is assembled by the intake out of messages that arrived on DIFFERENT
/// edges, each under its own oneshot. Nothing about the ack protocol changes beneath: every member
/// delivery is still answered exactly once, on its own token, with its own keys. What this type
/// adds is the bookkeeping that lets ONE outcome reach all of them — the pair is processed as a
/// single input, so its members share one fate, and this is where that fate is fanned out.
///
/// # The keys are per SHARE, and that is load-bearing
///
/// Item ids are minted per SENDER, so two members can carry the same [`ItemId`]
/// meaning two different items. A composed answer that broadcast one released set to every token
/// would release, at each sender, whichever item happened to wear that number — a silent skip. So a
/// [`Share`] carries the member's OWN key beside the obligation it belongs to, and nothing is ever
/// released under a key its sender did not mint.
///
/// # It never nests
///
/// A member delivery arrives off the wire, and the wire's own constructor mints
/// [`Sole`](Self::Sole) — see [`Delivery::new`]. So the obligation a [`Share`]
/// points at is always a one-token one, and settling a composed custody takes each member's lock
/// exactly once with nothing behind it.
#[derive(Debug)]
pub enum Custody<K> {
  /// One token, answering for every key the delivery carries — the wire's own shape.
  Sole(AckSender<K>),
  /// The tokens a JOIN composed: the joined item's own key, and one [`Share`] per member message
  /// that went into it.
  ///
  /// A joined delivery carries exactly ONE joined item in v1 — the intake hands a pair over the
  /// moment it completes — so `key` is that item's, and whether it was released is the whole of
  /// what the members are told.
  Joined {
    /// The joined item's key, as the intake minted it.
    key: K,
    /// One per member message, in arrival order.
    shares: Vec<Share<K>>,
  },
}

impl<K> Custody<K> {
  /// One token — what an ordinary wire delivery carries.
  #[inline]
  #[must_use]
  pub const fn sole(ack: AckSender<K>) -> Self {
    Self::Sole(ack)
  }

  /// The `shares` a join composed, for the joined item released by `key`.
  #[inline]
  #[must_use]
  pub const fn joined(key: K, shares: Vec<Share<K>>) -> Self {
    Self::Joined { key, shares }
  }

  /// Answer this delivery — the composed counterpart of [`AckSender::send`], and what an
  /// obligation settles through.
  ///
  /// `true` where at least one sender was still listening. `I: Clone` is the JOINED arm's: one
  /// outcome is stated to every member's token, and the sole arm clones nothing.
  pub fn send<I>(self, answer: Ack<K, I>) -> bool
  where
    K: Eq + Hash,
    I: core::any::Any + Clone + Send + Sync,
  {
    match self {
      Self::Sole(ack) => ack.send(answer),
      Self::Joined { key, shares } => {
        let Ack {
          released,
          worker,
          lifecycle,
          // DROPPED, and it is the joined shape's own honesty rather than an omission: this answer
          // is owed to SEVERAL senders on several tokens, its keys are the JOINED item's and not any
          // member's, and one boxed value cannot be split between them. A member's own receipt is the
          // one its `Owed` collected, which is what `settle` below sends — see `Owed::receipt`.
          receipts: _,
        } = answer;
        let took = released.contains(&key);
        let mut answered = false;
        for share in shares {
          let Share { owing, member } = share;
          let mut owed = owing.0.lock().unwrap_or_else(|held| held.into_inner());
          if took {
            owed.release(member);
          } else {
            owed.withhold(&member);
          }
          // Only the member delivery whose LAST undecided item this was may answer: a batch of
          // three frames joins three different groups, and two of them completing says nothing
          // about the third. The one that finishes it states the pass it finished on.
          if owed.is_complete() {
            answered |= owed.settle(worker.clone(), lifecycle.clone());
          }
        }
        answered
      }
    }
  }

  /// Answer this delivery with a TERMINAL FATE — it was shed, given up on, or its budget elapsed,
  /// and it will never reach a consumer at all.
  ///
  /// # The window is CREDITED, and that is the whole point
  ///
  /// `released` is the delivery's own keys and not a subset: the items are gone, so holding them
  /// would stall the sender's watermark on work that is never coming back — which is exactly what a
  /// dropped token does today, and what it looks like from the far end is a consumer that hung up.
  /// A fate says WHICH ending it was instead, on the same oneshot, in the same breath as the credit.
  ///
  /// `true` where at least one sender was still listening. `M: Clone` is the JOINED arm's, for
  /// [`send`](Self::send)'s reason: one ending is stated to every member's token, and the sole arm
  /// clones nothing.
  pub fn fate<M>(self, released: HashSet<K>, worker: impl Into<Utf8Bytes>, fate: Fate<M>) -> bool
  where
    K: Eq + Hash,
    M: Any + Clone + Send + Sync,
  {
    let worker = worker.into();
    match self {
      Self::Sole(ack) => ack.fate(released, worker, fate),
      // The joined item's own key is not consulted, and the difference from `send` is the fate
      // itself: an answer states which of a group's items the consumer took, while an ending took
      // none of them. So every member is credited rather than tested — see the note on the released
      // set above.
      Self::Joined { shares, .. } => {
        let mut answered = false;
        for share in shares {
          let Share { owing, member } = share;
          let mut owed = owing.0.lock().unwrap_or_else(|held| held.into_inner());
          owed.release(member);
          // Only the member delivery whose LAST undecided item this was may answer, exactly as an
          // ordinary answer's fan-out does: a batch of three frames joins three different groups,
          // and one group ending says nothing about the other two.
          if owed.is_complete() {
            answered |= owed.settle_fate(worker.clone(), fate.clone());
          }
        }
        answered
      }
    }
  }
}

/// A member delivery's obligation, SHARED by every group its items joined.
///
/// One per delivery and not one per item, because the token is one per delivery: a batch of three
/// frames whose keys join three different groups is three [`Share`]s of THIS, and it is answered
/// when the last of the three has been decided. Until then it stays open, which is exactly the
/// promise a half-arrived pair makes — the sender's window keeps the items outstanding and its own
/// lag sweep is what re-pulls a flow that stopped.
///
/// Dropping it unanswered is the protocol's other legal outcome: the oneshot disconnects, the
/// sender reads that as held, and the items come back.
#[derive(Debug)]
pub struct Owing<K>(Arc<Mutex<Owed<K>>>);

impl<K> Owing<K> {
  /// Open an obligation for `keys`, answerable on `ack`.
  #[must_use]
  pub fn open(keys: impl IntoIterator<Item = K>, ack: Option<Custody<K>>) -> Self
  where
    K: Eq + Hash,
  {
    Self(Arc::new(Mutex::new(Owed::open(keys, ack))))
  }

  /// This obligation's share for the item keyed `member` — what a joined delivery's custody carries.
  #[inline]
  #[must_use]
  pub fn share(&self, member: K) -> Share<K> {
    Share {
      owing: Self(Arc::clone(&self.0)),
      member,
    }
  }

  /// How many of its items are still undecided.
  #[must_use]
  pub fn held(&self) -> usize {
    self
      .0
      .lock()
      .unwrap_or_else(|held| held.into_inner())
      .held()
  }

  /// Whether its answer has already gone.
  #[must_use]
  pub fn is_settled(&self) -> bool {
    self
      .0
      .lock()
      .unwrap_or_else(|held| held.into_inner())
      .is_settled()
  }
}

/// ONE member item's share of its delivery's obligation.
///
/// Two facts, and neither is enough alone: WHICH obligation — a delivery may have items in several
/// groups — and WHICH of its keys this share speaks for, since a released set is only ever read by
/// the sender that minted the keys in it.
#[derive(Debug)]
pub struct Share<K> {
  owing: Owing<K>,
  member: K,
}

/// The sending half of one delivery's oneshot.
///
/// [`send`](Self::send) takes `self` BY VALUE, which is what makes it a oneshot rather than a
/// channel that happens to be used once: a second answer to one delivery is not a thing that can be
/// written. Dropping it unsent is the other legal outcome, and it is the one that holds the window.
#[derive(Debug)]
pub struct AckSender<K> {
  tx: flume::Sender<Settled<K>>,
}

impl<K> AckSender<K> {
  /// Answer this delivery, erasing the consumer's info at the boundary.
  ///
  /// `I`'s ONLY bound in this layer is here. A tap has to be able to ask for its own type back —
  /// acting on a rendered string is what this crate refuses elsewhere — so the info crosses as
  /// `Any`, which costs `'static + Send + Sync` and nothing else. Everything upstream of this call
  /// carries `I` unbounded.
  ///
  /// The result is `false` when the sender's receiver is already gone. That is not an error to
  /// handle: a sender that stopped waiting is one that has already treated the delivery as held.
  #[inline]
  pub fn send<I>(self, ack: Ack<K, I>) -> bool
  where
    I: core::any::Any + Send + Sync,
  {
    let settled = Settled {
      released: ack.released,
      worker: ack.worker,
      observation: ack.lifecycle.erase(),
      message: None,
      receipts: ack.receipts,
    };
    self.tx.send(settled).is_ok()
  }

  /// Answer this delivery with a TERMINAL FATE, releasing `released` and erasing the fate's extra
  /// message at the boundary.
  ///
  /// `M`'s only bound in this layer is here, exactly as `I`'s is on [`send`](Self::send) and for the
  /// same reason: the far end harvesting this answer knows nothing about the type, so the message
  /// crosses as `Any` and the typing lives at the ends. Everything upstream of this call carries `M`
  /// unbounded.
  ///
  /// The result is `false` when the sender's receiver is already gone — which for a fate means the
  /// ending had nobody left to tell, not that anything went wrong.
  #[inline]
  pub fn fate<M>(self, released: HashSet<K>, worker: impl Into<Utf8Bytes>, fate: Fate<M>) -> bool
  where
    M: Any + Send + Sync,
  {
    let (observation, message) = fate.erase();
    let settled = Settled {
      released,
      worker: worker.into(),
      observation,
      message: Some(Box::new(message)),
      // A fate is an ending NO CONSUMER SAW, so there is nobody to have stated a receipt: the slot is
      // empty here by construction rather than by omission, and a producer awaiting one reads the
      // ending through the observation instead.
      receipts: None,
    };
    self.tx.send(settled).is_ok()
  }
}

/// The receiving half, kept by the sender of the delivery until it is answered or hung up.
#[derive(Debug)]
pub struct AckReceiver<K> {
  rx: flume::Receiver<Settled<K>>,
}

impl<K> AckReceiver<K> {
  /// Take the answer if it has arrived.
  ///
  /// [`Answer::Waiting`] and [`Answer::HungUp`] are BOTH "still held" as far as the window is
  /// concerned; they differ in whether waiting longer can change it, which is what lets the window
  /// stop tracking a delivery nobody will ever answer.
  #[inline]
  pub fn take(&self) -> Answer<K> {
    match self.rx.try_recv() {
      Ok(settled) => Answer::Settled(settled),
      Err(flume::TryRecvError::Empty) => Answer::Waiting,
      Err(flume::TryRecvError::Disconnected) => Answer::HungUp,
    }
  }

  /// WAIT for the answer — the THREAD engine's door, and the one an acked give blocks on.
  ///
  /// [`take`](Self::take) is the poll a WINDOW spends: a sender harvesting hundreds of outstanding
  /// deliveries must not block on any one of them, so its door answers [`Waiting`](Answer::Waiting)
  /// and moves on. This is the opposite caller — one party, one delivery, and waiting for it IS the
  /// work — and the two doors are the same shape [`Inbox::park`](super::Inbox::park) and
  /// [`Inbox::drain`](super::Inbox::drain) already are.
  ///
  /// `self` BY VALUE, because a delivery is answered exactly once: after this there is nothing left
  /// to wait for, and a receiver kept past its answer is a receiver that can only hang up.
  ///
  /// # Errors
  ///
  /// [`Unsettled::HungUp`] where the consumer dropped the token instead of answering. That is the
  /// protocol's other legal outcome and not a fault: the delivery stays held, and a sender with a
  /// durable position re-delivers it.
  #[inline]
  pub fn settled(self) -> Result<Settled<K>, Unsettled> {
    self.rx.recv().map_err(|_| Unsettled::HungUp)
  }

  /// Wait at most `deadline` — the door a caller with a budget takes.
  ///
  /// The THREAD half only, for [`Awaiting::take_within`](super::Awaiting::take_within)'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
  /// [`settled_async`](Self::settled_async).
  ///
  /// # Errors
  ///
  /// [`settled`](Self::settled)'s, and [`Unsettled::TimedOut`] where `deadline` elapses first —
  /// which says nothing about the consumer, since it may still be working.
  #[inline]
  pub fn settled_within(self, deadline: Duration) -> Result<Settled<K>, Unsettled> {
    self.rx.recv_timeout(deadline).map_err(|error| match error {
      flume::RecvTimeoutError::Timeout => Unsettled::TimedOut,
      flume::RecvTimeoutError::Disconnected => Unsettled::HungUp,
    })
  }

  /// WAIT for the answer — the ASYNC engine's door.
  ///
  /// # Errors
  ///
  /// [`settled`](Self::settled)'s, unchanged.
  #[inline]
  pub async fn settled_async(self) -> Result<Settled<K>, Unsettled> {
    self.rx.recv_async().await.map_err(|_| Unsettled::HungUp)
  }
}

/// What a sender learns when it asks one outstanding delivery for its answer.
#[derive(Debug, derive_more::IsVariant)]
pub enum Answer<K> {
  /// The consumer answered.
  Settled(Settled<K>),
  /// No answer yet, and the consumer is still there.
  Waiting,
  /// The consumer dropped the oneshot without answering. Everything this delivery carried stays
  /// held, and the sender re-delivers it from its durable position.
  HungUp,
}

/// One delivery's oneshot.
///
/// A bounded channel of capacity one, which is the whole implementation: `flume` is already this
/// layer's transport, so a oneshot is a shape of it rather than a second dependency, and the
/// capacity is what makes a second send impossible even before the by-value `send` does.
#[inline]
#[must_use]
pub fn ack_channel<K>() -> (AckSender<K>, AckReceiver<K>) {
  let (tx, rx) = flume::bounded(1);
  (AckSender { tx }, AckReceiver { rx })
}

#[cfg(test)]
mod tests;