clawft

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::shutdown returns WrongState unless the state is Running.
  • Halted: terminal state.

Boot Phases

Boot events carry a BootPhase (console.rs). There are eight phases:

PhaseTagMeaning in the enum
InitINITPre-boot initialization
ConfigCONFIGLoading configuration
ServicesSERVICESRegistering system services
ResourceTreeLoading the resource tree from the DAG
AgentsSpawning service agents
NetworkNetwork service discovery
EccECC cognitive substrate initialization
ReadyBoot 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):

  1. Resolve the chain location, and take chain.lock beside the chain so only one kernel runs per chain. An older lock-unaware kernel still writing the legacy chain makes boot refuse.
  2. Resolve the runtime-file directory used for cluster peers, apps and the revocation list. A project kernel takes its rules from the user's signed parent policy (ADR-103 D8).
  3. Create the process table, service registry, AppContext (reusing the existing bootstrap), KernelIpc on the app's message bus, and the health system.
  4. Register the kernel as PID 0.
  5. Derive the node identity. With mesh enabled, the key-derived node id is shared with the mesh and assessment transports up front.
  6. Load the host revocation list.
  7. Create cluster membership (always present). Peer membership and the installed application catalog (apps.json) persist to disk and survive restarts.
  8. With the cluster feature, register the cluster service; mesh without cluster still gets membership.
  9. 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_hash is pinned.
  10. With the exochain feature, 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.
  11. With the ecc feature, run calibration and register the HNSW and cognitive-tick services.
  12. Log Ready and move to Running.

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:

  1. Stop accepting on the router and stop the mesh listeners first, so a slow later step never leaves a dying daemon holding its ports.
  2. Finish the RPC accept loop, then the child accept loop.
  3. Shut down stream-window anchors, so they flush their final windows before the chain manager stops.
  4. Drain the agent service: in-flight agent.chat dispatches are cancelled and the drain waits up to 5 seconds.
  5. Kernel::shutdown: set ShuttingDown, call ServiceRegistry::stop_all, append a kernel/shutdown event 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).
  6. State becomes Halted and 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

SignalAction (daemon.rs)
SIGINT, SIGTERMBegin graceful shutdown
SIGHUPShut 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
}

On this page