clawft
Weftos

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 gate

Testing

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 package

Raw 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

  1. Create the source file in crates/clawft-kernel/src/.

  2. Add module declaration in lib.rs:

    // If feature-gated:
    #[cfg(feature = "my-feature")]
    pub mod my_module;
    
    // If always compiled:
    pub mod my_module;
  3. Add re-exports for key types:

    #[cfg(feature = "my-feature")]
    pub use my_module::{MyType, MyOtherType};
  4. Add tests as a #[cfg(test)] mod tests block inside the module.

  5. 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 exochain feature)
  • 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 includes exochain, ecc, mesh and quic
  • 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 integrity

The 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

On this page