Struct Node 

pub struct Node { /* private fields */ }

Constructed BB Node ready to drive ML work. Produced by [bytesandbrains::install] — by the time the host holds one, the engine has resolved its dispatch table, registered every bound concrete, and installed the target function as the root graph.

Implementations

impl Node

pub fn with_config(self, cfg: NodeConfig) -> Self

Override the default NodeConfig (the cycle / async / outbound caps). Must be called before [crate::install] for the new caps to apply at build time.

impl Node

pub fn snapshot(&self) -> Result<NodeSnapshot, SnapshotError>

Capture the snapshottable state. refuses to proceed when the bus still carries un-drained events that a restore would silently drop or re-fire stale; callers drive Node::poll to quiescence first and retry.

pub fn restore(&mut self, snap: NodeSnapshot) -> Result<(), RestoreError>

Restore a Node’s state from a snapshot.

pub fn clear(&mut self)

Reset transient runtime state without dropping the bound components or installed graphs.

pub fn incarnation(&self) -> u64

Current incarnation count. Bumped on every restore().

pub fn loaded_modules(&self) -> Vec<&str>

Names of every module registered at construction time.

pub fn linked_components(&self) -> Vec<&ComponentHandle>

References to every owned component handle.

pub fn peer_id(&self) -> PeerId

Local peer identity.

pub fn execution_state(&self, exec_id: ExecId) -> Option<&ExecutionState>

Read-only execution-state lookup.

pub fn pending_async_count(&self) -> usize

Number of AsyncSuspended Ops currently awaiting completion.

pub fn engine_stats(&self) -> EngineStats

Snapshot of the engine’s hot-path counters.

pub fn model(&self) -> Option<Arc<ModelProto>>

The compiled ModelProto the Node was installed with, or None if the Node was built internally by a crate-private path that bypassed [crate::install] (the public entry point always sets a model). Returns a shared Arc so callers can read per-target metadata without cloning the proto.

pub fn slot(&self, slot_name: &str) -> Option<ComponentRef>

Look up the ComponentRef bound at slot_name in the engine’s generic slot registry. Returns None when no slot of that name is bound.

pub fn slots_iter(&self) -> impl Iterator<Item = (&str, ComponentRef)>

Iterate every (slot_name, ComponentRef) pair bound in the engine’s slot registry.

pub fn roles_for(&self, cref: ComponentRef) -> HashSet<ComponentRole>

Inventory-declared roles for a registered component. Read from the per-Engine component_roles map populated by ensure_ready from crate::registry::roles_for_component(T::TYPE_NAME). Returns the empty set when the component wasn’t registered via a #[derive(bb::<Role>)] chain (test fixtures that hand-implement role traits surface here as empty).

pub fn block_peer(&mut self, peer: PeerId)

Add peer to the inbound + outbound blocklist.

pub fn unblock_peer(&mut self, peer: PeerId)

Remove peer from the blocklist.

pub fn set_allowlist(&mut self, allowlist: Option<HashSet<PeerId>>)

Configure an allowlist for inbound + outbound delivery.

pub fn peer_health(&self, peer: PeerId) -> Option<PeerHealth>

Per-peer health snapshot.

pub fn resolve_peer_addresses(&self, peer: PeerId) -> Option<Vec<Address>>

Resolve a PeerId to its ordered address list (cloned).

pub fn set_telemetry_tap<F>(&mut self, tap: F)

where F: FnMut(&EngineStep) + 'static,

Install an EngineStep observer onto the live Node.

pub fn add_peer( &mut self, peer: PeerId, addresses: Vec<Address>, ) -> Result<(), AddressBookError>

Announce a peer with one or more reachable addresses.

pub fn ingress_handle(&self) -> IngressQueueRef

Concern 2 - cheap-clone handle to the shared IngressQueue. Used by off-thread transport / clock adapters to push events into the Node.

pub fn config(&self) -> &NodeConfig

Read-only view on the registered NodeConfig.

pub fn peer_address(&self) -> Address

First entry of the local-address bag, or [Address::empty] when none registered. The AddressBook entry for self.peer_id() is the source of truth.

pub fn local_addresses(&self) -> &[Address]

Ordered local-address bag for this Node. Reads directly from the AddressBook entry keyed by self.peer_id(); returns an empty slice when the Node was installed with no addresses or the bag was pruned to zero entries.

pub fn add_local_address( &mut self, address: Address, ) -> Result<(), AddressBookError>

