Struct Engine 

pub struct Engine {
    pub syscall_table: HashMap<(String, String), StatelessInvokeFn>,
    pub self_peer: PeerId,
    pub framework: FrameworkComponents,
    pub bus: TypedBus,
    pub exec: ExecState,
    pub lifecycle_table: HashMap<String, Vec<OpRef>>,
    /* private fields */
}

Single-Node engine state. Built via Node::ensure_ready; tests use Engine::new() and seed fields directly.

Fields

syscall_table: HashMap<(String, String), StatelessInvokeFn>

Unified syscall dispatch table — one lookup per op by (domain, op_type) to its stateless invoke fn pointer. Populated by register_syscall and register_all_framework_syscalls at Engine construction; resolve_dispatch reads this to stamp OpDispatch::Stateless for matching NodeProtos.

self_peer: PeerId

The Node’s own PeerId (the one passed to Node::new). Threaded into every RuntimeResourceRef so Components can identify themselves in outbound envelopes.

framework: FrameworkComponents

Per-Node framework primitive bundle (scheduler, peer_gate, request_tracker, backoff_table, inbound_dedup, address_book). Exposed as pub so cross-crate test fixtures in bb-ops can construct RuntimeResourceRef from an Engine’s framework primitives. Engine internals proper stay encapsulated; this is the dependency-injection boundary.

bus: TypedBus

The per-Node typed event bus.

exec: ExecState

Per-poll execution-state bundle: frontier, slot table, per- execution liveness, parked async ops + in-cycle completions, function-call invocation frames, inbound-envelope context map, the timer scheduler, and the monotonic ID allocator. See crate::exec_state::ExecState.

lifecycle_table: HashMap<String, Vec<OpRef>>

Per-LifecyclePhase Op enrollments. pub for cross-crate bb-ops test fixtures that exercise the LifecyclePhase syscall.

Implementations

impl Engine

pub fn new() -> Self

Construct an empty engine with the default ingress capacity. Node::new wraps this with self_peer, framework syscalls, and config caps applied. For non-default bus_capacity use Self::with_bus_capacity so the ingress queue sizes to bus_capacity * 4 per ENGINE.md §2.2.

pub fn with_bus_capacity(bus_capacity: usize) -> Self

Construct an empty engine whose ingress queue holds up to bus_capacity * 4 events (the ENGINE.md §2.2 ratio that reserves headroom for async completions, app events, and inbound envelopes between poll cycles).

pub fn clear_for_restore(&mut self)

wipe restorable engine state ahead of a Node::restore call, leaving the install-time-stamped surfaces (graphs, functions, dispatch_table, atomic_dispatch, components, self_peer, syscall_index, role_dispatchers, binding_id_index, lifecycle_table, event_subscriptions, cycle_op_budget, max_pending_async) intact. The Node re-applies the snapshot’s framework state, ID counters, and pending async/completion queues on top of the cleared state, so the post-restore Engine is the same install re-seeded with the snapshot’s restorable transient state.

Restorable surfaces explicitly cleared:

• frontier, slot_table, execution_state, pending_async, pending_completions, pending_calls, fired_phases
• framework (FrameworkComponents reseeds from snapshot)
• bus (re-establishes subscriptions from snapshot)
• ingress queue (fresh; in-flight inbound is the host’s responsibility to redeliver)

pub fn allocate_exec_id(&mut self) -> ExecId

Mint a fresh ExecId. Replaces the prior static counter in src/ids.rs so allocation runs single-threaded under the engine’s borrow discipline.

pub fn allocate_command_id(&mut self) -> CommandId

Mint a fresh CommandId. Used by async-suspending syscall ops via RuntimeResourceRef::next_command_id.

pub fn allocate_node_site_id(&mut self) -> NodeSiteId

Mint a fresh NodeSiteId. Used by graph installation; sites must be globally unique across installed graphs.

pub fn apply_config_caps(&mut self, config: &NodeConfig)

