qae-kernel 0.1.1

Domain-agnostic safety certification kernel for AI agents and autonomous systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# qae-kernel

[![Crates.io](https://img.shields.io/crates/v/qae-kernel.svg)](https://crates.io/crates/qae-kernel)
[![docs.rs](https://docs.rs/qae-kernel/badge.svg)](https://docs.rs/qae-kernel)
[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](https://mariadb.com/bsl11/)

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

```rust
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

```text
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:

| Min Margin | Zone    | Decision             |
|-----------|---------|----------------------|
| > 0.6     | Safe    | Certified            |
| (0.3, 0.6]| Caution | CertifiedWithWarning |
| (0.1, 0.3]| Danger  | EscalateToHuman      |
| <= 0.1    | Danger  | Blocked              |

## 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](https://docs.rs/qae-kernel)
- [GitHub Repository](https://github.com/tb8412/qae-safety-kernel)
- [Developer Portal](https://qaesubstrate.com)

## License

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