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
//! ONE ROW of the validate walk's answer, and the payloads the rows are read through.
//!
//! # Why a row and not an error
//!
//! The validate walk COLLECTS. Its checks are independent and side-effect-free, so stopping at the
//! first one would be telling an operator about one of their problems and hiding the rest behind a
//! restart — and the whole value of checking at start-up is that the deployment can be fixed in one
//! pass. So each check appends a [`Refusal`] and the walk keeps going;
//! [`LaunchError::Refused`](super::LaunchError::Refused) is the list.
//!
//! The CREATE walk that follows is the opposite and for the opposite reason: it builds things, so
//! its failures are not independent — the second construction runs in a world the first one already
//! changed. It stops at the first.
//!
//! # The order is a reading order
//!
//! Rows come out in the order the walk states them, and that order is chosen for a reader rather
//! than to suppress anything: a name that names nothing comes first because everything after it
//! describes the deployment as literally written — in which the node a typo meant to name is
//! ABSENT, and therefore not launched. The rows that follow are the honest consequences, not noise.

use smol_bytes::Utf8Bytes;

use crate::{
  arrange::{EdgeId, NodeId},
  resource::{ResourceKind, ResourceName},
};

#[cfg(test)]
mod tests;

/// The payload of [`Refusal::UnknownNode`]: the name the options used.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownNodeError {
  name: Utf8Bytes,
}

impl UnknownNodeError {
  #[inline]
  pub(crate) const fn new(name: Utf8Bytes) -> Self {
    Self { name }
  }

  /// The name that names nothing.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }
}

/// The payload of [`Refusal::UndeclaredResource`]: the node that demanded, its name, and the
/// resource nothing declared.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UndeclaredResourceError {
  node: NodeId,
  name: Utf8Bytes,
  resource: &'static ResourceName,
}

impl UndeclaredResourceError {
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes, resource: &'static ResourceName) -> Self {
    Self {
      node,
      name,
      resource,
    }
  }

  /// The node holding the `Shared<R>` field.
  #[inline]
  #[must_use]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }

  /// The resource it demanded — the compiler's own path for the type, so a reader can find it.
  #[inline]
  #[must_use]
  pub const fn resource(&self) -> &'static ResourceName {
    self.resource
  }
}

/// The payload of [`Refusal::UnboundSlot`]: the corpus that named no resource, the KIND it needs,
/// and every resource this deployment declared that could have held it.
///
/// # It carries the CANDIDATES, and it is the first refusal in this family that lists anything
///
/// The two ways a sole default fails are one variant and two sentences, and the candidate list is
/// what tells them apart without a second shape: EMPTY means the deployment declared nothing that
/// could hold this corpus, and SEVERAL means the choice is real and is the deployment's to make.
/// Printing them is not a courtesy — it is the whole fix, because the leg is repaired by writing
/// `resource = "…"` and the list is where the spelling comes from.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnboundSlotError {
  slot: Utf8Bytes,
  kind: ResourceKind,
  candidates: Vec<&'static ResourceName>,
}

impl UnboundSlotError {
  #[inline]
  pub(crate) const fn new(
    slot: Utf8Bytes,
    kind: ResourceKind,
    candidates: Vec<&'static ResourceName>,
  ) -> Self {
    Self {
      slot,
      kind,
      candidates,
    }
  }

  /// The corpus, by its durable name — `<index>__<field>__<label>`, which is what an author greps
  /// for to find the leg.
  #[inline]
  #[must_use]
  pub fn slot(&self) -> &str {
    self.slot.as_str()
  }

  /// What the corpus needs a resource to hold.
  #[inline]
  #[must_use]
  pub const fn kind(&self) -> ResourceKind {
    self.kind
  }

  /// Every declared resource that could have held it, in name order.
  #[inline]
  #[must_use]
  pub fn candidates(&self) -> &[&'static ResourceName] {
    &self.candidates
  }