Apply production-safety caps from a NodeConfig. Called by Node::ensure_ready after constructing the Engine; tests can invoke directly to exercise specific cap values.

pub fn ingress_bytes_in_flight(&self) -> usize

Live count of ingress bytes the engine currently holds across its ingress queue + slot table + pending async completion buffers. Updated by every successful charge / release pair on the ingress paths. Surfaced for observability (operator dashboards) and assertions.

pub fn ingress_byte_budget(&self) -> usize

Configured cap on cumulative in-flight ingress bytes, sourced from NodeConfig::ingress_byte_budget. Constant between apply_config_caps calls.

pub fn engine_stats(&self) -> EngineStats

Snapshot of the engine’s hot-path state, sized for cheap reads on every poll cycle (no allocation). Production observability: operators see saturation building up before the process locks up.

pub fn register_protocol_dispatcher<T: ProtocolRuntime + 'static>(&mut self)

where T::Error: Display,

Register a ProtocolRuntime dispatcher for the concrete component type T. Call once per T after constructing the Engine - typically alongside register_component for any component whose dispatch_atomic you want to drive. Indexed by TypeId::of::<T>() so dispatch is one HashMap lookup, not a linear scan across the registry.

pub fn register_index_dispatcher<T: IndexRuntime + 'static>(&mut self)

where <T as IndexRuntime>::Error: Display,

Register a role dispatcher keyed by TypeId::of::<T>() for a concrete IndexRuntime impl. Lets Node::with_index(&value) wire atomic dispatch even when T does not implement ProtocolRuntime. Calling this twice for the same T silently overwrites; the dispatcher is idempotent because T::dispatch_atomic is the only consumer.

pub fn register_aggregator_dispatcher<T: AggregatorRuntime + 'static>(&mut self)

where <T as AggregatorRuntime>::Error: Display,

Register an AggregatorRuntime dispatcher. See Engine::register_index_dispatcher for the rationale.

pub fn register_model_dispatcher<T: ModelRuntime + 'static>(&mut self)

where <T as ModelRuntime>::Error: Display,

Register a ModelRuntime dispatcher. See Engine::register_index_dispatcher for the rationale.

pub fn register_codec_dispatcher<T: CodecRuntime + 'static>(&mut self)

where <T as CodecRuntime>::Error: Display,

Register a CodecRuntime dispatcher. See Engine::register_index_dispatcher for the rationale.

pub fn register_data_source_dispatcher<T: DataSourceRuntime + 'static>( &mut self, )

where <T as DataSourceRuntime>::Error: Display,

Register a DataSourceRuntime dispatcher. See Engine::register_index_dispatcher for the rationale.

pub fn register_peer_selector_dispatcher<T: PeerSelectorRuntime + 'static>( &mut self, )

where <T as PeerSelectorRuntime>::Error: Display,

Register a PeerSelectorRuntime dispatcher. See Engine::register_index_dispatcher for the rationale.

pub fn register_backend_dispatcher<T: BackendRuntime + 'static>(&mut self)

where <T as BackendRuntime>::Error: Display,

Register a BackendRuntime dispatcher. The Backend Contract trait’s per-atomic-op surface dispatches through this entry, emitted from #[derive(bb::Backend)].

pub fn register_bootstrap_dispatcher<T: Bootstrap + 'static>(&mut self)

where <T as Bootstrap>::Error: Display,

Register a Bootstrap dispatcher. The Bootstrap Contract method dispatches through this entry — keyed on TypeId::of::<T>() so the engine’s fire_ready_bootstrap Component arm reaches the concrete T::bootstrap impl via downcast without scanning the registry. The derive bridge in F5 emits the call to this method alongside the Component’s other role registrations.

pub fn register_component_bootstrap(&mut self, slot: &str, cref: ComponentRef)

Bind a Component bootstrap entry. Records slot → cref in bootstrap.component_bootstraps; subsequent host-supplied BootstrapRequests targeting slot resolve the bound ComponentRef through this map. Wires the Component-arm seam the F5 install path will populate; F3 Commit 3 exposes it under test-components so the integration tests in core_component_bootstrap_tests.rs can register fixtures without going through the install pipeline.

