Kernel Developer Guide
Practical guide for working with the WeftOS kernel: building, testing, extending, adding modules, and common development patterns.
This guide covers practical development workflows for working with the WeftOS kernel.
Building
Always use scripts/build.sh for build operations:
# Build native CLI (release)
scripts/build.sh native
# Build native CLI (debug, fast iteration)
scripts/build.sh native-debug
# Fast compile check (no codegen)
scripts/build.sh check
# Lint (clippy, warnings as errors)
scripts/build.sh clippy
# Full phase gate (11 checks -- use before committing)
scripts/build.sh gateTesting
Use scripts/build.sh test (it runs nextest when installed, else cargo test, and takes package names to narrow the scope):
scripts/build.sh test # whole workspace
scripts/build.sh test clawft-kernel # one packageRaw cargo test is for debugging a specific failure with flags the script does not expose. Feature combinations (crates/clawft-kernel/Cargo.toml, [features]):
cargo test -p clawft-kernel # default features
cargo test -p clawft-kernel --no-default-features --features native
cargo test -p clawft-kernel --features "wasm-sandbox,containers,os-patterns"The default features are native, exochain, cluster, tilezero, ecc, mesh, quic and workload-runtime. wasm-sandbox, containers and os-patterns are off by default. Earlier versions of this page quoted per-feature test counts; they were out of date and are not kept.
Project structure
The kernel crate has 224 entries under src/ (see Kernel Architecture for the module groups and the feature each needs). The files you will touch most:
crates/clawft-kernel/src/
lib.rs crate root: module declarations and re-exports
boot.rs Kernel<P>, boot and shutdown
process.rs ProcessTable
supervisor.rs AgentSupervisor, SpawnRequest, restart strategies (os-patterns)
capability.rs AgentCapabilities, CapabilityChecker
ipc.rs, a2a.rs, topic.rs, agent_loop.rs messaging
service.rs ServiceRegistry, SystemService, ServiceApi, adapters
chain.rs, tree_manager.rs, gate.rs ExoChain (exochain)
governance.rs GovernanceEngine (always compiled)
mesh*.rs mesh transport and admission (mesh)
workload_*/ workload placement runtime and governance
causal.rs, cognitive_tick.rs, hnsw_service.rs ECC (ecc)Adding a New Kernel Module
-
Create the source file in
crates/clawft-kernel/src/. -
Add module declaration in
lib.rs:// If feature-gated: #[cfg(feature = "my-feature")] pub mod my_module; // If always compiled: pub mod my_module; -
Add re-exports for key types:
#[cfg(feature = "my-feature")] pub use my_module::{MyType, MyOtherType}; -
Add tests as a
#[cfg(test)] mod testsblock inside the module. -
If feature-gated, add the feature to
Cargo.toml:[features] my-feature = ["dep:some-crate"]
Integration Checklist
Every new module should satisfy:
- Chain logging for state changes (if
exochainfeature) - Tree registration in standard namespace
- Gate check before privileged operations
- Tests (aim for >80% coverage)
- CLI commands in
clawft-weave(if user-facing) - Feature flag if external dependency
- Documentation: a page under
docs/src/content/docs/weftos/(the site) and, for operator-facing behaviour,docs/guides/
Common Patterns
Adding a System Service
Implement the SystemService trait and register during boot:
use crate::service::{ServiceType, SystemService};
use crate::health::HealthStatus;
pub struct MyService { /* ... */ }
#[async_trait]
impl SystemService for MyService {
fn name(&self) -> &str { "my-service" }
fn service_type(&self) -> ServiceType { ServiceType::Core }
async fn start(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
async fn stop(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
async fn health_check(&self) -> HealthStatus { HealthStatus::Healthy }
}Adding Chain Events
#[cfg(feature = "exochain")]
{
let event = chain.append( // ChainManager methods take &self
"my-module", // source
"my-module.action", // kind
Some(json!({ // payload
"key": "value"
})),
);
}Adding a Gate Check
#[cfg(feature = "exochain")]
if let Some(gate) = &self.gate {
let context = json!({ "pid": pid, "tool": tool_name });
match gate.check(&agent_id, "tool.my_tool", &context) {
GateDecision::Permit { .. } => { /* proceed */ }
GateDecision::Deny { reason, .. } => {
return Err(KernelError::GovernanceDenied(reason));
}
GateDecision::Defer { reason } => { /* queue for review */ }
}
}Using DashMap for Concurrent State
use dashmap::DashMap;
pub struct MyRegistry {
entries: DashMap<String, MyEntry>,
}
impl MyRegistry {
pub fn insert(&self, key: String, entry: MyEntry) {
self.entries.insert(key, entry);
}
pub fn get(&self, key: &str) -> Option<MyEntry> {
self.entries.get(key).map(|e| e.clone())
}
}Feature Flag Guidelines
- Use feature gates for external dependencies (wasmtime, docker, quinn, snow)
- Keep what is off by default off (
wasm-sandbox,containers,os-patterns,onnx-embeddings); the default set already includesexochain,ecc,meshandquic - All types should compile unconditionally where possible
- Feature gates control runtime behavior, not type definitions
- One feature flag per subsystem (not per-module)
CLI Integration
Kernel commands are exposed through the weaver binary (clawft-weave):
weaver kernel start # Boot the kernel daemon
weaver kernel stop # Graceful shutdown (--force escalates TERM to KILL)
weaver kernel status # Show kernel state
weaver kernel logs # Boot and event log snapshot
weaver kernel services # Registered services and health
weaver kernel ps # Process listing
weaver agent list # List agents
weaver agent inspect <pid> # Show process details
weaver agent spawn <type> # Spawn a new agent
weaver chain status # ExoChain status
weaver chain verify # Verify chain integrityThe complete list is the generated CLI reference.
Debugging
# Run with verbose logging
RUST_LOG=clawft_kernel=debug cargo test -p clawft-kernel
# Run a specific test
cargo test -p clawft-kernel test_name -- --nocapture
# Trace A2A routing
RUST_LOG=clawft_kernel::a2a=trace cargo test -p clawft-kernel