  /// The candidate list as a sentence — the half the `Display` row splices in.
  ///
  /// A function rather than a formatting expression, because the two arms are two different
  /// SENTENCES and not one sentence with a list in it: nothing declared is a *declare one* and
  /// several declared is a *choose one*, and a reader gets the instruction that applies.
  #[must_use]
  pub fn advice(&self) -> String {
    if self.candidates.is_empty() {
      return format!(
        "this deployment declares no resource that holds {kind}; declare one with \
         `#[ingraph::resource(…)]` and mount it on the graph root",
        kind = self.kind,
      );
    }
    let listed = self
      .candidates
      .iter()
      .map(|name| format!("`{}`", name.as_str()))
      .collect::<Vec<_>>()
      .join(", ");
    format!(
      "this deployment declares {count} resources that hold {kind} ({listed}), and choosing \
       between them is not this framework's to do; write `resource = \"…\"` on the leg",
      count = self.candidates.len(),
      kind = self.kind,
    )
  }
}

/// The payload of [`Refusal::PureLeaf`]: the node that lands nothing, publishes to nobody and
/// polls nothing, and its name.
///
/// # AN ORPHAN HEAD IS THIS, and there is no second word for it
///
/// A SOURCE nobody listens to — an origin mounted as a dataflow head with no consumer — is refused
/// here and nowhere else, and the word is not a rename waiting to happen. The vocabulary is named
/// after WHAT IS WRONG rather than after WHO it happened to, which is the same clause
/// [`ErrorCode`](crate::ErrorCode)'s derivation rule states one layer out: *this computes into
/// nothing* is one mistake whether the node that computes into nothing has an upstream or is the
/// head of the whole arrangement, and a head-shaped family beside this one would be two refusals for
/// one thing.
///
/// It works for the origin layer without knowing about it, which is what makes the mapping honest
/// rather than a coincidence: an origin's declared effect is the PURE one — it lands nothing, what
/// it produces becoming durable wherever its consumers land it — so the check that was already here
/// fires on the shape. See [`Blueprint::origin`](super::Blueprint::origin), which is where that
/// effect is stated.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PureLeafError {
  node: NodeId,
  name: Utf8Bytes,
}

impl PureLeafError {
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
    Self { node, name }
  }

  /// The node that computes into nothing.
  #[inline]
  #[must_use]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }
}

/// The payload of [`Refusal::LandsNowhere`]: the node that says it lands, and its name.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LandsNowhereError {
  node: NodeId,
  name: Utf8Bytes,
}

impl LandsNowhereError {
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
    Self { node, name }
  }

  /// The node whose claim nothing keeps.
  #[inline]
  #[must_use]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }
}

/// The payload of [`Refusal::FeederAbsent`]: the change-feed edge, and both of its ends by name.
///
/// Both ends, because the sentence has to name the WATCHED store's node — that is the one the
/// operator would go and give a lander to — as well as the listener that would have waited forever.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FeederAbsentError {
  edge: EdgeId,
  consumer: NodeId,
  consumer_name: Utf8Bytes,
  watched: NodeId,
  watched_name: Utf8Bytes,
}

impl FeederAbsentError {
  #[inline]
  pub(crate) const fn new(
    edge: EdgeId,
    consumer: NodeId,
    consumer_name: Utf8Bytes,
    watched: NodeId,
    watched_name: Utf8Bytes,
  ) -> Self {
    Self {
      edge,
      consumer,
      consumer_name,
      watched,
      watched_name,
    }
  }

  /// The edge that would have listened.
  #[inline]
  #[must_use]
  pub const fn edge(&self) -> EdgeId {
    self.edge
  }

  /// The listening node.
  #[inline]
  #[must_use]
  pub const fn consumer(&self) -> NodeId {
    self.consumer
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn consumer_name(&self) -> &str {
    self.consumer_name.as_str()
  }

  /// The node whose store the edge watches.
  #[inline]
  #[must_use]
  pub const fn watched(&self) -> NodeId {
    self.watched
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn watched_name(&self) -> &str {
    self.watched_name.as_str()
  }
}

/// The payload of [`Refusal::DisabledUpstream`]: the edge and both of its ends by name.
///
/// WHY the upstream is dark takes no field: presence is the only enablement axis, so a node that is
/// not running is a node no section named, and the refusal's own sentence says so.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DisabledUpstreamError {
  edge: EdgeId,
  consumer: NodeId,
  consumer_name: Utf8Bytes,
  producer: NodeId,
  producer_name: Utf8Bytes,
}

impl DisabledUpstreamError {
  #[inline]
  pub(crate) const fn new(
    edge: EdgeId,
    consumer: NodeId,
    consumer_name: Utf8Bytes,
    producer: NodeId,
    producer_name: Utf8Bytes,
  ) -> Self {
    Self {
      edge,
      consumer,
      consumer_name,
      producer,
      producer_name,
    }
  }

