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
//! ONE ROOT KEY'S OWN STATE, and the pure transitions that move it.
//!
//! Nothing in this file reads a clock, takes a lock, writes a row or spawns anything. A key's whole
//! life is [`RootState`], what may be asked of it is [`RootAction`], what one ask did is
//! [`RootAdvance`], and the durable acts a move EARNED are [`Retirement`] and [`Flip`] — handed to
//! sinks rather than performed, because performing them is the retirement ledger's and the
//! generations seat's business, and this file reads no clock and writes no row.
//!
//! # TWO ACTS, TWO SEATS, and they never wait on each other
//!
//! A [`Retirement`] says *this key is out*; a [`Flip`] says *this key's re-run closed, so point its
//! closure at the run that closed*. They are earned at different transitions, performed by different
//! parties against different tables, and a deployment may occupy either seat, both, or neither. The
//! one place they meet is the masking: a retirement taken over an open run DROPS that run, so a key
//! going out never flips a closure nobody may read.
//!
//! That posture is [`crate::batch`]'s, one module over and for its reason: `now` arrives as an
//! ARGUMENT (see [`Stamp`]), so a five-state machine with a thirty-second drain window is exercised
//! in microseconds by arithmetic on a value, and the party that owns the clock is the party that
//! owns the loop.
//!
//! # ABSENT IS `Idle`, and that is a saving rather than a convention
//!
//! A key nobody has said anything about is [`Idle`](RootState::Idle), and a key that reaches `Idle`
//! with nothing waiting behind it is DROPPED from the table it lived in. The two halves are one
//! decision: `Idle` is the state a registry has no information about, so storing it would be storing
//! the absence of news for every root key a deployment has ever seen. What the table therefore holds
//! is exactly the keys something is true of — analyzing, retiring, retired, restoring — and
//! [`Registry::state`](super::Registry::state) is total, answering `Idle` for a key it has never
//! heard of.
//!
//! # The QUEUE, and why a repeat is absorbed at the TAIL rather than anywhere
//!
//! Two states are MID-ACT: [`Retiring`](RootState::Retiring) is waiting for a count this registry
//! holds, and [`Restoring`](RootState::Restoring) is waiting for a write it does not. An action that
//! arrives at either does not apply and is not refused — it WAITS, in the order it was asked, and
//! the completion that ends the act drains it.
//!
//! A repeat of whatever is already at the BACK of that queue is absorbed. That is the whole of
//! *repeats coalesce*, and the width matters: a burst of three identical deletes is one act, which
//! is what coalescing is for, while `retire`, `restore`, `retire` keeps all three — dropping the
//! second `retire` as a duplicate of the first would answer the last thing anybody asked with its
//! opposite.
//!
//! # THE RETIRING WAIT IS BOUNDED, and the bound is a fact the retirement carries
//!
//! `Retiring` ends itself at zero, which is the path nearly every retirement takes. But a count
//! that never reaches zero is reachable — a consumer that hung up mid-chain, a body killed with
//! items out — and a state whose only exit may never be taken is a key stuck out of service
//! forever. So the wait has a ceiling: `retire_drain`
//! ([`RegistryOptions::retire_drain`](super::RegistryOptions::retire_drain)), spent by
//! [`Registry::lapse`](super::Registry::lapse), which offers the key
//! [`Lapsed`](RootAction::Lapsed).
//!
//! What the ceiling costs is stated rather than hidden: a key that lapses retires with `late_tails`
//! set, in the state AND in the durable act, and that flag is the sweep's whole instruction — work
//! for this key may land after the row was written, so what it wrote has to be found rather than
//! assumed absent.

use std::time::Instant;

use smol_bytes::Utf8Bytes;

use crate::{Timestamp, drive::generations::RunId};

#[cfg(test)]
mod tests;

/// The three readings a transition may need, taken as ONE argument.
///
/// Two clocks because the machine measures two different things and neither can stand in for the
/// other. An age — how long this key has been analyzing — is measured on the MONOTONIC clock, which
/// does not go backwards when somebody corrects the time. A retirement's `at` is written into a
/// durable row and read by a person, so it is WALL time.
///
/// The third reading is not a clock at all. A [`RunId`] is what a re-analysis is NUMBERED with, and
/// it rides here for the same reason the other two do: [`now`](Self::now) is the one impure door in
/// this module, so a number that has to be minted is minted there rather than inside a transition
/// that is otherwise a function of its arguments. A driver pass that opened an analysis for several
/// keys under one `Stamp` numbered them all with one run, which is the honest reading of what a pass
/// IS — one sweep of the feed, one generation of work — and costs nothing, a run being unique within
/// a root rather than globally (see [`RunId`]).
///
/// [`now`](Self::now) is the only impure thing in this module and it is a constructor rather than a
/// call inside a transition, which is what keeps every transition a function of its arguments: a
/// test builds a `Stamp` out of arithmetic, and a driver that already woke at an instant hands over
/// the one it woke at instead of reading the clock a second time.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Stamp {
  monotonic: Instant,
  wall: Timestamp,
  run: RunId,
}

impl Stamp {
  /// The three a caller already holding them states.
  #[inline]
  #[must_use]
  pub const fn new(monotonic: Instant, wall: Timestamp, run: RunId) -> Self {
    Self {
      monotonic,
      wall,
      run,
    }
  }

