Struct Kernel 

pub struct Kernel { /* private fields */ }

Top-level kernel orchestrator.

Lifecycle: Kernel::new (or Kernel::new_with_wal / Kernel::new_with_wal_signed) → register_action → create_instance → submit → step (repeat) → optional snapshot / export_wal.

Kernel is !Sync (A2 single-thread) and is owned by the caller — no internal locking, no async. All determinism guarantees depend on the caller driving a single kernel from one thread.

Implementations

impl Kernel

pub fn new() -> Self

Construct a fresh kernel with no instances, no observers, and no WAL. Use new_with_wal or new_with_wal_signed instead if you want WAL recording from step zero.

pub fn new_with_wal(world_id: [u8; 32], manifest_digest: [u8; 32]) -> Self

Construct a Kernel with an attached WAL writer. Each successfully committed step appends one record (A13/A14).

pub fn new_with_wal_signed( world_id: [u8; 32], manifest_digest: [u8; 32], sig_class: SignatureClass, ) -> Self

Construct a Kernel with a WAL writer that signs each record under the supplied SignatureClass (A16 — Ed25519 (Tier 2) or Hybrid (Ed25519 + ML-DSA 65, CNSA 2.0)). The verifying key is pinned in the WAL header so post-hoc verification is self-contained.

pub fn wal_chain_tip(&self) -> Option<[u8; 32]>

Current chain tip if the kernel has a WAL attached.

pub fn wal_record_count(&self) -> Option<usize>

Number of WAL records currently buffered (None if no WAL attached).

pub fn export_wal(self) -> Option<Wal>

Consume the kernel and return the accumulated WAL (if any).

pub fn register_action<A: Action>(&mut self)

Register a domain action type with the kernel’s dispatch registry. Required before submit accepts the action’s TYPE_CODE.

pub fn register_observer( &mut self, obs: Box<dyn KernelObserver>, ) -> ObserverHandle

Register an observer for every kernel event. Equivalent to register_observer_filtered with EventMask::ALL.

pub fn register_observer_filtered( &mut self, obs: Box<dyn KernelObserver>, mask: EventMask, ) -> ObserverHandle

Register an observer with an event-class filter. Only events whose variant bit is set in mask are delivered to this observer — useful when an observer cares about a narrow slice of the event stream (e.g. only DOMAIN_EVENT_EMITTED). EventMask::ALL is equivalent to register_observer.

pub fn create_instance(&mut self, config: InstanceConfig) -> InstanceId

Create a new instance with the supplied config. Returns the freshly-allocated InstanceId (monotonic per kernel lifetime).

pub fn instances_len(&self) -> usize

Number of live instances.

pub fn instance_view(&self, id: InstanceId) -> Option<InstanceView<'_>>

Read-only view of one instance’s state. Returns None if id does not exist. The borrow is &self, so callers cannot mutate the kernel concurrently while a view is live.

pub fn snapshot(&self) -> KernelSnapshot

Capture current kernel state as a serializable snapshot. Excludes observers and action registry — caller re-registers those after Kernel::from_snapshot(...). WAL is independent and not captured here.

pub fn from_snapshot(snap: KernelSnapshot) -> Self

Restore a Kernel from a snapshot. The returned kernel has no observers, an empty action registry, and no attached WAL — caller must re-register everything before resuming step().

pub fn stats(&self) -> Stats

Aggregate observability across all instances. See Stats.

pub fn force_unload( &mut self, route_id: RouteId, caps: CapabilityMask, ) -> Result<usize, ArkheError>

Force-unload: drop every instance’s inflight-refs entry for route_id and emit KernelEvent::ModuleForceUnloaded with the summed live-ref count for the audit trail. Requires ADMIN_UNLOAD.

Returns the total live refs that were dropped (Ok(0) if no instance held the route).

pub fn submit( &mut self, instance: InstanceId, principal: Principal, actor: Option<EntityId>, at: Tick, action_type_code: TypeCode, action_bytes: Vec<u8>, ) -> Result<ScheduledActionId, ArkheError>

Schedule a serialized action against an instance for execution at tick at. The bytes must be the canonical postcard encoding produced by <A as Action>::canonical_bytes() for some previously-registered action type matching action_type_code. Returns the freshly-allocated ScheduledActionId.

Errors with ArkheError::InstanceNotFound if instance is unknown.

pub fn step(&mut self, now: Tick, caps: CapabilityMask) -> StepReport

Process at most one due action per instance, in ascending InstanceId order (A23). Returns aggregated counters for the step.

Trait Implementations

impl Default for Kernel

fn default() -> Self

Returns the “default value” for a type.