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
//! THE TABLES: one [`Registry`] per root family, and the [`Registries`] that holds them.
//!
//! # A FRAMEWORK-HELD RUNTIME COMPONENT — not a mount, and not a resource
//!
//! [`Resources`](crate::Resources) is the DOMAIN's namespace: `mount` and `resource` are words an
//! application author writes, and what they reach is what that author declared. This is not one of
//! those. It sits where [`Taps`](crate::Taps) and [`Policies`](crate::Policies) sit — built by the
//! launch itself, threaded to every resident, and reachable afterwards through
//! [`App::registries`](crate::App::registries) — and the declaration face grows no word for it at
//! all. A deployment tunes it through the `[registry]` section
//! ([`RegistryOptions`](super::RegistryOptions)) and never mounts it.
//!
//! # ONE OBJECT, TABLED BY FAMILY, TYPED ALL THE WAY DOWN
//!
//! A root family is a TYPE — `MediaId` is one family and `TrackId` is another — so the table for a
//! family is a `Registry<Root>` and there is no erased key anywhere in it. What is erased is the
//! MAP FROM FAMILY TO TABLE, which has to be: a heterogeneous set of typed tables has no other
//! form, and it is the same erasure [`App`](crate::App)'s own feeder map already pays for the same
//! reason.
//!
//! That is deliberately not *one resource per family*, which was the other candidate. A family is a
//! fact about the graph's declarations rather than about the deployment's document, so a shape that
//! made every family a thing somebody mounts would put a runtime detail on the declaration face.
//!
//! # FAMILIES ARE OPENED, NOT DECLARED
//!
//! [`Registries::open`] mints a family's table on first ask and hands the same one back ever after;
//! [`Registries::of`] is the read that mints nothing. Two doors rather than one because they need
//! different things: opening resolves the family's own options and therefore needs the family's
//! NAME, which a [`TypeId`] cannot supply and only the party holding the emitted projection has —
//! see [`RootProjection`](super::RootProjection), whose `FAMILY` const is exactly that name.
//!
//! An [`Arc`] rather than a borrow, and that is what makes lazy opening possible at all: a `&`
//! handed out of a map that can still grow is a `&` into storage that can move, so the table is
//! behind its own pointer and the map holds pointers.
//!
//! # THE REGISTRY OWNS ITS INTERIOR MUTABILITY
//!
//! Every door on both types takes `&self`. Nothing here is wrapped in a
//! [`Shared`](crate::Share) and nothing here needs to be: the sharding below is the lock, and a
//! second one around it would serialise the whole family to save writing this one.
//!
//! # IT IS A COORDINATION CACHE, AND NOTHING IN IT IS THE TRUTH
//!
//! The truth about a retired key is a row in the retirement ledger; the truth about work in flight
//! is the runs ledger. A restart rebuilds these tables by reading those, with every inflight count
//! back at zero and no debounce timer surviving. So nothing here is persisted, nothing here is
//! recovered, and a durable act a transition earns is HANDED OUT rather than performed — see
//! [`RetiredLedger`] and [`GenerationLedger`], the two seats this knife exposes, and
//! [`Keeper`](crate::Keeper) and [`Curator`](crate::Curator), the parties that occupy them.

use core::hash::{BuildHasher, Hash};

use std::{
  any::{Any, TypeId},
  collections::HashMap,
  sync::{Arc, Mutex, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard},
};

#[cfg(feature = "async-graphql")]
use smol_bytes::Utf8Bytes;

#[cfg(feature = "async-graphql")]
use super::dynamic::DynRegistry;
use crate::Timestamp;

use super::{
  RegistryOptions, RegistryOverride,
  state::{Entry, Flip, RetireOrigin, Retirement, RootAction, RootAdvance, RootState, Stamp},
};

#[cfg(test)]
mod tests;

/// How many independently locked stripes one family's table is cut into.
///
/// A power of two so the modulus is a mask, and SIXTEEN because of what contends here: a root key's
/// entry is touched once per dispatch and once per answer by whichever resident is working on it,
/// which is a short critical section reached from as many threads as the deployment has nodes. Deep
/// enough that a graph with a dozen busy nodes rarely collides, shallow enough that the whole array
/// is one cache-friendly allocation rather than a per-key lock.
const SHARDS: usize = 16;

/// THE BOUND A ROOT FAMILY'S KEY MEETS, wearing a name.
///
/// It is blanket-implemented and is never written by hand — not by an application, not by an
/// expansion, not here. What it buys is that [`Registry`] and [`Registries`] say `Root: RootKey`
/// instead of repeating five bounds at every door, and that the ONE place the bound set is decided
/// is this declaration.
///
/// Each of the five earns its place. [`Eq`] and [`Hash`] are what a table keyed by the root needs;
/// [`Clone`] is what taking a key by reference and storing it costs, and a root key is an id, which
/// is the cheapest thing in the vocabulary to clone; [`Send`] and [`Sync`] and `'static` are what
/// living inside an [`Arc`] shared by every resident costs. The set is also exactly what
/// [`Drives`](crate::Drives) already asks of [`Attributes::Root`](crate::Attributes::Root), so a
/// projection that satisfies the journal satisfies this with nothing further to state.
pub trait RootKey: Clone + Eq + Hash + Send + Sync + 'static {}