  /// Both clocks read and a run minted — the impure door, and the only one in this module.
  #[inline]
  #[must_use]
  pub fn now() -> Self {
    Self {
      monotonic: Instant::now(),
      wall: Timestamp::from(jiff::Timestamp::now()),
      run: RunId::mint(),
    }
  }

  /// The monotonic reading — what an age is measured from.
  #[inline]
  #[must_use]
  pub const fn monotonic(&self) -> Instant {
    self.monotonic
  }

  /// The wall reading — what a durable row is stamped with.
  #[inline]
  #[must_use]
  pub const fn wall(&self) -> Timestamp {
    self.wall
  }

  /// The run an analysis opened under this stamp is numbered with — see the type note.
  #[inline]
  #[must_use]
  pub const fn run(&self) -> RunId {
    self.run
  }
}

/// WHO retired a key, and the whole of what the answer decides.
///
/// It is not bookkeeping. A retiree whose content simply went away comes back on its own the moment
/// the content does — that is what a re-scan of a moved directory should mean — while a retiree a
/// PERSON stood down stays down until a person says otherwise, because a reappearance is exactly
/// what they were retiring it against.
///
/// # It is the LEDGER's own column, which is why the third arm is OPEN
///
/// This value is written into `__ig_retired_<family>` and read back at boot — see
/// [`RetiredRow`](crate::RetiredRow). The two the framework names are the two it can act on; every
/// other reason a deployment retires something is [`Other`](Self::Other), carrying that
/// deployment's own word verbatim so the row a person reads says *why* rather than *some other
/// reason*. The framework-open law, at a vocabulary where the closed half is exactly the half the
/// framework's own behaviour turns on.
///
/// Not [`Copy`], and the loss is the third arm's price: a word a deployment wrote is
/// [`Utf8Bytes`], which clones cheaply and copies not at all. Everything downstream of it —
/// [`RootState`], [`RootAction`], [`Retirement`] — takes the same trade for the same reason.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum RetireOrigin {
  /// The content is GONE from where it lived — a file deleted under the watcher, a directory
  /// unmounted. A key retired this way [`Reappear`](RootAction::Reappear)s back to life.
  Vanished,
  /// A PERSON stood it down. Nothing automatic ever brings it back — only
  /// [`Restore`](RootAction::Restore), which is a person saying so again.
  User,
  /// A reason of the DEPLOYMENT's own — a policy, a quota, a tenancy that ended — carried as the
  /// word that deployment wrote.
  ///
  /// It behaves as [`User`](Self::User) does at every fork this machine has, and that is derived
  /// rather than chosen: the one thing an origin decides is whether a reappearance brings the key
  /// back, and the framework cannot know that a reason it has never seen is content-driven. The
  /// safe answer to *should this resurrect itself?* for an unknown reason is **no** — see
  /// [`restores_itself`](Self::restores_itself).
  Other(Utf8Bytes),
}

impl RetireOrigin {
  /// The word [`Vanished`](Self::Vanished) is written with, in a row and on a wire.
  pub const VANISHED: &'static str = "vanished";

  /// The word [`User`](Self::User) is written with, in a row and on a wire.
  pub const USER: &'static str = "user";

  /// **WHETHER A REAPPEARANCE BRINGS THIS KEY BACK** — the one thing an origin decides, and
  /// therefore the one predicate the rest of this type is written over.
  ///
  /// True for [`Vanished`](Self::Vanished) alone. A key a person stood down is one a reappearance
  /// is exactly what they were retiring it against, and a key retired for a reason this framework
  /// has never seen is one it cannot claim to know that about — so both stay down until somebody
  /// says otherwise.
  #[inline]
  #[must_use]
  pub const fn restores_itself(&self) -> bool {
    matches!(self, Self::Vanished)
  }

  /// Whether a retirement on `self`'s say-so REPLACES one already under way on `other`'s.
  ///
  /// The rank is not a preference — it falls straight out of
  /// [`restores_itself`](Self::restores_itself). A person standing a key down while a
  /// vanish-retirement is still draining must not end with a key that resurrects itself on the next
  /// re-scan, which is precisely what keeping the `Vanished` origin would leave behind. So an origin
  /// that does NOT resurrect outranks one that does, and no other pair moves: two origins that both
  /// stay down disagree about nothing this machine acts on, and the first one asked is kept.
  #[inline]
  #[must_use]
  pub const fn outranks(&self, other: &Self) -> bool {
    !self.restores_itself() && other.restores_itself()
  }

  /// The word this origin is written with — [`VANISHED`](Self::VANISHED), [`USER`](Self::USER), or
  /// the deployment's own.
  ///
  /// It is what the ledger's `origin` column HOLDS, which is why it is one string rather than a
  /// discriminant and a payload: a row a person opens says `vanished` or says the word that
  /// deployment wrote, and nothing has to be joined to read it.
  #[inline]
  #[must_use]
  pub fn as_str(&self) -> &str {
    match self {
      Self::Vanished => Self::VANISHED,
      Self::User => Self::USER,
      Self::Other(word) => word.as_str(),
    }
  }
}

/// The inverse of [`RetireOrigin::as_str`] — TOTAL, which is what a column read back has to be.
///
/// The two shipped words resolve to their arms and everything else is [`Other`](RetireOrigin::Other)
/// verbatim, so a row this deployment did not write is still a row it can read. There is no refusal
/// to make: an origin's whole vocabulary is open past the two arms the framework acts on.
impl<T> From<T> for RetireOrigin
where
  T: Into<Utf8Bytes>,
{
  fn from(word: T) -> Self {
    let word = word.into();
    match word.as_str() {
      Self::VANISHED => Self::Vanished,
      Self::USER => Self::User,
      _ => Self::Other(word),
    }
  }
}