Append address to the local-address bag. Creates the AddressBook entry if none exists; idempotent on duplicates.

pub fn forget_local_address( &mut self, address: &Address, ) -> Result<(), AddressBookError>

Prune address from the local-address bag. Errors when no entry exists; succeeds (no-op) when the bag has no matching address.

pub fn run_bootstrap( &mut self, target: BootstrapTarget<'_>, ) -> Result<Vec<EngineStep>, BootstrapError>

Drive bootstrap targets to completion. Returns every EngineStep the bootstrap path emitted, including each drained phase’s BootstrapComplete or the yielding WaitingOnBootstrap. Idempotent: a Node whose bootstrap already completed (or a Node with no install-order recording) returns an empty vec.

Variant semantics:

• BootstrapTarget::All arms + seeds the install-order queue, then polls until every queued target reaches BootstrapComplete or one suspends on an async completion. Equivalent to the F4 host kick.
• BootstrapTarget::ModuleNames / BootstrapTarget::ModuleRequests validate target names + input formals atomically — the whole batch rejects with BootstrapError::UnknownTarget / BootstrapError::AlreadyTransitivelyQueued / BootstrapError::UnknownInput / BootstrapError::MissingInput before any staging happens. On success the framework copies each request’s borrowed &[u8] inputs into engine-owned storage (Principle 1a: caller slices may drop the moment this call returns), then drives the staged bodies to completion.
• BootstrapTarget::Slots resolves each slot to a registered Component bootstrap, validates the whole batch atomically, then fires each in slice order through the dispatcher. The drain loop runs after all slots fire so synchronous Immediate dispatches retire inline and async ones surface WaitingOnBootstrap.

On async suspension the host posts the matured completion via the ingress and re-invokes run_bootstrap to drain the resumed op.

Body-phase ops touching a locked ComponentRef do not fire during this call; the is_op_locked gate in pop_frontier_fireable keeps them parked until the bootstrap in-flight set drops.

pub fn bootstrap_status(&self) -> BootstrapStatus

Snapshot of the engine’s bootstrap lifecycle. Returns BootstrapStatus::Idle when no bootstrap is queued or in-flight, Running when at least one bootstrap is in-flight (the body gate is parking touched ops), and WaitingForInput when the install-order queue still has unseeded targets or host-staged requests sit on pending_requests / waiting. Pure read — does not advance any queue.

pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Vec<EngineStep>>

Drive one poll cycle. Returns Pending when the engine drains to quiescence (the ingress waker is registered with cx); otherwise yields the steps the engine made progress on. Construction-time validation lives in crate::node::Node’s installation path (see bytesandbrains::install) and surfaces InstallError before the first poll.

pub fn deliver_inbound( &mut self, src_peer: PeerId, bytes: &[u8], ) -> Result<(), DeliveryError>

Decode and push inbound wire bytes onto the ingress queue. Routes through EnvelopeCodec::decode_capped so malformed, schema-mismatched, or oversize buffers fail with DeliveryError::InvalidEnvelope BEFORE any prost allocation. The transport layer supplies src_peer so the engine can consult PeerGovernor::check_inbound before routing.

pub fn deliver_event( &mut self, module: &str, input: &str, value_bytes: &[u8], ) -> Result<(), DeliveryError>

Push an app-event onto the ingress queue.

Per Principle 1a (docs/internal/superpowers/specs/2026-06-24-engine-boundary-fallibility-and-backend-owned-tensors.md) the byte payload crosses the engine boundary as a BORROWED slice: the framework caps value_bytes.len() against NodeConfig::max_app_event_bytes, charges the length against NodeConfig::ingress_byte_budget, fallibly reserves a fresh framework-owned Vec<u8>, and copies the caller’s bytes in. The caller may free value_bytes the moment this call returns. Cap / budget / alloc failures return a synchronous DeliveryError::* AND publish a matching InfraEvent::AppIngressError on the bus for observers.

pub fn invoke( &mut self, module: &str, inputs: &[(&str, &[u8])], ) -> Result<ExecId, DeliveryError>

Invoke a Module with the given pre-encoded inputs.

Inputs cross as borrowed &[(&str, &[u8])] per Principle 1a; the framework caps count + cumulative bytes, charges against ingress_byte_budget, and per-input fallibly reserves + copies into framework-owned Vec<u8> storage. Any failure releases prior charges and emits the matching InfraEvent::AppIngressError.

Trait Implementations

impl Debug for Node

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.