impl<T> RootKey for T where T: Clone + Eq + Hash + Send + Sync + 'static {}

/// WHERE A RETIREMENT'S OWN DURABLE ACT GOES — the seat.
///
/// The registry is a cache and the ledger is the truth, so a transition that retires or restores a
/// key does not write the row: it says what is owed, and whoever occupies this seat writes it. The
/// row's own shape, its table, its transaction and the ordering of the write against the in-memory
/// move are all that party's, which is why nothing about them is named here.
///
/// [`Keeper`](crate::Keeper) is what occupies it in a deployment that declared `retired(<engine>)`:
/// it queues the act and returns, exactly as the contract below asks, and its own body performs the
/// durable write and only then publishes to the mirror. A deployment that declared no ledger seats
/// nobody, and a retirement that reaches no seat is an in-memory move with nothing behind it.
///
/// # Queue and return
///
/// Called on the thread that made the transition, exactly as
/// [`Attributes::observe`](crate::Attributes::observe) is called from inside a resident's loop —
/// and under the same contract, for the same reason. An implementation that writes to a store
/// QUEUES the write and returns; one that blocks stops the resident whose dispatch earned the act.
///
/// It is called with NO LOCK OF THIS REGISTRY'S HELD — every door on [`Registry`] collects the acts
/// under the key's stripe and spends them after dropping it — so an implementation may read the
/// registry back. That is a guarantee about deadlock and not an invitation: reading a key's state
/// from inside the act that changed it answers the state AFTER the change, which is rarely the
/// question.
pub trait RetiredLedger<Root>: Send + Sync {
  /// `act` is owed for `key`. Queue it and return.
  fn owed(&self, key: &Root, act: Retirement);
}

/// WHERE A CLOSED RUN'S OWN DURABLE ACT GOES — the flip seat, [`RetiredLedger`]'s sibling.
///
/// The registry is a cache and the pointer table is the truth about which generation a closure is
/// reading, so a transition that closes a run does not write the pointer: it says what is owed, and
/// whoever occupies this seat writes it. The row's own shape, its table and the ordering of the write
/// against the retention duty behind it are all that party's — see
/// [`Curator`](crate::Curator), which is what occupies this one.
///
/// # Queue and return
///
/// [`RetiredLedger`]'s contract verbatim, and for its reason: this is called on the thread that made
/// the transition, from inside a resident's own loop, and an implementation that blocked there would
/// stop the worker whose last answer earned the flip.
///
/// It is called with NO LOCK OF THIS REGISTRY'S HELD, on the same law: every door on [`Registry`]
/// collects the acts under the key's stripe and spends them after dropping it.
///
/// # It is a SECOND seat and not a widening of the first
///
/// A deployment may occupy either, both or neither. One seat taking both acts would make every party
/// pattern-match past acts that are not theirs, and would tie two orderings together that the sealed
/// design keeps apart: a retirement is orthogonal to a generation, and masks it at the transition
/// rather than at the write.
pub trait GenerationLedger<Root>: Send + Sync {
  /// `act` is owed for `key`. Queue it and return.
  fn flipped(&self, key: &Root, act: Flip);
}

/// **HOW MANY KEYS ONE FAMILY IS HOLDING**, broken down by which of the four STORED states each is
/// in — see [`Registry::counts`].
///
/// No `idle` field: an idle key is not an entry this table could count, on
/// [`RootState`]'s own reasoning. A reader that wants the wire face's four-field shape —
/// `{ idle analyzing retiring retired }` — supplies the zero itself; see [`crate::graphql`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct RegistryCounts {
  /// Keys [`Analyzing`](RootState::Analyzing).
  pub analyzing: usize,
  /// Keys [`Retiring`](RootState::Retiring).
  pub retiring: usize,
  /// Keys [`Retired`](RootState::Retired).
  pub retired: usize,
  /// Keys [`Restoring`](RootState::Restoring).
  pub restoring: usize,
}

