Integration Patterns
How RVF crypto, ExoChain, resource trees, governance, and scoring integrate across the WeftOS kernel.
WeftOS Integration Patterns
How RVF crypto, ExoChain, resource trees, governance, and scoring integrate across the kernel. This document is the primary reference for K3+ implementors adding new subsystems.
1. The Three Pillars
WeftOS kernel integration rests on three interconnected subsystems:
- ExoChain (the ledger) -- append-only hash-linked event log
- Resource Tree (the economy) -- hierarchical namespace with Merkle integrity
- Governance Gate (the judiciary) -- effect-algebra access control
Every new kernel subsystem should integrate with all three.
2. ExoChain Integration
When to Log
Log a chain event when:
- An agent lifecycle state changes (spawn, suspend, resume, stop)
- A message is sent or received (IPC events)
- A resource is created, modified, or deleted (tree mutations)
- An access control decision is made (gate events)
- A service starts or stops
- A cron job fires
How to Log
// Get chain reference (passed through boot or daemon context)
let chain: Arc<ChainManager> = /* from kernel context */;
// Append an event
let event = chain.append(
"source-module", // e.g. "supervisor", "governance", "cron"
"event.kind", // e.g. "agent.spawn", "governance.permit"
Some(serde_json::json!({
"agent_id": "agent-1",
"action": "tool.exec",
"details": { /* arbitrary JSON */ }
})),
);
// event.sequence, event.hash now availableEvent Naming Convention
{source}.{verb}
Examples:
agent.spawn supervisor spawned an agent
agent.suspend agent suspended
agent.resume agent resumed
ipc.recv message received
ipc.ack acknowledgment sent
cron.fire cron job executed
tree.insert resource tree node created
tree.remove resource tree node deleted
tree.bootstrap standard namespaces created
governance.permit gate permitted action
governance.deny gate denied action
governance.warn gate permitted with warning
governance.defer gate deferred to human
gate.permit capability gate permitted
gate.deny capability gate denied
service.start service started
service.stop service stopped
service.contract.register service API schema anchored (D8)
service.contract.version new contract version published
shell.wasm.compile shell script compiled to WASM (D10)Chain Verification
let result = chain.verify_integrity();
assert!(result.valid);
// result.event_count, result.errors availableRVF Persistence
The chain persists to RVF segment files on kernel shutdown:
// Save (called during Kernel::shutdown)
chain.save_to_rvf(&path)?;
// Load (called during Kernel::boot)
let chain = ChainManager::load_from_rvf(&path)?;RVF file format:
- Segment header (ExoChainHeader: magic, version, chain_id, sequence)
- CBOR-encoded payload (ChainEvent fields)
- Content hash for validation
- Padding to 64-byte boundary
- Ed25519 signature footer (last segment)
Witness Chains
Witness chains provide independent verification:
// Create witness entries from chain events
let verified = chain.verify_witness()?; // Ok(count of verified witness entries)
// Record provenance (DNA-style lineage)
let event = chain.record_lineage(child_id, parent_id, parent_hash,
DerivationType::Clone, 0, "description"); // ids are [u8; 16], parent_hash [u8; 32]3. Resource Tree Integration
When to Use
Register resources in the tree when:
- A new agent is spawned ->
/kernel/agents/{name} - A service is registered ->
/kernel/services/{name} - An app is installed ->
/apps/{name} - A cluster peer joins ->
/network/peers/{node_id} - An environment is created ->
/environments/{name}
How to Integrate
let tree: Arc<TreeManager> = /* from kernel context */;
// Insert a node (creates a chain event and a mutation event)
tree.insert(
ResourceId::new("/kernel/my_module/instance-1"),
ResourceKind::Namespace,
ResourceId::new("/kernel/my_module"),
)?;
// Higher-level helpers exist for the common cases, for example
// tree.register_agent(agent_id, pid, &caps) and tree.register_service(...)
// (crates/clawft-kernel/src/tree_manager.rs).Standard Namespace Layout
/
├── kernel/
│ ├── services/ # registered SystemService instances
│ ├── processes/
│ └── agents/ # spawned agent processes
├── apps/ # installed applications (AppManifest)
├── network/
│ └── peers/ # cluster peer nodes
└── environments/ # governance-scoped environmentsTwo-Way Traceability
Tree mutations append a chain event and a mutation-log entry (TreeManager::insert appends a tree/insert event). The chain event payload carries the tree path. Whether every node also stores its chain_seq was not re-verified for this page.
Merkle Integrity
The resource tree uses rvf_crypto for Merkle hashing. After any mutation,
the tree's root hash changes, providing tamper-evident integrity.
4. Governance Gate Integration
When to Gate
Gate checks should happen when:
- An agent attempts to execute a tool (
tool.exec) - An agent modifies cron jobs (
service.cron.add,service.cron.remove) - An agent sends a message to another agent (IPC scope check)
- An application requests privileged capabilities
- A service call is routed through A2ARouter (D7 routing-time check)
- A WASM tool is loaded or executed (K3)
- A container is started or stopped (K4)
- An app is installed or started (K5)
How to Add a Gate Check
In the agent loop or any command handler:
// Gate is available as Option<Arc<dyn GateBackend>>
if let Some(ref gate) = gate {
let context = serde_json::json!({
"pid": pid,
"effect": {
"risk": 0.3,
"security": 0.2,
"privacy": 0.1,
"novelty": 0.0,
"fairness": 0.0
}
});
match gate.check(agent_id, "tool.my_action", &context) {
GateDecision::Permit { .. } => {
// proceed with action
}
GateDecision::Defer { reason } => {
// queue for human review
// send error reply to agent
}
GateDecision::Deny { reason, .. } => {
// log denial, send error reply
}
}
}Effect Vector Guidelines
The 5D effect vector quantifies the impact of an action:
| Dimension | Meaning | Example |
|---|---|---|
risk | Probability of negative outcome | 0.9 for rm -rf, 0.1 for read |
security | System security impact | 0.8 for credential access |
privacy | Data privacy impact | 0.7 for PII processing |
novelty | How unprecedented the action is | 0.5 for first-time tool use |
fairness | Impact on equitable treatment | 0.3 for resource reallocation |
Magnitude calculation: sqrt(risk^2 + security^2 + privacy^2 + novelty^2 + fairness^2)
The symposium plan (C9, D20) was to make the EffectVector N-dimensional with named dimensions. That is not implemented: EffectVector in governance.rs has exactly the five fields above.
If the score exceeds the engine's risk threshold and a Blocking or Critical rule applies, the action is denied or escalated; see Governance for the exact decision. Environment thresholds are 0.9 (development), 0.6 (staging) and 0.3 (production).
Adding Governance Rules
let gate = GovernanceGate::new(0.8, false) // threshold, human_approval
.with_chain(chain.clone())
.add_rule(GovernanceRule {
id: "my-rule".into(),
description: "Block dangerous operations".into(),
branch: GovernanceBranch::Judicial,
severity: RuleSeverity::Blocking,
active: true,
reference_url: None,
sop_category: None,
rule_type: GovernanceRuleType::General,
action_selector: None,
tool_selector: None,
force_on_match: false,
});Rule severities:
Advisory-- no effect on the decisionWarning-- permit with a warning when the threshold is exceededBlocking-- denies (or escalates) when the threshold is exceeded orforce_on_matchis setCritical-- treated likeBlockingby the engine
5. RVF Crypto Usage
Available Functions (rvf-crypto)
| Function | Purpose | Used In |
|---|---|---|
shake256_256(data) | SHAKE-256 hash (256-bit) | ChainManager event hashing |
sign_segment(data, key) | Ed25519 signing | Chain checkpoint persistence |
verify_segment(data, sig, pubkey) | Ed25519 verification | Chain loading |
create_witness_chain(entries) | Serialize witness entries | Witness chain creation |
verify_witness_chain(data) | Parse + verify witnesses | Witness chain verification |
lineage_record_to_bytes(record) | Serialize lineage | Provenance tracking |
lineage_witness_entry(lineage) | Create witness from lineage | Spawn provenance |
encode_signature_footer(footer) | Encode sig footer | RVF file writing |
decode_signature_footer(data) | Decode sig footer | RVF file loading |
Available Types (rvf-types)
| Type | Purpose |
|---|---|
ExoChainHeader | 64-byte segment header (magic, version, chain_id, sequence, timestamp, prev_hash) |
LineageRecord | DNA-style provenance: parent_id, child_id, derivation_type, timestamp |
DerivationType | Clone, Mutate, Combine, Derive, Fork |
FileIdentity | File identifier tuple (file_id, parent_id, parent_hash, lineage_depth) |
Scorecard | Witness scorecard for aggregated metrics |
EXOCHAIN_MAGIC | Magic bytes [0x45, 0x58, 0x4F] ("EXO") |
SEGMENT_HEADER_SIZE | 32 bytes |
Available Functions (rvf-wire)
| Function | Purpose |
|---|---|
read_segment(data) | Parse segment header + payload |
validate_segment(header, data) | Verify content hash |
write_exochain_event(header, payload) | Create full RVF segment |
calculate_padded_size(size) | Align to 64-byte boundaries |
6. Pattern: Adding a New Gated Subsystem
When implementing K3+ features that need full integration, follow this pattern:
Step 1: Define the Module
// crates/clawft-kernel/src/my_module.rs
pub struct MyManager {
// ... module state
}
impl MyManager {
pub fn new() -> Self { /* ... */ }
}Step 2: Add Chain Logging
impl MyManager {
pub fn do_action(
&self,
#[cfg(feature = "exochain")] chain: &Option<Arc<ChainManager>>,
) {
// ... perform action ...
#[cfg(feature = "exochain")]
if let Some(ref cm) = chain {
cm.append("my_module", "my_module.action", Some(json!({
"details": "..."
})));
}
}
}Step 3: Register in Resource Tree
// During boot or registration
#[cfg(feature = "exochain")]
if let Some(ref tree) = tree_manager {
tree.insert(
ResourceId::new("/kernel/my_module/instance-1"),
ResourceKind::Namespace,
ResourceId::new("/kernel/my_module"),
)?;
}Step 4: Add Gate Check
// Before performing a potentially risky action
#[cfg(feature = "exochain")]
if let Some(ref gate) = gate {
let ctx = json!({"pid": pid.0, "effect": {"risk": 0.5}});
match gate.check(agent_id, "my_module.action", &ctx) {
GateDecision::Permit { .. } => { /* proceed */ }
GateDecision::Deny { reason, .. } => {
return Err(KernelError::PermissionDenied(reason));
}
GateDecision::Defer { reason } => {
return Err(KernelError::DeferredToHuman(reason));
}
}
}Step 5: Wire into Boot
In boot.rs or daemon.rs, initialize your module during kernel boot and pass
chain/tree/gate references as needed.
Step 6: Add CLI Commands
In crates/clawft-weave/src/commands/, add a command module following existing
patterns (e.g. resource_cmd.rs, chain_cmd.rs).
Step 7: Write Tests
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn action_logs_to_chain() {
let cm = Arc::new(ChainManager::new(0, 100));
let manager = MyManager::new();
manager.do_action(&Some(cm.clone()));
let events = cm.tail(1);
assert_eq!(events[0].kind, "my_module.action");
}
#[test]
fn action_denied_by_gate() {
// ... test gate denial ...
}
}7. Integration Status Matrix
This matrix is the K3-era snapshot of which module touches which pillar. Several entries were not re-checked at 0.8.4 (for example
cron.fireandpeer.joinevent names, andconfig.rsloading governance). Treat it as a pointer to where to look, and confirm in the code. Known corrections:send_checkedonly appends anipc.sendchain event; it does not check capabilities (the router'ssenddoes).
| Module | Chain | Tree | Governance | Gate |
|---|---|---|---|---|
| boot.rs | Boot events | Bootstrap tree | Init engine | Create gate |
| process.rs | Via agent_loop | /kernel/agents | Via capabilities | Via gate check |
| supervisor.rs | agent.spawn/stop | /kernel/agents/{name} | Enforce spawn rules | Gate spawn |
| ipc.rs | ipc.send/recv/ack | - | Check scope | IPC scope |
| a2a.rs | Via send_checked | - | Sender capabilities | routing-time gate (D7) + send_checked |
| topic.rs | Via publish | - | Subscription perms | Check access |
| agent_loop.rs | Built-in logging | - | - | Before exec/cron |
| cron.rs | cron.fire | /kernel/cron | Execution perms | Gate execution |
| health.rs | Health results | - | - | - |
| service.rs | service.start/stop | /kernel/services | - | - |
| chain.rs | IS the chain | Checkpoint metadata | Lineage | - |
| tree_manager.rs | tree.insert/remove | IS the tree | Via scoring | Via gate |
| gate.rs | governance.* events | - | IS the engine | IS the gate |
| governance.rs | - | - | IS the engine | EffectVector scoring |
| cluster.rs | peer.join/leave | /network/peers | Node join rules | - |
| app.rs | app.install/start | /apps | Validate manifest | Check perms |
| container.rs | container.start/stop | /kernel/services | - | - |
| environment.rs | - | /environments | Scoped governance | Environment rules |
| agency.rs | Role assignments | /kernel/agents | Agent manifests | - |
| wasm_runner.rs | Tool execution | - | Sandbox policy | Via capability |
| console.rs | Boot events | - | - | - |
| config.rs | - | - | Load governance | - |
| capability.rs | - | - | Enforced at gate | Central to gate |
| error.rs | - | - | - | - |
8. K2 Symposium Patterns
The K2 Symposium (2026-03-04) introduced several new integration patterns for K3+.
Full decisions: k2-symposium/08-symposium-results-report.md
Service Routing
Services are separate from processes (D1). MessageTarget::Service(name) routes
through ServiceRegistry::resolve_target() to find the owning agent's PID.
// Route to a service by name
let msg = KernelMessage {
to: MessageTarget::Service("redis".to_string()),
// ...
};
// A2ARouter resolves "redis" -> owner PID -> deliver to inboxDual-Layer Gate (D7)
Every service call passes TWO gate checks:
- Routing-time in
A2ARouter::route()-- prevents unauthorized messages from reaching services - Handler-time in
kernel_agent_loop()-- GovernanceGate checks before command execution
Universal Witness (D9)
Every service call generates a witness entry by default (SHAKE-256, sub-microsecond).
Services can opt out via AuditLevel::GateOnly in their ServiceEntry.
Chain-Anchored Contracts (D8)
When a service registers its schema, the schema hash is written to the ExoChain:
chain.append("service", "service.contract.register", json!({
"service": name,
"version": 1,
"schema_hash": shake256(&schema_bytes),
}));ECC Worked Example (K3c)
The ECC cognitive substrate (Phase K3c) demonstrates the standard integration pattern for adding a new subsystem to the kernel.
Step 1: Define module (causal.rs, hnsw_service.rs, etc.)
Each module is a standalone Rust file with its own types, public API, and tests.
Feature-gated via #[cfg(feature = "ecc")] in lib.rs.
Step 2: Add chain logging
ECC operations emit chain events with ecc.* event kinds:
ecc.boot.calibration-- calibration results at bootecc.hnsw.insert,ecc.hnsw.search-- vector operationsecc.causal.link-- causal edge creationecc.crossref.create-- cross-structure referenceecc.impulse.emit-- ephemeral eventsecc.tick.drift-- tick budget exceeded
Step 3: Register in resource tree
Boot creates 6 namespaces under /kernel/services/ecc/:
/kernel/services/ecc/
/kernel/services/ecc/hnsw/
/kernel/services/ecc/causal/
/kernel/services/ecc/tick/
/kernel/services/ecc/calibration/
/kernel/services/ecc/crossrefs/Step 4: Add gate checks
7 tool specs in builtin_tool_catalog() with ToolCategory::Ecc:
ecc.embed, ecc.search, ecc.causal.link, ecc.causal.query,
ecc.crossref.create, ecc.tick.status, ecc.calibration.run.
Each has an EffectVector for governance scoring.
Step 5: Wire into boot
boot_ecc() runs after tree bootstrap:
- Create
HnswService,CausalGraph,CrossRefStore,ImpulseQueue - Run
run_calibration()-- N synthetic ticks measuring performance - Create
CognitiveTickwith calibrated interval - Register
HnswServiceandCognitiveTickasSystemService - Log calibration to chain
- Advertise
NodeEccCapabilityto cluster
Step 6: Add CLI commands
weaver ecc subcommands: status, calibrate, search, causal, crossrefs, tick.
Step 7: Write tests
83 unit tests across 6 modules + integration via calibration tests.
See Also
- ExoChain -- detailed ExoChain documentation
- Governance -- governance engine details
- Kernel Modules -- per-module reference
Feature Flags
The Cargo feature flags of the kernel, the weftos and weaver binaries, and where the full per-crate reference lives.
Kernel Modules
Where each part of the clawft-kernel crate is documented, grouped by subsystem. The per-file reference was removed because it could not be kept in step with the code.