Core Framework

KernelComponent trait, state machine, orchestrator, event system, and panic handling.

Profile Reference

Core Framework

The helix-core crate is the heart of the kernel. It defines the fundamental abstractions that every other crate depends on — the orchestrator that manages subsystem lifecycles, the capability broker that controls resource access, and the panic handler that decides what happens when things go wrong.

Everything in helix-core is designed around the KernelComponent trait. If your code is part of the kernel, it implements this trait.

KernelComponent Trait

This is the base interface for any kernel subsystem or service. It provides lifecycle management, health monitoring, and runtime statistics.

core/src/component.rs
rust
pub trait KernelComponent: Send + Sync {
fn name(&self) -> &'static str;
fn init(&mut self) -> KernelResult<()>;
fn start(&mut self) -> KernelResult<()>;
fn stop(&mut self) -> KernelResult<()>;
fn status(&self) -> ComponentStatus;
fn health_check(&self) -> bool;
fn stats(&self) -> ComponentStats;
9
}
10
2 refs
pub struct ComponentStats {
12
pub uptime_ns: u64,
13
pub operations: u64,
14
pub errors: u64,
15
pub last_error: Option<String>,
16
pub memory_bytes: usize,
17
}
Index

Kernel State Machine

The kernel itself is a state machine. Every transition is logged and can trigger registered callbacks — this is how NEXUS monitors kernel health.

Kernel State Machine6N · 7E
init completeall subsystems upcomponent failureself-healedshutdown signalunrecoverablecomplete▶BootingHardware initializat…1InitializingSubsystem startup2RunningNormal kernel operat…3DegradedPartial failure2ShuttingDownGraceful shutdown3■HaltedTerminal state1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node
StateDescriptionTransitions To
EarlyBootFirmware just handed controlInitializing
InitializingSubsystems starting in dependency orderRunning
RunningNormal operation — all subsystems activeShuttingDown, Panic, Suspended
ShuttingDownGraceful shutdown in progressPanic
PanicUnrecoverable fault — halt or reboot—
SuspendedLow-power state (future)Running

Kernel Errors

Errors in Helix are strongly typed. Every subsystem returns KernelResult<T>, which uses this error enum. This makes error handling consistent across the entire codebase.