  /// The edge that would starve.
  #[inline]
  #[must_use]
  pub const fn edge(&self) -> EdgeId {
    self.edge
  }

  /// The listening node.
  #[inline]
  #[must_use]
  pub const fn consumer(&self) -> NodeId {
    self.consumer
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn consumer_name(&self) -> &str {
    self.consumer_name.as_str()
  }

  /// The node this deployment does not launch.
  #[inline]
  #[must_use]
  pub const fn producer(&self) -> NodeId {
    self.producer
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn producer_name(&self) -> &str {
    self.producer_name.as_str()
  }
}

/// The payload of [`Refusal::UnbridgedOrigin`]: the edge no bridge can open, and both of its ends by
/// name.
///
/// Both ends, for [`FeederAbsentError`]'s reason and with the same shape: the sentence has to name
/// the ORIGIN — the one being asked for something it does not have — and the consumer that would
/// have waited forever for it.
///
/// # WHAT IT MEANS NOW, since the bridge landed
///
/// The row's subject is unchanged — *this origin's items reach no intake* — and what changed is
/// where that is still true. A CHANNEL edge from an origin is opened: the origin's feed IS that edge
/// and the items flow ([`Feed::bridging`](crate::Feed::bridging)). The other three words a consumer
/// can listen by ask an origin for something else entirely, and an origin has none of it: an origin
/// LANDS NOTHING, so there is no store for a `changes` feed to report or a `poll` tick to sweep, and
/// it answers nobody, so there is no door for a `transient` query arm to knock on. The word, not the
/// wiring, is what is wrong — so the fix in the sentence is the word.
///
/// # It is a DEPLOYMENT fact, and that is what keeps it out of the arrangement's own refusals
///
/// The edge is legal and the arrangement is honest: an origin with a consumer is exactly what keeps
/// it from being a leaf that computes into nothing, and the whole declared-mount suite is built on
/// arrangements shaped that way. What this row is about is a deployment that LAUNCHES BOTH ENDS of
/// one — and only then does the consumer's word become a claim about a running origin.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnbridgedOriginError {
  edge: EdgeId,
  origin: NodeId,
  origin_name: Utf8Bytes,
  consumer: NodeId,
  consumer_name: Utf8Bytes,
  listen: &'static str,
}

impl UnbridgedOriginError {
  #[inline]
  pub(crate) const fn new(
    edge: EdgeId,
    origin: NodeId,
    origin_name: Utf8Bytes,
    consumer: NodeId,
    consumer_name: Utf8Bytes,
    listen: &'static str,
  ) -> Self {
    Self {
      edge,
      origin,
      origin_name,
      consumer,
      consumer_name,
      listen,
    }
  }

  /// The word the consumer listened by — [`Listen::as_str`](crate::Listen::as_str)'s own spelling,
  /// which is what a refusal and a log line identify an edge's mode as.
  #[inline]
  #[must_use]
  pub const fn listen(&self) -> &'static str {
    self.listen
  }

  /// The edge nothing opens.
  #[inline]
  #[must_use]
  pub const fn edge(&self) -> EdgeId {
    self.edge
  }