impl core::fmt::Display for RetireOrigin {
  #[inline]
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.write_str(self.as_str())
  }
}

/// ONE ROOT KEY'S STATE.
///
/// Five, and the two in the middle are the ones that mean *an act is under way*: see the module
/// note for what waits behind them and what ends them.
///
/// [`Clone`] rather than [`Copy`], because [`Retired`](Self::Retired) carries a [`RetireOrigin`]
/// and an origin may carry a deployment's own word — see that type's own note for the trade.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RootState {
  /// Nothing is true of this key — and so nothing is stored for it. See the module note.
  Idle,
  /// Work for this key is OUT: `inflight` items have been dispatched and not yet answered, and the
  /// key has been analyzing since `since`.
  ///
  /// `inflight` reaching zero is what ends it, which is why the ack discipline is a correctness
  /// requirement on the counting side rather than a nicety.
  Analyzing {
    /// Dispatched and not yet answered.
    inflight: u32,
    /// When this key last left [`Idle`](Self::Idle) — a MONOTONIC reading, so an age computed off
    /// it survives a clock correction.
    since: Instant,
  },
  /// The key is on its way out: no new dispatch is taken, and `inflight` answers are still owed.
  ///
  /// It carries no origin, though the retirement has one. The origin lives beside the state in the
  /// registry's own entry rather than in this variant, because the shape of these five states is
  /// the ruled one and a field for the ORIGIN is not a thing a knife may add to it — see
  /// [`RootAdvance`] for what the pending origin decides while it waits.
  ///
  /// `since` is the exception, and it is this state's own arithmetic rather than a second fact
  /// about it: `retire_drain` BOUNDS this wait ([`RegistryOptions::retire_drain`]), and a wait
  /// cannot be bounded without knowing when it began. It is [`Analyzing`](Self::Analyzing)'s field
  /// verbatim, on the same clock and for the same reason.
  Retiring {
    /// Answers still owed before the retirement lands.
    inflight: u32,
    /// When the retirement started draining — a MONOTONIC reading, so the drain window survives a
    /// clock correction. See [`Registry::lapse`](super::Registry::lapse).
    since: Instant,
  },
  /// The key is OUT, as of `at`, on `origin`'s say-so.
  Retired {
    /// When it retired — WALL time, because this is the reading a durable row carries.
    at: Timestamp,
    /// Who retired it, and therefore whether it can come back on its own.
    origin: RetireOrigin,
    /// Whether it went out with answers still owed.
    ///
    /// `false` is the ordinary retirement: the drain reached zero and nothing this key sent is
    /// still out. `true` is the flag a sweep reads — work for this key may still land after the row
    /// was written, so whatever that work wrote has to be found and cleared rather than assumed
    /// absent.
    ///
    /// Two endings set it, and they are the two ways a drain can finish early: the ceiling
    /// ([`Lapsed`](RootAction::Lapsed)) and a dispatch refused while the drain ran
    /// ([`Dispatched`](RootAction::Dispatched)).
    late_tails: bool,
  },
  /// The key is coming BACK: its retirement row is owed an erase, and
  /// [`Restored`](RootAction::Restored) is what says the erase landed.
  Restoring,
}

impl RootState {
  /// Whether an act is UNDER WAY — the two states an action waits behind rather than applying to.
  #[inline]
  #[must_use]
  pub const fn is_busy(&self) -> bool {
    matches!(self, Self::Retiring { .. } | Self::Restoring)
  }

  /// **HOW MUCH WORK IS OUT** for this key — dispatched and not yet answered.
  ///
  /// Total, and zero for the three states that have nothing out. It is the reading the whole ack
  /// discipline is about: this number reaching zero is what ends
  /// [`Analyzing`](Self::Analyzing), so a driver that acked an input before dispatching its
  /// outputs would make it touch zero in the middle of a chain that is not finished. See
  /// [`Resident`](crate::Resident)'s own note on the orderings that are not negotiable.
  #[inline]
  #[must_use]
  pub const fn inflight(&self) -> u32 {
    match self {
      Self::Analyzing { inflight, .. } | Self::Retiring { inflight, .. } => *inflight,
      Self::Idle | Self::Retired { .. } | Self::Restoring => 0,
    }
  }

  /// Whether this key went out with answers still owed — `false` for every state but a
  /// [`Retired`](Self::Retired) one whose drain was bounded. See
  /// [`Lapsed`](RootAction::Lapsed).
  #[inline]
  #[must_use]
  pub const fn has_late_tails(&self) -> bool {
    matches!(
      self,
      Self::Retired {
        late_tails: true,
        ..
      }
    )
  }
}

