bb_runtime/contracts/
bootstrap.rs

1//! `bb::Bootstrap` — optional Component initialization phase.
2//!
3//! Components override `Bootstrap::bootstrap()` to record one-shot
4//! setup logic the framework fires before any body-phase op invokes
5//! their Contract methods. Backends use this to wire backend-native
6//! tensor pools; indexes use it to mmap their on-disk state; codecs
7//! that need a calibration pass use it to drain a sample buffer.
8//!
9//! The trait default is a no-op so existing Components (Backend,
10//! Codec, Index, Aggregator, …) need no change. Authors opt in by
11//! implementing the trait alongside their primary Contract — the
12//! framework drives Bootstrap ahead of body ops when any of the
13//! Component's other Contract methods is reachable from a queued
14//! target.
15//!
16//! Today the trait ships with its types only; F5 wires the Component
17//! bootstrap dispatch path (registration + per-poll seeding).
18//! Sibling tests assert the default no-op + override observability.
19
20use crate::ids::ComponentRef;
21
22/// Per-dispatch context handed to a Component bootstrap. F5 will
23/// extend this with `RuntimeResourceRef`-style accessors so impls
24/// can stage outputs, allocate resources, or surface
25/// `CompletionHandle`s for async work. Today the struct only
26/// carries the dispatching Component's reference so impls have a
27/// stable identifier they can log against.
28///
29/// Held by-mut so the F5 plumbing can mutate per-dispatch staging
30/// state without exposing the framework's internal sequencing to
31/// the impl.
32pub struct BootstrapCtx {
33    /// `ComponentRef` of the Component whose bootstrap is firing.
34    /// Impls treat this as opaque; debug printers + telemetry taps
35    /// surface it so cross-Component traces can correlate the
36    /// bootstrap phase with later Contract-method dispatches.
37    pub component_ref: ComponentRef,
38}
39
40impl BootstrapCtx {
41    /// Construct a fresh context for `component_ref`.
42    pub fn new(component_ref: ComponentRef) -> Self {
43        Self { component_ref }
44    }
45}
46
47/// User-facing Contract trait for Component bootstrap. Default no-op
48/// means existing Components opt in by implementing the trait — the
49/// framework treats every Component as implicitly bootstrap-capable.
50///
51/// Sized to keep the trait usable as a regular bound; the framework
52/// invokes the impl through the engine's component table where each
53/// entry already carries the concrete type.
54pub trait Bootstrap {
55    /// Library-maker-defined error type. Must satisfy the standard
56    /// engine error bounds so the framework can box it into the
57    /// dispatch error channel.
58    type Error: std::error::Error + Send + Sync + 'static;
59
60    /// Run one-shot setup. Default no-op so Components without an
61    /// initialization phase need no boilerplate. Authors override
62    /// to mmap state, allocate backend tensors, prime calibration
63    /// buffers, etc.
64    fn bootstrap(&mut self, _ctx: &mut BootstrapCtx) -> Result<(), Self::Error> {
65        Ok(())
66    }
67}
68
bb_runtime/contracts/bootstrap.rs

bb_runtime/contracts/
bootstrap.rs