/// ONE ROOT FAMILY'S TABLE: every key it is holding something for, and this family's own timing.
///
/// # What it HOLDS is the exception rather than the rule
///
/// A key nothing is true of is [`Idle`](RootState::Idle) and is not stored — see
/// [`state`](Self::state), which is total, and the [state module note](super::state) for why the
/// absence and the idle state are one fact. So [`held`](Self::held) counts the keys that are
/// analyzing, retiring, retired or restoring, and a deployment that has swept everything back to
/// idle holds an empty table however many roots it has ever seen.
pub struct Registry<Root> {
  /// This family's own resolved knobs — [`RegistryOptions::for_family`]'s answer, with no override
  /// table left to carry.
  ///
  /// # BEHIND A LOCK, unlike every other field a Rust value merely holds
  ///
  /// Every other knob-bearing type in this crate is a document read once at start-up. This one is
  /// also a LIVE DIAL: [`registryKnobs`](crate::graphql) turns it at request time, which is the
  /// options layer's own third tier — default, `[registry]` section, request — landing on the one
  /// grain that is a runtime value rather than a parsed document. The lock is scoped to exactly this
  /// field and nothing wider: [`apply_knobs`](Self::apply_knobs) takes the write side for the
  /// duration of five field writes and nothing else in this type ever blocks behind it.
  options: RwLock<RegistryOptions>,
  /// The stripes, `SHARDS` of them, each an independently locked slice of the whole table.
  shards: Box<[Mutex<HashMap<Root, Entry>>]>,
  /// WHICH stripe a key lands in. Its own hasher rather than the maps' — a `HashMap`'s
  /// [`RandomState`](std::collections::hash_map::RandomState) is per-map, so reading one map's
  /// hasher to choose between sixteen of them would be choosing with the wrong instrument.
  stripe: std::collections::hash_map::RandomState,
  /// The seat a durable act goes to, installed at most once — see
  /// [`installing`](Self::installing).
  ledger: OnceLock<Arc<dyn RetiredLedger<Root>>>,
  /// The seat a CLOSED RUN's act goes to, installed at most once — see [`curating`](Self::curating).
  ///
  /// A second `OnceLock` rather than a second field on one seat, on [`GenerationLedger`]'s own
  /// reasoning: the two are independently occupied, and a deployment that writes retirement rows and
  /// no pointers is a deployment with one of them seated.
  curator: OnceLock<Arc<dyn GenerationLedger<Root>>>,
}

/// Written rather than derived, on [`App`](crate::App)'s own precedent: a derived one would carry
/// `Root: Debug`, and a root key that cannot print itself would make its whole family's table
/// unprintable for the sake of a bound nothing else here needs. What a reader wants is the arity
/// anyway — how much this family is holding.
impl<Root> core::fmt::Debug for Registry<Root> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("Registry")
      .field("options", &self.options())
      .field("shards", &self.shards.len())
      .field("held", &self.held())
      .field("ledger", &self.ledger.get().is_some())
      .field("curator", &self.curator.get().is_some())
      .finish()
  }
}

impl<Root> Registry<Root> {
  /// An empty family, running `options`.
  #[must_use]
  pub fn new(options: RegistryOptions) -> Self {
    Self {
      options: RwLock::new(options),
      shards: core::iter::repeat_with(|| Mutex::new(HashMap::new()))
        .take(SHARDS)
        .collect(),
      stripe: std::collections::hash_map::RandomState::new(),
      ledger: OnceLock::new(),
      curator: OnceLock::new(),
    }
  }

  /// This family's own resolved knobs, AS OF THIS READ — a snapshot rather than a borrow, because
  /// [`apply_knobs`](Self::apply_knobs) may have moved on by the time a caller looks at what came
  /// back. Poison read through, on [`shard`](Self::shard)'s own idiom.
  #[inline]
  #[must_use]
  pub fn options(&self) -> RegistryOptions {
    self
      .options
      .read()
      .unwrap_or_else(|held| held.into_inner())
      .clone()
  }

  /// **TURN THE LIVE DIAL**: fold `over`'s named knobs onto this family's own, in place — the request
  /// tier of the options layer's three, and the only one that acts on an already-running family
  /// rather than on a document read once at start-up.
  ///
  /// A knob `over` leaves unnamed is UNCHANGED, exactly as [`RegistryOptions::for_family`] leaves it
  /// reading the wider default rather than resetting it — this is that same fold, run again over the
  /// value a family is ALREADY holding instead of over the shipped defaults.
  pub fn apply_knobs(&self, over: &RegistryOverride) {
    let mut current = self
      .options
      .write()
      .unwrap_or_else(|held| held.into_inner());
    if let Some(debounce) = over.debounce() {
      current.set_debounce(debounce);
    }
    if let Some(batch_max_items) = over.batch_max_items() {
      current.set_batch_max_items(batch_max_items);
    }
    if let Some(batch_max_wait) = over.batch_max_wait() {
      current.set_batch_max_wait(batch_max_wait);
    }
    if let Some(retire_drain) = over.retire_drain() {
      current.set_retire_drain(retire_drain);
    }
    if let Some(settle) = over.settle() {
      current.set_settle(settle);
    }
  }

  /// **SEAT THE LEDGER**: send every durable act this family earns to `ledger`.
  ///
  /// Once, and once only — `false` where a ledger is already seated, and the one offered is dropped
  /// rather than replacing it. A second writer for one family's rows is two parties disagreeing
  /// about what a retirement means, and the honest answer to the second is *no*.
  #[must_use = "a refused install leaves the acts going to whoever was already seated"]
  pub fn installing(&self, ledger: Arc<dyn RetiredLedger<Root>>) -> bool {
    self.ledger.set(ledger).is_ok()
  }