  /// The origin whose feed reaches nobody.
  #[inline]
  #[must_use]
  pub const fn origin(&self) -> NodeId {
    self.origin
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn origin_name(&self) -> &str {
    self.origin_name.as_str()
  }

  /// The node that would have listened.
  #[inline]
  #[must_use]
  pub const fn consumer(&self) -> NodeId {
    self.consumer
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn consumer_name(&self) -> &str {
    self.consumer_name.as_str()
  }
}

/// The payload of [`Refusal::SplitOrigin`]: the origin, and every launched consumer pulling at its
/// one feed.
///
/// # An origin has ONE feed, and a feed has one far end
///
/// A node that fans out publishes through a [`Downstream`](crate::Downstream) set, whose own
/// [`Sink`](crate::Sink) row demands `T: Clone` — copying is what fanning out IS. An origin's
/// [`Yield`](crate::Source::Yield) carries no such bound and deliberately: a source hands over what
/// it produced, once, and a face that demanded a copy of it would refuse every origin whose item is
/// a handle, a file, a decoded frame it does not own twice.
///
/// So the two facts do not meet, and the honest place to say so is here rather than in a bound that
/// would narrow the origin face for everybody. THE FIX IS AN OPERATOR: a pass-through node
/// immediately downstream of the origin fans out through the road that already knows how, on a type
/// its own declaration says is copyable.
///
/// # Every consumer is NAMED, not counted
///
/// The count is the number in the sentence and the names are what an operator acts on: a deployment
/// with three listeners on one origin is fixed by knowing WHICH three, and a row that said *three*
/// would send its reader back to the graph to find out.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SplitOriginError {
  origin: NodeId,
  origin_name: Utf8Bytes,
  consumers: Vec<Utf8Bytes>,
}

impl SplitOriginError {
  #[inline]
  pub(crate) const fn new(
    origin: NodeId,
    origin_name: Utf8Bytes,
    consumers: Vec<Utf8Bytes>,
  ) -> Self {
    Self {
      origin,
      origin_name,
      consumers,
    }
  }

  /// The origin whose one feed is being pulled at from several sides.
  #[inline]
  #[must_use]
  pub const fn origin(&self) -> NodeId {
    self.origin
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn origin_name(&self) -> &str {
    self.origin_name.as_str()
  }

  /// Every launched consumer of it, in the graph's own edge order.
  #[inline]
  #[must_use]
  pub fn consumers(&self) -> &[Utf8Bytes] {
    &self.consumers
  }

  /// How many there are — the number the sentence leads with.
  #[inline]
  #[must_use]
  pub fn count(&self) -> usize {
    self.consumers.len()
  }

  /// The consumers as one comma-separated list, for the sentence.
  fn listed(&self) -> String {
    self
      .consumers
      .iter()
      .map(|name| format!("`{}`", name.as_str()))
      .collect::<Vec<_>>()
      .join(", ")
  }
}

/// The payload of [`Refusal::DroppingUnbounded`]: the node, its name, and WHICH of its upstreams
/// resolved to an edge nothing bounds.
///
/// The upstream is a POSITION, which is the same currency the resolution speaks: a document's
/// `[node.channels]` key, a declaration's `channel = …` word and a [`PollUpstream`](crate::PollUpstream)
/// are all numbered by declaration order, so a position is what an operator can walk back to the
/// word they wrote.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DroppingUnboundedError {
  node: NodeId,
  name: Utf8Bytes,
  upstream: usize,
}

impl DroppingUnboundedError {
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes, upstream: usize) -> Self {
    Self {
      node,
      name,
      upstream,
    }
  }

  /// The node whose edge nothing bounds.
  #[inline]
  #[must_use]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// Its declared name.
  #[inline]
  #[must_use]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }

