qae_kernel/

certifier.rs

// SPDX-License-Identifier: BUSL-1.1
//! SafetyCertifier — orchestrates the certification pipeline.
//!
//! Takes a DomainAdapter, evaluates all constraint channels against a
//! proposed action, applies decision logic, and builds a SafetyCertificate.

use crate::KernelResult;
use chrono::Utc;
use std::collections::BTreeMap;

use super::action::ProposedAction;
use super::certificate::{
    CertificationDecision, SafetyCertificate, SafetyCertificateBuilder, SafetyZone,
};
use super::domain::DomainAdapter;

/// Configuration for the safety certifier.
#[derive(Debug, Clone)]
pub struct CertifierConfig {
    /// Margin threshold above which the action is in the Safe zone.
    pub safe_threshold: f64,
    /// Margin threshold above which the action is in the Caution zone.
    pub caution_threshold: f64,
    /// Margin threshold at or below which the action is Blocked.
    pub block_threshold: f64,
    /// Margin threshold below which warnings are generated for individual channels.
    pub warning_margin_threshold: f64,
}

impl Default for CertifierConfig {
    fn default() -> Self {
        Self {
            safe_threshold: 0.6,
            caution_threshold: 0.3,
            block_threshold: 0.1,
            warning_margin_threshold: 0.5,
        }
    }
}

/// Certify an action against a borrowed domain adapter.
///
/// This is the core certification pipeline as a free function, allowing callers
/// to certify without transferring adapter ownership. Used by `SafetyCertifier`
/// and directly by the gateway.
///
/// Flow:
/// 1. Map action to state vector via domain adapter
/// 2. Evaluate all constraint channels against the state
/// 3. Find the bottleneck (minimum margin)
/// 4. Apply decision logic (zone + decision)
/// 5. Build and return the safety certificate
pub fn certify_action(
    adapter: &dyn DomainAdapter,
    config: &CertifierConfig,
    action: &dyn ProposedAction,
) -> KernelResult<SafetyCertificate> {
    let decided_at = Utc::now();

    // Step 1: Map action to state vector
    let state = adapter.map_action_to_state(action)?;

    // Step 2: Evaluate all constraint channels
    let channels = adapter.constraint_channels();
    let mut margins = BTreeMap::new();

    for channel in &channels {
        let margin = channel.evaluate(&state)?.clamp(0.0, 1.0);
        margins.insert(channel.name().to_string(), margin);
    }

    // Step 3: Find bottleneck
    let (binding_channel, min_margin) = margins
        .iter()
        .min_by(|a, b| a.1.partial_cmp(b.1).unwrap_or(std::cmp::Ordering::Equal))
        .map(|(k, v)| (k.clone(), *v))
        .unwrap_or_else(|| ("none".to_string(), 1.0));

    // Step 4: Detect regime change using adapter's current state
    let current_state = adapter.current_state().unwrap_or_else(|_| vec![0.0; state.len()]);
    let regime_change = adapter.detect_regime_change(&current_state, &state);

    // Step 5: Apply decision logic
    let (decision, zone) = if regime_change {
        (
            CertificationDecision::EscalateToHuman {
                reason: format!(
                    "Regime change detected (binding constraint: {}, margin: {:.4})",
                    binding_channel, min_margin
                ),
            },
            // Regime change forces at least Caution zone — emitting Safe while
            // escalating to human review would be a contradictory certificate.
            if min_margin > config.caution_threshold {
                SafetyZone::Caution
            } else {
                SafetyZone::Danger
            },
        )
    } else if min_margin <= config.block_threshold {
        (
            CertificationDecision::Blocked {
                reason: format!(
                    "Margin {:.4} on '{}' is at or below block threshold {:.2}",
                    min_margin, binding_channel, config.block_threshold
                ),
            },
            SafetyZone::Danger,
        )
    } else if min_margin <= config.caution_threshold {
        (
            CertificationDecision::EscalateToHuman {
                reason: format!(
                    "Margin {:.4} on '{}' requires human review (threshold: {:.2})",
                    min_margin, binding_channel, config.caution_threshold
                ),
            },
            SafetyZone::Danger,
        )
    } else if min_margin <= config.safe_threshold {
        let mut warnings = Vec::new();
        for (name, margin) in &margins {
            if *margin <= config.warning_margin_threshold {
                warnings.push(format!(
                    "Channel '{}' margin {:.4} below warning threshold",
                    name, margin
                ));
            }
        }
        if warnings.is_empty() {
            warnings.push(format!(
                "Minimum margin {:.4} in caution zone",
                min_margin
            ));
        }
        (
            CertificationDecision::CertifiedWithWarning { warnings },
            SafetyZone::Caution,
        )
    } else {
        (CertificationDecision::Certified, SafetyZone::Safe)
    };

    // Compute drift budget (distance to next zone boundary)
    let drift_budget = if min_margin > config.safe_threshold {
        min_margin - config.safe_threshold
    } else if min_margin > config.caution_threshold {
        min_margin - config.caution_threshold
    } else if min_margin > config.block_threshold {
        min_margin - config.block_threshold
    } else {
        0.0 // already blocked — no remaining budget
    };

    // Get domain payload
    let domain_payload = adapter.format_domain_payload(&margins);

    // Step 6: Build certificate
    let mut builder = SafetyCertificateBuilder::new(
        action.action_id().to_string(),
        action.agent_id().to_string(),
        decided_at,
    )
    .decision(decision)
    .zone(zone)
    .margins(margins)
    .binding_constraint(binding_channel)
    .drift_budget(drift_budget);

    if let Some(payload) = domain_payload {
        builder = builder.domain_payload(payload);
    }

    builder.build()
}

