clawft

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

GroupModulesFeature
Boot and processboot, console, config, error, process, supervisor, capability, capability_claimdefault
IPC and servicesipc, a2a, topic, agent_loop, agent_registry, cron, health, service, config_service, auth_servicenative for the router, loop and registry
Apps and environmentsapp, container, environment, agency, wasm_runner, assessmentcontainer and wasm_runner compile always; wasmtime itself needs wasm-sandbox
ExoChainchain, chain_anchor, chain_storage, chain_migrate, chain_subscribe, tree_manager, gate, token_authority, governance_overlay, overlay_*, parent_policyexochain
ECCcausal, cognitive_tick, crossref, calibration, hnsw_service, impulse, embedding*, vector_*, spatial_*, democritus, weaverecc
Meshmesh*mesh (QUIC under quic)
Workloads and placementworkload_runtime, workload_ctl, workload_kind, workload_pkg, workload_governance, cog_ingest, infer_proxyworkload-runtime (Unix), plus ecc/exochain/mesh for some
Licencelicence/mesh + ecc + exochain + native
Observability (os-patterns)monitor, reconciler, dead_letter, log_service, metrics, named_pipe, reliable_queue, timeros-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].

FeaturePulls in
exochainresource tree, RVF crypto and wire crates, ed25519, CBOR
tilezeroexochain plus cognitum-gate-tilezero
clusterruvector cluster, raft and replication
meshed25519, weftos-leaf-types, WebSocket, Noise (snow)
quicmesh plus quinn, rcgen, rustls
ecccore vector memory, the BVH crate
workload-runtimenative, ecc, exochain, reqwest, rustls, serde_yaml
wasm-sandboxwasmtime and wasmtime-wasi

Concurrency model

PrimitiveUsage
DashMapConcurrent maps for the process table, service registry and A2A inboxes
tokio::sync::MutexProtecting chain and tree internals
ArcShared ownership across async tasks
CancellationTokenCooperative shutdown for agent loops and services
tokio::sync::mpscChannels for IPC message delivery

Boot and shutdown

See Boot Sequence and Lifecycle.

On this page