  /// Which of its declared channel upstreams, in declaration order.
  #[inline]
  #[must_use]
  pub const fn upstream(&self) -> usize {
    self.upstream
  }
}

/// ONE thing wrong with a deployment, as [`Plan::validate`](super::Plan::validate) found it.
///
/// Variants are declared in the walk's own order, which is the order a report reads in.
///
/// The rendering is derived per variant rather than written as one `match`, which keeps each
/// sentence beside the variant it describes; the payloads are read through their accessors and
/// nothing is computed on the way out.
#[derive(
  Debug,
  Clone,
  PartialEq,
  Eq,
  derive_more::Display,
  derive_more::IsVariant,
  derive_more::Unwrap,
  derive_more::TryUnwrap,
)]
#[unwrap(ref, ref_mut)]
#[try_unwrap(ref, ref_mut)]
#[non_exhaustive]
pub enum Refusal {
  /// The options name a node the arrangement does not declare — a misspelling, or a node that has
  /// since been removed.
  #[display("the options name `{}`, which this arrangement does not declare", _0.name())]
  UnknownNode(UnknownNodeError),
  /// An ENABLED node demands a resource nothing declared, so there would be nothing to build and
  /// nothing to hand it.
  #[display(
    "{} (`{}`) demands the resource `{}`, which no declaration registered; \
     declare it with `#[ingraph::resource]`",
    _0.node(), _0.name(), _0.resource().as_str()
  )]
  UndeclaredResource(Box<UndeclaredResourceError>),
  /// An enabled node lands nothing, publishes to nobody, polls nothing and answers nobody, so
  /// nothing it computes can be observed.
  #[display(
    "{} (`{}`) lands nothing, publishes to nobody, polls nothing and answers nobody; \
     give it a consumer, a store, a poll upstream, or a query arm",
    _0.node(), _0.name()
  )]
  PureLeaf(PureLeafError),
  /// An enabled node declares [`Effect::Lands`](crate::Effect::Lands) and has neither of the two
  /// things that make a landing real: no write lane of its own, and nobody to publish to.
  ///
  /// The pure leaf's twin, and the other way round. That one computes and nothing keeps the result;
  /// this one SAYS the result is kept and nothing does the keeping — a node whose ack answers
  /// *persisted* over a write that happens nowhere, which is worse than a wasted cycle because
  /// everything downstream of the claim believes it.
  #[display(
    "{} (`{}`) declares that it lands, and holds no write lane and publishes to nobody; \
     give it a lane of its own, or a consumer that lands what it emits",
    _0.node(), _0.name()
  )]
  LandsNowhere(LandsNowhereError),
  /// An enabled node listens on the CHANNEL of a node this deployment does not launch, so it would
  /// wait for a message that is never sent. Listening to that node's STORE instead is legal and is
  /// the reindex posture.
  #[display(
    "{} (`{}`) listens on the channel of {} (`{}`), which this deployment does not launch (no \
     section names it); listen to its changes instead, or launch it",
    _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
  )]
  DisabledUpstream(Box<DisabledUpstreamError>),
  /// An enabled node's QUERY edge comes from a node this deployment does not launch — the dark
  /// embedder under a running index.
  ///
  /// Its own variant rather than [`DisabledUpstream`](Self::DisabledUpstream)'s sentence, because
  /// the escape is not the same one: a starved channel listener can read the upstream's STORE
  /// instead, and a starved query edge cannot — the unlaunched node computes the query's own input,
  /// which no store holds because nobody has asked the question yet.
  #[display(
    "{} (`{}`) takes its query edge from {} (`{}`), which this deployment does not launch (no \
     section names it); a query has no store to fall back on, so launch it",
    _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
  )]
  DisabledQueryUpstream(Box<DisabledUpstreamError>),
  /// An enabled node listens to the CHANGES of a store this graph has no hand in filling, and did
  /// not say so.
  ///
  /// A default `changes(<db>)` is a claim about the graph — *somebody here lands into that store* —
  /// and this is the deployment where nobody does. Left alone it starts, waits, and reports nothing:
  /// a feed with no writer looks exactly like a feed with nothing new. The sentence teaches THREE
  /// ROADS because there are exactly three, and which one is right is the operator's to know: the
  /// store really is filled from another process (say `external`), or this graph should be reading
  /// what the node itself emits (point `upstream` at it — the in-graph geometry), or the lander is
  /// simply missing and belongs in the deployment.
  #[display(
    "{} (`{}`) listens to the changes of {} (`{}`), and no node of this graph lands into that \
     store; say `external` if the store is filled from another process, or subscribe to `{}` \
     directly if you meant the in-graph geometry, or add the node that lands into it",
    _0.consumer(), _0.consumer_name(), _0.watched(), _0.watched_name(), _0.watched_name()
  )]
  FeederAbsent(Box<FeederAbsentError>),
  /// An enabled node listens to an enabled ORIGIN, and nothing joins the two: the origin's feed
  /// comes back in [`Mounted`](super::Mounted) and the consumer's inbox is fed by nobody.
  ///
  /// **A consumer listens to an origin by a word an origin cannot be heard through.**
  ///
  /// A CHANNEL edge from an origin is opened — the origin's feed IS that edge, minted by
  /// [`Ignition::origin_bridged`](super::Ignition::origin_bridged) — so the ordinary subscription
  /// reaches an origin exactly as it reaches a node. The other three words do not, and cannot: an
  /// origin's effect is the PURE one, so there is no store for `changes` to report or `poll` to
  /// sweep, and it runs a life rather than answering calls, so there is no door for a `transient`
  /// query arm. The plan holds an edge whose word asks for machinery the producer does not have, and
  /// until this row existed the consumer waited on it forever and nothing said why.
  ///
  /// It is not [`DisabledUpstream`](Self::DisabledUpstream)'s sentence one axis over. That row is
  /// about a producer this deployment does not LAUNCH — the fix is to launch it or to read its store
  /// — and here the producer is launched and running, and the fix is a WORD: subscribe over the
  /// channel, which is what an origin publishes on.
  #[display(
    "{} (`{}`) listens to the origin {} (`{}`) by `{}`, and an origin has nothing to be heard \
     through that word with: it lands nothing, so there is no store to watch or poll, and it answers \
     nobody, so there is no door to ask; subscribe to `{}` over the channel, which is what an origin \
     publishes on",
    _0.consumer(), _0.consumer_name(), _0.origin(), _0.origin_name(), _0.listen(), _0.origin_name()
  )]
  UnbridgedOrigin(Box<UnbridgedOriginError>),
  /// **One origin, several launched consumers — and an origin has ONE feed.**
  ///
  /// The bridge hands an origin the consumer's own inbox as its feed, which is what makes the bound
  /// single and the teardown exact. There is no second one to hand out: fanning a message to several
  /// edges is copying it, and the [`Downstream`](crate::Downstream) set that does it demands
  /// `T: Clone` — a bound the origin face declines, because a source hands over what it produced
  /// once. See [`SplitOriginError`] for the whole of that argument and for the fix, which is an
  /// operator immediately downstream.
  ///
  /// A DEPLOYMENT fact, exactly as [`UnbridgedOrigin`](Self::UnbridgedOrigin) is: an arrangement may
  /// declare an origin with any number of consumers, and what is refused is a deployment that
  /// launches more than one of them.
  #[display(
    "{} (`{}`) is an origin and this deployment launches {} consumers of it ({}), but an origin has \
     ONE feed and it becomes ONE edge — put a pass-through operator under `{}` and fan out from \
     there, or launch one of them",
    _0.origin(), _0.origin_name(), _0.count(), _0.listed(), _0.origin_name()
  )]
  SplitOrigin(Box<SplitOriginError>),
  /// A node's declaration draws from an upstream THIS ROOT DOES NOT MOUNT.
  ///
  /// The join's own refusal, and it is a fact about the CATALOG rather than about a deployment: a
  /// declaration names its upstream by TYPE and the root's fields are the whole set of types there
  /// are, so an upstream missing from them is missing from every deployment of this root. A
  /// deployment that merely leaves a mounted upstream's section unwritten is a different thing and
  /// has its own sentence — see [`DisabledUpstream`](Self::DisabledUpstream).
  #[display(
    "`{}` subscribes to `{}`, which this graph root does not mount; give the root a field for it, \
     or point the subscription at a node the root declares",
    _0.node(), _0.upstream()
  )]
  UnknownUpstream(UnknownUpstreamError),
  /// A node's declaration GRANTS itself the right to write into a node THIS ROOT DOES NOT MOUNT.
  ///
  /// [`UnknownUpstream`](Self::UnknownUpstream)'s twin on the permission axis, and a fact about the
  /// CATALOG for the same reason: a grant names its store by TYPE and the root's fields are the
  /// whole set of types there are, so a grant missing from them is missing from every deployment.
  ///
  /// What it is NOT is a deployment fact. A grant on a mounted node this deployment does not LAUNCH
  /// is legal and is the poll mode's own point — collecting a dead node's garbage is exactly the
  /// work that outlives the node.
  #[display(
    "`{}`'s `{}` clock grants itself `write = \"{}\"`, which this graph root does not mount; give \
     the root a field for it, or point the grant at a node the root declares",
    _0.node(), _0.clock(), _0.granted()
  )]
  UnknownGrant(UnknownGrantError),
  /// A node's declaration grants itself the right to write into a mounted node that KEEPS NO STORE.
  ///
  /// The grant resolves and there is still nothing behind it: a pure node's output is computed and
  /// gone, so there is no store for a sweep to reach into. It is the contradiction
  /// [`LandsNowhere`](Self::LandsNowhere) refuses one axis over — a claim about durability with no
  /// durability under it — read from the granting end rather than from the landing one.
  ///
  /// The emitted context cannot answer this and does not pretend to: it mints the write socket the
  /// word asked for, because the granting node's own derive cannot see the granted node's
  /// declaration. This walk is the one vantage where both are in view.
  #[display(
    "`{}`'s `{}` clock grants itself `write = \"{}\"`, and `{}` keeps no store to write into — a \
     pure node's output is computed and gone; grant a node that lands, or drop the word",
    _0.node(), _0.clock(), _0.granted(), _0.mount()
  )]
  GrantsNoStore(GrantsNoStoreError),
  /// An enabled node's edge resolved to UNBOUNDED under an
  /// [`OverflowPolicy`](crate::OverflowPolicy) that can shed.
  ///
  /// The two words contradict each other: nothing overflows a queue nothing bounds, so the shed
  /// would never happen — and a deployment that believes it is dropping under pressure while its
  /// memory grows without limit is worse off than one told at start-up. It is read on the RESOLVED
  /// kind rather than on any one layer's word, because the edge that results is the thing that can
  /// or cannot overflow.
  #[display(
    "{} (`{}`) opens its upstream #{} unbounded, and this deployment's overflow policy sheds; \
     nothing overflows a queue nothing bounds — bound the edge, or run a policy that blocks",
    _0.node(), _0.name(), _0.upstream()
  )]
  DroppingUnbounded(Box<DroppingUnboundedError>),
  /// A corpus whose leg named NO resource, and the deployment's own catalog could not decide for it.
  ///
  /// # The SOLE-DEFAULT law, from the side where it did not apply
  ///
  /// A leg that writes no `resource = "…"` is bound by the catalog: exactly ONE kind-compatible
  /// resource declared and the leg takes it, silently and correctly. This row is both other cases —
  /// none declared, or several — and the payload's own [`advice`](UnboundSlotError::advice) is what
  /// tells them apart, because the fixes are different sentences rather than one sentence with a
  /// number in it.
  ///
  /// It is a START-UP refusal and not a compile error, and that is the axis rather than a
  /// concession: which resources exist is a DEPLOYMENT's fact, written at a graph root that the
  /// declaring library never sees. A leg is written once and bound per deployment, so the binding
  /// can only be checked where the catalog is.
  #[display(
    "the `{}` corpus names no resource, and {}",
    _0.slot(), _0.advice()
  )]
  UnboundSlot(Box<UnboundSlotError>),
  /// The declared edges do not make an arrangement — a cycle through the declarations.
  ///
  /// The arrangement layer's own refusal, carried in the collect-all list because it is that kind
  /// of answer: structural, side-effect-free, and about the DECLARATIONS rather than about anything
  /// a deployment wrote. What it holds is that layer's own sentence, which already names the node
  /// the cycle runs through.
  #[display("{}", _0.sentence())]
  Arrangement(ArrangementError),
}

