Kernel Architecture
Deep dive into the WeftOS kernel's layer model, module groups, key types, and feature gate matrix, checked against the 0.8.4 code.
The kernel crate crates/clawft-kernel is organized into layers that build on each other. The layer and phase names (K0 to K6) come from the kernel phase plan; see Kernel Phases. Many modules are gated by feature flags where external dependencies are involved.
At 0.8.4 the crate has 224 entries under src/ (files and directories; git ls-tree count) and exports 187 top-level modules (grep -c '^pub mod\|^mod ' src/lib.rs). Earlier versions of this page listed about 30 files; the crate has grown far beyond that, so this page names module groups and points to the code for the rest.
Layer model
+-------------------------------------------------------------------+
| MESH AND PLACEMENT (K6 and later) features: mesh, quic |
| mesh*.rs (54 non-test modules: noise, framing, listener, QUIC, |
| mDNS, Kademlia, admission, liveness, swarm, artifacts, leaf) |
| workload_*, licence/, exposure/, node_facts/ (placement, |
| licensing, exposures; see platform pages) |
+-------------------------------------------------------------------+
| SERVICES (K3-K5) |
| wasm_runner/ -- WASM tool execution (wasmtime when wasm-sandbox)|
| container.rs -- container lifecycle |
| app.rs -- application manifests and lifecycle |
| governance.rs -- three-branch governance engine |
| environment.rs, agency.rs, assessment/, substrate_service.rs |
+-------------------------------------------------------------------+
| IPC (K2) |
| ipc.rs, a2a.rs (agent-to-agent router), topic.rs, agent_loop.rs, |
| cron.rs, health.rs, service.rs (registry, ServiceApi, adapters) |
+-------------------------------------------------------------------+
| PROCESS (K1) |
| process.rs (PID table), supervisor.rs, capability.rs |
+-------------------------------------------------------------------+
| BOOT (K0) |
| boot.rs (Kernel<P>), console.rs (boot events), config.rs, |
| error.rs |
+-------------------------------------------------------------------+
| Cross-cutting: EXOCHAIN (feature exochain) |
| chain.rs, chain_*.rs (anchoring, storage, migration, subscribe), |
| tree_manager.rs, gate.rs, token_authority/, governance_overlay.rs|
+-------------------------------------------------------------------+
| Cross-cutting: ECC cognitive substrate (feature ecc) |
| causal.rs, cognitive_tick.rs, crossref.rs, hnsw_service.rs, |
| embedding*.rs, vector_*.rs, spatial_*.rs, weaver.rs |
+-------------------------------------------------------------------+The node daemon (crates/clawft-weave, binary weaver) hosts the kernel and adds the RPC server, the router and the cogbus broker; the kernel crate is the library underneath.
Layered protocol architecture (Symposium D4)
Protocol adapters bind to the internal ServiceApi:
Kernel IPC
|
v
ServiceApi (service.rs -- internal, local dispatch)
|
+---> McpAdapter (service.rs)
+---> ShellAdapter (service.rs)
+---> HTTP modules (http_api.rs, http_facade.rs; feature http-api, off by default)ShellAdapter and McpAdapter are in crates/clawft-kernel/src/service.rs. No gRPC adapter exists in the tree (grep -ril grpc crates/clawft-kernel/src matches only chain_anchor.rs, agency.rs and assessment/analyzers/network.rs, none an adapter). The symposium plan named one; it was not built.
Module groups
| Group | Modules | Feature |
|---|---|---|
| Boot and process | boot, console, config, error, process, supervisor, capability, capability_claim | default |
| IPC and services | ipc, a2a, topic, agent_loop, agent_registry, cron, health, service, config_service, auth_service | native for the router, loop and registry |
| Apps and environments | app, container, environment, agency, wasm_runner, assessment | container and wasm_runner compile always; wasmtime itself needs wasm-sandbox |
| ExoChain | chain, chain_anchor, chain_storage, chain_migrate, chain_subscribe, tree_manager, gate, token_authority, governance_overlay, overlay_*, parent_policy | exochain |
| ECC | causal, cognitive_tick, crossref, calibration, hnsw_service, impulse, embedding*, vector_*, spatial_*, democritus, weaver | ecc |
| Mesh | mesh* | mesh (QUIC under quic) |
| Workloads and placement | workload_runtime, workload_ctl, workload_kind, workload_pkg, workload_governance, cog_ingest, infer_proxy | workload-runtime (Unix), plus ecc/exochain/mesh for some |
| Licence | licence/ | mesh + ecc + exochain + native |
| Observability (os-patterns) | monitor, reconciler, dead_letter, log_service, metrics, named_pipe, reliable_queue, timer | os-patterns |
Source for the module-to-feature mapping: #[cfg(...)] attributes in crates/clawft-kernel/src/lib.rs.
Key types
Kernel (boot.rs)
The central coordinator, generic over the Platform trait so it runs on native and browser targets. Its fields include (not exhaustive): state, config, app_context, the message bus, process_table, service_registry, ipc, a2a_router, cron_service, assessment_service, health, supervisor, boot_log, event_log, cluster_membership, app_manager, revocation_list, agent_registry, node_registry, substrate_service, and feature-gated chain (a ChainSubsystem), ecc (an EccSubsystem) and observability.
pub enum KernelState { Booting, Running, ShuttingDown, Halted }See Boot Sequence for how these are created and stopped.
ProcessTable (process.rs)
PID-based agent tracking. Entries live in a DashMap<Pid, ProcessEntry> with an atomic PID counter and a max_processes limit. See Process Table.
A2ARouter (a2a.rs)
Agent-to-agent routing with per-agent inboxes. When the governance gate is wired in at boot, routing and handler checks both enforce it (dual-layer, symposium D7).
ChainManager and TreeManager (exochain)
ChainManager is the append-only hash-linked event log (chain.rs). TreeManager is a facade over the resource tree, a mutation log and the chain: every tree mutation creates a chain event. See ExoChain.
Feature flags
default = ["native", "exochain", "cluster", "tilezero", "ecc", "mesh", "quic", "workload-runtime"]. Off by default: wasm-sandbox, containers, os-patterns, treesitter, http-api, sensor, onnx-embeddings, diskann, mesh-rvf (experimental), quantum-pasqal and quantum-braket (experimental; interface only, stubs return NotImplemented). Source: crates/clawft-kernel/Cargo.toml, [features].
| Feature | Pulls in |
|---|---|
exochain | resource tree, RVF crypto and wire crates, ed25519, CBOR |
tilezero | exochain plus cognitum-gate-tilezero |
cluster | ruvector cluster, raft and replication |
mesh | ed25519, weftos-leaf-types, WebSocket, Noise (snow) |
quic | mesh plus quinn, rcgen, rustls |
ecc | core vector memory, the BVH crate |
workload-runtime | native, ecc, exochain, reqwest, rustls, serde_yaml |
wasm-sandbox | wasmtime and wasmtime-wasi |
Concurrency model
| Primitive | Usage |
|---|---|
DashMap | Concurrent maps for the process table, service registry and A2A inboxes |
tokio::sync::Mutex | Protecting chain and tree internals |
Arc | Shared ownership across async tasks |
CancellationToken | Cooperative shutdown for agent loops and services |
tokio::sync::mpsc | Channels for IPC message delivery |