  /// Whether a ledger is seated.
  #[inline]
  #[must_use]
  pub fn is_recorded(&self) -> bool {
    self.ledger.get().is_some()
  }

  /// **SEAT THE CURATOR**: send every flip this family earns to `curator`.
  ///
  /// [`installing`](Self::installing)'s sibling, once and once only, and refused the same way for
  /// the same reason: a second writer for one family's pointers is two parties disagreeing about
  /// which generation is current, and the honest answer to the second is `false`.
  #[must_use = "a refused install leaves the flips going to whoever was already seated"]
  pub fn curating(&self, curator: Arc<dyn GenerationLedger<Root>>) -> bool {
    self.curator.set(curator).is_ok()
  }

  /// Whether a curator is seated.
  #[inline]
  #[must_use]
  pub fn is_curated(&self) -> bool {
    self.curator.get().is_some()
  }

  /// How many keys this family is holding something for — see the type note: an idle key is not
  /// one of them.
  #[must_use]
  pub fn held(&self) -> usize {
    self
      .shards
      .iter()
      .map(|shard| shard.lock().unwrap_or_else(|held| held.into_inner()).len())
      .sum()
  }

  /// Whether it is holding nothing at all.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.held() == 0
  }
}

impl<Root: RootKey> Registry<Root> {
  /// **WHERE `key` IS** — total, answering [`Idle`](RootState::Idle) for a key this family has
  /// never heard of, which is what an idle key IS.
  #[must_use]
  pub fn state(&self, key: &Root) -> RootState {
    self
      .shard(key)
      .get(key)
      .map_or(RootState::Idle, Entry::state)
  }

  /// **HOW MUCH WORK IS OUT** for `key` — [`RootState::inflight`] without the match, and the
  /// reading the counting exists to make true.
  #[inline]
  #[must_use]
  pub fn inflight(&self, key: &Root) -> u32 {
    self.state(key).inflight()
  }