/// The payload of [`Refusal::UnknownUpstream`]: who subscribed, and to what.
///
/// The upstream is the PATH the declaration wrote rather than a mount name, because there is no
/// mount — that is the whole refusal. A reader looking for the fix reads back the string they typed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownUpstreamError {
  node: Utf8Bytes,
  upstream: &'static str,
}

impl UnknownUpstreamError {
  #[inline]
  pub(crate) const fn new(node: Utf8Bytes, upstream: &'static str) -> Self {
    Self { node, upstream }
  }

  /// The mount whose declaration named it.
  #[inline]
  #[must_use]
  pub fn node(&self) -> &str {
    self.node.as_str()
  }

  /// The upstream path that names nothing this root mounts.
  #[inline]
  #[must_use]
  pub const fn upstream(&self) -> &'static str {
    self.upstream
  }
}

/// The payload of [`Refusal::UnknownGrant`]: who granted itself the write, from which clock, and
/// over what.
///
/// The granted node is the PATH the declaration wrote rather than a mount name, for
/// [`UnknownUpstreamError`]'s reason: there is no mount — that is the whole refusal — and a reader
/// looking for the fix reads back the string they typed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownGrantError {
  node: Utf8Bytes,
  clock: &'static str,
  granted: &'static str,
}

impl UnknownGrantError {
  #[inline]
  pub(crate) const fn new(node: Utf8Bytes, clock: &'static str, granted: &'static str) -> Self {
    Self {
      node,
      clock,
      granted,
    }
  }