/// WHAT MAY BE ASKED OF A ROOT KEY.
///
/// Eight, and they arrive from four different places: [`Intake`](Self::Intake) from the debounced
/// origin feed, [`Dispatched`](Self::Dispatched) and [`Observed`](Self::Observed) from inside a
/// resident's own loop, [`Lapsed`](Self::Lapsed) from the sweep that bounds a drain, and the other
/// four from a person or from whatever watches the content.
///
/// [`Clone`] rather than [`Copy`], for [`RootState`]'s reason one type over: `Retire` carries the
/// origin.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum RootAction {
  /// A debounced burst on this key landed — take it in.
  ///
  /// It is not the only road into [`Analyzing`](RootState::Analyzing): a
  /// [`Dispatched`](Self::Dispatched) reaching an idle key says the same thing with evidence, which
  /// is what keeps the count right in a deployment whose intake driver is not running.
  Intake,
  /// One item for this key was fanned out.
  ///
  /// # It is REFUSED mid-drain, and the refusal is REMEMBERED
  ///
  /// *No new dispatch while a retirement drains* is what [`Retiring`](RootState::Retiring) MEANS,
  /// so this answers [`Declined`](RootAdvance::Declined) there. But a refusal does not unsend
  /// anything — the resident that called it has already committed the record and put the item on an
  /// edge — while that item's later [`Observed`](Self::Observed) IS taken. So an uncounted dispatch
  /// and a counted answer would let the drain reach zero one answer early, with a tail genuinely
  /// still out.
  ///
  /// The entry therefore remembers the refusal, and the retirement it lands lands with
  /// `late_tails` set. The ruling stands and the flag tells the truth about what it cost, which is
  /// the same trade [`Lapsed`](Self::Lapsed) makes for the other early ending.
  Dispatched,
  /// One answer for this key came back.
  Observed,
  /// Retire it, on this origin's say-so.
  Retire(RetireOrigin),
  /// Bring it back — a person saying so.
  Restore,
  /// The content is THERE again. A [`Vanished`](RetireOrigin::Vanished) retiree restores itself on
  /// this; a [`User`](RetireOrigin::User) one never does.
  Reappear,
  /// The erase a [`Restoring`](RootState::Restoring) key was waiting for has LANDED.
  ///
  /// The asymmetry with the retiring side is deliberate and is the difference between the two
  /// waits: `Retiring` waits on a count this registry holds and therefore ends itself, while
  /// `Restoring` waits on a durable write it does not hold and must be TOLD.
  Restored,
  /// **THE DRAIN WINDOW IS SPENT** — retire this key with its answers still owed.
  ///
  /// [`Retiring`](RootState::Retiring) ends itself when the count reaches zero, and that is the
  /// path nearly every retirement takes. This is the OTHER one, and it exists because a count that
  /// never reaches zero is reachable: a consumer that hung up mid-chain, a node killed with items
  /// out, a discipline broken somewhere upstream. `retire_drain`
  /// ([`RegistryOptions::retire_drain`]) is how long the wait is allowed to be, and
  /// [`Registry::lapse`](super::Registry::lapse) is the sweep that spends it.
  ///
  /// What it earns is a retirement that is HONEST about what it is: the key lands
  /// [`Retired`](RootState::Retired) with `late_tails` set, so both the in-memory state and the
  /// durable row say *work for this key may still land after this*. It is the only action that
  /// sets that flag.
  Lapsed,
}

/// WHAT ONE ASK DID.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[must_use = "an ignored answer hides a refused action and a queued one alike"]
pub enum RootAdvance {
  /// The entry CHANGED — a new state, a different inflight count, or a stronger retirement origin.
  Moved,
  /// The entry was already saying what this action would have made it say. Nothing changed, nothing
  /// waits, and nothing is wrong.
  Unchanged,
  /// The key is mid-act; the action WAITS behind what it is doing.
  Queued,
  /// A repeat of what is already waiting at the back of the queue — absorbed rather than queued
  /// twice. See the module note for why the absorption is at the tail.
  Coalesced,
  /// This state does not take this action at all, and nothing was queued: an intake for a retired
  /// key, a dispatch while a retirement drains, an answer for work nobody sent.
  Declined,
}

/// THE DURABLE ACT A MOVE EARNED — named here, performed elsewhere.
///
/// The registry is a COORDINATION CACHE and nothing in it is the truth: the truth about a retired
/// key is a row in the retirement ledger, and a restarted deployment rebuilds these states by
/// reading it. So a transition that changes whether a key is retired does not write anything — it
/// says what is OWED, and the seat that performs it is [`RetiredLedger`](super::RetiredLedger),
/// which [`Keeper`](crate::Keeper) occupies.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[must_use = "a dropped act leaves the ledger disagreeing with the registry"]
pub enum Retirement {
  /// The key RETIRED — write its row.
  Recorded {
    /// When it retired.
    at: Timestamp,
    /// Who retired it.
    origin: RetireOrigin,
    /// Whether it went out with answers still owed — [`RootState::Retired`]'s own field, carried
    /// into the durable act because the registry is a cache and the row is the truth. A restart
    /// rebuilds the states by reading these rows, and a sweep that had to be told about a bounded
    /// drain would have nothing to read it from if the flag stopped at the in-memory state.
    late_tails: bool,
  },
  /// The key came BACK — erase its row.
  Erased,
}