  /// A debounced burst on `key` landed — take it in.
  pub fn intake(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Intake, stamp)
  }

  /// One item for `key` was fanned out. The call reaches here from a resident's loop in a later
  /// knife; the transition is already whole.
  pub fn dispatched(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Dispatched, stamp)
  }

  /// One answer for `key` came back.
  pub fn observed(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Observed, stamp)
  }

  /// Retire `key`, on `origin`'s say-so.
  pub fn retire(&self, key: &Root, origin: RetireOrigin, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Retire(origin), stamp)
  }

  /// Bring `key` back — a person saying so.
  pub fn restore(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Restore, stamp)
  }

  /// `key`'s content is THERE again. A [`Vanished`](RetireOrigin::Vanished) retiree comes back on
  /// this; a [`User`](RetireOrigin::User) one never does.
  pub fn reappear(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Reappear, stamp)
  }

  /// The erase `key` was waiting for has landed.
  pub fn restored(&self, key: &Root, stamp: Stamp) -> RootAdvance {
    self.act(key, RootAction::Restored, stamp)
  }

  /// **THE BOOT DOOR**: state that `key` is already retired, exactly as the ledger's row says, and
  /// earn NO durable act for saying so.
  ///
  /// It is the one door on this table that does not go through
  /// [`act`](Self::act), and the reason is what a rebuild IS. Every other door describes something
  /// that just happened and may therefore owe a row; this describes a row that already exists. A
  /// rebuild routed through [`retire`](Self::retire) would re-write every row it had just read —
  /// stamped with the boot's own clock rather than the retirement's, and with `late_tails` recomputed
  /// from a drain that is not this process's.
  ///
  /// It REPLACES whatever the entry said, which is the honest posture for the truth arriving: the
  /// table is a cache, this is what it is a cache of, and a boot road runs before anything else has
  /// put a word in it. See [`rebuild`](crate::rebuild) for the walk that calls it.
  pub fn rebuilt(&self, key: &Root, at: Timestamp, origin: RetireOrigin, late_tails: bool) {
    self
      .shard(key)
      .insert(key.clone(), Entry::rebuilt(at, origin, late_tails));
  }

  /// **THE TALLY**: how many keys this family is holding in each of the states worth counting at a
  /// glance.
  ///
  /// [`Idle`](RootState::Idle) is not among them and never can be — the type note's own reason: an
  /// idle key is the absence of an entry, and there is no table this call could count it out of. A
  /// reader that wants an idle count answers zero for the same reason [`held`](Self::held) does for a
  /// swept-clean family: nothing is wrong, there is simply nothing stored to see.
  #[must_use]
  pub fn counts(&self) -> RegistryCounts {
    let mut counts = RegistryCounts::default();
    for stripe in &self.shards {
      let shard = stripe.lock().unwrap_or_else(|held| held.into_inner());
      for entry in shard.values() {
        match entry.state_ref() {
          RootState::Idle => {}
          RootState::Analyzing { .. } => counts.analyzing += 1,
          RootState::Retiring { .. } => counts.retiring += 1,
          RootState::Retired { .. } => counts.retired += 1,
          RootState::Restoring => counts.restoring += 1,
        }
      }
    }
    counts
  }

  /// **UP TO `limit` KEYS THIS FAMILY IS HOLDING SOMETHING FOR**, each beside the state it is in.
  ///
  /// The table's own order — the stripe walk, then a stripe's own hash order — and NOT a recency
  /// ranking: nothing in an [`Entry`] is a global sequence number, so promising *most recent first*
  /// would be a promise this call cannot keep. What it keeps is narrower and still useful: a sample
  /// of what a family is holding, for a glance rather than an audit.
  #[must_use]
  pub fn snapshot(&self, limit: usize) -> Vec<(Root, RootState)> {
    let mut out = Vec::with_capacity(limit.min(SHARDS * 4));
    'walk: for stripe in &self.shards {
      let shard = stripe.lock().unwrap_or_else(|held| held.into_inner());
      for (key, entry) in shard.iter() {
        if out.len() >= limit {
          break 'walk;
        }
        out.push((key.clone(), entry.state()));
      }
    }
    out
  }

  /// **SPEND THE DRAIN CEILING**: retire every key that has been
  /// [`Retiring`](RootState::Retiring) for longer than this family's own `retire_drain`, and hand
  /// back the ones that went.
  ///
  /// It is a SWEEP and is meant to be called on a cadence — the whole table is walked, which is
  /// affordable because the table holds only the keys something is true of (see the type note) and
  /// a deployment that has swept everything back to idle walks nothing at all.
  ///
  /// # The walk takes each stripe ONCE, and the ledger is paid after all of them
  ///
  /// [`act`](Self::act)'s law, widened to a walk: the durable acts are collected under the stripes
  /// and spent with no lock of this registry's held, so a [`RetiredLedger`] may read the registry
  /// back. The stripes are taken one at a time and never two at once, so this holds no more of the
  /// family shut than an ordinary transition does.
  ///
  /// # A key that lapses is flagged rather than forgotten
  ///
  /// The abandoned answers are exactly what `late_tails` says — see [`RootAction::Lapsed`]. This
  /// call is the ONLY writer of that flag.
  pub fn lapse(&self, stamp: Stamp) -> Vec<Root> {
    let ceiling = self
      .options
      .read()
      .unwrap_or_else(|held| held.into_inner())
      .retire_drain();
    let mut lapsed: Vec<Root> = Vec::new();
    let mut owed: Vec<(Root, Retirement)> = Vec::new();
    let mut turned: Vec<(Root, Flip)> = Vec::new();
    for stripe in &self.shards {
      let mut shard = stripe.lock().unwrap_or_else(|held| held.into_inner());
      shard.retain(|key, entry| {
        let RootState::Retiring { since, .. } = entry.state_ref() else {
          return true;
        };
        // COPIED OFF THE BORROW, and that is the whole of what a `Clone` state costs here: the
        // reading is wanted after `advance` has taken the entry mutably, and a borrow into the
        // entry could not outlive that.
        let since = *since;
        // `saturating_duration_since`, because a `Stamp` may have been minted before this entry
        // started draining — a caller is allowed to hand over the instant it woke at, and a sweep
        // racing a retirement is not a reason to lapse it early.
        if stamp.monotonic().saturating_duration_since(since) < ceiling {
          return true;
        }
        let _spent = entry.advance(
          RootAction::Lapsed,
          stamp,
          &mut |act| owed.push((key.clone(), act)),
          &mut |act| turned.push((key.clone(), act)),
        );
        lapsed.push(key.clone());
        // The drain behind the lapse may have taken the key all the way back to idle — a `Restore`
        // that was waiting, then its `Restored`. Such an entry is the absence of news and leaves
        // the table, exactly as it would through `act`.
        !entry.is_vacant()
      });
    }
    if let Some(ledger) = self.ledger.get() {
      for (key, act) in owed {
        ledger.owed(&key, act);
      }
    }
    // The FLIPS are spent after the retirements and under no lock either. A lapse RETIRES, and the
    // drain behind it cannot close a run — an answer is one of the actions that never queues — so
    // this list is empty on every path this machine has today. It is collected all the same, because
    // the alternative is a transition whose acts depend on which door called it.
    if let Some(curator) = self.curator.get() {
      for (key, act) in turned {
        curator.flipped(&key, act);
      }
    }
    lapsed
  }

  /// **THE ONE DOOR EVERY ACTION GOES THROUGH**: take the key's stripe, move its entry, drop the
  /// stripe, and only THEN hand the durable acts to the ledger.
  ///
  /// The order is the point. A ledger's `owed` is somebody else's code, and running it under a
  /// stripe lock would hold a slice of this family shut for as long as that code takes — so the
  /// acts are collected first and spent after. The collection allocates nothing in the ordinary
  /// case: a [`Vec`] that is never pushed to never allocates, and the overwhelming majority of
  /// transitions earn no act at all.
  fn act(&self, key: &Root, action: RootAction, stamp: Stamp) -> RootAdvance {
    let mut owed: Vec<Retirement> = Vec::new();
    let mut turned: Vec<Flip> = Vec::new();
    let advance = {
      let mut shard = self.shard(key);
      let entry = shard.entry(key.clone()).or_insert_with(Entry::idle);
      let advance = entry.advance(action, stamp, &mut |act| owed.push(act), &mut |act| {
        turned.push(act)
      });
      // A key back at the absence of news leaves the table — see the type note.
      if entry.is_vacant() {
        shard.remove(key);
      }
      advance
    };
    if let Some(ledger) = self.ledger.get() {
      for act in owed {
        ledger.owed(key, act);
      }
    }
    if let Some(curator) = self.curator.get() {
      for act in turned {
        curator.flipped(key, act);
      }
    }
    advance
  }

  /// `key`'s own stripe, already locked.
  ///
  /// A poisoned stripe is READ THROUGH rather than propagated — `unwrap_or_else(into_inner)`, this
  /// crate's own idiom one module over. A panic while a transition held the lock leaves an entry
  /// that may be mid-move, and the recovery from that is the next transition over it, not a whole
  /// deployment refusing to coordinate.
  fn shard(&self, key: &Root) -> std::sync::MutexGuard<'_, HashMap<Root, Entry>> {
    let stripe = (self.stripe.hash_one(key) as usize) % SHARDS;
    self.shards[stripe]
      .lock()
      .unwrap_or_else(|held| held.into_inner())
  }
}

