Skip to main content

ingraph/drive/launch/
create.rs

1//! THE CREATE WALK: what a validated deployment BECOMES, and the one order it can be built in.
2//!
3//! [`Plan::validate`](super::Plan::validate) answered everything a deployment can be wrong about
4//! without touching the world. This is the half that touches it, and it is the opposite kind of walk
5//! for a reason that is not a preference: its steps BUILD things, so the second one runs in a world
6//! the first one made, and a failure leaves the rest describing a deployment that no longer exists.
7//! It stops at the first — [`LaunchError::Construction`] — where the validate walk collects.
8//!
9//! What it leaves behind is [`unwind`](Creation::unwind)'s: a walk that refuses partway holds
10//! everything the steps before it built, so the values that enrolled a goodbye SAY it — in reverse,
11//! resources last, through the shutdown's own chain — and everything else is dropped as the error
12//! propagates, which is the shipped teardown and the right one for nearly everything. Nothing is a
13//! second mechanism: the pre-ignition road differs from the post-ignition one only in where the
14//! value was when the chain reached for it.
15//!
16//! # The order, and what actually depends on what
17//!
18//! 1. **RESOURCES, demand-scanned.** A resource is built iff this deployment MOUNTS it — a
19//!    declaration's leg points at it — or at least one ENABLED node demands it; and it is built
20//!    ONCE. They come first because a node's construction may reach for one:
21//!    `ctx.shared::<Egemma>()` inside a boot body can only find what an earlier pass put there.
22//! 2. **SLOTS.** A store is a resource, so its slots open once the store is in hand, and this is
23//!    where the pairing between a declaration and an engine is asserted — the ONE production
24//!    [`SlotHandle::mint`](crate::SlotHandle::mint) site.
25//! 3. **NODES**, each from its own section, through [`AsyncConstructor::with_options`] — and the
26//!    ORIGINS beside them, each from its own section, through its own face's
27//!    [`Source::build`](crate::Source::build). Two doors and one stage: the tiers are constructed
28//!    alike and differ only in which trait states the construction, per [`origin`](Creation::origin).
29//!
30//! Wiring and ignition are the rounds after this one. A create walk hands back constructed values
31//! and the [`Resources`] it filled; what edges they get is [`wire`](Creation::wire)'s sentence and
32//! when they start is the ignition's.
33//!
34//! # The resource step has TWO doors, and the CATALOG says which one a resource goes through
35//!
36//! A resource's declaration names exactly one source for its options, and that is the whole of the
37//! single-source law: [`declared_resource`](Creation::declared_resource) serves the two sources a
38//! root states on its own — the deployment's `[resources.<mount>]` section and the initialization
39//! function a declaration names — and [`resource`](Creation::resource) serves the one the
40//! APPLICATION spends by hand, the `prepare` closure. Each reads
41//! [`ResourceCatalog::source`](crate::ResourceCatalog::source) before it builds anything and refuses where the
42//! declaration named the other, so a second door does not silently win a race it was never meant to
43//! be in.
44//!
45//! Both are lazy in the same way and for the same reason: the options arrive as a THUNK, so a
46//! resource nobody demands costs neither a spelled section nor a call to an initializer.
47//!
48//! # The slot step opens the kind that has a name to open it under
49//!
50//! A full-text slot's name is [`FulltextTable::SLOT`] and an artifact family's is
51//! [`BlobTable::SLOT`], each written on its own declaration — which is what lets the mint read the
52//! name and the brand off ONE place. The blob kind's authority arrived with the blob-engine round,
53//! so [`async_blob_slot`](Creation::async_blob_slot) and its blocking twin sit beside
54//! [`async_fulltext_slot`](Creation::async_fulltext_slot) here.
55//!
56//! The VECTOR kind still has no such trait, and it is named rather than sketched: its store takes a
57//! slot name as a plain argument, so a door for it would have the caller state the pairing, which is
58//! exactly the lie the one-mint-site law exists to keep out of production. The width question
59//! [`AsyncVectorStore::vector`](crate::AsyncVectorStore::vector) parks in its own note is the second half — a
60//! slot electing several embeddings may hold columns of several widths, and whether that is one slot
61//! per column or one slot per width is a design act, not a default this walk should pick. A blob
62//! store's per-slot factory takes no such second argument, which is why the blob door could be built
63//! the day its authority landed and the vector one still cannot.
64//!
65//! # The walk is DRIVEN, not looped
66//!
67//! Constructing a node means naming its TYPE, and a graph carries names rather than types — so this
68//! layer cannot hold the loop. It holds the STEPS, and the declaration's emission spends them, one
69//! call per declared mount, in the order above. That is the division [`Wired`] itself is written
70//! for: the checked facts live here, and the party that knows the types spends them.
71//!
72//! # PRESENCE IS ENABLEMENT, and the section is the only authority for it
73//!
74//! [`node`](Creation::node) reads whether a node runs off the SECTION it is handed — an absent one
75//! is a node that is not built, and that is the whole of the question. It does not read the frozen
76//! [`Enablement`](super::Enablement) beside it, and that is what keeps the two from disagreeing:
77//! the same sections produced that enablement through the spine's own `enablement()`, so there is
78//! one source and no second one to drift from it.
79
80use core::{any::type_name, marker::PhantomData};
81
82use smol_bytes::Utf8Bytes;
83
84use crate::{
85  drive::{Taps, lane::block_on},
86  record::{BlobTable, FulltextTable},
87  resource::{AsyncResource, DeclaredResource, ResourceName, ResourceSource, Shared},
88  source::DeclaredOrigin,
89  store::{AsyncBlobStore, AsyncFulltextStore, BlobStore, FulltextStore, SlotHandle},
90};
91
92use super::{
93  AsyncConstructor, LaunchError, NodeSection, Resources, Staging, Wired, Wiring,
94  origin::{Died, Lived, Tuned},
95  teardown::farewell,
96};
97
98#[cfg(test)]
99mod tests;
100
101/// The CREATE walk over a checked deployment: resources, then slots, then nodes.
102///
103/// Begun with [`Wired::create`], which is the only door — a walk that builds is reachable only from
104/// a plan that passed, so nothing constructs anything for a deployment whose refusals have not been
105/// read.
106///
107/// It owns the [`Resources`] it fills and hands it on at the end — to the wiring walk through
108/// [`wire`](Self::wire), or to a caller that wires by hand through
109/// [`into_context`](Self::into_context). Dropping it instead is the failed launch's own teardown:
110/// every resource it built goes with it.
111///
112/// # Examples
113///
114/// ```
115/// use ingraph::{Context, AsyncConstructor, Resources, NodeSection};
116/// # use ingraph::{
117/// #   DriverKind, Effect, Enablement, GraphBuilder, NodeWiring, Operator, Plan,
118/// # };
119///
120/// struct Decode {
121///   threads: usize,
122/// }
123///
124/// struct DecodeOptions {
125///   threads: usize,
126/// }
127///
128/// impl Default for DecodeOptions {
129///   fn default() -> Self {
130///     Self { threads: 4 }
131///   }
132/// }
133///
134/// impl AsyncConstructor for Decode {
135///   type Options = DecodeOptions;
136///   type Error = std::io::Error;
137///
138///   async fn with_options(_ctx: &Resources, options: DecodeOptions) -> Result<Self, Self::Error> {
139///     Ok(Self {
140///       threads: options.threads,
141///     })
142///   }
143/// }
144///
145/// # struct Decoding;
146/// # impl Operator for Decoding {
147/// #   type Error = core::convert::Infallible;
148/// #   type In = u8;
149/// #   type Out = u8;
150/// #   fn accept(&mut self, ctx: &Context, _: ingraph::Delivery<u8>, _: &mut ingraph::Emitter<u8>)
151/// #     -> Result<(), Self::Error> { Ok(()) }
152/// # }
153/// # impl ingraph::Declared for Decoding {
154/// #   const EFFECT: Effect = Effect::Pure;
155/// #   type Channels = ingraph::Unchanneled;
156/// #   type Mode = ingraph::Block;
157/// #   type Options = ();
158/// #   type Pair = ingraph::Buffered;
159/// #   type Wires<O> = ingraph::Downstream<O>;
160/// #   type Attribution<O> = ();
161/// # }
162/// # let mut builder = GraphBuilder::new();
163/// # let mount = builder.source::<Decoding>("decode", DriverKind::Thread);
164/// # let plan = Plan::new(builder.validate().expect("one node validates"))
165/// #   .with_enablement(Enablement::new().launching("decode"))
166/// #   .wiring(mount.id(), NodeWiring::new(Effect::Lands).landing());
167/// // A deployment that passed its checks — one node, named by its section.
168/// let wired = plan.validate().expect("the deployment checks out");
169///
170/// # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
171/// let mut walk = wired.create();
172///
173/// // A section that states its tuning goes through `with_options`.
174/// let decode = walk
175///   .node::<Decode>(
176///     "decode",
177///     Some(NodeSection::new(DecodeOptions { threads: 8 })),
178///     ingraph::bare_options!(Decode),
179///   )
180///   .await
181///   .expect("it builds")
182///   .expect("the deployment names it");
183/// assert_eq!(decode.threads, 8);
184///
185/// // A node this deployment never named is a node the walk does not build.
186/// let absent = walk
187///   .node::<Decode>("decode", None, ingraph::bare_options!(Decode))
188///   .await
189///   .expect("nothing to refuse");
190/// assert!(absent.is_none());
191/// # });
192/// ```
193#[derive(Debug)]
194pub struct Creation<'a> {
195  wired: &'a Wired,
196  ctx: Resources,
197  taps: Taps,
198  // LAYER TWO's machines, kept BETWEEN steps: one slot maker per target, shown every declaration
199  // that lives there. It is here rather than in the launch entry's own locals because the steps are
200  // emitted per DECLARATION — see `habitats` — and the walk's shape is one visitor per target.
201  makers: super::habitats::Makers,
202}
203
204impl<'a> Creation<'a> {
205  /// The walk over `wired`, with nothing built yet.
206  #[inline]
207  pub(super) fn new(wired: &'a Wired) -> Self {
208    Self {
209      wired,
210      ctx: Resources::new(),
211      taps: Taps::new(),
212      makers: super::habitats::Makers::default(),
213    }
214  }
215
216  /// LAYER TWO's machine bag — see [`habitats`](super::habitats).
217  #[inline]
218  pub(super) fn makers(&mut self) -> &mut super::habitats::Makers {
219    &mut self.makers
220  }
221
222  /// The resource `R` THIS WALK BUILT, or `None` where this deployment neither mounts nor demands
223  /// one.
224  ///
225  /// The door layer two reaches a mount through, and the lazy law is what the `None` states: a
226  /// resource no declaration points at and no enabled node asked for was never built. It is not
227  /// itself a refusal — a target that is not there is a deployment that does not use it — but the
228  /// party that asks decides what the absence means, and layer two's own step refuses it, having
229  /// been spelled for a target this deployment does point at.
230  #[inline]
231  #[must_use]
232  pub fn built<R: crate::AsyncResource + 'static>(&self) -> Option<Shared<R>> {
233    self.ctx.shared::<R>().ok()
234  }
235
236  /// Observe this walk's own unwind through `taps`.
237  ///
238  /// The tap seam, one stage EARLIER than [`Wiring::with_taps`], and it is here for exactly one
239  /// reason: a create walk that refuses says the goodbyes of everything it had already built — see
240  /// [`unwind`](Self::unwind) — and a chain nothing could observe would be a chain said in silence.
241  /// Nothing else in this stage observes anything; a resident is wired and watched one walk on.
242  ///
243  /// They travel with the walk: [`wire`](Self::wire) hands them to the [`Wiring`] it opens, so a
244  /// deployment states its taps ONCE and both unwinds report through them. A `set_taps` on the
245  /// wiring still has the last word for the residents, which is where it always had it.
246  #[inline]
247  #[must_use]
248  pub fn with_taps(mut self, taps: Taps) -> Self {
249    self.set_taps(taps);
250    self
251  }
252
253  /// [`with_taps`](Self::with_taps), in place.
254  #[inline]
255  pub fn set_taps(&mut self, taps: Taps) -> &mut Self {
256    self.taps = taps;
257    self
258  }
259
260  /// The taps this walk's own unwind reports through.
261  #[inline]
262  #[must_use]
263  pub const fn taps(&self) -> &Taps {
264    &self.taps
265  }
266
267  /// Build `R` from the application's own `prepare` closure — the door
268  /// [`ResourceSource::Prepare`] names, and the one a `#[ingraph(resource(factory))]` field
269  /// declares.
270  ///
271  /// THE LAZY LAW, as a door: `options` is called only where the demand exists, so a deployment
272  /// whose enabled nodes reach for none of a declaration's resources needs no options for any of
273  /// them — a factory for something nobody asked for is never spent and never has to be spellable.
274  /// A resource already in the context is left alone, which is what makes ONCE a fact of the walk
275  /// rather than a discipline its caller keeps.
276  ///
277  /// THE SINGLE-SOURCE LAW, as the same door: a resource whose declaration named another source is
278  /// refused here rather than quietly overriding what that source will say. The refusal names the
279  /// source the declaration DID write, so a reader is told where the options belong instead of
280  /// which call to delete.
281  ///
282  /// Answers whether THIS call built one: `false` where nothing enabled demands `R`, and where the
283  /// walk had already built it.
284  ///
285  /// # Errors
286  ///
287  /// [`LaunchError::Loading`], naming the resource, where its own
288  /// [`build`](crate::AsyncResource::build) refused — or where this is not the door its declaration
289  /// named. The walk stops there — see the module note.
290  pub async fn resource<R, F>(&mut self, options: F) -> Result<bool, LaunchError>
291  where
292    R: DeclaredResource + 'static,
293    R::Error: core::error::Error + Send + Sync + 'static,
294    F: FnOnce() -> R::Options,
295  {
296    // THE DOOR IS CHECKED BEFORE THE DEMAND, and the two orders are not the same rule. A resource
297    // this deployment does not need is not built — but spelling the wrong door for it is a mistake
298    // in the CODE rather than in the deployment, and one that would otherwise stay hidden until
299    // some later document enabled the demander. It also has to come before the already-built guard:
300    // the walk builds the declared sources first, so a `prepare` call for one of them would find it
301    // in the context and answer a quiet `false` for exactly the mistake this refuses.
302    self.admits::<R>(ResourceSource::Prepare)?;
303    if !self.wired.demands(R::resource()) || self.ctx.holds::<R>() {
304      return Ok(false);
305    }
306
307    let built = Shared::<R>::build(&self.ctx, options())
308      .await
309      .map_err(LaunchError::loading::<R, _>)?;
310    self.ctx.insert(built);
311    Ok(true)
312  }
313
314  /// [`resource`](Self::resource) for one the declaration wrote `teardown` on — a pool to drain, a
315  /// lock to remove, a directory to clean up after.
316  ///
317  /// Enrolled in the same chain the nodes' own goodbyes are said through and released at its LAST
318  /// step: resources are built first, so they are let go of after every node that was handed a
319  /// handle has finished with it. See [`Resources::release`], which is the step, and
320  /// [`Shared::unseal`](crate::Shared::unseal), which is why a resource somebody else still holds is
321  /// a row in the report rather than a wait.
322  ///
323  /// What gets said is [`AsyncResource::goodbye`], whose default drops — so this door demands no second
324  /// trait of the resource and the WORD stays the whole of the opt-in.
325  ///
326  /// Answers whether THIS call built one, exactly as [`resource`](Self::resource) does — and a call
327  /// that answered `false` enrolled nothing, there being nothing of its own to say goodbye to.
328  ///
329  /// # Errors
330  ///
331  /// [`resource`](Self::resource)'s, for the same three reasons.
332  pub async fn resource_saying_goodbye<R, F>(&mut self, options: F) -> Result<bool, LaunchError>
333  where
334    R: DeclaredResource + 'static,
335    R::Error: core::error::Error + Send + Sync + 'static,
336    F: FnOnce() -> R::Options,
337  {
338    self.admits::<R>(ResourceSource::Prepare)?;
339    if !self.wired.demands(R::resource()) || self.ctx.holds::<R>() {
340      return Ok(false);
341    }
342
343    let built = Shared::<R>::build(&self.ctx, options())
344      .await
345      .map_err(LaunchError::loading::<R, _>)?;
346    self.ctx.insert_goodbye(built);
347    Ok(true)
348  }
349
350  /// Build `R` from the source its own DECLARATION named — the walk's own door, driven by the
351  /// emission that holds the catalog.
352  ///
353  /// The two sources it serves are the two a declaration can state without the application's hand:
354  /// [`Section`](ResourceSource::Section), whose `options` are the deployment's
355  /// `[resources.<mount>]` block, and [`Initializer`](ResourceSource::Initializer), whose `options`
356  /// are what the named function returned. Both arrive already resolved, because resolving them is
357  /// the emission's own step — it is the party that can name the field and spell the path.
358  ///
359  /// `options` is a THUNK for [`resource`](Self::resource)'s reason, and it is the lazy law that
360  /// asks for it: an initializer for a resource nobody demands must not run, and a document section
361  /// for one must not have to be spellable.
362  ///
363  /// A `None` from the thunk is the mandatory-knob rule arriving at a resource: the section was not
364  /// written and the options have no [`Default`] to stand in, which is
365  /// [`MandatoryOptionsError`]'s sentence one tier over.
366  ///
367  /// Answers whether THIS call built one, exactly as [`resource`](Self::resource) does.
368  ///
369  /// # Errors
370  ///
371  /// [`LaunchError::Loading`], naming the resource: where its own
372  /// [`build`](crate::AsyncResource::build) refused, where this is not the door its declaration named,
373  /// or where its options had nowhere to come from.
374  pub async fn declared_resource<R, F>(&mut self, options: F) -> Result<bool, LaunchError>
375  where
376    R: DeclaredResource + 'static,
377    R::Error: core::error::Error + Send + Sync + 'static,
378    F: FnOnce() -> Option<R::Options>,
379  {
380    let (mount, declared) = self.declaration::<R>()?;
381    if declared.is_prepare() {
382      return Err(LaunchError::loading::<R, _>(ResourceSourceError::new(
383        mount,
384        declared,
385        ResourceSource::Prepare,
386      )));
387    }
388    if !self.wired.demands(R::resource()) || self.ctx.holds::<R>() {
389      return Ok(false);
390    }
391
392    let Some(options) = options() else {
393      return Err(LaunchError::loading::<R, _>(
394        MandatoryResourceOptionsError::of::<R>(mount, declared),
395      ));
396    };
397    let built = Shared::<R>::build(&self.ctx, options)
398      .await
399      .map_err(LaunchError::loading::<R, _>)?;
400    self.ctx.insert(built);
401    Ok(true)
402  }
403
404  /// [`declared_resource`](Self::declared_resource) for one whose root field wrote
405  /// `resource(teardown)` — the composed forms' own door.
406  ///
407  /// The WORD is the whole difference, and it is the emission that reads it: a
408  /// `#[ingraph(resource(teardown))]` field and a `#[ingraph(resource(factory = "…", teardown))]`
409  /// field are driven through here, and every other resource through the door above. What that buys
410  /// is [`Resources::insert_goodbye`] instead of [`Resources::insert`] — a seat in the release walk,
411  /// said LAST of everything the launch built.
412  ///
413  /// Answers whether THIS call built one, exactly as [`declared_resource`](Self::declared_resource)
414  /// does — and a call that answered `false` enrolled nothing.
415  ///
416  /// # Errors
417  ///
418  /// [`declared_resource`](Self::declared_resource)'s, for the same three reasons.
419  pub async fn declared_resource_saying_goodbye<R, F>(
420    &mut self,
421    options: F,
422  ) -> Result<bool, LaunchError>
423  where
424    R: DeclaredResource + 'static,
425    R::Error: core::error::Error + Send + Sync + 'static,
426    F: FnOnce() -> Option<R::Options>,
427  {
428    let (mount, declared) = self.declaration::<R>()?;
429    if declared.is_prepare() {
430      return Err(LaunchError::loading::<R, _>(ResourceSourceError::new(
431        mount,
432        declared,
433        ResourceSource::Prepare,
434      )));
435    }
436    if !self.wired.demands(R::resource()) || self.ctx.holds::<R>() {
437      return Ok(false);
438    }
439
440    let Some(options) = options() else {
441      return Err(LaunchError::loading::<R, _>(
442        MandatoryResourceOptionsError::of::<R>(mount, declared),
443      ));
444    };
445    let built = Shared::<R>::build(&self.ctx, options)
446      .await
447      .map_err(LaunchError::loading::<R, _>)?;
448    self.ctx.insert_goodbye(built);
449    Ok(true)
450  }
451
452  /// **THE PRE-IGNITION UNWIND**: say the goodbyes of everything this walk built, and hand `error`
453  /// back UNCHANGED.
454  ///
455  /// [`Ignition::unwind`](super::Ignition::unwind)'s duty one stage earlier, and the ruled
456  /// difference between them is where the values are. Post-ignition a value is on an engine and its
457  /// goodbye has to travel back through its party's settlement. HERE nothing runs: the create walk
458  /// refused, so ownership never left the launch — `staged` holds the values themselves, and the
459  /// chain consumes them directly.
460  ///
461  /// It is the SAME chain either way. [`farewell`](super::teardown::farewell) says the staged
462  /// goodbyes last-staged first and never stops for a refusal; [`Resources::release`] then releases
463  /// the resources, which were built before any of them and are therefore let go of after all of
464  /// them. How it went rides the [`Taps`] — see [`with_taps`](Self::with_taps), which is the only
465  /// reason this stage has any.
466  ///
467  /// The un-torn ROWS are dropped rather than collected, exactly as the ignition's unwind drops
468  /// them: the error a failed launch reports is the failure, and how the tidying after it went is
469  /// the taps' to tell.
470  ///
471  /// # It is SYNCHRONOUS, and that is what keeps a launch future `Send`
472  ///
473  /// A [`Goodbye`](super::Goodbye) promises no `Send` — that is what lets a value pinned to one
474  /// thread say one — so an `async` unwind would hold a `!Send` future across the emitted launch's
475  /// own awaits and make the whole launch `!Send` for any deployment with one such node. Driving the
476  /// chain to its end inside this call keeps it where it belongs.
477  #[must_use]
478  pub fn unwind(self, staged: Staging, error: LaunchError) -> LaunchError {
479    let Self { ctx, taps, .. } = self;
480    block_on(async {
481      drop(farewell(staged.into_farewells(), &taps).await);
482      drop(ctx.release(&taps).await);
483    });
484    error
485  }
486
487  /// What `R`'s declaration says — its mount and its one source — or the refusal for a resource the
488  /// catalog does not carry.
489  ///
490  /// The undeclared case is reachable only from a HAND-WRITTEN launch: the validate walk already
491  /// refuses a demand for an undeclared resource, and this walk is reached only from a plan whose
492  /// refusals were read — so what is left is a call for a resource nothing demands, which the lazy
493  /// rule answered before this is asked. It is spelled anyway, because the alternative is deciding
494  /// which door an undeclared resource belongs to.
495  fn declaration<R: DeclaredResource>(
496    &self,
497  ) -> Result<(&'static str, ResourceSource), LaunchError> {
498    let catalog = self.wired.resources();
499    catalog
500      .mount(R::resource())
501      .zip(catalog.source(R::resource()))
502      .ok_or_else(|| LaunchError::loading::<R, _>(UncataloguedResourceError::of::<R>()))
503  }
504
505  /// Refuse `door` where `R`'s declaration named another source.
506  fn admits<R: DeclaredResource>(&self, door: ResourceSource) -> Result<(), LaunchError> {
507    let (mount, declared) = self.declaration::<R>()?;
508    if declared == door {
509      return Ok(());
510    }
511    Err(LaunchError::loading::<R, _>(ResourceSourceError::new(
512      mount, declared, door,
513    )))
514  }
515
516  /// Open `T`'s full-text slot on `store`, branded — THE production mint site.
517  ///
518  /// The slot's name is `T::SLOT`, read off the declaration rather than taken from a caller, and
519  /// that is the whole of what makes this the auditable one: [`mint`](SlotHandle::mint) states a
520  /// pairing nothing in the type system checks, so the site that states it has to be the site that
521  /// KNOWS it — here, where the name and the brand are read from the same declaration and cannot be
522  /// given different answers. A test hand-mints deliberately, to build the wrong pairing on purpose
523  /// and prove it is refused.
524  ///
525  /// The name is not carried as a second field for the same reason: the brand names the
526  /// declaration, the declaration owns the name, and a copy beside it would be a second thing to
527  /// keep true.
528  #[inline]
529  #[must_use]
530  pub fn async_fulltext_slot<S, T>(&self, store: &S) -> SlotHandle<S::Handle, T>
531  where
532    S: AsyncFulltextStore,
533    T: FulltextTable,
534  {
535    // `from_static` rather than an owned copy: a slot name is a `const` a declaration wrote, so the
536    // `&'static str` under it is already the byte string the engine will be given.
537    SlotHandle::mint(store.fulltext(Utf8Bytes::from_static(T::SLOT.as_ref())))
538  }
539
540  /// [`async_fulltext_slot`](Self::async_fulltext_slot) over a store whose OPENING was a blocking
541  /// act.
542  ///
543  /// [`blob_slot`](Self::blob_slot)'s argument verbatim, one family over: the mint is MODE-BLIND —
544  /// `fulltext` is sync and infallible on both store faces, so nothing inside these two bodies
545  /// differs. What differs is the BOUND, and that is the whole of it: a blocking-only store
546  /// implements [`FulltextStore`] and nothing else, so a single door bounded on
547  /// [`AsyncFulltextStore`] would have shut launch's door on exactly the backends the dual-mode
548  /// birth order exists to make first-class — the shipped tantivy store among them, whose opening is
549  /// two syscalls and no await.
550  ///
551  /// Folding the pair behind one capability naming just the factory is spellable and is NOT built,
552  /// for the reason its blob twin records: nothing asks for it, and a third trait over two that
553  /// already say it would be a seam minted ahead of a consumer.
554  #[inline]
555  #[must_use]
556  pub fn fulltext_slot<S, T>(&self, store: &S) -> SlotHandle<S::Handle, T>
557  where
558    S: FulltextStore,
559    T: FulltextTable,
560  {
561    SlotHandle::mint(store.fulltext(Utf8Bytes::from_static(T::SLOT.as_ref())))
562  }
563
564  /// Open `T`'s ARTIFACT FAMILY on `store`, branded — the blob side's production mint site.
565  ///
566  /// [`async_fulltext_slot`](Self::async_fulltext_slot)'s law, one family over and unchanged: the name is
567  /// `T::SLOT`, read off the declaration rather than taken from a caller, so the site that states
568  /// the pairing [`mint`](SlotHandle::mint) cannot check is the site that KNOWS it. What differs is
569  /// only what the name means downstream — a directory under the store's root, or an object store's
570  /// leading key segment, instead of a corpus.
571  ///
572  /// # It is not conditional on the store having opened anything
573  ///
574  /// A blob store's per-slot factory is SYNC and INFALLIBLE by [`AsyncBlobStore::blob`]'s own contract: a
575  /// stateless handle needs no I/O to mint, and any per-slot opening happens lazily behind the shared
576  /// manager on first use. So this door has nothing to await and nothing to fail, which is why it is
577  /// neither `async` nor fallible where the resource steps around it are both.
578  #[inline]
579  #[must_use]
580  pub fn async_blob_slot<S, T>(&self, store: &S) -> SlotHandle<S::Handle, T>
581  where
582    S: AsyncBlobStore,
583    T: BlobTable,
584  {
585    // `from_static` rather than an owned copy: a slot name is a `const` a declaration wrote, so the
586    // `&'static str` under it is already the byte string the store will be given.
587    SlotHandle::mint(store.blob(Utf8Bytes::from_static(T::SLOT.as_ref())))
588  }
589
590  /// [`async_blob_slot`](Self::async_blob_slot) over a store whose OPENING was a blocking act.
591  ///
592  /// # Why the door is written twice when the act it performs is identical
593  ///
594  /// The mint is MODE-BLIND — `blob` is sync and infallible on both store faces, so nothing inside
595  /// these two bodies differs. What differs is the BOUND, and that is the whole of it: a blocking-only
596  /// store implements [`BlobStore`] and nothing else, so a single door bounded on
597  /// [`AsyncBlobStore`] would have shut launch's door on exactly the backends the dual-mode birth order
598  /// exists to make first-class. Two bounds, one act, no fiction in either.
599  ///
600  /// Folding the pair behind one capability naming just the factory is spellable and is NOT built:
601  /// nothing asks for it yet, and a third trait over two that already say it would be a seam minted
602  /// ahead of a consumer.
603  #[inline]
604  #[must_use]
605  pub fn blob_slot<S, T>(&self, store: &S) -> SlotHandle<S::Handle, T>
606  where
607    S: BlobStore,
608    T: BlobTable,
609  {
610    SlotHandle::mint(store.blob(Utf8Bytes::from_static(T::SLOT.as_ref())))
611  }
612
613  /// Build the node mounted at `name` from its `section`, or answer `None` where this deployment
614  /// does not launch it.
615  ///
616  /// # The two doors, and which one a section picks
617  ///
618  /// A section carrying `options` goes to [`AsyncConstructor::with_options`] with them. A BARE section —
619  /// present, with no `options` key, which is the common `[decode]` and the only shape a zero-knob
620  /// node can be written in — runs at the options' own [`Default`], which is exactly
621  /// [`AsyncConstructor::new`]'s condition restated as data. `bare` is that default where the type has
622  /// one, and [`bare_options!`](crate::bare_options) is what answers it: see
623  /// [`BareOptions`] for why the question can only be asked at a call site.
624  ///
625  /// A bare section over an options type with no `Default` is where "an options type without a
626  /// `Default` makes its knobs naturally mandatory" is enforced, and it is enforced HERE rather than
627  /// at the document: the emitted spine has to deserialize a section for every node, including the
628  /// zero-knob ones, so the parse cannot be the thing that demands the knobs.
629  ///
630  /// # Errors
631  ///
632  /// [`LaunchError::Construction`], naming the mount, where the node's own construction refused —
633  /// or where a bare section met options with no [`Default`], which is the same refusal with the
634  /// framework's own sentence inside it. The walk stops at the first: see the module note.
635  pub async fn node<T>(
636    &mut self,
637    name: &str,
638    section: Option<NodeSection<T::Options>>,
639    bare: Option<T::Options>,
640  ) -> Result<Option<T>, LaunchError>
641  where
642    T: AsyncConstructor,
643    T::Error: core::error::Error + Send + Sync + 'static,
644  {
645    let Some(section) = section else {
646      return Ok(None);
647    };
648    let Some(options) = section.into_options().or(bare) else {
649      return Err(LaunchError::construction(
650        name,
651        MandatoryOptionsError::of::<T::Options>(),
652      ));
653    };
654
655    T::with_options(&self.ctx, options)
656      .await
657      .map(Some)
658      .map_err(|error| LaunchError::construction(name, error))
659  }
660
661  /// Build the ORIGIN mounted at `name` from its `section`, or answer `None` where this deployment
662  /// does not launch it.
663  ///
664  /// [`node`](Self::node)'s step one tier over, and everything that door's note says holds verbatim:
665  /// the two section shapes, the bare-section default, the mandatory-knob refusal, and the stop at
666  /// the first failure. [`bare_origin_options!`](crate::bare_origin_options) is the probe, spelled
667  /// for this tier's own projection.
668  ///
669  /// # What differs is the DOOR it calls, and that is the whole of it
670  ///
671  /// A node is constructed through [`AsyncConstructor::with_options`]; an origin is constructed
672  /// through its OWN face — [`Source::build`](crate::Source::build) or
673  /// [`AsyncSource::build`](crate::AsyncSource::build) — reached through
674  /// [`Lived::open`](crate::Lived::open) under the mode its declaration named. So an origin has ONE
675  /// options seat rather than two, and the section this walk is handed is that seat.
676  ///
677  /// The window is the same `&Resources` every construction door in this framework takes, which is
678  /// what made calling the face's own `build` possible at all — see
679  /// [`Lived`](crate::Lived)'s own note for what the old runtime window cost.
680  ///
681  /// # Errors
682  ///
683  /// [`LaunchError::Construction`], naming the mount, where the origin's own construction refused —
684  /// or where a bare section met options with no [`Default`], which is [`node`](Self::node)'s same
685  /// refusal.
686  pub async fn origin<T>(
687    &mut self,
688    name: &str,
689    section: Option<NodeSection<Tuned<T>>>,
690    bare: Option<Tuned<T>>,
691  ) -> Result<Option<T>, LaunchError>
692  where
693    T: DeclaredOrigin + Lived<<T as DeclaredOrigin>::Mode>,
694    Died<T>: core::error::Error + Send + Sync + 'static,
695  {
696    let Some(section) = section else {
697      return Ok(None);
698    };
699    let Some(options) = section.into_options().or(bare) else {
700      return Err(LaunchError::construction(
701        name,
702        MandatoryOptionsError::of::<Tuned<T>>(),
703      ));
704    };
705
706    T::open(&self.ctx, options)
707      .await
708      .map(Some)
709      .map_err(|error| LaunchError::construction(name, error))
710  }
711
712  /// What the walk has built so far — the map a construction reaches its shared resources through.
713  #[inline]
714  #[must_use]
715  pub const fn context(&self) -> &Resources {
716    &self.ctx
717  }
718
719  /// The filled context, for a caller that wires by hand.
720  #[inline]
721  #[must_use]
722  pub fn into_context(self) -> Resources {
723    self.ctx
724  }
725
726  /// Begin the WIRING walk — edges, clocks, and the shutdown registry.
727  ///
728  /// The only door onto [`Wiring`], as [`Wired::create`] is onto this walk and for the same reason:
729  /// connecting values nothing built is not a thing to spell. The context goes with it, because a
730  /// wired deployment is what keeps the resources alive — and so do the TAPS, so a deployment that
731  /// stated them before it built anything is watched by them from that moment on.
732  #[inline]
733  #[must_use]
734  pub fn wire(self) -> Wiring<'a> {
735    Wiring::new(self.wired, self.ctx, self.taps)
736  }
737}
738
739/// THE SINGLE-SOURCE LAW, refused: a resource was built through a door its declaration did not
740/// name.
741///
742/// There is no precedence chain to lose to, and that is the whole reason this is loud. A `prepare`
743/// closure beside a document section, or a section beside a named initializer, would be two answers
744/// to one question — and the one that won would depend on the order the walk happened to run in,
745/// which is exactly the class of surprise a start-up refusal exists to keep out of production. So
746/// the door that is not the declared one refuses, and the sentence names the one that IS, because
747/// what a reader needs is where the options belong rather than which call to delete.
748#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, derive_more::Display)]
749#[display(
750  "its declaration mounts it at `{mount}` and names {declared} as the ONE source of its options, \
751   and this launch spent {door} instead — a resource has one source, so the door that is not it \
752   refuses rather than overriding the one that is"
753)]
754pub struct ResourceSourceError {
755  mount: &'static str,
756  declared: ResourceSource,
757  door: ResourceSource,
758}
759
760impl ResourceSourceError {
761  /// The refusal a resource mounted at `mount` and declared from `declared` earns at `door`.
762  #[inline]
763  #[must_use]
764  const fn new(mount: &'static str, declared: ResourceSource, door: ResourceSource) -> Self {
765    Self {
766      mount,
767      declared,
768      door,
769    }
770  }
771
772  /// The mount its declaration wrote it under.
773  #[inline]
774  #[must_use]
775  pub const fn mount(&self) -> &'static str {
776    self.mount
777  }
778
779  /// The ONE source its declaration named.
780  #[inline]
781  #[must_use]
782  pub const fn declared(&self) -> ResourceSource {
783    self.declared
784  }
785
786  /// The door that was spent instead.
787  #[inline]
788  #[must_use]
789  pub const fn door(&self) -> ResourceSource {
790    self.door
791  }
792}
793
794impl core::error::Error for ResourceSourceError {}
795
796/// A demanded resource whose declared source produced no options, and whose options cannot be built
797/// out of nothing.
798///
799/// [`MandatoryOptionsError`]'s sentence one tier over, and it is the same rule: a section nobody
800/// wrote runs at the options' own [`Default`], and a type without one has said its knobs are
801/// mandatory. It names the OPTIONS TYPE for that reason — that is where a reader finds which knobs
802/// they now have to write — and the MOUNT, because that is the section they write them in.
803#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
804pub struct MandatoryResourceOptionsError {
805  mount: &'static str,
806  options: &'static str,
807  declared: ResourceSource,
808}
809
810impl MandatoryResourceOptionsError {
811  /// The refusal a resource mounted at `mount` and declared from `declared` earns with no options.
812  #[inline]
813  #[must_use]
814  fn of<R: AsyncResource>(mount: &'static str, declared: ResourceSource) -> Self {
815    Self {
816      mount,
817      options: type_name::<R::Options>(),
818      declared,
819    }
820  }
821
822  /// The mount its declaration wrote it under — the section a reader writes the knobs in.
823  #[inline]
824  #[must_use]
825  pub const fn mount(&self) -> &'static str {
826    self.mount
827  }
828
829  /// The options type that has no [`Default`] — the compiler's own path for it.
830  #[inline]
831  #[must_use]
832  pub const fn options(&self) -> &'static str {
833    self.options
834  }
835
836  /// The source its declaration named, which is the one that produced nothing.
837  #[inline]
838  #[must_use]
839  pub const fn declared(&self) -> ResourceSource {
840    self.declared
841  }
842}
843
844/// Written rather than derived, because the ADVICE differs by source and a reader gets one sentence:
845/// a document resource is told to write its section, and an initializer is told its function
846/// answered with nothing.
847impl core::fmt::Display for MandatoryResourceOptionsError {
848  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
849    let Self {
850      mount,
851      options,
852      declared,
853    } = self;
854    match declared {
855      ResourceSource::Section => write!(
856        f,
857        "nothing wrote its `[resources.{mount}]` section and `{options}` cannot be built out of \
858         nothing; write the section, or give the options type a `Default`"
859      ),
860      ResourceSource::Prepare | ResourceSource::Initializer => write!(
861        f,
862        "{declared} produced no options for the resource mounted at `{mount}`, and `{options}` \
863         cannot be built out of nothing"
864      ),
865    }
866  }
867}
868
869impl core::error::Error for MandatoryResourceOptionsError {}
870
871/// A resource built through the create walk that the ROOT CATALOG does not carry.
872///
873/// Unreachable from an emitted launch — the emission drives one call per catalogued field — and
874/// reachable from a hand-written one, which is why it is a refusal rather than an assumption. It
875/// names the TYPE, because the fix is a declaration: the resource is missing from the root's fields,
876/// or from the [`ResourceCatalog`](crate::ResourceCatalog) a hand-wired arrangement states in their place.
877#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, derive_more::Display)]
878#[display(
879  "the root catalog does not declare it — a resource is a FIELD of the graph root, so declare it \
880   there with `#[ingraph(resource)]`, or add it to the `ResourceCatalog` a hand-wired arrangement states \
881   in their place"
882)]
883pub struct UncataloguedResourceError {
884  resource: &'static ResourceName,
885}
886
887impl UncataloguedResourceError {
888  /// The refusal a call for an undeclared `R` earns.
889  #[inline]
890  #[must_use]
891  fn of<R: AsyncResource>() -> Self {
892    Self {
893      resource: ResourceName::of::<R>(),
894    }
895  }
896
897  /// The resource the catalog does not carry.
898  #[inline]
899  #[must_use]
900  pub const fn resource(&self) -> &'static ResourceName {
901    self.resource
902  }
903}
904
905impl core::error::Error for UncataloguedResourceError {}
906
907/// A launched node or ORIGIN whose section is BARE and whose options cannot be built out of nothing.
908///
909/// The create-time half of the mandatory-knob rule: a present section with no `options` key runs a
910/// member at its options' [`Default`], and a type without one has said that its knobs are not
911/// optional. It names the OPTIONS TYPE, because that is where a reader finds which knobs they now
912/// have to write — and naming the options rather than the member is also what lets ONE refusal serve
913/// both tiers, whose options seats are projected through different traits.
914#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, derive_more::Display)]
915#[display(
916  "its section carries no `options`, and `{options}` cannot be built out of nothing; write the \
917   node's `options` in its section, or give the options type a `Default`"
918)]
919pub struct MandatoryOptionsError {
920  options: &'static str,
921}
922
923impl MandatoryOptionsError {
924  /// The refusal a bare section over the options type `O` earns.
925  #[inline]
926  #[must_use]
927  fn of<O>() -> Self {
928    Self {
929      options: type_name::<O>(),
930    }
931  }
932
933  /// The options type that has no [`Default`] — the compiler's own path for it, so a reader can
934  /// find the knobs.
935  #[inline]
936  #[must_use]
937  pub const fn options(&self) -> &'static str {
938    self.options
939  }
940}
941
942impl core::error::Error for MandatoryOptionsError {}
943
944/// THE BARE-SECTION PROBE: does `O` have a [`Default`] for a section with no `options` to run at?
945///
946/// # Why this is a probe and not a bound
947///
948/// The walk's `T` is a type PARAMETER, and a bound written on
949/// [`Creation::node`](Creation::node) would be a bound on every node a deployment declares — which
950/// would make an options type without a `Default` undeclarable, and the mandatory-knob rule says
951/// the opposite: such a type is legal, and what it costs is that its sections must carry `options`.
952/// So the question has to be asked where the answer exists, and on stable Rust that is a site with a
953/// CONCRETE type: an inherent method whose impl block demands `Default` is preferred by method
954/// resolution, and where the bound does not hold the candidate is discarded and the autoref one
955/// below it answers instead.
956///
957/// [`bare_options!`](crate::bare_options) is the spelling, and callers should use it: it names the
958/// node, projects its options and brings the fallback's trait into scope for exactly one expression.
959///
960/// # The honest tooth
961///
962/// The probe answers what the COMPILER can prove at the site it is written. Spelled inside a generic
963/// function over an unbounded `O`, `O: Default` cannot be proven there and the answer is `None` —
964/// so a wrapper that forwards without the bound turns every bare section into a mandatory-knob
965/// refusal. The refusal names the node and the fix, so the failure is loud at start-up rather than
966/// silent; the fix for the wrapper is to spell the probe at the site that knows the type, which is
967/// the emitted arm and the hand-written launch alike.
968pub struct BareOptions<O>(PhantomData<fn() -> O>);
969
970impl<O> BareOptions<O> {
971  /// The probe for `O`.
972  #[inline]
973  #[must_use]
974  pub const fn new() -> Self {
975    Self(PhantomData)
976  }
977}
978
979impl<O> Default for BareOptions<O> {
980  #[inline]
981  fn default() -> Self {
982    Self::new()
983  }
984}
985
986/// The arm taken where `O: Default` HOLDS — an inherent method, which method resolution reaches
987/// before it autorefs into [`NoDefaultOptions`].
988impl<O: Default> BareOptions<O> {
989  /// What a bare section runs at: the options' own default.
990  #[inline]
991  #[must_use]
992  pub fn resolve(self) -> Option<O> {
993    Some(O::default())
994  }
995}
996
997/// The arm taken where `O: Default` does NOT hold — one autoref away from
998/// [`BareOptions::resolve`], which is what makes it the fallback rather than an ambiguity.
999///
1000/// Nothing implements this by hand and nothing should: it exists to be the second candidate in one
1001/// method lookup, and its blanket impl over `&BareOptions<O>` is the whole of it.
1002pub trait NoDefaultOptions {
1003  /// The options type probed for.
1004  type Options;
1005
1006  /// `None` — the type has no [`Default`], so a bare section has nothing to run at.
1007  fn resolve(self) -> Option<Self::Options>;
1008}
1009
1010impl<O> NoDefaultOptions for &BareOptions<O> {
1011  type Options = O;
1012
1013  #[inline]
1014  fn resolve(self) -> Option<O> {
1015    None
1016  }
1017}
1018
1019/// The options a resource mounted with NO document section runs at — `Some` at the options'
1020/// [`Default`], `None` where the type has none.
1021///
1022/// [`bare_options!`](crate::bare_options)'s sibling one tier over, and the probe under it is the
1023/// same one for the same reason: the answer exists only where the type is CONCRETE, so a macro is
1024/// what puts the question at a call site that has one. What differs is the projection — a resource's
1025/// options are `<R as AsyncResource>::Options` — and what does not is everything else, including the
1026/// honest tooth [`BareOptions`] records.
1027///
1028/// It is what the emitted create walk hands
1029/// [`declared_resource`](crate::Creation::declared_resource) for a `#[ingraph(resource)]` field: the
1030/// section where the deployment wrote one, and this where it did not.
1031///
1032/// # Examples
1033///
1034/// ```
1035/// # use ingraph::Resources;
1036/// use ingraph::AsyncResource;
1037///
1038/// struct Egemma;
1039/// struct EgemmaOptions {
1040///   weights: String,
1041/// }
1042///
1043/// impl AsyncResource for Egemma {
1044///   type Options = EgemmaOptions;
1045///   type Error = core::convert::Infallible;
1046///
1047///   async fn build(_ctx: &Resources, _options: EgemmaOptions) -> Result<Self, Self::Error> {
1048///     Ok(Self)
1049///   }
1050/// }
1051///
1052/// // No `Default`, so a resource nobody wrote a section for has nothing to load from.
1053/// assert!(ingraph::bare_resource_options!(Egemma).is_none());
1054///
1055/// struct Clock;
1056///
1057/// impl AsyncResource for Clock {
1058///   type Options = ();
1059///   type Error = core::convert::Infallible;
1060///
1061///   async fn build(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> {
1062///     Ok(Self)
1063///   }
1064/// }
1065///
1066/// // A zero-knob resource needs no section at all.
1067/// assert_eq!(ingraph::bare_resource_options!(Clock), Some(()));
1068/// ```
1069#[macro_export]
1070macro_rules! bare_resource_options {
1071  ($resource:ty) => {{
1072    // See `bare_options!` for why the import is here, and why an unused one is the probe answering.
1073    #[allow(unused_imports)]
1074    use $crate::NoDefaultOptions as _;
1075
1076    $crate::BareOptions::<<$resource as $crate::AsyncResource>::Options>::new().resolve()
1077  }};
1078}
1079
1080/// The options a BARE section of `$node` runs at — `Some` at the options' [`Default`], `None` where
1081/// the type has none.
1082///
1083/// The third argument of [`Creation::node`](crate::Creation::node), and the reason it is a macro is
1084/// [`BareOptions`]'s whole note: the probe answers only where the type is concrete, and a macro is
1085/// what puts it at the call site that has one. It brings the fallback's trait into scope for one
1086/// block and leaves no name behind.
1087///
1088/// # Examples
1089///
1090/// ```
1091/// use ingraph::{AsyncConstructor, Resources};
1092///
1093/// struct Decode;
1094/// struct DecodeOptions {
1095///   threads: usize,
1096/// }
1097///
1098/// impl AsyncConstructor for Decode {
1099///   type Options = DecodeOptions;
1100///   type Error = core::convert::Infallible;
1101///
1102///   async fn with_options(_ctx: &Resources, _options: DecodeOptions) -> Result<Self, Self::Error> {
1103///     Ok(Self)
1104///   }
1105/// }
1106///
1107/// // No `Default`, so a bare section has nothing to fill its knobs from.
1108/// assert!(ingraph::bare_options!(Decode).is_none());
1109///
1110/// struct Watchdog;
1111///
1112/// impl AsyncConstructor for Watchdog {
1113///   type Options = ();
1114///   type Error = core::convert::Infallible;
1115///
1116///   async fn with_options(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> {
1117///     Ok(Self)
1118///   }
1119/// }
1120///
1121/// // A zero-knob node's `()` is `Default`, which is what lets `[watchdog]` alone launch it.
1122/// assert_eq!(ingraph::bare_options!(Watchdog), Some(()));
1123/// ```
1124#[macro_export]
1125macro_rules! bare_options {
1126  ($node:ty) => {{
1127    // The fallback is a trait method, so reaching it needs the trait in scope. The import is
1128    // anonymous and lives for this block alone, so a call site gains no name it did not write.
1129    //
1130    // `unused_imports` is allowed because an unused import is the probe ANSWERING: where the options
1131    // have a `Default`, the inherent arm wins and the trait is never reached — so the warning fires
1132    // at exactly the call sites where nothing is wrong.
1133    #[allow(unused_imports)]
1134    use $crate::NoDefaultOptions as _;
1135
1136    $crate::BareOptions::<<$node as $crate::AsyncConstructor>::Options>::new().resolve()
1137  }};
1138}
1139
1140/// The options a BARE section of the ORIGIN `$origin` runs at — `Some` at the options' [`Default`],
1141/// `None` where the type has none.
1142///
1143/// [`bare_options!`](crate::bare_options)'s sibling one tier over, and the probe under it is the
1144/// same one for the same reason. What differs is the PROJECTION: an origin's options are its own
1145/// face's, reached through the mode row as [`Tuned<S>`](crate::Tuned) — one seat, and the same one
1146/// [`Creation::origin`](crate::Creation::origin) fills from the deployment's section.
1147///
1148/// # Examples
1149///
1150/// ```
1151/// use ingraph::{Context, Control, Feed, Fin, Resources, Source};
1152///
1153/// /// The declaration is what states the MODE the projection reads, so the probe is spelled over a
1154/// /// real origin rather than over a bare `Source` impl.
1155/// #[ingraph::source]
1156/// struct Counting {
1157///   remaining: u64,
1158/// }
1159///
1160/// struct CountingOptions {
1161///   remaining: u64,
1162/// }
1163///
1164/// impl Default for CountingOptions {
1165///   fn default() -> Self {
1166///     Self { remaining: 3 }
1167///   }
1168/// }
1169///
1170/// impl Source for Counting {
1171///   type Options = CountingOptions;
1172///   type Yield = u64;
1173///   type Mutation = ();
1174///   type Error = core::convert::Infallible;
1175///
1176///   fn build(_ctx: &Resources, options: CountingOptions) -> Result<Self, Self::Error> {
1177///     Ok(Self {
1178///       remaining: options.remaining,
1179///     })
1180///   }
1181///
1182///   fn run(
1183///     self,
1184///     _ctx: Context,
1185///     _feed: Feed<u64>,
1186///     _control: Control<core::convert::Infallible>,
1187///   ) -> Result<Fin, Self::Error> {
1188///     Ok(Fin::Spent)
1189///   }
1190/// }
1191///
1192/// // A bare `[counting]` section runs the origin at its own options' default.
1193/// assert_eq!(
1194///   ingraph::bare_origin_options!(Counting).map(|options| options.remaining),
1195///   Some(3)
1196/// );
1197/// ```
1198#[macro_export]
1199macro_rules! bare_origin_options {
1200  ($origin:ty) => {{
1201    // See `bare_options!` for why the import is here, and why an unused one is the probe answering.
1202    #[allow(unused_imports)]
1203    use $crate::NoDefaultOptions as _;
1204
1205    $crate::BareOptions::<$crate::Tuned<$origin>>::new().resolve()
1206  }};
1207}