Module engine 

The sans-IO Engine state machine. The sans-IO Engine state machine

Modules

bootstrap

Engine bootstrap state — consolidated owner of every bootstrap field the engine reads during install + poll.

call_context

Per-function-call invocation context.

core

The Engine struct + test-only constructor + registration accessors. Hot-path poll cycle lives in engine::poll.

dispatch_entry

Engine dispatch types

graph_slot

GraphSlot - per-FunctionProto compiled data per docs/ENGINE.md §3.

invoke

Op invocation lifecycle

pending_async

PendingAsync + ExecutionState - engine’s async-suspension bookkeeping + execution liveness tracking per §5.3.

poll

8-phase poll cycle + handle_completion per docs/ENGINE.md §7 + §9.

step

EngineStep - observable output of Engine::poll per docs/ENGINE.md §10 + docs/internal/IMPLEMENTATION_PLAN.md //! lines 751-753.

Structs

BootstrapRequest

Host-supplied bootstrap input staging request — borrowed shape per the F5 host-driven bootstrap spec (docs/internal/superpowers/specs/2026-06-25-host-driven-bootstrap.md §3.1). The host hands the engine a target name plus an ordered (input_name, value_bytes) slice; the engine validates against the target’s declared formal input ports and runs the Principle 1a copy (cap-check → try_reserve_exact → extend_from_slice) so the caller’s borrowed buffers can drop the moment crate::engine::core::Engine::enqueue_bootstrap_request returns.

ComponentBootstrap

Per-slot Component bootstrap metadata. Stamped into the engine bootstrap state when a Component registers a Bootstrap Contract impl. Empty today; F5 wires the registration path.

Engine

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

EngineStats

Point-in-time hot-path counters for dashboards + saturation detection. Not synchronized against an in-flight poll cycle.

ExecutionState

Per-execution liveness tracker Stored in Engine.execution_state, keyed by ExecId. /// minimum-viable: just the output counter for GC bookkeeping; may extend.

GraphSlot

Per-FunctionProto compiled data installed on the Engine. Keyed in Engine.graphs by (domain, name, overload) - the canonical symbol-table key the linker dedupes on. The map key IS the name, so GraphSlot carries no separate name field.

InFlightBootstrap

Currently executing bootstrap. The host-driven seeder (Engine::seed_bootstrap_call) pops one Module target per phase and pushes it here; the Vec shape supports concurrent disjoint Component bootstraps fired through the conflict-queue path.

ModuleBootstrap

Per-target Module bootstrap metadata. Stamped into the engine bootstrap state when the install path sees a module_phase = bootstrap FunctionProto.

OwnedBootstrapRequest

Owned-form bootstrap input request used by the engine’s internal conflict-queue path (BootstrapState::pending_requests). The host- facing borrowed BootstrapRequest is the canonical staging shape; this owned mirror exists so the conflict queue can keep parked requests alive across poll cycles. Kept internal-ish to the engine — the [BootstrapState::enqueue_request] consumer is exercised by sibling tests only.

PendingAsync

Bookkeeping for an Op suspended on a CommandId per docs/ENGINE.md §9.1. Stored in Engine.pending_async, keyed by CommandId.

QueuedBootstrap

Validated + staged bootstrap awaiting an in-flight slot. F4 drains waiting once in_flight clears. Empty today.

ReadyBootstrap

Validated + staged bootstrap that cleared the touch-set conflict check and is ready for the engine to assign an ExecId + push its body onto the frontier. The conflict queue (BootstrapState::process_pending_requests / on_bootstrap_drained) emits ReadyBootstraps back to the engine instead of mutating in-flight state directly so the seed step (ExecId allocation, frontier population) stays on the engine side where the OpRef tables live.

Enums

BootstrapKind

Discriminator for the two bootstrap dispatch kinds the engine drives. Module bootstraps splice into the FunctionCall path under a fresh ExecId; Component bootstraps invoke a Contract method on the bound runtime impl directly.

BootstrapStatus

Host-facing bootstrap lifecycle status. Returned by Node::bootstrap_status so the caller can decide whether to keep polling or surface a “wait for input” prompt. F3 fills the observable surface.

EngineStep

One step of work the engine performed during a poll cycle. Engine::poll returns Vec<EngineStep> capturing every event the host can observe.

OpDispatch

Per-OpRef dispatch decision, pre-stamped at install time by Engine::resolve_dispatch. Runtime invoke is one indirect probe against GraphSlot.op_dispatch[idx]. Four variants:

Functions

make_protocol_dispatcher

Build a RoleDispatcher for a concrete ProtocolRuntime impl. Called from Engine::register_protocol_dispatcher and from any test/production setup that needs to register dispatcher entries on a fresh Engine.

Type Aliases

StatelessInvokeFn

Stateless syscall invoke fn pointer Same input/output shape as a role-trait dispatch_atomic call; returns DispatchResult for uniform handling by invoke_one.