/// **THE OTHER DURABLE ACT A MOVE EARNED** — a re-run CLOSED, so point its closure at the run that
/// closed.
///
/// [`Retirement`]'s sibling, and it is a separate act for a separate seat rather than a third
/// variant of that enum: the two are performed by different parties against different tables, and a
/// deployment may occupy one seat and not the other. What they share is the posture — named here,
/// performed elsewhere, because this file writes no row.
///
/// # ONE FLIP PER CLOSED RUN, and never a partial one
///
/// It is earned at exactly one transition: [`Analyzing`](RootState::Analyzing) reaching zero work in
/// flight, which is the moment every item the run fanned out has been answered. A flip earned any
/// earlier would point a closure at a generation still being written, and a reader joining two of
/// that closure's tables would see one of them at the new run and the other at the old — a row set
/// that never existed at any instant. That is what *never a mixed-generation join* means, and the
/// arrival of this act is where it is decided.
///
/// # A RETIREMENT MASKS IT rather than racing it
///
/// A key retired mid-analysis earns NO flip: the run it was numbered with is dropped where the
/// retirement is taken, so a closure never flips to a generation nobody may read. The two acts are
/// orthogonal — a retired root's rows are hidden whichever run wrote them — which is why the masking
/// is a drop rather than an ordering.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[must_use = "a dropped flip leaves the closure reading the generation this run replaced"]
pub struct Flip {
  /// The run that closed — what the pointer is to be moved to.
  run: RunId,
  /// When it closed — WALL time, because this is written into a durable row a person reads.
  at: Timestamp,
}

impl Flip {
  /// The act a closed run earns.
  ///
  /// No `#[must_use]` of its own: the TYPE carries one, with the sentence that matters — a dropped
  /// flip leaves the closure reading the generation this run replaced.
  #[inline]
  pub const fn new(run: RunId, at: Timestamp) -> Self {
    Self { run, at }
  }

  /// The run that closed.
  #[inline]
  #[must_use]
  pub const fn run(&self) -> RunId {
    self.run
  }

  /// When it closed.
  #[inline]
  #[must_use]
  pub const fn at(&self) -> Timestamp {
    self.at
  }
}

/// One root key's whole record: where it is, who is retiring it, and what is waiting behind that.
///
/// Private, and it stays private. What a reader outside this module wants is
/// [`Registry::state`](super::Registry::state) and a count; the queue and the pending origin are
/// this machine's own workings and exposing them would be exposing a shape the next knife may
/// still change.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct Entry {
  state: RootState,
  /// Who asked for the retirement now draining — see [`RootState::Retiring`] for why the origin
  /// lives here rather than in that variant.
  retiring_as: Option<RetireOrigin>,
  /// Whether a dispatch was refused while THIS retirement was draining — see
  /// [`RootAction::Dispatched`], where the consequence is argued. It rides beside `retiring_as`
  /// for its reason: both are facts about the act now running rather than about the state, and
  /// both are spent by [`land`](Self::land).
  refused_dispatch: bool,
  /// The run the analysis now open was numbered with — [`Flip`]'s own value, held here for
  /// [`retiring_as`](Self::retiring_as)'s reason: it is a fact about the ACT now running rather than
  /// about the state, and a [`RootState::Analyzing`] that carried it would put a durable-act detail
  /// on the value every counter and every wire face reads.
  ///
  /// `Some` exactly while a run is open. It is TAKEN by the transition that closes the run — which
  /// is what makes a flip earned once — and DROPPED by the one that retires the key, a retirement
  /// masking every generation beneath it.
  running_as: Option<RunId>,
  /// What was asked while this key was mid-act, in the order it was asked.
  ///
  /// Empty for every key that is not [`busy`](RootState::is_busy), which is nearly all of them, and
  /// a [`Vec`] that has never been pushed to allocates nothing.
  queued: Vec<RootAction>,
}

impl Entry {
  /// A key nothing is yet true of.
  #[inline]
  pub(super) fn idle() -> Self {
    Self {
      state: RootState::Idle,
      retiring_as: None,
      refused_dispatch: false,
      running_as: None,
      queued: Vec::new(),
    }
  }

  /// **A KEY THE LEDGER SAYS IS ALREADY OUT** — the boot shape, earning no durable act.
  ///
  /// It is not [`retire`](Self::retire) with the write suppressed. The four facts come off a ROW
  /// rather than off a transition: `at` is when the key actually went out, which a boot's own clock
  /// does not know, and `late_tails` is a fact about a drain that ended in another process. Nothing
  /// waits behind it and no origin is pending, because whatever was mid-act when that process died
  /// is not in the ledger at all — see [`rebuild`](crate::rebuild).
  ///
  /// No RUN is open on it either, and that is the same fact one field over: a run belongs to the
  /// process that opened it, so a boot inherits none. The generation such a key was last read at is
  /// not lost by that — it is a POINTER ROW, which outlives the process exactly as the retirement
  /// row this entry was rebuilt from does.
  #[inline]
  pub(super) fn rebuilt(at: Timestamp, origin: RetireOrigin, late_tails: bool) -> Self {
    Self {
      state: RootState::Retired {
        at,
        origin,
        late_tails,
      },
      retiring_as: None,
      refused_dispatch: false,
      running_as: None,
      queued: Vec::new(),
    }
  }

  /// Where this key is.
  ///
  /// A CLONE rather than a copy, [`RootState`] carrying a [`RetireOrigin`] — which is cheap for the
  /// two shipped origins and a refcount for a deployment's own word. It is what a caller wanting a
  /// VALUE takes; a caller that only matches takes [`state_ref`](Self::state_ref) and pays nothing.
  #[inline]
  pub(super) fn state(&self) -> RootState {
    self.state.clone()
  }

  /// Where this key is, BORROWED — for the walks that only match.
  ///
  /// [`Registry::counts`](super::Registry::counts) and
  /// [`Registry::lapse`](super::Registry::lapse) visit every entry a family holds and read one arm
  /// off each, so a clone per entry would be a clone per key for an answer that is a count.
  #[inline]
  pub(super) const fn state_ref(&self) -> &RootState {
    &self.state
  }