  /// The mount whose declaration wrote the grant.
  #[inline]
  #[must_use]
  pub fn node(&self) -> &str {
    self.node.as_str()
  }

  /// The `poll(…)` entry that wrote it — the one an author goes and edits.
  #[inline]
  #[must_use]
  pub const fn clock(&self) -> &'static str {
    self.clock
  }

  /// The granted path that names nothing this root mounts.
  #[inline]
  #[must_use]
  pub const fn granted(&self) -> &'static str {
    self.granted
  }
}

/// The payload of [`Refusal::GrantsNoStore`]: who granted itself the write, from which clock, over
/// what, and where that node is mounted.
///
/// It carries BOTH names, unlike [`UnknownGrantError`] beside it, and the difference is the whole
/// distinction between the two rows: here the grant resolved, so the mount exists and a reader
/// fixing the catalog wants to be told which field they are looking at as well as which string.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GrantsNoStoreError {
  node: Utf8Bytes,
  clock: &'static str,
  mount: Utf8Bytes,
  granted: &'static str,
}

impl GrantsNoStoreError {
  #[inline]
  pub(crate) const fn new(
    node: Utf8Bytes,
    clock: &'static str,
    mount: Utf8Bytes,
    granted: &'static str,
  ) -> Self {
    Self {
      node,
      clock,
      mount,
      granted,
    }
  }

