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}