// 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 available

{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)

let result = chain.verify_integrity();
assert!(result.valid);
// result.event_count, result.errors available

// Save (called during Kernel::shutdown)
chain.save_to_rvf(&path)?;

// Load (called during Kernel::boot)
let chain = ChainManager::load_from_rvf(&path)?;

// Create witness entries from chain events
let witness = chain.verify_witness()?;

// Record provenance (DNA-style lineage)
let lineage = chain.record_lineage(parent_id, child_id, DerivationType::Clone);

let tree: Arc<TreeManager> = /* from kernel context */;

// Insert a node (automatically creates chain event + mutation event)
tree.insert(
    "/kernel/agents/worker-1",
    HashMap::from([
        ("pid".to_string(), "42".to_string()),
        ("type".to_string(), "worker".to_string()),
    ]),
)?;

// The chain event includes the tree path and metadata
// The tree node stores chain_seq for two-way traceability

/
├── kernel/
│   ├── services/       # registered SystemService instances
│   ├── agents/         # spawned agent processes
│   └── cron/           # registered cron jobs
├── apps/               # installed applications (AppManifest)
├── network/
│   └── peers/          # cluster peer nodes
└── environments/       # governance-scoped environments

// Gate is available as Option<Arc<dyn GateBackend>>
if let Some(ref gate) = gate {
    let context = serde_json::json!({
        "pid": pid.0,
        "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
        }
    }
}

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,
    });

// crates/clawft-kernel/src/my_module.rs

pub struct MyManager {
    // ... module state
}

impl MyManager {
    pub fn new() -> Self { /* ... */ }
}

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": "..."
            })));
        }
    }
}

// During boot or registration
#[cfg(feature = "exochain")]
if let Some(ref tree) = tree_manager {
    tree.insert("/kernel/my_module/instance-1", metadata)?;
}

// 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));
        }
    }
}

#[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 ...
    }
}

// Route to a service by name
let msg = KernelMessage {
    to: MessageTarget::Service("redis".to_string()),
    // ...
};
// A2ARouter resolves "redis" -> owner PID -> deliver to inbox

chain.append("service", "service.contract.register", json!({
    "service": name,
    "version": 1,
    "schema_hash": shake256(&schema_bytes),
}));

/kernel/services/ecc/
/kernel/services/ecc/hnsw/
/kernel/services/ecc/causal/
/kernel/services/ecc/tick/
/kernel/services/ecc/calibration/
/kernel/services/ecc/crossrefs/