Skip to main content

ingraph/drive/launch/
refusal.rs

1//! ONE ROW of the validate walk's answer, and the payloads the rows are read through.
2//!
3//! # Why a row and not an error
4//!
5//! The validate walk COLLECTS. Its checks are independent and side-effect-free, so stopping at the
6//! first one would be telling an operator about one of their problems and hiding the rest behind a
7//! restart — and the whole value of checking at start-up is that the deployment can be fixed in one
8//! pass. So each check appends a [`Refusal`] and the walk keeps going;
9//! [`LaunchError::Refused`](super::LaunchError::Refused) is the list.
10//!
11//! The CREATE walk that follows is the opposite and for the opposite reason: it builds things, so
12//! its failures are not independent — the second construction runs in a world the first one already
13//! changed. It stops at the first.
14//!
15//! # The order is a reading order
16//!
17//! Rows come out in the order the walk states them, and that order is chosen for a reader rather
18//! than to suppress anything: a name that names nothing comes first because everything after it
19//! describes the deployment as literally written — in which the node a typo meant to name is
20//! ABSENT, and therefore not launched. The rows that follow are the honest consequences, not noise.
21
22use smol_bytes::Utf8Bytes;
23
24use crate::{
25  arrange::{EdgeId, NodeId},
26  resource::{ResourceKind, ResourceName},
27};
28
29#[cfg(test)]
30mod tests;
31
32/// The payload of [`Refusal::UnknownNode`]: the name the options used.
33#[derive(Debug, Clone, PartialEq, Eq)]
34pub struct UnknownNodeError {
35  name: Utf8Bytes,
36}
37
38impl UnknownNodeError {
39  #[inline]
40  pub(crate) const fn new(name: Utf8Bytes) -> Self {
41    Self { name }
42  }
43
44  /// The name that names nothing.
45  #[inline]
46  #[must_use]
47  pub fn name(&self) -> &str {
48    self.name.as_str()
49  }
50}
51
52/// The payload of [`Refusal::UndeclaredResource`]: the node that demanded, its name, and the
53/// resource nothing declared.
54#[derive(Debug, Clone, PartialEq, Eq)]
55pub struct UndeclaredResourceError {
56  node: NodeId,
57  name: Utf8Bytes,
58  resource: &'static ResourceName,
59}
60
61impl UndeclaredResourceError {
62  #[inline]
63  pub(crate) const fn new(node: NodeId, name: Utf8Bytes, resource: &'static ResourceName) -> Self {
64    Self {
65      node,
66      name,
67      resource,
68    }
69  }
70
71  /// The node holding the `Shared<R>` field.
72  #[inline]
73  #[must_use]
74  pub const fn node(&self) -> NodeId {
75    self.node
76  }
77
78  /// Its declared name.
79  #[inline]
80  #[must_use]
81  pub fn name(&self) -> &str {
82    self.name.as_str()
83  }
84
85  /// The resource it demanded — the compiler's own path for the type, so a reader can find it.
86  #[inline]
87  #[must_use]
88  pub const fn resource(&self) -> &'static ResourceName {
89    self.resource
90  }
91}
92
93/// The payload of [`Refusal::UnboundSlot`]: the corpus that named no resource, the KIND it needs,
94/// and every resource this deployment declared that could have held it.
95///
96/// # It carries the CANDIDATES, and it is the first refusal in this family that lists anything
97///
98/// The two ways a sole default fails are one variant and two sentences, and the candidate list is
99/// what tells them apart without a second shape: EMPTY means the deployment declared nothing that
100/// could hold this corpus, and SEVERAL means the choice is real and is the deployment's to make.
101/// Printing them is not a courtesy — it is the whole fix, because the leg is repaired by writing
102/// `resource = "…"` and the list is where the spelling comes from.
103#[derive(Debug, Clone, PartialEq, Eq)]
104pub struct UnboundSlotError {
105  slot: Utf8Bytes,
106  kind: ResourceKind,
107  candidates: Vec<&'static ResourceName>,
108}
109
110impl UnboundSlotError {
111  #[inline]
112  pub(crate) const fn new(
113    slot: Utf8Bytes,
114    kind: ResourceKind,
115    candidates: Vec<&'static ResourceName>,
116  ) -> Self {
117    Self {
118      slot,
119      kind,
120      candidates,
121    }
122  }
123
124  /// The corpus, by its durable name — `<index>__<field>__<label>`, which is what an author greps
125  /// for to find the leg.
126  #[inline]
127  #[must_use]
128  pub fn slot(&self) -> &str {
129    self.slot.as_str()
130  }
131
132  /// What the corpus needs a resource to hold.
133  #[inline]
134  #[must_use]
135  pub const fn kind(&self) -> ResourceKind {
136    self.kind
137  }
138
139  /// Every declared resource that could have held it, in name order.
140  #[inline]
141  #[must_use]
142  pub fn candidates(&self) -> &[&'static ResourceName] {
143    &self.candidates
144  }
145
146  /// The candidate list as a sentence — the half the `Display` row splices in.
147  ///
148  /// A function rather than a formatting expression, because the two arms are two different
149  /// SENTENCES and not one sentence with a list in it: nothing declared is a *declare one* and
150  /// several declared is a *choose one*, and a reader gets the instruction that applies.
151  #[must_use]
152  pub fn advice(&self) -> String {
153    if self.candidates.is_empty() {
154      return format!(
155        "this deployment declares no resource that holds {kind}; declare one with \
156         `#[ingraph::resource(…)]` and mount it on the graph root",
157        kind = self.kind,
158      );
159    }
160    let listed = self
161      .candidates
162      .iter()
163      .map(|name| format!("`{}`", name.as_str()))
164      .collect::<Vec<_>>()
165      .join(", ");
166    format!(
167      "this deployment declares {count} resources that hold {kind} ({listed}), and choosing \
168       between them is not this framework's to do; write `resource = \"…\"` on the leg",
169      count = self.candidates.len(),
170      kind = self.kind,
171    )
172  }
173}
174
175/// The payload of [`Refusal::PureLeaf`]: the node that lands nothing, publishes to nobody and
176/// polls nothing, and its name.
177///
178/// # AN ORPHAN HEAD IS THIS, and there is no second word for it
179///
180/// A SOURCE nobody listens to — an origin mounted as a dataflow head with no consumer — is refused
181/// here and nowhere else, and the word is not a rename waiting to happen. The vocabulary is named
182/// after WHAT IS WRONG rather than after WHO it happened to, which is the same clause
183/// [`ErrorCode`](crate::ErrorCode)'s derivation rule states one layer out: *this computes into
184/// nothing* is one mistake whether the node that computes into nothing has an upstream or is the
185/// head of the whole arrangement, and a head-shaped family beside this one would be two refusals for
186/// one thing.
187///
188/// It works for the origin layer without knowing about it, which is what makes the mapping honest
189/// rather than a coincidence: an origin's declared effect is the PURE one — it lands nothing, what
190/// it produces becoming durable wherever its consumers land it — so the check that was already here
191/// fires on the shape. See [`Blueprint::origin`](super::Blueprint::origin), which is where that
192/// effect is stated.
193#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct PureLeafError {
195  node: NodeId,
196  name: Utf8Bytes,
197}
198
199impl PureLeafError {
200  #[inline]
201  pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
202    Self { node, name }
203  }
204
205  /// The node that computes into nothing.
206  #[inline]
207  #[must_use]
208  pub const fn node(&self) -> NodeId {
209    self.node
210  }
211
212  /// Its declared name.
213  #[inline]
214  #[must_use]
215  pub fn name(&self) -> &str {
216    self.name.as_str()
217  }
218}
219
220/// The payload of [`Refusal::LandsNowhere`]: the node that says it lands, and its name.
221#[derive(Debug, Clone, PartialEq, Eq)]
222pub struct LandsNowhereError {
223  node: NodeId,
224  name: Utf8Bytes,
225}
226
227impl LandsNowhereError {
228  #[inline]
229  pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
230    Self { node, name }
231  }
232
233  /// The node whose claim nothing keeps.
234  #[inline]
235  #[must_use]
236  pub const fn node(&self) -> NodeId {
237    self.node
238  }
239
240  /// Its declared name.
241  #[inline]
242  #[must_use]
243  pub fn name(&self) -> &str {
244    self.name.as_str()
245  }
246}
247
248/// The payload of [`Refusal::FeederAbsent`]: the change-feed edge, and both of its ends by name.
249///
250/// Both ends, because the sentence has to name the WATCHED store's node — that is the one the
251/// operator would go and give a lander to — as well as the listener that would have waited forever.
252#[derive(Debug, Clone, PartialEq, Eq)]
253pub struct FeederAbsentError {
254  edge: EdgeId,
255  consumer: NodeId,
256  consumer_name: Utf8Bytes,
257  watched: NodeId,
258  watched_name: Utf8Bytes,
259}
260
261impl FeederAbsentError {
262  #[inline]
263  pub(crate) const fn new(
264    edge: EdgeId,
265    consumer: NodeId,
266    consumer_name: Utf8Bytes,
267    watched: NodeId,
268    watched_name: Utf8Bytes,
269  ) -> Self {
270    Self {
271      edge,
272      consumer,
273      consumer_name,
274      watched,
275      watched_name,
276    }
277  }
278
279  /// The edge that would have listened.
280  #[inline]
281  #[must_use]
282  pub const fn edge(&self) -> EdgeId {
283    self.edge
284  }
285
286  /// The listening node.
287  #[inline]
288  #[must_use]
289  pub const fn consumer(&self) -> NodeId {
290    self.consumer
291  }
292
293  /// Its declared name.
294  #[inline]
295  #[must_use]
296  pub fn consumer_name(&self) -> &str {
297    self.consumer_name.as_str()
298  }
299
300  /// The node whose store the edge watches.
301  #[inline]
302  #[must_use]
303  pub const fn watched(&self) -> NodeId {
304    self.watched
305  }
306
307  /// Its declared name.
308  #[inline]
309  #[must_use]
310  pub fn watched_name(&self) -> &str {
311    self.watched_name.as_str()
312  }
313}
314
315/// The payload of [`Refusal::DisabledUpstream`]: the edge and both of its ends by name.
316///
317/// WHY the upstream is dark takes no field: presence is the only enablement axis, so a node that is
318/// not running is a node no section named, and the refusal's own sentence says so.
319#[derive(Debug, Clone, PartialEq, Eq)]
320pub struct DisabledUpstreamError {
321  edge: EdgeId,
322  consumer: NodeId,
323  consumer_name: Utf8Bytes,
324  producer: NodeId,
325  producer_name: Utf8Bytes,
326}
327
328impl DisabledUpstreamError {
329  #[inline]
330  pub(crate) const fn new(
331    edge: EdgeId,
332    consumer: NodeId,
333    consumer_name: Utf8Bytes,
334    producer: NodeId,
335    producer_name: Utf8Bytes,
336  ) -> Self {
337    Self {
338      edge,
339      consumer,
340      consumer_name,
341      producer,
342      producer_name,
343    }
344  }
345
346  /// The edge that would starve.
347  #[inline]
348  #[must_use]
349  pub const fn edge(&self) -> EdgeId {
350    self.edge
351  }
352
353  /// The listening node.
354  #[inline]
355  #[must_use]
356  pub const fn consumer(&self) -> NodeId {
357    self.consumer
358  }
359
360  /// Its declared name.
361  #[inline]
362  #[must_use]
363  pub fn consumer_name(&self) -> &str {
364    self.consumer_name.as_str()
365  }
366
367  /// The node this deployment does not launch.
368  #[inline]
369  #[must_use]
370  pub const fn producer(&self) -> NodeId {
371    self.producer
372  }
373
374  /// Its declared name.
375  #[inline]
376  #[must_use]
377  pub fn producer_name(&self) -> &str {
378    self.producer_name.as_str()
379  }
380}
381
382/// The payload of [`Refusal::UnbridgedOrigin`]: the edge no bridge can open, and both of its ends by
383/// name.
384///
385/// Both ends, for [`FeederAbsentError`]'s reason and with the same shape: the sentence has to name
386/// the ORIGIN — the one being asked for something it does not have — and the consumer that would
387/// have waited forever for it.
388///
389/// # WHAT IT MEANS NOW, since the bridge landed
390///
391/// The row's subject is unchanged — *this origin's items reach no intake* — and what changed is
392/// where that is still true. A CHANNEL edge from an origin is opened: the origin's feed IS that edge
393/// and the items flow ([`Feed::bridging`](crate::Feed::bridging)). The other three words a consumer
394/// can listen by ask an origin for something else entirely, and an origin has none of it: an origin
395/// LANDS NOTHING, so there is no store for a `changes` feed to report or a `poll` tick to sweep, and
396/// it answers nobody, so there is no door for a `transient` query arm to knock on. The word, not the
397/// wiring, is what is wrong — so the fix in the sentence is the word.
398///
399/// # It is a DEPLOYMENT fact, and that is what keeps it out of the arrangement's own refusals
400///
401/// The edge is legal and the arrangement is honest: an origin with a consumer is exactly what keeps
402/// it from being a leaf that computes into nothing, and the whole declared-mount suite is built on
403/// arrangements shaped that way. What this row is about is a deployment that LAUNCHES BOTH ENDS of
404/// one — and only then does the consumer's word become a claim about a running origin.
405#[derive(Debug, Clone, PartialEq, Eq)]
406pub struct UnbridgedOriginError {
407  edge: EdgeId,
408  origin: NodeId,
409  origin_name: Utf8Bytes,
410  consumer: NodeId,
411  consumer_name: Utf8Bytes,
412  listen: &'static str,
413}
414
415impl UnbridgedOriginError {
416  #[inline]
417  pub(crate) const fn new(
418    edge: EdgeId,
419    origin: NodeId,
420    origin_name: Utf8Bytes,
421    consumer: NodeId,
422    consumer_name: Utf8Bytes,
423    listen: &'static str,
424  ) -> Self {
425    Self {
426      edge,
427      origin,
428      origin_name,
429      consumer,
430      consumer_name,
431      listen,
432    }
433  }
434
435  /// The word the consumer listened by — [`Listen::as_str`](crate::Listen::as_str)'s own spelling,
436  /// which is what a refusal and a log line identify an edge's mode as.
437  #[inline]
438  #[must_use]
439  pub const fn listen(&self) -> &'static str {
440    self.listen
441  }
442
443  /// The edge nothing opens.
444  #[inline]
445  #[must_use]
446  pub const fn edge(&self) -> EdgeId {
447    self.edge
448  }
449
450  /// The origin whose feed reaches nobody.
451  #[inline]
452  #[must_use]
453  pub const fn origin(&self) -> NodeId {
454    self.origin
455  }
456
457  /// Its declared name.
458  #[inline]
459  #[must_use]
460  pub fn origin_name(&self) -> &str {
461    self.origin_name.as_str()
462  }
463
464  /// The node that would have listened.
465  #[inline]
466  #[must_use]
467  pub const fn consumer(&self) -> NodeId {
468    self.consumer
469  }
470
471  /// Its declared name.
472  #[inline]
473  #[must_use]
474  pub fn consumer_name(&self) -> &str {
475    self.consumer_name.as_str()
476  }
477}
478
479/// The payload of [`Refusal::SplitOrigin`]: the origin, and every launched consumer pulling at its
480/// one feed.
481///
482/// # An origin has ONE feed, and a feed has one far end
483///
484/// A node that fans out publishes through a [`Downstream`](crate::Downstream) set, whose own
485/// [`Sink`](crate::Sink) row demands `T: Clone` — copying is what fanning out IS. An origin's
486/// [`Yield`](crate::Source::Yield) carries no such bound and deliberately: a source hands over what
487/// it produced, once, and a face that demanded a copy of it would refuse every origin whose item is
488/// a handle, a file, a decoded frame it does not own twice.
489///
490/// So the two facts do not meet, and the honest place to say so is here rather than in a bound that
491/// would narrow the origin face for everybody. THE FIX IS AN OPERATOR: a pass-through node
492/// immediately downstream of the origin fans out through the road that already knows how, on a type
493/// its own declaration says is copyable.
494///
495/// # Every consumer is NAMED, not counted
496///
497/// The count is the number in the sentence and the names are what an operator acts on: a deployment
498/// with three listeners on one origin is fixed by knowing WHICH three, and a row that said *three*
499/// would send its reader back to the graph to find out.
500#[derive(Debug, Clone, PartialEq, Eq)]
501pub struct SplitOriginError {
502  origin: NodeId,
503  origin_name: Utf8Bytes,
504  consumers: Vec<Utf8Bytes>,
505}
506
507impl SplitOriginError {
508  #[inline]
509  pub(crate) const fn new(
510    origin: NodeId,
511    origin_name: Utf8Bytes,
512    consumers: Vec<Utf8Bytes>,
513  ) -> Self {
514    Self {
515      origin,
516      origin_name,
517      consumers,
518    }
519  }
520
521  /// The origin whose one feed is being pulled at from several sides.
522  #[inline]
523  #[must_use]
524  pub const fn origin(&self) -> NodeId {
525    self.origin
526  }
527
528  /// Its declared name.
529  #[inline]
530  #[must_use]
531  pub fn origin_name(&self) -> &str {
532    self.origin_name.as_str()
533  }
534
535  /// Every launched consumer of it, in the graph's own edge order.
536  #[inline]
537  #[must_use]
538  pub fn consumers(&self) -> &[Utf8Bytes] {
539    &self.consumers
540  }
541
542  /// How many there are — the number the sentence leads with.
543  #[inline]
544  #[must_use]
545  pub fn count(&self) -> usize {
546    self.consumers.len()
547  }
548
549  /// The consumers as one comma-separated list, for the sentence.
550  fn listed(&self) -> String {
551    self
552      .consumers
553      .iter()
554      .map(|name| format!("`{}`", name.as_str()))
555      .collect::<Vec<_>>()
556      .join(", ")
557  }
558}
559
560/// The payload of [`Refusal::DroppingUnbounded`]: the node, its name, and WHICH of its upstreams
561/// resolved to an edge nothing bounds.
562///
563/// The upstream is a POSITION, which is the same currency the resolution speaks: a document's
564/// `[node.channels]` key, a declaration's `channel = …` word and a [`PollUpstream`](crate::PollUpstream)
565/// are all numbered by declaration order, so a position is what an operator can walk back to the
566/// word they wrote.
567#[derive(Debug, Clone, PartialEq, Eq)]
568pub struct DroppingUnboundedError {
569  node: NodeId,
570  name: Utf8Bytes,
571  upstream: usize,
572}
573
574impl DroppingUnboundedError {
575  #[inline]
576  pub(crate) const fn new(node: NodeId, name: Utf8Bytes, upstream: usize) -> Self {
577    Self {
578      node,
579      name,
580      upstream,
581    }
582  }
583
584  /// The node whose edge nothing bounds.
585  #[inline]
586  #[must_use]
587  pub const fn node(&self) -> NodeId {
588    self.node
589  }
590
591  /// Its declared name.
592  #[inline]
593  #[must_use]
594  pub fn name(&self) -> &str {
595    self.name.as_str()
596  }
597
598  /// Which of its declared channel upstreams, in declaration order.
599  #[inline]
600  #[must_use]
601  pub const fn upstream(&self) -> usize {
602    self.upstream
603  }
604}
605
606/// ONE thing wrong with a deployment, as [`Plan::validate`](super::Plan::validate) found it.
607///
608/// Variants are declared in the walk's own order, which is the order a report reads in.
609///
610/// The rendering is derived per variant rather than written as one `match`, which keeps each
611/// sentence beside the variant it describes; the payloads are read through their accessors and
612/// nothing is computed on the way out.
613#[derive(
614  Debug,
615  Clone,
616  PartialEq,
617  Eq,
618  derive_more::Display,
619  derive_more::IsVariant,
620  derive_more::Unwrap,
621  derive_more::TryUnwrap,
622)]
623#[unwrap(ref, ref_mut)]
624#[try_unwrap(ref, ref_mut)]
625#[non_exhaustive]
626pub enum Refusal {
627  /// The options name a node the arrangement does not declare — a misspelling, or a node that has
628  /// since been removed.
629  #[display("the options name `{}`, which this arrangement does not declare", _0.name())]
630  UnknownNode(UnknownNodeError),
631  /// An ENABLED node demands a resource nothing declared, so there would be nothing to build and
632  /// nothing to hand it.
633  #[display(
634    "{} (`{}`) demands the resource `{}`, which no declaration registered; \
635     declare it with `#[ingraph::resource]`",
636    _0.node(), _0.name(), _0.resource().as_str()
637  )]
638  UndeclaredResource(Box<UndeclaredResourceError>),
639  /// An enabled node lands nothing, publishes to nobody, polls nothing and answers nobody, so
640  /// nothing it computes can be observed.
641  #[display(
642    "{} (`{}`) lands nothing, publishes to nobody, polls nothing and answers nobody; \
643     give it a consumer, a store, a poll upstream, or a query arm",
644    _0.node(), _0.name()
645  )]
646  PureLeaf(PureLeafError),
647  /// An enabled node declares [`Effect::Lands`](crate::Effect::Lands) and has neither of the two
648  /// things that make a landing real: no write lane of its own, and nobody to publish to.
649  ///
650  /// The pure leaf's twin, and the other way round. That one computes and nothing keeps the result;
651  /// this one SAYS the result is kept and nothing does the keeping — a node whose ack answers
652  /// *persisted* over a write that happens nowhere, which is worse than a wasted cycle because
653  /// everything downstream of the claim believes it.
654  #[display(
655    "{} (`{}`) declares that it lands, and holds no write lane and publishes to nobody; \
656     give it a lane of its own, or a consumer that lands what it emits",
657    _0.node(), _0.name()
658  )]
659  LandsNowhere(LandsNowhereError),
660  /// An enabled node listens on the CHANNEL of a node this deployment does not launch, so it would
661  /// wait for a message that is never sent. Listening to that node's STORE instead is legal and is
662  /// the reindex posture.
663  #[display(
664    "{} (`{}`) listens on the channel of {} (`{}`), which this deployment does not launch (no \
665     section names it); listen to its changes instead, or launch it",
666    _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
667  )]
668  DisabledUpstream(Box<DisabledUpstreamError>),
669  /// An enabled node's QUERY edge comes from a node this deployment does not launch — the dark
670  /// embedder under a running index.
671  ///
672  /// Its own variant rather than [`DisabledUpstream`](Self::DisabledUpstream)'s sentence, because
673  /// the escape is not the same one: a starved channel listener can read the upstream's STORE
674  /// instead, and a starved query edge cannot — the unlaunched node computes the query's own input,
675  /// which no store holds because nobody has asked the question yet.
676  #[display(
677    "{} (`{}`) takes its query edge from {} (`{}`), which this deployment does not launch (no \
678     section names it); a query has no store to fall back on, so launch it",
679    _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
680  )]
681  DisabledQueryUpstream(Box<DisabledUpstreamError>),
682  /// An enabled node listens to the CHANGES of a store this graph has no hand in filling, and did
683  /// not say so.
684  ///
685  /// A default `changes(<db>)` is a claim about the graph — *somebody here lands into that store* —
686  /// and this is the deployment where nobody does. Left alone it starts, waits, and reports nothing:
687  /// a feed with no writer looks exactly like a feed with nothing new. The sentence teaches THREE
688  /// ROADS because there are exactly three, and which one is right is the operator's to know: the
689  /// store really is filled from another process (say `external`), or this graph should be reading
690  /// what the node itself emits (point `upstream` at it — the in-graph geometry), or the lander is
691  /// simply missing and belongs in the deployment.
692  #[display(
693    "{} (`{}`) listens to the changes of {} (`{}`), and no node of this graph lands into that \
694     store; say `external` if the store is filled from another process, or subscribe to `{}` \
695     directly if you meant the in-graph geometry, or add the node that lands into it",
696    _0.consumer(), _0.consumer_name(), _0.watched(), _0.watched_name(), _0.watched_name()
697  )]
698  FeederAbsent(Box<FeederAbsentError>),
699  /// An enabled node listens to an enabled ORIGIN, and nothing joins the two: the origin's feed
700  /// comes back in [`Mounted`](super::Mounted) and the consumer's inbox is fed by nobody.
701  ///
702  /// **A consumer listens to an origin by a word an origin cannot be heard through.**
703  ///
704  /// A CHANNEL edge from an origin is opened — the origin's feed IS that edge, minted by
705  /// [`Ignition::origin_bridged`](super::Ignition::origin_bridged) — so the ordinary subscription
706  /// reaches an origin exactly as it reaches a node. The other three words do not, and cannot: an
707  /// origin's effect is the PURE one, so there is no store for `changes` to report or `poll` to
708  /// sweep, and it runs a life rather than answering calls, so there is no door for a `transient`
709  /// query arm. The plan holds an edge whose word asks for machinery the producer does not have, and
710  /// until this row existed the consumer waited on it forever and nothing said why.
711  ///
712  /// It is not [`DisabledUpstream`](Self::DisabledUpstream)'s sentence one axis over. That row is
713  /// about a producer this deployment does not LAUNCH — the fix is to launch it or to read its store
714  /// — and here the producer is launched and running, and the fix is a WORD: subscribe over the
715  /// channel, which is what an origin publishes on.
716  #[display(
717    "{} (`{}`) listens to the origin {} (`{}`) by `{}`, and an origin has nothing to be heard \
718     through that word with: it lands nothing, so there is no store to watch or poll, and it answers \
719     nobody, so there is no door to ask; subscribe to `{}` over the channel, which is what an origin \
720     publishes on",
721    _0.consumer(), _0.consumer_name(), _0.origin(), _0.origin_name(), _0.listen(), _0.origin_name()
722  )]
723  UnbridgedOrigin(Box<UnbridgedOriginError>),
724  /// **One origin, several launched consumers — and an origin has ONE feed.**
725  ///
726  /// The bridge hands an origin the consumer's own inbox as its feed, which is what makes the bound
727  /// single and the teardown exact. There is no second one to hand out: fanning a message to several
728  /// edges is copying it, and the [`Downstream`](crate::Downstream) set that does it demands
729  /// `T: Clone` — a bound the origin face declines, because a source hands over what it produced
730  /// once. See [`SplitOriginError`] for the whole of that argument and for the fix, which is an
731  /// operator immediately downstream.
732  ///
733  /// A DEPLOYMENT fact, exactly as [`UnbridgedOrigin`](Self::UnbridgedOrigin) is: an arrangement may
734  /// declare an origin with any number of consumers, and what is refused is a deployment that
735  /// launches more than one of them.
736  #[display(
737    "{} (`{}`) is an origin and this deployment launches {} consumers of it ({}), but an origin has \
738     ONE feed and it becomes ONE edge — put a pass-through operator under `{}` and fan out from \
739     there, or launch one of them",
740    _0.origin(), _0.origin_name(), _0.count(), _0.listed(), _0.origin_name()
741  )]
742  SplitOrigin(Box<SplitOriginError>),
743  /// A node's declaration draws from an upstream THIS ROOT DOES NOT MOUNT.
744  ///
745  /// The join's own refusal, and it is a fact about the CATALOG rather than about a deployment: a
746  /// declaration names its upstream by TYPE and the root's fields are the whole set of types there
747  /// are, so an upstream missing from them is missing from every deployment of this root. A
748  /// deployment that merely leaves a mounted upstream's section unwritten is a different thing and
749  /// has its own sentence — see [`DisabledUpstream`](Self::DisabledUpstream).
750  #[display(
751    "`{}` subscribes to `{}`, which this graph root does not mount; give the root a field for it, \
752     or point the subscription at a node the root declares",
753    _0.node(), _0.upstream()
754  )]
755  UnknownUpstream(UnknownUpstreamError),
756  /// A node's declaration GRANTS itself the right to write into a node THIS ROOT DOES NOT MOUNT.
757  ///
758  /// [`UnknownUpstream`](Self::UnknownUpstream)'s twin on the permission axis, and a fact about the
759  /// CATALOG for the same reason: a grant names its store by TYPE and the root's fields are the
760  /// whole set of types there are, so a grant missing from them is missing from every deployment.
761  ///
762  /// What it is NOT is a deployment fact. A grant on a mounted node this deployment does not LAUNCH
763  /// is legal and is the poll mode's own point — collecting a dead node's garbage is exactly the
764  /// work that outlives the node.
765  #[display(
766    "`{}`'s `{}` clock grants itself `write = \"{}\"`, which this graph root does not mount; give \
767     the root a field for it, or point the grant at a node the root declares",
768    _0.node(), _0.clock(), _0.granted()
769  )]
770  UnknownGrant(UnknownGrantError),
771  /// A node's declaration grants itself the right to write into a mounted node that KEEPS NO STORE.
772  ///
773  /// The grant resolves and there is still nothing behind it: a pure node's output is computed and
774  /// gone, so there is no store for a sweep to reach into. It is the contradiction
775  /// [`LandsNowhere`](Self::LandsNowhere) refuses one axis over — a claim about durability with no
776  /// durability under it — read from the granting end rather than from the landing one.
777  ///
778  /// The emitted context cannot answer this and does not pretend to: it mints the write socket the
779  /// word asked for, because the granting node's own derive cannot see the granted node's
780  /// declaration. This walk is the one vantage where both are in view.
781  #[display(
782    "`{}`'s `{}` clock grants itself `write = \"{}\"`, and `{}` keeps no store to write into — a \
783     pure node's output is computed and gone; grant a node that lands, or drop the word",
784    _0.node(), _0.clock(), _0.granted(), _0.mount()
785  )]
786  GrantsNoStore(GrantsNoStoreError),
787  /// An enabled node's edge resolved to UNBOUNDED under an
788  /// [`OverflowPolicy`](crate::OverflowPolicy) that can shed.
789  ///
790  /// The two words contradict each other: nothing overflows a queue nothing bounds, so the shed
791  /// would never happen — and a deployment that believes it is dropping under pressure while its
792  /// memory grows without limit is worse off than one told at start-up. It is read on the RESOLVED
793  /// kind rather than on any one layer's word, because the edge that results is the thing that can
794  /// or cannot overflow.
795  #[display(
796    "{} (`{}`) opens its upstream #{} unbounded, and this deployment's overflow policy sheds; \
797     nothing overflows a queue nothing bounds — bound the edge, or run a policy that blocks",
798    _0.node(), _0.name(), _0.upstream()
799  )]
800  DroppingUnbounded(Box<DroppingUnboundedError>),
801  /// A corpus whose leg named NO resource, and the deployment's own catalog could not decide for it.
802  ///
803  /// # The SOLE-DEFAULT law, from the side where it did not apply
804  ///
805  /// A leg that writes no `resource = "…"` is bound by the catalog: exactly ONE kind-compatible
806  /// resource declared and the leg takes it, silently and correctly. This row is both other cases —
807  /// none declared, or several — and the payload's own [`advice`](UnboundSlotError::advice) is what
808  /// tells them apart, because the fixes are different sentences rather than one sentence with a
809  /// number in it.
810  ///
811  /// It is a START-UP refusal and not a compile error, and that is the axis rather than a
812  /// concession: which resources exist is a DEPLOYMENT's fact, written at a graph root that the
813  /// declaring library never sees. A leg is written once and bound per deployment, so the binding
814  /// can only be checked where the catalog is.
815  #[display(
816    "the `{}` corpus names no resource, and {}",
817    _0.slot(), _0.advice()
818  )]
819  UnboundSlot(Box<UnboundSlotError>),
820  /// The declared edges do not make an arrangement — a cycle through the declarations.
821  ///
822  /// The arrangement layer's own refusal, carried in the collect-all list because it is that kind
823  /// of answer: structural, side-effect-free, and about the DECLARATIONS rather than about anything
824  /// a deployment wrote. What it holds is that layer's own sentence, which already names the node
825  /// the cycle runs through.
826  #[display("{}", _0.sentence())]
827  Arrangement(ArrangementError),
828}
829
830/// The payload of [`Refusal::UnknownUpstream`]: who subscribed, and to what.
831///
832/// The upstream is the PATH the declaration wrote rather than a mount name, because there is no
833/// mount — that is the whole refusal. A reader looking for the fix reads back the string they typed.
834#[derive(Debug, Clone, PartialEq, Eq)]
835pub struct UnknownUpstreamError {
836  node: Utf8Bytes,
837  upstream: &'static str,
838}
839
840impl UnknownUpstreamError {
841  #[inline]
842  pub(crate) const fn new(node: Utf8Bytes, upstream: &'static str) -> Self {
843    Self { node, upstream }
844  }
845
846  /// The mount whose declaration named it.
847  #[inline]
848  #[must_use]
849  pub fn node(&self) -> &str {
850    self.node.as_str()
851  }
852
853  /// The upstream path that names nothing this root mounts.
854  #[inline]
855  #[must_use]
856  pub const fn upstream(&self) -> &'static str {
857    self.upstream
858  }
859}
860
861/// The payload of [`Refusal::UnknownGrant`]: who granted itself the write, from which clock, and
862/// over what.
863///
864/// The granted node is the PATH the declaration wrote rather than a mount name, for
865/// [`UnknownUpstreamError`]'s reason: there is no mount — that is the whole refusal — and a reader
866/// looking for the fix reads back the string they typed.
867#[derive(Debug, Clone, PartialEq, Eq)]
868pub struct UnknownGrantError {
869  node: Utf8Bytes,
870  clock: &'static str,
871  granted: &'static str,
872}
873
874impl UnknownGrantError {
875  #[inline]
876  pub(crate) const fn new(node: Utf8Bytes, clock: &'static str, granted: &'static str) -> Self {
877    Self {
878      node,
879      clock,
880      granted,
881    }
882  }
883
884  /// The mount whose declaration wrote the grant.
885  #[inline]
886  #[must_use]
887  pub fn node(&self) -> &str {
888    self.node.as_str()
889  }
890
891  /// The `poll(…)` entry that wrote it — the one an author goes and edits.
892  #[inline]
893  #[must_use]
894  pub const fn clock(&self) -> &'static str {
895    self.clock
896  }
897
898  /// The granted path that names nothing this root mounts.
899  #[inline]
900  #[must_use]
901  pub const fn granted(&self) -> &'static str {
902    self.granted
903  }
904}
905
906/// The payload of [`Refusal::GrantsNoStore`]: who granted itself the write, from which clock, over
907/// what, and where that node is mounted.
908///
909/// It carries BOTH names, unlike [`UnknownGrantError`] beside it, and the difference is the whole
910/// distinction between the two rows: here the grant resolved, so the mount exists and a reader
911/// fixing the catalog wants to be told which field they are looking at as well as which string.
912#[derive(Debug, Clone, PartialEq, Eq)]
913pub struct GrantsNoStoreError {
914  node: Utf8Bytes,
915  clock: &'static str,
916  mount: Utf8Bytes,
917  granted: &'static str,
918}
919
920impl GrantsNoStoreError {
921  #[inline]
922  pub(crate) const fn new(
923    node: Utf8Bytes,
924    clock: &'static str,
925    mount: Utf8Bytes,
926    granted: &'static str,
927  ) -> Self {
928    Self {
929      node,
930      clock,
931      mount,
932      granted,
933    }
934  }
935
936  /// The mount whose declaration wrote the grant.
937  #[inline]
938  #[must_use]
939  pub fn node(&self) -> &str {
940    self.node.as_str()
941  }
942
943  /// The `poll(…)` entry that wrote it — the one an author goes and edits.
944  #[inline]
945  #[must_use]
946  pub const fn clock(&self) -> &'static str {
947    self.clock
948  }
949
950  /// The mount the granted node sits at — where a reader goes to look at it.
951  #[inline]
952  #[must_use]
953  pub fn mount(&self) -> &str {
954    self.mount.as_str()
955  }
956
957  /// The granted path, as the declaration wrote it.
958  #[inline]
959  #[must_use]
960  pub const fn granted(&self) -> &'static str {
961    self.granted
962  }
963}
964
965/// The payload of [`Refusal::Arrangement`]: the arrangement layer's own sentence.
966///
967/// Rendered rather than held, and that is the erasure a collect-all list forces: a [`Refusal`] is
968/// `Clone`, `PartialEq` and `Eq`, and the arrangement layer's error type is none of the three. What
969/// a reader wants from it is the sentence, which is what this keeps.
970#[derive(Debug, Clone, PartialEq, Eq)]
971pub struct ArrangementError {
972  sentence: Utf8Bytes,
973}
974
975impl ArrangementError {
976  #[inline]
977  pub(crate) fn new(sentence: impl Into<Utf8Bytes>) -> Self {
978    Self {
979      sentence: sentence.into(),
980    }
981  }
982
983  /// What the arrangement layer said.
984  #[inline]
985  #[must_use]
986  pub fn sentence(&self) -> &str {
987    self.sentence.as_str()
988  }
989}