  /// What is waiting behind the act under way.
  #[cfg(test)]
  pub(super) fn queued(&self) -> &[RootAction] {
    &self.queued
  }

  /// The origin of the retirement now draining.
  #[cfg(test)]
  pub(super) fn retiring_as(&self) -> Option<RetireOrigin> {
    self.retiring_as.clone()
  }

  /// The run of the analysis now open.
  #[cfg(test)]
  pub(super) const fn running_as(&self) -> Option<RunId> {
    self.running_as
  }

  /// Whether this entry is the ABSENCE of news, and can therefore be dropped from the table — see
  /// the module note.
  ///
  /// The open RUN is one of the things it must not be holding, and that falls out of the two doors
  /// it leaves by: a closed run's number is TAKEN by the flip and a retired key's is DROPPED, so an
  /// entry back at `Idle` with a run still on it would be a run nothing is ever going to close.
  #[inline]
  pub(super) fn is_vacant(&self) -> bool {
    matches!(self.state, RootState::Idle)
      && self.queued.is_empty()
      && self.retiring_as.is_none()
      && self.running_as.is_none()
      && !self.refused_dispatch
  }

  /// **THE TRANSITION**: take `action` at `stamp`, offering whatever durable acts it earns to `owed`
  /// and `turned`.
  ///
  /// Pure but for the two sinks, which are sinks and not writers: the caller collects what comes out
  /// of them and performs it after the lock this ran under is gone.
  ///
  /// TWO sinks rather than one enum over both acts, and the reason is who is on the other end. A
  /// [`Retirement`] goes to the retirement ledger and a [`Flip`] goes to the generations seat; a
  /// deployment may occupy either, both or neither, and one enum would make every party pattern-match
  /// past acts that are not theirs. The parameters are also what makes the two orderings independent
  /// — neither seat waits on the other — which is the whole of *retired is orthogonal to
  /// generations*.
  ///
  /// A completion — a retirement's last answer, a restore's landed erase, a run's last answer —
  /// DRAINS the queue behind it before returning, so one call may earn more than one act. The drain
  /// terminates because it stops the moment the state is busy again, and an action applied to a
  /// settled state never queues.
  pub(super) fn advance(
    &mut self,
    action: RootAction,
    stamp: Stamp,
    owed: &mut dyn FnMut(Retirement),
    turned: &mut dyn FnMut(Flip),
  ) -> RootAdvance {
    let advance = if self.state.is_busy() {
      self.busy(action, stamp, owed)
    } else {
      self.apply(action, stamp, owed, turned)
    };
    self.drain(stamp, owed, turned);
    advance
  }

  /// An action reaching a key that is MID-ACT.
  ///
  /// The first two arms are the ONLY ways out of the two busy states, and they are spelled first for
  /// that reason: a state nothing leaves is a hang. Everything else either WAITS behind the act, is
  /// absorbed into what is already waiting, or is refused outright.
  fn busy(
    &mut self,
    action: RootAction,
    stamp: Stamp,
    owed: &mut dyn FnMut(Retirement),
  ) -> RootAdvance {
    match (self.state.clone(), action) {
      // THE RETIREMENT'S LAST ANSWER. `Retiring` waits on a count this registry holds, so it ends
      // itself the moment the count reaches zero.
      (RootState::Retiring { inflight, since }, RootAction::Observed) => {
        let left = inflight.saturating_sub(1);
        if left == 0 {
          self.land(stamp.wall(), false, owed);
        } else {
          self.state = RootState::Retiring {
            inflight: left,
            since,
          };
        }
        RootAdvance::Moved
      }
      // THE ERASE LANDED. `Restoring` waits on a durable write it does not hold, so it is TOLD.
      (RootState::Restoring, RootAction::Restored) => {
        self.state = RootState::Idle;
        RootAdvance::Moved
      }
      // THE DRAIN WINDOW IS SPENT — the OTHER way out of `Retiring`, and the only writer of
      // `late_tails`. The count is abandoned rather than waited on, which is the whole of what
      // bounding the wait means; what the abandoned answers become is the flag's own story.
      (RootState::Retiring { .. }, RootAction::Lapsed) => {
        self.land(stamp.wall(), true, owed);
        RootAdvance::Moved
      }
      // A DISPATCH MID-DRAIN IS REFUSED AND REMEMBERED. The refusal is the whole of what
      // `Retiring` means; the memory is what keeps the retirement honest, because the item the
      // resident already put on an edge will be ANSWERED, and that answer is taken. See
      // `RootAction::Dispatched`, where the arithmetic is argued.
      (RootState::Retiring { .. }, RootAction::Dispatched) => {
        self.refused_dispatch = true;
        RootAdvance::Declined
      }
      // The rest of the counting calls never queue either. An answer for work this key never had
      // out is nothing to remember, and a lapse reaching `Restoring` is a sweep looking at a state
      // that has no drain to bound.
      (
        _,
        RootAction::Dispatched | RootAction::Observed | RootAction::Restored | RootAction::Lapsed,
      ) => RootAdvance::Declined,
      // A STRONGER ORIGIN arriving mid-drain REPLACES the one draining rather than waiting behind
      // it: see [`RetireOrigin::outranks`], where the rank is argued. It applies whatever is
      // queued, because it is a change to the act NOW RUNNING rather than a new one — the
      // retirement about to land lands as the stronger origin's, and whatever waits behind it is
      // untouched.
      (RootState::Retiring { .. }, RootAction::Retire(origin))
        if self
          .retiring_as
          .as_ref()
          .is_none_or(|pending| origin.outranks(pending)) =>
      {
        self.retiring_as = Some(origin);
        RootAdvance::Moved
      }
      // *ALREADY HAPPENING*, and it holds ONLY while nothing waits behind the act.
      //
      // Once something is queued, where this key is HEADED is the queue's last word rather than the
      // act now running — a `Restore` reaching a restoring key with a retirement waiting behind it
      // would end retired, which is the opposite of what was asked — so an ask that agrees with the
      // running act still has to take its place in line.
      (RootState::Retiring { .. }, RootAction::Retire(_))
      | (RootState::Restoring, RootAction::Restore | RootAction::Reappear)
        if self.queued.is_empty() =>
      {
        RootAdvance::Unchanged
      }
      // The action is BOUND rather than discarded, which is what a non-`Copy` action costs and
      // all it costs: the tuple moved it into the match, so the tail that queues it has to name it.
      (_, action) => {
        if self.queued.last() == Some(&action) {
          return RootAdvance::Coalesced;
        }
        self.queued.push(action);
        RootAdvance::Queued
      }
    }
  }