/// **THE COUNTING SEAT ONE DRIVER PASS HOLDS**: the family table this node counts into, opened
/// once, and the one clock reading every transition in the pass shares.
///
/// # Why a pass holds one rather than reaching for the registry per item
///
/// Both halves are per-ITEM work turned into per-PASS work. Opening the family takes a read lock
/// on the family map and clones an [`Arc`]; a [`Stamp`] reads two clocks. A delivery of 256
/// records fanned across two edges is 512 counted dispatches, and paying either of those 512 times
/// would put a lock and two clock reads on the hot path of every node in the graph. The state
/// module's own note already rules the clock half — *a driver that already woke at an instant hands
/// over the one it woke at instead of reading the clock a second time* — and one instant for one
/// pass is exactly that.
///
/// # It exists only where the node has a real projection
///
/// [`Registries::counting`] is what mints it, and that door refuses the unit root; see its note.
/// So a node with no attribution holds `None` here and contributes nothing to any family, which is
/// the honest state of a node whose outputs name no root.
pub(crate) struct Counting<Root> {
  table: Arc<Registry<Root>>,
  stamp: Stamp,
}

impl<Root: RootKey> Counting<Root> {
  /// The seat a pass takes where `registries` is wired and `Root` is a real family.
  pub(crate) fn open(registries: Option<&Arc<Registries>>, family: &str) -> Option<Self> {
    let table = registries?.counting::<Root>(family)?;
    Some(Self {
      table,
      stamp: Stamp::now(),
    })
  }

  /// **ONE ITEM WENT OUT** under `key`.
  ///
  /// The advance is DELIBERATELY not acted on, and that is worth stating once here rather than at
  /// every call site. A dispatch reaching a retiring or a retired key is
  /// [`Declined`](RootAdvance::Declined) — and by the time this is called the record has committed
  /// and the item is on the wire, so there is nothing a refusal here could undo. What that refusal
  /// MEANS is the late tail the registry already names: the read side filters by root, and the
  /// sweep clears what was written.
  #[inline]
  pub(crate) fn dispatched(&self, key: &Root) {
    let _late = self.table.dispatched(key, self.stamp);
  }

  /// **ONE ITEM CAME BACK** under `key` — or will never come back, which counts the same.
  ///
  /// The two callers are the answer and the abandonment, and they are one call because the count
  /// cannot tell them apart: an item whose consumer hung up, or one a rewind retracted, is an item
  /// no answer is ever coming for. Leaving those uncounted would hold a key `Analyzing` forever
  /// over work that no longer exists.
  #[inline]
  pub(crate) fn observed(&self, key: &Root) {
    let _late = self.table.observed(key, self.stamp);
  }
}

/// EVERY ROOT FAMILY'S TABLE, held as one — the framework's own runtime component.
///
/// See the [module note](self) for what it is, what it deliberately is not, and how a family comes
/// to exist.
pub struct Registries {
  /// The graph-level document — `[registry]`'s defaults and whatever families it named their own
  /// words for. Kept whole so that a family opened later resolves against the same document the
  /// first one did.
  options: RegistryOptions,
  /// One typed table per family, behind the one erasure this design pays — see the module note.
  by_family: RwLock<HashMap<TypeId, Arc<dyn Any + Send + Sync>>>,
  /// The SAME tables, a second time, under the ONE erasure a STRING-KEYED reader needs — see
  /// [`expose`](Self::expose) and [`dyn_for`](Self::dyn_for).
  ///
  /// A second map rather than a second lookup into `by_family`, because the two are keyed on
  /// different axes for reasons neither can absorb: `by_family` is keyed on [`TypeId`] because a
  /// typed caller supplies the type and asks the map to confirm it, while this one is keyed on the
  /// family's OWN NAME because a wire caller — a GraphQL `family: String` argument — has nothing
  /// else to supply. Nothing here is opened by [`open`](Self::open) or
  /// [`counting`](Self::counting): a family becomes reachable by name only where something calls
  /// [`expose`](Self::expose) for it, which is additional to opening rather than a consequence of it
  /// — see that door's own note for why a NEW bound is the reason.
  ///
  /// Behind the SAME feature the door itself rides — see `registry::dynamic`'s own module note for
  /// why this seam is gated where [`RetiredLedger`]'s is not.
  #[cfg(feature = "async-graphql")]
  by_name: RwLock<HashMap<Utf8Bytes, Arc<dyn DynRegistry>>>,
}