  /// The mount whose declaration wrote the grant.
  #[inline]
  #[must_use]
  pub fn node(&self) -> &str {
    self.node.as_str()
  }

  /// The `poll(…)` entry that wrote it — the one an author goes and edits.
  #[inline]
  #[must_use]
  pub const fn clock(&self) -> &'static str {
    self.clock
  }

  /// The mount the granted node sits at — where a reader goes to look at it.
  #[inline]
  #[must_use]
  pub fn mount(&self) -> &str {
    self.mount.as_str()
  }

  /// The granted path, as the declaration wrote it.
  #[inline]
  #[must_use]
  pub const fn granted(&self) -> &'static str {
    self.granted
  }
}

/// The payload of [`Refusal::Arrangement`]: the arrangement layer's own sentence.
///
/// Rendered rather than held, and that is the erasure a collect-all list forces: a [`Refusal`] is
/// `Clone`, `PartialEq` and `Eq`, and the arrangement layer's error type is none of the three. What
/// a reader wants from it is the sentence, which is what this keeps.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArrangementError {
  sentence: Utf8Bytes,
}

impl ArrangementError {
  #[inline]
  pub(crate) fn new(sentence: impl Into<Utf8Bytes>) -> Self {
    Self {
      sentence: sentence.into(),
    }
  }

  /// What the arrangement layer said.
  #[inline]
  #[must_use]
  pub fn sentence(&self) -> &str {
    self.sentence.as_str()
  }
}