Boot Sequence and Lifecycle
WeftOS kernel boot state machine, boot phases and events, service registration, shutdown sequence, and boot event logging.
The WeftOS kernel manages its lifecycle through a KernelState state machine. The Kernel<P: Platform> struct is the central coordinator, wrapping AppContext<P> with structured startup and shutdown.
Source: crates/clawft-kernel/src/boot.rs (the kernel boot and shutdown), crates/clawft-kernel/src/console.rs (boot events), crates/clawft-weave/src/daemon.rs (the daemon that owns signals and the RPC listener)
KernelState State Machine
pub enum KernelState {
Booting,
Running,
ShuttingDown,
Halted,
}- Booting: the kernel is initializing subsystems.
- Running: all subsystems are active and the daemon accepts RPC requests.
- ShuttingDown: graceful teardown.
Kernel::shutdownreturnsWrongStateunless the state isRunning. - Halted: terminal state.
Boot Phases
Boot events carry a BootPhase (console.rs). There are eight phases:
| Phase | Tag | Meaning in the enum |
|---|---|---|
Init | INIT | Pre-boot initialization |
Config | CONFIG | Loading configuration |
Services | SERVICES | Registering system services |
ResourceTree | Loading the resource tree from the DAG | |
Agents | Spawning service agents | |
Network | Network service discovery | |
Ecc | ECC cognitive substrate initialization | |
Ready | Boot complete, ready for commands |
The phases label log events; they are not strictly sequential. In boot.rs the Network and Services events interleave because mesh and chain setup are interleaved with service registration.
What boot does
Kernel::boot calls boot_with_node_key with no persisted key (an ephemeral node identity, used by tests and one-shot CLI boots). The daemon boots with its persisted node key, so the node id, derived from the key by node_id_from_pubkey, is stable across restarts (ADR-025, ADR-103 D11). The main steps, in the order they appear in boot_bound (boot.rs):
- Resolve the chain location, and take
chain.lockbeside the chain so only one kernel runs per chain. An older lock-unaware kernel still writing the legacy chain makes boot refuse. - Resolve the runtime-file directory used for cluster peers, apps and the revocation list. A
projectkernel takes its rules from the user's signed parent policy (ADR-103 D8). - Create the process table, service registry,
AppContext(reusing the existing bootstrap),KernelIpcon the app's message bus, and the health system. - Register the kernel as PID 0.
- Derive the node identity. With mesh enabled, the key-derived node id is shared with the mesh and assessment transports up front.
- Load the host revocation list.
- Create cluster membership (always present). Peer membership and the installed application catalog (
apps.json) persist to disk and survive restarts. - With the
clusterfeature, register the cluster service; mesh withoutclusterstill gets membership. - Register services and start them. With mesh enabled the listener must bind or boot fails (ADR-103 D2). Mesh admission is allow-all unless
kernel.mesh.genesis_hashis pinned. - With the
exochainfeature, start the chain and tree manager, and attach the governance gate: the genesis rules are written to the chain, then the gate is wired into the A2A router for dual-layer enforcement. - With the
eccfeature, run calibration and register the HNSW and cognitive-tick services. - Log
Readyand move toRunning.
The default feature set of clawft-kernel is native, exochain, cluster, tilezero, ecc, mesh, quic and workload-runtime (Cargo.toml, [features]). The containers, wasm-sandbox, os-patterns, treesitter and http-api features are off by default.
Resource tree namespaces
With exochain, TreeManager::bootstrap creates the namespaces /kernel, /kernel/services, /kernel/processes, /kernel/agents, /network, /network/peers, /apps and /environments (tree_manager.rs, bootstrapped_paths).
Boot Event Logging
Every boot step emits a BootEvent to the BootLog:
pub struct BootEvent {
pub timestamp: DateTime<Utc>,
pub phase: BootPhase,
pub message: String,
pub level: LogLevel, // Debug, Info, Warn, Error
pub seq: u64, // assigned by KernelEventLog on ingest (WEFT-434)
}The KernelEventLog aggregates events. weaver kernel logs shows a snapshot and weaver kernel attach streams them (crates/clawft-weave/src/commands/kernel_cmd.rs header).
Service Registration
Services are registered with the ServiceRegistry while boot runs. Those seen in boot.rs are cron, the assessment service, the container service, mesh, and with ecc the HNSW and cognitive-tick services. Use weaver kernel services on a running kernel for the live list; this page no longer carries a table of services because the set changes between releases.
Each service implements the SystemService trait (service.rs):
#[async_trait]
pub trait SystemService: Send + Sync {
fn name(&self) -> &str;
fn service_type(&self) -> ServiceType;
async fn start(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>>;
async fn stop(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>>;
async fn health_check(&self) -> HealthStatus;
fn health_detail(&self) -> Option<String> { None }
// plus further probe methods with defaults
}Shutdown Sequence
Triggered by weaver kernel stop, SIGINT, SIGTERM, or an RPC shutdown. The daemon (daemon.rs) bounds every step with a time limit and logs it; a guard thread ends the process if the whole shutdown overruns, and kernel.pid is removed only at exit (CHANGELOG 0.8.4-rc.15, "Bounded shutdown"). In order:
- Stop accepting on the router and stop the mesh listeners first, so a slow later step never leaves a dying daemon holding its ports.
- Finish the RPC accept loop, then the child accept loop.
- Shut down stream-window anchors, so they flush their final windows before the chain manager stops.
- Drain the agent service: in-flight
agent.chatdispatches are cancelled and the drain waits up to 5 seconds. Kernel::shutdown: setShuttingDown, callServiceRegistry::stop_all, append akernel/shutdownevent to the chain (tree root hash, chain sequence, node count), abort agent tasks, cancel every process except PID 0, and save the chain as an RVF checkpoint with a JSON fallback plus a tree checkpoint (boot.rs,Kernel::shutdown).- State becomes
Haltedand the process exits.
weaver kernel stop exits 1 and keeps the pid file when the daemon does not exit. weaver kernel stop --force finds the daemon through kernel.lock and escalates from TERM to KILL (CHANGELOG 0.8.4-rc.15).
Signal Handling
| Signal | Action (daemon.rs) |
|---|---|
SIGINT, SIGTERM | Begin graceful shutdown |
SIGHUP | Shut down, then re-exec the daemon (boot_refusal.rs plans the re-exec) |
On Windows only Ctrl+C is handled.
Kernel Public API
impl<P: Platform> Kernel<P> {
pub async fn boot(config: Config, kernel_config: KernelConfig, platform: Arc<P>)
-> KernelResult<Self>;
pub async fn boot_with_node_key(config, kernel_config, platform, node_key_seed: Option<[u8; 32]>)
-> KernelResult<Self>;
pub async fn shutdown(&mut self) -> KernelResult<()>;
pub fn boot_log(&self) -> &BootLog;
// accessors for the process table, service registry, IPC, health and A2A router
}