  /// The transition proper, over a state that is NOT mid-act. It never queues, which is what makes
  /// the drain terminate.
  fn apply(
    &mut self,
    action: RootAction,
    stamp: Stamp,
    owed: &mut dyn FnMut(Retirement),
    turned: &mut dyn FnMut(Flip),
  ) -> RootAdvance {
    match (self.state.clone(), action) {
      // ─── Idle ────────────────────────────────────────────────────────────────────────────────
      (RootState::Idle, RootAction::Intake) => {
        self.open(stamp, 0);
        RootAdvance::Moved
      }
      // A DISPATCH IS EVIDENCE, and it is taken as such. A deployment whose intake driver is not
      // running still fans work out, and a registry that answered `Declined` here would report an
      // idle key for every root the graph was actually working on.
      (RootState::Idle, RootAction::Dispatched) => {
        self.open(stamp, 1);
        RootAdvance::Moved
      }
      (RootState::Idle, RootAction::Retire(origin)) => self.retire(origin, stamp, owed),
      (RootState::Idle, RootAction::Reappear) => RootAdvance::Unchanged,
      (
        RootState::Idle,
        RootAction::Observed | RootAction::Restore | RootAction::Restored | RootAction::Lapsed,
      ) => RootAdvance::Declined,

      // ─── Analyzing ───────────────────────────────────────────────────────────────────────────
      (RootState::Analyzing { .. }, RootAction::Intake) => RootAdvance::Unchanged,
      (RootState::Analyzing { inflight, since }, RootAction::Dispatched) => {
        self.state = RootState::Analyzing {
          inflight: inflight.saturating_add(1),
          since,
        };
        RootAdvance::Moved
      }
      (RootState::Analyzing { inflight: 0, .. }, RootAction::Observed) => RootAdvance::Declined,
      (RootState::Analyzing { inflight, since }, RootAction::Observed) => {
        let left = inflight - 1;
        if left == 0 {
          // THE RUN CLOSED. Every item it fanned out has been answered, which is the one moment a
          // whole cascade closure is consistent — see [`Flip`], where that is the ruling.
          self.state = RootState::Idle;
          self.close(stamp.wall(), turned);
        } else {
          self.state = RootState::Analyzing {
            inflight: left,
            since,
          };
        }
        RootAdvance::Moved
      }
      (RootState::Analyzing { .. }, RootAction::Retire(origin)) => self.retire(origin, stamp, owed),
      (RootState::Analyzing { .. }, RootAction::Reappear) => RootAdvance::Unchanged,
      (
        RootState::Analyzing { .. },
        RootAction::Restore | RootAction::Restored | RootAction::Lapsed,
      ) => RootAdvance::Declined,

      // ─── Retired ─────────────────────────────────────────────────────────────────────────────
      (
        RootState::Retired {
          at,
          origin,
          late_tails,
        },
        RootAction::Retire(second),
      ) => {
        if second.outranks(&origin) {
          self.state = RootState::Retired {
            at,
            origin: second.clone(),
            late_tails,
          };
          // The flag rides along UNCHANGED: a stronger origin restates who stood the key down and
          // says nothing about whether work was still out when it went, which is a fact about the
          // drain that already happened.
          owed(Retirement::Recorded {
            at,
            origin: second,
            late_tails,
          });
          RootAdvance::Moved
        } else {
          RootAdvance::Unchanged
        }
      }
      (RootState::Retired { .. }, RootAction::Restore) => self.restore(owed),
      // The fork is [`RetireOrigin::restores_itself`] and not a match on the arms, which is what
      // keeps a deployment's own word answering the same way `User` does without this arm having to
      // enumerate a vocabulary that is open.
      (RootState::Retired { origin, .. }, RootAction::Reappear) => {
        if origin.restores_itself() {
          self.restore(owed)
        } else {
          RootAdvance::Declined
        }
      }
      // Everything else a retired key is offered is a LATE TAIL — an answer for work sent before it
      // went out, an intake from a feed that had not caught up. Harmless: the read side filters by
      // root, and the sweep clears what is left. A `Lapsed` is here too, and it is the sweep
      // looking at a key that retired between the walk and the act.
      (
        RootState::Retired { .. },
        RootAction::Intake
        | RootAction::Dispatched
        | RootAction::Observed
        | RootAction::Restored
        | RootAction::Lapsed,
      ) => RootAdvance::Declined,

      // ─── Retiring / Restoring ────────────────────────────────────────────────────────────────
      // Unreachable: `advance` sends every busy state to `wait`, and `drain` stops the moment one
      // is entered. Spelled rather than left to a catch-all so that a sixth state added later is a
      // compile error here rather than a silent refusal.
      (RootState::Retiring { .. } | RootState::Restoring, _) => RootAdvance::Declined,
    }
  }