core/src/lib.rs
rust
2 refs
pub enum KernelError {
2
NotPermitted,
3
NotFound,
4
AlreadyExists,
5
InvalidArgument,
6
WouldBlock,
7
Busy,
8
OutOfMemory,
9
Timeout,
10
Interrupted,
11
IoError,
12
NotImplemented,
13
Internal,
14
CapabilityError(CapabilityError),
15
SubsystemError(&'static str),
16
}
17
pub type KernelResult<T> = Result<T, KernelError>;
Index

Event System

The kernel event system allows components to react to state changes without tight coupling. Components register as listeners and receive events asynchronously.

core/src/events.rs
rust
2 refs
pub enum KernelEvent {
2
ComponentStarted(String),
3
ComponentStopped(String),
4
ComponentFailed { name: String, error: String },
5
StateChanged { from: KernelState, to: KernelState },
6
MemoryPressure { level: MemoryPressureLevel, available: u64 },
7
Tick { timestamp_ns: u64, tick_number: u64 },
8
Shutdown,
9
}
10
pub trait KernelEventListener: Send + Sync {
fn on_event(&self, event: &KernelEvent);
fn event_filter(&self) -> Option<Vec<KernelEventType>> { None }
14
}
Index

Orchestrator

The Orchestrator is the top-level kernel manager. It owns every subsystem, starts them in dependency order, monitors their health, and coordinates shutdown. Think of it as the init process, but for kernel components.

core/src/orchestrator.rs
rust
2 refs
pub struct Orchestrator {
2
subsystems: Vec<Box<dyn Subsystem>>,
3
lifecycle: LifecycleManager,
4
capabilities: CapabilityBroker,
5
panic_handler: Box<dyn PanicHandler>,
6
}
7
2 refs
impl Orchestrator {
pub fn new() -> Self;
pub fn register(&mut self, subsystem: Box<dyn Subsystem>);
pub fn start_all(&mut self) -> KernelResult<()>;
pub fn stop_all(&mut self) -> KernelResult<()>;
pub fn health_report(&self) -> Vec<(String, bool)>;
14
}
Index

Subsystem Trait

Every major kernel component implements Subsystem. It extends KernelComponent with dependency declarations so the orchestrator can resolve the startup order automatically.

core/src/subsystem.rs
rust
pub trait Subsystem: KernelComponent {
fn dependencies(&self) -> Vec<&'static str>;
fn provides(&self) -> Vec<&'static str>;
fn priority(&self) -> u32 { 100 } // Lower = starts first
fn is_essential(&self) -> bool { false }
6
}
7
8
// If an essential subsystem fails, the kernel panics.
9
// Non-essential subsystems enter Degraded state.
Index

Lifecycle Manager

The lifecycle manager tracks component states and fires callbacks on transitions. This is how the self-healing system knows when something crashes.

Component Lifecycle6N · 7E
init()start()stop()panic / crashauto-recoverysuccessfailed againRegisteredModule known to kern…1Initializinginit() called2Runningstart() completed4StoppedGraceful stop1FailedUnrecoverable error2RestartingRecovery in progress2
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node
core/src/lifecycle.rs
rust
4 refs
pub enum LifecycleState {
2
Registered, Initializing, Running,
3
Stopped, Failed(String), Restarting,
4
}
5
3 refs
pub struct LifecycleCallback {
7
pub on_start: Option<Box<dyn Fn(&str)>>,
8
pub on_stop: Option<Box<dyn Fn(&str)>>,
9
pub on_fail: Option<Box<dyn Fn(&str, &str)>>,
10
pub on_restart: Option<Box<dyn Fn(&str)>>,
11
}
12
2 refs
pub struct LifecycleManager {
14
states: HashMap<String, LifecycleState>,
15
callbacks: Vec<LifecycleCallback>,
16
}
17
2 refs
impl LifecycleManager {
pub fn transition(&mut self, name: &str, to: LifecycleState);
pub fn add_callback(&mut self, cb: LifecycleCallback);
pub fn state_of(&self, name: &str) -> Option<&LifecycleState>;
22
}
Index

Capability Broker

Helix uses a capability-based security model. Instead of traditional Unix permissions, every resource access requires a capability token. The broker manages grants, revocations, and rights checking.

core/src/capabilities.rs
rust
1
bitflags! {
4 refs
pub struct CapabilityRights: u32 {
3
const READ = 1 << 0;
4
const WRITE = 1 << 1;
5
const EXECUTE = 1 << 2;
6
const CREATE = 1 << 3;
7
const DELETE = 1 << 4;
8
const GRANT = 1 << 5; // Can delegate this capability
9
const ADMIN = 1 << 6; // Full control
10
}
11
}
12
2 refs
pub enum ResourceType { Memory, Io, Interrupt, File, Process, Module, Device }
14
2 refs
pub struct CapabilityBroker { /* ... */ }
16
2 refs
impl CapabilityBroker {
pub fn grant(&mut self, subject: SubjectId, resource: ResourceType,
19
rights: CapabilityRights) -> CapabilityToken;
pub fn check(&self, token: &CapabilityToken,
21
required: CapabilityRights) -> bool;
pub fn revoke(&mut self, token: CapabilityToken);
2 refs
pub fn delegate(&mut self, token: &CapabilityToken,
24
to: SubjectId, rights: CapabilityRights) -> Option<CapabilityToken>;
25
}
Index

Panic Handler

When something goes critically wrong, the panic handler decides what to do. It's a trait — you can replace the default handler with your own recovery strategy.

core/src/panic.rs
rust
pub trait PanicHandler: Send + Sync {
fn on_panic(&self, info: &PanicInfo) -> PanicAction;
3
}
4
2 refs
pub enum PanicAction {
6
Halt, // Stop the CPU
7
Reboot, // Triple-fault reboot
8
RecoverComponent(String), // Try to restart the failed component
9
ContinueDegraded, // Mark as degraded and keep running
10
}
11
12
// Kernel assertion macros — use instead of std assert!
13
macro_rules! kernel_assert {
14
($cond:expr) => { if !($cond) { kernel_panic!("assertion failed"); } };
15
($cond:expr, $msg:expr) => { if !($cond) { kernel_panic!($msg); } };
16
}
Index

The PanicAction::RecoverComponent option is what enables self-healing. Instead of halting on every failure, the kernel can attempt to restart just the failed component while everything else keeps running.