/// Written rather than derived, for [`Registry`]'s own reason one door over: the erased maps carry
/// no [`Debug`](core::fmt::Debug) of their own, and what a reader of a start-up log wants is the
/// arity — how many families this world has opened, and how many of them a wire caller can reach by
/// name.
impl core::fmt::Debug for Registries {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    let mut debug = f.debug_struct("Registries");
    debug.field("options", &self.options);
    debug.field("families", &self.families());
    #[cfg(feature = "async-graphql")]
    debug.field("named", &self.read_names().len());
    debug.finish()
  }
}

impl Registries {
  /// No family opened yet, and every one that will be opened running `options`.
  #[must_use]
  pub fn new(options: RegistryOptions) -> Self {
    Self {
      options,
      by_family: RwLock::new(HashMap::new()),
      #[cfg(feature = "async-graphql")]
      by_name: RwLock::new(HashMap::new()),
    }
  }

  /// The graph-level document every family resolves against.
  #[inline]
  #[must_use]
  pub const fn options(&self) -> &RegistryOptions {
    &self.options
  }

  /// **OPEN `Root`'s TABLE**, minting it at `family`'s own resolved options on first ask and
  /// handing back the same one ever after.
  ///
  /// `family` is the lowercase spelling of the root type — `media` for `MediaId` — and it is what
  /// [`RegistryOptions::for_family`] resolves against. It is read on the FIRST ask only: a family
  /// is opened once, and the name a later caller passes cannot re-tune a table already in use.
  /// Callers that hold the emitted projection pass
  /// [`Attributes::FAMILY`](crate::Attributes::FAMILY); a caller that has no name passes `""`,
  /// which resolves to the shipped defaults exactly as an unwritten section does.
  pub fn open<Root: RootKey>(&self, family: &str) -> Arc<Registry<Root>> {
    if let Some(open) = self.of::<Root>() {
      return open;
    }
    let mut families = self.write();
    // Asked again under the WRITE lock, because two threads may both have missed above and only one
    // of them may mint: the loser takes the winner's table rather than replacing it.
    let entry = families
      .entry(TypeId::of::<Root>())
      .or_insert_with(|| Arc::new(Registry::<Root>::new(self.options.for_family(family))));
    Arc::clone(entry)
      .downcast::<Registry<Root>>()
      .unwrap_or_else(|_| unreachable!("a family's table is keyed by its own root type"))
  }

  /// **`Root`'s TABLE, IF SOMEBODY HAS ALREADY OPENED IT** — the read that mints nothing.
  ///
  /// `None` is an honest answer rather than a defect: a family exists once something in this
  /// deployment attributes work to it, so a query face asking about a family no node feeds is
  /// asking about a family that has nothing to say.
  #[must_use]
  pub fn of<Root: RootKey>(&self) -> Option<Arc<Registry<Root>>> {
    let families = self.read();
    let table = families.get(&TypeId::of::<Root>())?;
    Arc::clone(table).downcast::<Registry<Root>>().ok()
  }

  /// **THE TABLE A DRIVER COUNTS THROUGH**, or [`None`] where this node's work belongs to no
  /// family at all.
  ///
  /// [`open`](Self::open) with the one refusal a counting site needs, stated HERE so that it is
  /// stated once: `Root = ()` is [`Attributes for ()`](crate::Attributes) — *the absence spelled as
  /// a type* — and a node carrying it has no projection, not a projection whose root happens to be
  /// the unit.
  ///
  /// Counting one would be worse than useless. Every unattributed node in a deployment shares that
  /// one `Root`, so they would all pile into a single family under a single key `()`, whose
  /// inflight would be the whole graph's and whose `Analyzing` would never end. The refusal is a
  /// [`TypeId`] comparison against a type both sides know at compile time, so it costs nothing at
  /// run time and is not a knob anybody can get wrong.
  ///
  /// It OPENS rather than reads, because a dispatch is what mints a family: nothing else in a
  /// deployment names one, so a counting site that only ever asked [`of`](Self::of) would find
  /// nothing to count into for as long as it ran.
  #[must_use]
  pub fn counting<Root: RootKey>(&self, family: &str) -> Option<Arc<Registry<Root>>> {
    (TypeId::of::<Root>() != TypeId::of::<()>()).then(|| self.open::<Root>(family))
  }