pub fn set_component_roles( &mut self, cref: ComponentRef, roles: HashSet<ComponentRole>, )

Record the inventory-declared roles for a registered component. Node::ensure_ready calls this once per ComponentRef after registration, passing the set computed from crate::registry::roles_for_component(T::TYPE_NAME).

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

Return the inventory-declared roles for a registered component, or an empty set if the component wasn’t registered through a derive emitting ComponentRoleBinding entries. Introspection surface for engine tests + host tooling.

pub fn register_binding_id(&mut self, binding_id: String, cref: ComponentRef)

Register a binding_id → ComponentRef mapping. Called by Node::ensure_ready after binding resolution so the bound- backend lookup can resolve a NodeProto’s binding_id metadata against an installed component.

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

Look up the ComponentRef bound at the given slot name - the GENERIC dependency-resolution accessor. Components reach declared dependencies through this method (typically via crate::runtime::ComponentsView::for_slot at dispatch time). Returns None when no slot of that name is bound.

pub fn bind_slot( &mut self, slot: String, cref: ComponentRef, ) -> Option<ComponentRef>

Bind a ComponentRef at the given slot name. The install facade in the bytesandbrains crate calls this from the T8 chain; in-crate callers use it from the transitional Node::with_backend(slot, &b) path. Returns the previous binding if any.

pub fn bind_slot_id( &mut self, slot_id: u32, cref: ComponentRef, ) -> Option<ComponentRef>

Register the compiler-assigned slot_id → ComponentRef mapping. Called by bb::install() alongside Self::bind_slot; the pair is read by Self::resolve_dispatch when stamping OpDispatch::Atomic against a role NodeProto’s ai.bytesandbrains.slot_id metadata. Returns the previous binding, if any.

pub fn bind_slot_id_with_role( &mut self, slot_id: u32, role: ComponentRole, cref: ComponentRef, ) -> Option<(ComponentRole, ComponentRef)>

Register the compiler-assigned slot_id → (role, ComponentRef) mapping. Called by bb::install() alongside Self::bind_slot_id; the role is required so decode_typed_fill can branch between framework-carrier decode (Codec, Index, …) and backend-mediated tensor materialisation (Backend). Returns the previous binding, if any.

pub fn role_ref_for_slot_id( &self, slot_id: u32, ) -> Option<(ComponentRole, ComponentRef)>

Look up the (role, ComponentRef) bound at a compiler-assigned slot_id. Used by decode_typed_fill to discover whether an inbound wire payload routes through a backend.

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

Iterate every (slot_name, ComponentRef) pair currently bound. Surfaces the registry to introspection tools + the compiler’s resolve-dependencies pass.

pub fn register_event_subscription( &mut self, event_kind: &str, site: NodeSiteId, )

Subscribe a NodeSiteId to bus events of event_kind (the discriminator returned by crate::bus::NodeEvent::kind). The bus-routing pass writes a TriggerValue to each subscribed site at a fresh ExecId and pushes the site’s downstream consumers onto the frontier — uniform with wire delivery semantics per docs/ADDRESSING.md.

Node calls this at install time for every EventSource syscall op, passing the op’s output NodeSiteId.

pub fn ingress_queue_handle(&self) -> Arc<IngressQueue>

Cheap clone of the shared IngressQueue handle. Test harnesses + transport adapters push IngressEvents through this surface.

pub fn fire_lifecycle(&mut self, phase: &str)

Queue a lifecycle phase for firing on the next poll() call. The framework emits EngineStep::LifecycleFired { phase } for each queued phase and also pushes every LifecyclePhase op enrolled under that phase name (via Engine::register_lifecycle_op) onto the frontier with a fresh ExecId.

pub fn register_lifecycle_op(&mut self, phase: &str, op_ref: OpRef)