/// The safety certifier engine.
pub struct SafetyCertifier {
    adapter: Box<dyn DomainAdapter>,
    config: CertifierConfig,
}

impl SafetyCertifier {
    /// Create a new certifier with the given domain adapter and configuration.
    pub fn new(adapter: Box<dyn DomainAdapter>, config: CertifierConfig) -> Self {
        Self { adapter, config }
    }

    /// Certify a proposed action.
    ///
    /// Delegates to [`certify_action`] using the owned adapter.
    pub fn certify(&self, action: &dyn ProposedAction) -> KernelResult<SafetyCertificate> {
        certify_action(self.adapter.as_ref(), &self.config, action)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::action::{ActionPriority, SimpleAction, StateDelta};
    use crate::constraint::ConstraintChannel;

    struct FixedChannel {
        name: String,
        margin: f64,
    }

    impl ConstraintChannel for FixedChannel {
        fn name(&self) -> &str {
            &self.name
        }
        fn evaluate(&self, _state: &[f64]) -> KernelResult<f64> {
            Ok(self.margin)
        }
        fn dimension_names(&self) -> Vec<String> {
            vec!["x".into()]
        }
    }

    struct TestAdapter {
        channels: Vec<(String, f64)>,
        regime_change: bool,
    }

    impl DomainAdapter for TestAdapter {
        fn domain_name(&self) -> &str {
            "test"
        }
        fn constraint_channels(&self) -> Vec<Box<dyn ConstraintChannel>> {
            self.channels
                .iter()
                .map(|(name, margin)| -> Box<dyn ConstraintChannel> {
                    Box::new(FixedChannel {
                        name: name.clone(),
                        margin: *margin,
                    })
                })
                .collect()
        }
        fn map_action_to_state(&self, _action: &dyn ProposedAction) -> KernelResult<Vec<f64>> {
            Ok(vec![1.0])
        }
        fn detect_regime_change(&self, _current: &[f64], _proposed: &[f64]) -> bool {
            self.regime_change
        }
        fn format_domain_payload(
            &self,
            margins: &BTreeMap<String, f64>,
        ) -> Option<serde_json::Value> {
            Some(serde_json::to_value(margins).unwrap())
        }
    }

    fn make_action() -> SimpleAction {
        SimpleAction {
            action_id: "act-1".into(),
            agent_id: "agent-1".into(),
            proposed_at: Utc::now(),
            state_deltas: vec![StateDelta {
                dimension: "x".into(),
                from_value: 0.0,
                to_value: 1.0,
            }],
            priority: ActionPriority::Standard,
        }
    }

    #[test]
    fn certifies_safe_action() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.8), ("ch2".into(), 0.9)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert_eq!(cert.decision, CertificationDecision::Certified);
        assert_eq!(cert.zone, SafetyZone::Safe);
    }

    #[test]
    fn blocks_dangerous_action() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.05), ("ch2".into(), 0.9)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert!(matches!(cert.decision, CertificationDecision::Blocked { .. }));
        assert_eq!(cert.zone, SafetyZone::Danger);
    }

    #[test]
    fn warns_on_moderate_action() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.45), ("ch2".into(), 0.9)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert!(matches!(
            cert.decision,
            CertificationDecision::CertifiedWithWarning { .. }
        ));
        assert_eq!(cert.zone, SafetyZone::Caution);
    }

    #[test]
    fn escalates_on_low_margin() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.2), ("ch2".into(), 0.9)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert!(matches!(
            cert.decision,
            CertificationDecision::EscalateToHuman { .. }
        ));
        assert_eq!(cert.zone, SafetyZone::Danger);
    }

    #[test]
    fn escalates_on_regime_change() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.8), ("ch2".into(), 0.9)],
            regime_change: true,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert!(matches!(
            cert.decision,
            CertificationDecision::EscalateToHuman { .. }
        ));
    }

    #[test]
    fn drift_budget_correct() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.45)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        let budget = cert.drift_budget.unwrap();
        assert!((budget - 0.15).abs() < 1e-10);
    }

    #[test]
    fn binding_constraint_identified() {
        let adapter = TestAdapter {
            channels: vec![
                ("high".into(), 0.9),
                ("low".into(), 0.4),
                ("mid".into(), 0.7),
            ],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert_eq!(cert.binding_constraint.as_deref(), Some("low"));
    }

    #[test]
    fn domain_payload_included() {
        let adapter = TestAdapter {
            channels: vec![("ch1".into(), 0.8)],
            regime_change: false,
        };
        let certifier = SafetyCertifier::new(Box::new(adapter), CertifierConfig::default());
        let cert = certifier.certify(&make_action()).unwrap();

        assert!(cert.domain_payload.is_some());
        let payload = cert.domain_payload.unwrap();
        assert!(payload.get("ch1").is_some());
    }
}