qae-kernel

Domain-agnostic safety certification kernel for AI agents and autonomous systems.

An agent proposes an action, the kernel evaluates it against pluggable constraint channels, and produces a tamper-evident safety certificate with a deterministic SHA-256 hash.

Quick Example

use qae_kernel::{
    certify_action, ActionPriority, CertifierConfig,
    ConstraintChannel, DomainAdapter, KernelResult,
    ProposedAction, SimpleAction, StateDelta,
};
use std::collections::BTreeMap;

// 1. Define a constraint channel
struct UsageChannel;
impl ConstraintChannel for UsageChannel {
    fn name(&self) -> &str { "usage" }
    fn evaluate(&self, state: &[f64]) -> KernelResult<f64> {
        Ok((1.0 - state[0]).clamp(0.0, 1.0)) // margin = 1 - usage
    }
    fn dimension_names(&self) -> Vec<String> { vec!["usage".into()] }
}

// 2. Define a domain adapter
struct MyAdapter;
impl DomainAdapter for MyAdapter {
    fn domain_name(&self) -> &str { "example" }
    fn constraint_channels(&self) -> Vec<Box<dyn ConstraintChannel>> {
        vec![Box::new(UsageChannel)]
    }
    fn map_action_to_state(&self, action: &dyn ProposedAction)
        -> KernelResult<Vec<f64>> {
        Ok(action.state_deltas().iter().map(|d| d.to_value).collect())
    }
    fn detect_regime_change(&self, _: &[f64], _: &[f64]) -> bool { false }
    fn format_domain_payload(&self, margins: &BTreeMap<String, f64>)
        -> Option<serde_json::Value> {
        Some(serde_json::to_value(margins).unwrap())
    }
}

// 3. Certify an action
let config = CertifierConfig::default();
let action = SimpleAction {
    action_id: "act-1".into(),
    agent_id: "agent-1".into(),
    proposed_at: chrono::Utc::now(),
    state_deltas: vec![StateDelta {
        dimension: "usage".into(), from_value: 0.0, to_value: 0.3,
    }],
    priority: ActionPriority::Standard,
};
let cert = certify_action(&MyAdapter, &config, &action).unwrap();
assert!(matches!(cert.decision, qae_kernel::CertificationDecision::Certified));

How It Works

ProposedAction --> DomainAdapter --> ConstraintChannels --> SafetyCertifier --> SafetyCertificate
                       |                    |
                 (domain-specific)   (margin in [0,1])

Each constraint channel returns a margin in [0, 1] where 0 = at boundary and 1 = maximum headroom. The minimum margin across all channels determines the certification decision:

Key Traits

• DomainAdapter -- plugs domain-specific logic into the kernel
• ConstraintChannel -- evaluates a single constraint dimension
• ProposedAction -- represents an agent's proposed action

Features

• Deterministic certification with SHA-256 tamper-evident hashing
• BTreeMap-based ordering for full reproducibility (no HashMap)
• Declarative constraint channels (JSON-defined, no recompilation)
• Runtime constraint registry (add/remove/enable/disable channels)
• Builder pattern for certificate assembly
• Zero domain dependencies -- bring your own adapter

Links

• API Documentation
• GitHub Repository
• Developer Portal

License

BSL-1.1 (Business Source License 1.1). Converts to Apache 2.0 on 2032-01-01.