Enroll op_ref under phase per IR_AND_DSL.md §5a. Idempotent - the same (phase, OpRef) pair never enrolls twice. Node calls this at install time after parsing each LifecyclePhase NodeProto’s phase attribute.

pub fn register_syscall( &mut self, domain: &str, op_type: &str, invoke_fn: StatelessInvokeFn, )

Register a stateless syscall op. Captures TypeId::of::<T>() into both dispatch_table (TypeId → invoke fn) and syscall_index ((domain, op_type) → TypeId) so resolve_dispatch can stamp OpDispatch::Stateless.

Register a stateless syscall by its (domain, op_type) key.

pub fn register_all_framework_syscalls(&mut self)

Install every framework syscall shipped via inventory by bb-ops. Each registration carries its own (domain, op_type) + invoke pointer; the engine stamps them into syscall_table.

pub fn install_graph_for_test( &mut self, name: String, function: FunctionProto, ) -> &mut GraphSlot

Test-only installer. Inserts a fresh GraphSlot keyed by name with empty per-node tables but with op_dispatch pre-filled with Unresolved so subsequent resolve_dispatch can stamp dispatch decisions. Use Engine::install_graph for the canonical path that walks the FunctionProto.

pub fn graph(&self, name: &str) -> Option<&GraphSlot>

Resolve a graph by name. Returns None when the name isn’t registered. Equivalent to self.graphs.get(name) on the prior HashMap-keyed shape.

pub fn graph_mut(&mut self, name: &str) -> Option<&mut GraphSlot>

Resolve a graph by name for mutation. None when the name isn’t registered.

pub fn has_graph(&self, name: &str) -> bool

true when a graph with this name is installed.

pub fn graph_idx(&self, name: &str) -> Option<u32>

Resolve a graph’s positional index by name. Used by paths that need to compute OpRef::pack(idx, node_idx) from a graph name (function-call site resolution, etc.).

pub fn op_ref_at(&self, graph_name: &str, node_idx: u32) -> Option<OpRef>

Build an OpRef for the node_idx-th NodeProto of a graph identified by name. Test-only convenience for tests that used to fish the OpRef out of GraphSlot.op_index; with positional OpRef::pack(graph_idx, node_idx) the lookup is trivial.

pub fn graphs_iter(&self) -> impl Iterator<Item = &GraphSlot>

Iterate every installed GraphSlot in install order.

pub fn graphs_named(&self) -> impl Iterator<Item = (&str, &GraphSlot)>

Iterate every (name, &GraphSlot) pair in install order.

pub fn install_graph( &mut self, name: String, function: FunctionProto, ) -> &mut GraphSlot

Canonical install path: builds an GraphSlot from the FunctionProto (allocating OpRefs + NodeSiteIds for every node + produced value) and inserts it under name.

Used by [crate::node::Node::ready] for each ModelProto.functions[0]. Returns a mutable reference for any subsequent setup (slot_bindings, local_event_subs).

pub fn install_function_library( &mut self, functions: &[FunctionProto], entry_point_keys: &[FunctionKey], )

Runtime-linker install: walk model.functions[] and install each FunctionProto as an GraphSlot keyed by its canonical (domain, name, overload)-derived string. Also populates the symbol-table index functions keyed on the same tuple, so call NodeProtos can be resolved at dispatch time.

entry_point_keys lists the FunctionKeys for the registered Modules’ main partition functions - those graphs get is_entry_point = true (their top-level outputs surface as EngineStep::AppEvent; sub-function bodies do not).

A function stamped MODULE_PHASE_KEY = "bootstrap" registers its FunctionKey with the engine’s bootstrap state (appends to install_order, populates module_bootstraps) without arming pending — install is pure. The host arms the queue by calling crate::node::Node::run_bootstrap, which fans out each install-order target serially and emits one BootstrapComplete step per drained phase; multi-target installs surface their targets in slice order without further host action.

Idempotent under ODR (same key + same body) - silently skips reinstall. Caller (Node linker) is responsible for the byte-equality check before calling.