  /// How many families are open.
  #[must_use]
  pub fn families(&self) -> usize {
    self.read().len()
  }

  /// Whether any family is open.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.families() == 0
  }

  /// **OPEN `Root`'s TABLE AND MAKE IT REACHABLE BY NAME** — [`open`](Self::open), plus the one
  /// thing a STRING-KEYED caller needs that a typed one does not.
  ///
  /// # Why a SEPARATE door, rather than `open` doing this always
  ///
  /// `open` asks [`RootKey`] alone — [`Clone`], [`Eq`], [`Hash`], [`Send`], [`Sync`], `'static` — and
  /// that bound is [`Drives`](crate::Drives)'s own, paid by every emitted [`Attributes`]
  /// projection with nothing further to state. Reaching a family by its WIRE NAME asks for two
  /// things `open`'s callers were never asked to supply: a `key` argument a client sent has to
  /// PARSE into `Root`, and a key this table already holds has to RENDER back out as the string a
  /// client sent it as. Widening `open` — or [`RootKey`] itself — to demand
  /// [`Display`](core::fmt::Display) and [`FromStr`](core::str::FromStr) from every family in every
  /// deployment would tax the counting path, which never once needs a key as text, to pay for a face
  /// only a wire caller reaches for. So the wire bound is asked HERE, at the one door that needs it,
  /// and [`open`](Self::open)/[`counting`](Self::counting) stay exactly as wide as they were.
  ///
  /// # It is additional, not automatic
  ///
  /// A family a node counts into through [`counting`](Self::counting) is NOT reachable by name until
  /// something ALSO calls this for it — the same posture [`crate::graphql`]'s own note states for
  /// the attribution itself: the seat exists, and installing it is a step a deployment takes rather
  /// than one this table takes for it. Calling this for a family already open widens nothing about
  /// its table — it is [`open`](Self::open) underneath, and minting happens at most once — it only
  /// adds the family to the name-keyed door.
  ///
  /// Idempotent, and safe to call from more than one site for the SAME family: the second call finds
  /// the same [`Arc`] `open` already minted and re-states the same name-keyed entry.
  #[cfg(feature = "async-graphql")]
  #[must_use]
  pub fn expose<Root>(&self, family: &str) -> Arc<Registry<Root>>
  where
    Root: RootKey + core::fmt::Display + core::str::FromStr,
  {
    let table = self.open::<Root>(family);
    let mut named = self.write_names();
    named.insert(
      Utf8Bytes::from(family),
      Arc::clone(&table) as Arc<dyn DynRegistry>,
    );
    table
  }

  /// **THE FAMILY NAMED `family`, REACHABLE BY STRING** — what a GraphQL `family: String` argument
  /// resolves through, or [`None`] where nothing has [`expose`](Self::expose)d that name yet.
  ///
  /// `None` is the SAME honest answer [`of`](Self::of) gives a typed caller asking about a family
  /// nothing has opened: family names are OPEN (see [`RegistryOptions`]'s own module note), so an
  /// unrecognised one is a name nothing has claimed rather than a mistake this door refuses.
  #[cfg(feature = "async-graphql")]
  #[must_use]
  pub(crate) fn dyn_for(&self, family: &str) -> Option<Arc<dyn DynRegistry>> {
    self.read_names().get(family).map(Arc::clone)
  }

  /// The family map, read — poison read through, on [`Registry::shard`]'s own reasoning.
  fn read(&self) -> RwLockReadGuard<'_, HashMap<TypeId, Arc<dyn Any + Send + Sync>>> {
    self
      .by_family
      .read()
      .unwrap_or_else(|held| held.into_inner())
  }

  /// The family map, written.
  fn write(&self) -> RwLockWriteGuard<'_, HashMap<TypeId, Arc<dyn Any + Send + Sync>>> {
    self
      .by_family
      .write()
      .unwrap_or_else(|held| held.into_inner())
  }

  /// The name-keyed map, read — poison read through, [`read`](Self::read)'s own idiom.
  #[cfg(feature = "async-graphql")]
  fn read_names(&self) -> RwLockReadGuard<'_, HashMap<Utf8Bytes, Arc<dyn DynRegistry>>> {
    self.by_name.read().unwrap_or_else(|held| held.into_inner())
  }

  /// The name-keyed map, written.
  #[cfg(feature = "async-graphql")]
  fn write_names(&self) -> RwLockWriteGuard<'_, HashMap<Utf8Bytes, Arc<dyn DynRegistry>>> {
    self
      .by_name
      .write()
      .unwrap_or_else(|held| held.into_inner())
  }
}

impl Default for Registries {
  /// Every family at the shipped defaults — what a deployment that wrote no `[registry]` section
  /// gets, and what a hand-wired arrangement that named none runs.
  #[inline]
  fn default() -> Self {
    Self::new(RegistryOptions::new())
  }
}