  /// Retire on `origin`'s say-so, from a state that is not already going out: straight to
  /// [`Retired`](RootState::Retired) where nothing is in flight, and through
  /// [`Retiring`](RootState::Retiring) where something is.
  fn retire(
    &mut self,
    origin: RetireOrigin,
    stamp: Stamp,
    owed: &mut dyn FnMut(Retirement),
  ) -> RootAdvance {
    let inflight = match self.state {
      RootState::Analyzing { inflight, .. } => inflight,
      _ => 0,
    };
    self.retiring_as = Some(origin);
    // THE MASK. A run open on a key going out earns no flip — see [`Flip`]'s own note: a closure
    // pointed at a generation nobody may read is a pointer that means nothing, and a retired root's
    // rows are hidden whichever run wrote them. The number is dropped rather than kept, so a restore
    // starts the next analysis on a run of its own.
    self.running_as = None;
    if inflight == 0 {
      // `Retiring { inflight: 0 }` is never stored: it has nothing to wait for, so waiting in it
      // would be a state whose only exit is the transition that should have happened here. Nothing
      // is out, so nothing can land late.
      self.land(stamp.wall(), false, owed);
    } else {
      self.state = RootState::Retiring {
        inflight,
        since: stamp.monotonic(),
      };
    }
    RootAdvance::Moved
  }

  /// The retirement LANDS: the state becomes [`Retired`](RootState::Retired) and the row is owed.
  ///
  /// `late_tails` is the caller's statement about the drain it just ended — `false` where the count
  /// reached zero and `true` where [`Lapsed`](RootAction::Lapsed) bounded the wait. It is written
  /// into both the state and the act, on [`Retirement::Recorded`]'s own reasoning.
  fn land(&mut self, at: Timestamp, late_tails: bool, owed: &mut dyn FnMut(Retirement)) {
    let origin = self.retiring_as.take().unwrap_or(RetireOrigin::Vanished);
    // A refusal this drain remembered is a tail too, and is spent HERE — the memory belongs to the
    // act that just ended, so a later retirement starts without it.
    let late_tails = late_tails || core::mem::take(&mut self.refused_dispatch);
    self.state = RootState::Retired {
      at,
      origin: origin.clone(),
      late_tails,
    };
    owed(Retirement::Recorded {
      at,
      origin,
      late_tails,
    });
  }

  /// Start bringing a retired key back: the row is owed an erase, and
  /// [`Restored`](RootAction::Restored) is what says the erase landed.
  fn restore(&mut self, owed: &mut dyn FnMut(Retirement)) -> RootAdvance {
    self.state = RootState::Restoring;
    self.retiring_as = None;
    self.refused_dispatch = false;
    owed(Retirement::Erased);
    RootAdvance::Moved
  }

  /// Spend what was waiting behind the act that just ended, in the order it was asked, until the
  /// queue is empty or another act is under way.
  ///
  /// It TERMINATES because [`apply`](Self::apply) never queues: every pass either empties the queue
  /// by one or enters a busy state, and both are progress.
  fn drain(
    &mut self,
    stamp: Stamp,
    owed: &mut dyn FnMut(Retirement),
    turned: &mut dyn FnMut(Flip),
  ) {
    while !self.state.is_busy() && !self.queued.is_empty() {
      let next = self.queued.remove(0);
      // The drained action's OWN answer is nobody's: the call that started this drain has already
      // decided what to report, and a queued action was accepted when it was queued.
      let _spent = self.apply(next, stamp, owed, turned);
    }
  }

  /// A RUN OPENS: the key starts analyzing, numbered with `stamp`'s own run.
  ///
  /// The two roads in — a debounced intake and a dispatch taken as evidence — differ only in what is
  /// already out, which is why they share this and pass it.
  #[inline]
  fn open(&mut self, stamp: Stamp, inflight: u32) {
    self.state = RootState::Analyzing {
      inflight,
      since: stamp.monotonic(),
    };
    self.running_as = Some(stamp.run());
  }

  /// A RUN CLOSES: the number is TAKEN, and the flip it earns is offered.
  ///
  /// Taking rather than reading is what makes a flip earned once: an entry that reached `Idle` holds
  /// no open run, so the same run can never be flipped to twice however the key moves afterwards.
  ///
  /// # The [`None`] arm is TOTALITY rather than a case
  ///
  /// Every [`Analyzing`](RootState::Analyzing) state this machine can reach was entered through
  /// [`open`](Self::open), which sets the number, and every road out of it either takes the number
  /// here or drops it in [`retire`](Self::retire) — so today the arm is unreachable. It is written
  /// as a take rather than an `expect` because of what a further road IN would mean if one is ever
  /// added: a state reaching `Analyzing` without opening a run would close it silently here, which
  /// is the safe direction — no pointer moves for a run nobody opened.
  #[inline]
  fn close(&mut self, at: Timestamp, turned: &mut dyn FnMut(Flip)) {
    if let Some(run) = self.running_as.take() {
      turned(Flip::new(run, at));
    }
  }
}