pub fn enqueue_bootstrap_request( &mut self, request: BootstrapRequest<'_>, ) -> Result<(), BootstrapError>

Stage a host-supplied crate::engine::BootstrapRequest and fire the target Module’s bootstrap immediately:

1. Resolve request.target → FunctionKey → graph_name → graph_idx.
2. Read the bootstrap function’s declared input port names (the slots minted by register_function_input_sites against function.input).
3. Validate the supplied (input_name, bytes) pairs against the formal set — missing required → MissingInput, extra → UnknownInput.
4. Allocate the body ExecId.
5. For each formal: charge against the ingress byte budget, fallibly reserve a framework-owned Vec<u8> via the try_reserve_exact seam, copy in the caller’s borrowed bytes, wrap as BytesValue, and write into the slot table at (site, body_exec_id). The caller’s slices may drop the moment this call returns — Principle 1a satisfied.
6. Mark the Module bootstrap in-flight + push the body’s OpRefs onto the frontier so the next Engine::poll drives it to completion.

Mid-flight failures (budget exhaustion, allocator fault) release every byte charge admitted earlier in the same call so the counter never leaks. The seed/in-flight bookkeeping only lands once every input stages successfully, so a failed request leaves the engine’s bootstrap state untouched.

pub fn run_bootstrap(&mut self) -> bool

Arm the install-order bootstrap queue + seed the next target. Host entry point invoked through crate::node::Node::run_bootstrap. Returns true when arming queued work (the caller should poll); false when no install-order target remains (idempotent on a fully drained Node).

Cascade-fires multiple targets via the same maybe_complete_bootstrap reseed path the body-poll cycle uses: one call here picks the next target, the regular drain advances next_idx, and the next seed_bootstrap_call (inside poll) picks the following target.

pub fn bootstrap_function_key(&self) -> Option<FunctionKey>

(domain, name, overload) of the first bootstrap function recorded at install time, or None when no module_phase = "bootstrap" FunctionProto reached the function library. Stable across clear_for_restore (which preserves install-order metadata but bumps next_idx past every queued target so the restored Node does not re-fire bootstraps it already ran). For the full ordered list (multi-target installs queue one key per target), use Self::bootstrap_function_keys.

pub fn bootstrap_function_keys(&self) -> Vec<FunctionKey>

All bootstrap function keys the engine has queued, in install order. Multi-target installs append one entry per target via Self::install_function_library; the seeder fires each in slice order. Stable across clear_for_restore for snapshot introspection.

pub fn bootstrap_pending(&self) -> bool

true while a bootstrap call is outstanding. Armed by Self::run_bootstrap (host kick) or by the host’s staged-formals path (enqueue_bootstrap_request); cleared once every queued phase drains.

pub fn has_component_bootstrap(&self, slot: &str) -> bool

true when a Component bootstrap is registered for slot. Today the Component bootstrap registry stays empty so this always returns false; F5 wires the registration path. Wired now so the host can introspect the Bootstrap Contract surface without reaching through internal accessors.

pub fn bootstrap_status(&self) -> BootstrapStatus

Lifecycle status for the host-facing crate::node::Node::bootstrap_status accessor. Idle when no bootstrap is queued or in-flight; Running when one or more bootstraps occupy in_flight (the body gate is parking touched ops); WaitingForInput when work is staged on pending_requests but no in-flight phase has been seeded yet (the host must drive the queue to advance).

pub fn fire_component_bootstrap_by_slot( &mut self, slot: &str, ) -> Result<ComponentRef, BootstrapError>

Fire a Component bootstrap by slot name. Resolves slot → ComponentRef via bootstrap.component_bootstraps, builds a ReadyBootstrap with the bound cref as the touch set, and dispatches through the engine’s internal fire path. Returns the dispatching ComponentRef on success so the host can wire per-slot telemetry; surfaces BootstrapError::UnknownTarget when no Component bootstrap is registered at the slot.

pub fn module_bootstrap_registered(&self, target_name: &str) -> bool

true when target_name is already on the install-order Module bootstrap queue (so Node::run_bootstrap can surface AlreadyTransitivelyQueued before re-staging the same target).

pub fn module_bootstrap_target_names(&self) -> Vec<String>

Snapshot of every registered Module bootstrap target name in install order. Used by Node::run_bootstrap to enqueue an empty-input request per target without reaching into the engine’s private install_order Vec.

pub fn resolve_dispatch(&mut self) -> usize

Resolve every NodeProto’s dispatch kind into op_dispatch[] per ENGINE.md §8.1 + §8.4. Run after install completes (so all symbols are in self.functions) but before the first poll.

Walk order: each GraphSlot in turn. For each NodeProto:

• syscall (syscall_index hit) → Stateless
• call to function in self.functions with domain ai.bytesandbrains.module → FunctionCall with the target key + input/output rename pairs from the call’s value names zipped against the target function’s formals.
• call to function with domain ai.bytesandbrains.framework starting with BackendSubgraph_ → BackendSubgraph with bound backend resolved via BINDING_ID_KEY metadata against the atomic-dispatch table.
• else atomic dispatch by (domain, op_type, instance) → Atomic.

Returns the number of nodes that remained Unresolved. Caller should fail build if non-zero.

pub fn component(&self, cref: ComponentRef) -> Option<&dyn ErasedComponent>

Resolve a registered component by ComponentRef. None when no component lives at that index, or when the slot was mem::take-ed out during dispatch (the caller dispatching component is invisible to itself).

pub fn component_mut( &mut self, cref: ComponentRef, ) -> Option<&mut Box<dyn ErasedComponent>>

Resolve a registered component by ComponentRef for mutation. Same null semantics as Self::component.

pub fn register_component( &mut self, cref: ComponentRef, component: Box<dyn ErasedComponent>, )

test-only registrar. Stores a bound component impl at cref. Grows the underlying Vec to fit the index, filling holes with None so out-of-order registration works.

pub fn push_frontier(&mut self, op_ref: OpRef, exec_id: ExecId)

Push an (OpRef, ExecId) onto the frontier.

pub fn pop_frontier(&mut self) -> Option<(OpRef, ExecId)>

Pop the next (OpRef, ExecId) off the frontier. Used by the poll cycle’s drain phases.

pub fn slot_table_keys(&self) -> Vec<(NodeSiteId, ExecId)>

Snapshot of the (NodeSiteId, ExecId) keys currently in the slot table. Test-only - used to assert wire-envelope delivery lands at the right site without exposing the full Box<dyn SlotValue> payload type.

pub fn slot_table_iter( &self, ) -> impl Iterator<Item = (&(NodeSiteId, ExecId), Option<&dyn SlotValue>)>

Iterate every ((NodeSiteId, ExecId), Option<&dyn SlotValue>) pair currently in the slot table. Test-only.

pub fn slot_at( &self, site: NodeSiteId, exec_id: ExecId, ) -> Option<&dyn SlotValue>

Read a slot value by (NodeSiteId, ExecId). Returns None if the slot is empty or not yet allocated.

impl Engine

pub fn handle_completion( &mut self, cmd_id: CommandId, values: Vec<(String, Box<dyn SlotValue>)>, ) -> Vec<EngineStep>

Handle a CommandId completion per ENGINE.md §9.2. Writes the values into the suspended Op’s output sites + pushes ready downstream consumers onto the frontier.

pub fn handle_completion_failed( &mut self, cmd_id: CommandId, error: OpError, ) -> Vec<EngineStep>

Handle a transport-reported failure for a suspended CommandId. The Op that was waiting on cmd_id fails through the existing OpFailed path (bus InfraEvent::OpFailure + EngineStep::OpFailed). Use this when the host’s transport adapter learns that the remote side failed to produce a result - the framework no longer silently swallows the outcome.

pub fn poll(&mut self) -> Vec<EngineStep>

8-phase poll cycle per ENGINE.md §7.

Trait Implementations

impl Default for Engine

fn default() -> Self

Returns the “default value” for a type.