fleetforge_changeops/

lib.rs

//! ChangeOps release gating engine: evaluates diffs, coverage, and eval signals
//! to decide whether a change may ship automatically, requires follow-up, or
//! must be blocked. Designed to be deterministic so gating decisions can be
//! replayed and exported as artifacts.

use anyhow::Result;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use thiserror::Error;
use uuid::Uuid;

/// Primary effect returned by the gating engine.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ChangeDecisionEffect {
    Allow,
    FollowUp,
    Deny,
}

impl ChangeDecisionEffect {
    pub fn as_str(self) -> &'static str {
        match self {
            ChangeDecisionEffect::Allow => "allow",
            ChangeDecisionEffect::FollowUp => "follow_up",
            ChangeDecisionEffect::Deny => "deny",
        }
    }

    fn raise(self, next: ChangeDecisionEffect) -> ChangeDecisionEffect {
        use ChangeDecisionEffect::*;
        match (self, next) {
            (Deny, _) | (_, Deny) => Deny,
            (FollowUp, _) | (_, FollowUp) => FollowUp,
            _ => Allow,
        }
    }
}

/// Summary of a single diff considered by the gate.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ChangeDiff {
    pub path: String,
    #[serde(default)]
    pub lines_added: u32,
    #[serde(default)]
    pub lines_deleted: u32,
    #[serde(default)]
    pub novelty_score: Option<f64>,
    #[serde(default)]
    pub risk_tags: Vec<String>,
    #[serde(default)]
    pub component: Option<String>,
}

/// Aggregated coverage information per component or file group.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CoverageComponent {
    pub name: String,
    #[serde(default)]
    pub coverage_ratio: Option<f64>,
    #[serde(default)]
    pub required_ratio: Option<f64>,
}

/// Coverage report derived from telemetry or test runs.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CoverageReport {
    #[serde(default)]
    pub overall_ratio: Option<f64>,
    #[serde(default)]
    pub minimum_ratio: Option<f64>,
    #[serde(default)]
    pub components: Vec<CoverageComponent>,
}

/// Direction for metric thresholds.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum MetricDirection {
    HigherIsBetter,
    LowerIsBetter,
}

impl Default for MetricDirection {
    fn default() -> Self {
        MetricDirection::HigherIsBetter
    }
}

/// Evaluation metric emitted by change validation (eval packs, smoke tests, etc.).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EvalMetric {
    pub name: String,
    #[serde(default)]
    pub slug: Option<String>,
    pub score: f64,
    #[serde(default)]
    pub threshold: Option<f64>,
    #[serde(default)]
    pub direction: MetricDirection,
    #[serde(default)]
    pub weight: Option<f64>,
}

/// Budget or cost signal derived from the change (e.g. projected spend).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct BudgetSignal {
    pub name: String,
    pub actual: f64,
    #[serde(default)]
    pub limit: Option<f64>,
}

/// Inputs considered by the gating engine.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ChangeGateRequest {
    pub change_id: String,
    #[serde(default)]
    pub gate_id: Option<Uuid>,
    #[serde(default)]
    pub revision: Option<String>,
    #[serde(default)]
    pub diffs: Vec<ChangeDiff>,
    #[serde(default)]
    pub coverage: CoverageReport,
    #[serde(default)]
    pub evals: Vec<EvalMetric>,
    #[serde(default)]
    pub budgets: Vec<BudgetSignal>,
    #[serde(default)]
    pub telemetry: Value,
    #[serde(default)]
    pub metadata: Value,
    #[serde(default)]
    pub actor: Option<String>,
}

/// Suggested follow-up action when the gate cannot auto-approve.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FollowupAction {
    pub slug: String,
    pub description: String,
    #[serde(default)]
    pub recommended: bool,
}

impl FollowupAction {
    pub fn recommended(slug: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            slug: slug.into(),
            description: description.into(),
            recommended: true,
        }
    }

    pub fn optional(slug: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            slug: slug.into(),
            description: description.into(),
            recommended: false,
        }
    }
}

/// Scorecard summarising the inputs considered while evaluating the gate.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct DecisionScorecard {
    pub novelty: NoveltySummary,
    pub coverage: CoverageSummary,
    pub evals: EvalSummary,
    pub budgets: BudgetSummary,
    #[serde(default)]
    pub telemetry: Value,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct NoveltySummary {
    pub max_novelty: f64,
    pub avg_novelty: f64,
    pub high_risk_paths: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CoverageSummary {
    pub overall_ratio: Option<f64>,
    pub components_below_threshold: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EvalSummary {
    pub failing_metrics: Vec<String>,
    pub attention_metrics: Vec<String>,
    pub score_per_token: Option<f64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct BudgetSummary {
    pub breaches: Vec<String>,
    pub near_limits: Vec<String>,
}

/// Final decision payload from the ChangeOps gate.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangeGateDecision {
    pub effect: ChangeDecisionEffect,
    pub reasons: Vec<String>,
    #[serde(default)]
    pub followups: Vec<FollowupAction>,
    pub scorecard: DecisionScorecard,
    pub decided_at: DateTime<Utc>,
    #[serde(default)]
    pub metadata: Value,
}

impl ChangeGateDecision {
    pub fn to_value(&self, request: &ChangeGateRequest) -> Value {
        json!({
            "change_id": request.change_id,
            "gate_id": request.gate_id,
            "revision": request.revision,
            "effect": self.effect,
            "reasons": self.reasons,
            "followups": self.followups,
            "scorecard": self.scorecard,
            "decided_at": self.decided_at,
            "metadata": self.metadata,
            "telemetry": request.telemetry,
            "diffs": request.diffs,
            "evals": request.evals,
            "budgets": request.budgets,
            "coverage": request.coverage,
        })
    }
}

/// Change follow-up request (manual acknowledgement).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangeFollowupRequest {
    pub gate_id: Uuid,
    pub actor: String,
    #[serde(default)]
    pub outcome: FollowupOutcome,
    #[serde(default)]
    pub note: Option<String>,
    #[serde(default)]
    pub details: Value,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum FollowupOutcome {
    Approved,
    NeedsChanges,
    Deferred,
}

impl Default for FollowupOutcome {
    fn default() -> Self {
        FollowupOutcome::Approved
    }
}

impl FollowupOutcome {
    pub fn as_str(&self) -> &'static str {
        match self {
            FollowupOutcome::Approved => "approved",
            FollowupOutcome::NeedsChanges => "needs_changes",
            FollowupOutcome::Deferred => "deferred",
        }
    }

    pub fn from_str(value: &str) -> Option<Self> {
        match value {
            "approved" => Some(FollowupOutcome::Approved),
            "needs_changes" => Some(FollowupOutcome::NeedsChanges),
            "deferred" => Some(FollowupOutcome::Deferred),
            _ => None,
        }
    }
}

/// Recorded follow-up decision.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangeFollowupRecord {
    pub gate_id: Uuid,
    pub actor: String,
    pub outcome: FollowupOutcome,
    #[serde(default)]
    pub note: Option<String>,
    #[serde(default)]
    pub details: Value,
    pub recorded_at: DateTime<Utc>,
}

/// Errors produced while evaluating the gate.
#[derive(Debug, Error)]
pub enum ChangeGateError {
    #[error("change id is required")]
    MissingChangeId,
    #[error("no diffs, metrics, or telemetry provided")]
    EmptySignalSet,
}

#[derive(Debug, Clone)]
pub struct Thresholds {
    pub deny_novelty: f64,
    pub followup_novelty: f64,
    pub required_coverage: f64,
    pub coverage_soft_floor: f64,
    pub eval_slack: f64,
    pub budget_soft_multiplier: f64,
    pub replay_drift_ratio: f64,
}

impl Default for Thresholds {
    fn default() -> Self {
        Self {
            deny_novelty: 0.95,
            followup_novelty: 0.8,
            required_coverage: 0.75,
            coverage_soft_floor: 0.6,
            eval_slack: 0.05,
            budget_soft_multiplier: 0.9,
            replay_drift_ratio: 0.01,
        }
    }
}

#[derive(Debug, Default, Clone)]
pub struct ChangeGateEngine {
    thresholds: Thresholds,
}

impl ChangeGateEngine {
    pub fn new(thresholds: Thresholds) -> Self {
        Self { thresholds }
    }

    pub fn evaluate(&self, request: &ChangeGateRequest) -> Result<ChangeGateDecision> {
        if request.change_id.trim().is_empty() {
            return Err(ChangeGateError::MissingChangeId.into());
        }

        if request.diffs.is_empty()
            && request.evals.is_empty()
            && request.budgets.is_empty()
            && request.telemetry == Value::Null
        {
            return Err(ChangeGateError::EmptySignalSet.into());
        }

        let mut effect = ChangeDecisionEffect::Allow;
        let mut reasons: Vec<String> = Vec::new();
        let mut followups: Vec<FollowupAction> = Vec::new();

        let mut scorecard = DecisionScorecard::default();
        scorecard.novelty =
            self.evaluate_novelty(request, &mut effect, &mut reasons, &mut followups);
        scorecard.coverage =
            self.evaluate_coverage(request, &mut effect, &mut reasons, &mut followups);
        scorecard.evals = self.evaluate_metrics(request, &mut effect, &mut reasons, &mut followups);
        scorecard.budgets =
            self.evaluate_budgets(request, &mut effect, &mut reasons, &mut followups);
        self.evaluate_replays(
            &request.telemetry,
            &mut effect,
            &mut reasons,
            &mut followups,
        );
        self.evaluate_canary(
            &request.telemetry,
            &mut effect,
            &mut reasons,
            &mut followups,
        );
        scorecard.telemetry = request.telemetry.clone();

        // Remove duplicate reasons while preserving insertion order.
        let mut reason_set = std::collections::HashSet::new();
        reasons.retain(|reason| reason_set.insert(reason.clone()));

        Ok(ChangeGateDecision {
            effect,
            reasons,
            followups,
            scorecard,
            decided_at: Utc::now(),
            metadata: request.metadata.clone(),
        })
    }

    fn evaluate_novelty(
        &self,
        request: &ChangeGateRequest,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) -> NoveltySummary {
        let mut summary = NoveltySummary::default();
        if request.diffs.is_empty() {
            return summary;
        }

        let mut total = 0.0;
        let mut count = 0.0;
        let mut high_risk: Vec<String> = Vec::new();

        for diff in &request.diffs {
            let novelty = diff.novelty_score.unwrap_or_default().clamp(0.0, 1.0);
            summary.max_novelty = summary.max_novelty.max(novelty);
            total += novelty;
            count += 1.0;

            if novelty >= self.thresholds.deny_novelty {
                *effect = effect.raise(ChangeDecisionEffect::Deny);
                reasons.push(format!("novelty_high:{}", diff.path));
                high_risk.push(diff.path.clone());
            } else if novelty >= self.thresholds.followup_novelty {
                *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                reasons.push(format!("novelty_review:{}", diff.path));
                high_risk.push(diff.path.clone());
            }

            if diff
                .risk_tags
                .iter()
                .any(|tag| matches!(tag.as_str(), "security" | "compliance" | "schema_break"))
            {
                *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                reasons.push(format!(
                    "risk_tag:{}:{}",
                    diff.path,
                    diff.risk_tags.join(",")
                ));
                high_risk.push(diff.path.clone());
            }
        }

        if count > 0.0 {
            summary.avg_novelty = (total / count).clamp(0.0, 1.0);
        }
        summary.high_risk_paths = high_risk;

        if summary.max_novelty >= self.thresholds.followup_novelty && followups.is_empty() {
            followups.push(FollowupAction::recommended(
                "novelty_review",
                "Review high-novelty diffs with on-call approver",
            ));
        }

        summary
    }

    fn evaluate_coverage(
        &self,
        request: &ChangeGateRequest,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) -> CoverageSummary {
        let mut summary = CoverageSummary::default();
        let coverage = &request.coverage;
        summary.overall_ratio = coverage.overall_ratio;

        let required = coverage
            .minimum_ratio
            .unwrap_or(self.thresholds.required_coverage);

        for component in &coverage.components {
            let ratio = component.coverage_ratio.unwrap_or(0.0);
            let expected = component
                .required_ratio
                .unwrap_or(required)
                .max(self.thresholds.coverage_soft_floor);
            if ratio + f64::EPSILON < expected {
                summary
                    .components_below_threshold
                    .push(component.name.clone());
                *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                reasons.push(format!(
                    "coverage_gap:{}:{:.2}->{:.2}",
                    component.name, ratio, expected
                ));
            }
        }

        if let Some(overall) = coverage.overall_ratio {
            if overall + f64::EPSILON < self.thresholds.coverage_soft_floor {
                *effect = effect.raise(ChangeDecisionEffect::Deny);
                reasons.push(format!(
                    "coverage_overall_low:{:.2}",
                    coverage.overall_ratio.unwrap_or_default()
                ));
            }
        }

        if !summary.components_below_threshold.is_empty() {
            followups.push(FollowupAction::recommended(
                "tests",
                "Add or rerun coverage for touched components",
            ));
        }

        summary
    }

    fn evaluate_metrics(
        &self,
        request: &ChangeGateRequest,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) -> EvalSummary {
        let mut summary = EvalSummary::default();
        if request.evals.is_empty() {
            return summary;
        }

        for metric in &request.evals {
            let slug = metric.slug.as_ref().unwrap_or(&metric.name);
            if slug.eq_ignore_ascii_case("score_per_token") {
                summary.score_per_token = Some(metric.score);
            }

            if let Some(threshold) = metric.threshold {
                match metric.direction {
                    MetricDirection::HigherIsBetter => {
                        if metric.score + self.thresholds.eval_slack < threshold {
                            *effect = effect.raise(ChangeDecisionEffect::Deny);
                            summary
                                .failing_metrics
                                .push(format!("{}:{:.3}->{:.3}", slug, metric.score, threshold));
                            reasons.push(format!("metric_below:{}", slug));
                        } else if metric.score < threshold {
                            summary
                                .attention_metrics
                                .push(format!("{}:{:.3}->{:.3}", slug, metric.score, threshold));
                            *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                        }
                    }
                    MetricDirection::LowerIsBetter => {
                        if metric.score > threshold + self.thresholds.eval_slack {
                            *effect = effect.raise(ChangeDecisionEffect::Deny);
                            summary
                                .failing_metrics
                                .push(format!("{}:{:.3}->{:.3}", slug, metric.score, threshold));
                            reasons.push(format!("metric_above:{}", slug));
                        } else if metric.score > threshold {
                            summary
                                .attention_metrics
                                .push(format!("{}:{:.3}->{:.3}", slug, metric.score, threshold));
                            *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                        }
                    }
                }
            }
        }

        if !summary.failing_metrics.is_empty() {
            followups.push(FollowupAction::recommended(
                "evals",
                "Investigate failing evaluation metrics",
            ));
        } else if !summary.attention_metrics.is_empty() {
            followups.push(FollowupAction::optional(
                "evals_watch",
                "Monitor marginal evaluation metrics before shipping",
            ));
        }

        summary
    }

    fn evaluate_budgets(
        &self,
        request: &ChangeGateRequest,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) -> BudgetSummary {
        let mut summary = BudgetSummary::default();
        for budget in &request.budgets {
            if let Some(limit) = budget.limit {
                if budget.actual > limit {
                    *effect = effect.raise(ChangeDecisionEffect::Deny);
                    summary
                        .breaches
                        .push(format!("{}:{:.2}>{:.2}", budget.name, budget.actual, limit));
                    reasons.push(format!("budget_exceeded:{}", budget.name));
                } else if budget.actual > limit * self.thresholds.budget_soft_multiplier {
                    summary
                        .near_limits
                        .push(format!("{}:{:.2}>{:.2}", budget.name, budget.actual, limit));
                    *effect = effect.raise(ChangeDecisionEffect::FollowUp);
                }
            }
        }

        if !summary.breaches.is_empty() {
            followups.push(FollowupAction::recommended(
                "budget",
                "Reduce cost or adjust budget thresholds before deploy",
            ));
        } else if !summary.near_limits.is_empty() {
            followups.push(FollowupAction::optional(
                "budget_watch",
                "Budget near limits; confirm with cost owner",
            ));
        }

        summary
    }

    fn evaluate_replays(
        &self,
        telemetry: &Value,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) {
        match telemetry.get("replays").and_then(Value::as_array) {
            Some(replays) if !replays.is_empty() => {
                for replay in replays {
                    let name = replay
                        .get("name")
                        .and_then(Value::as_str)
                        .unwrap_or("replay");
                    let attestation_ok = replay
                        .get("attestation_match")
                        .and_then(Value::as_bool)
                        .unwrap_or(false);
                    if !attestation_ok {
                        reasons.push(format!("replay_attestation_mismatch:{name}"));
                        *effect = effect.raise(ChangeDecisionEffect::Deny);
                    }
                    if let Some(drift) = replay.get("token_drift").and_then(Value::as_f64) {
                        if drift > self.thresholds.replay_drift_ratio + f64::EPSILON {
                            reasons.push(format!("replay_drift_exceeded:{name}:{drift:.4}"));
                            *effect = effect.raise(ChangeDecisionEffect::Deny);
                        }
                    }
                    let tool_match = replay
                        .get("tool_io_match")
                        .and_then(Value::as_bool)
                        .unwrap_or(true);
                    if !tool_match {
                        reasons.push(format!("replay_tool_io_mismatch:{name}"));
                        *effect = effect.raise(ChangeDecisionEffect::Deny);
                    }
                }
            }
            _ => {
                if !followups.iter().any(|f| f.slug == "replay_evidence") {
                    followups.push(FollowupAction::recommended(
                        "replay_evidence",
                        "Attach deterministic replay results with attestation alignment",
                    ));
                }
                reasons.push("replay_missing".into());
                *effect = effect.raise(ChangeDecisionEffect::FollowUp);
            }
        }
    }

    fn evaluate_canary(
        &self,
        telemetry: &Value,
        effect: &mut ChangeDecisionEffect,
        reasons: &mut Vec<String>,
        followups: &mut Vec<FollowupAction>,
    ) {
        match telemetry.get("canary").and_then(Value::as_array) {
            Some(canary_runs) if !canary_runs.is_empty() => {
                for entry in canary_runs {
                    let name = entry
                        .get("name")
                        .and_then(Value::as_str)
                        .unwrap_or("canary");
                    let attestation_ok = entry
                        .get("attestation_match")
                        .and_then(Value::as_bool)
                        .unwrap_or(false);
                    if !attestation_ok {
                        reasons.push(format!("canary_attestation_mismatch:{name}"));
                        *effect = effect.raise(ChangeDecisionEffect::Deny);
                    }
                    let ids_present = entry
                        .get("attestation_ids")
                        .and_then(Value::as_array)
                        .map(|arr| !arr.is_empty())
                        .unwrap_or(false);
                    if !ids_present {
                        reasons.push(format!("canary_attestation_missing:{name}"));
                        *effect = effect.raise(ChangeDecisionEffect::Deny);
                    }
                }
            }
            _ => {
                if !followups.iter().any(|f| f.slug == "canary_attestations") {
                    followups.push(FollowupAction::recommended(
                        "canary_attestations",
                        "Surface canary attestation set before promotion",
                    ));
                }
                reasons.push("canary_missing".into());
                *effect = effect.raise(ChangeDecisionEffect::FollowUp);
            }
        }
    }
}

impl ChangeFollowupRecord {
    pub fn to_value(&self) -> Value {
        let mut map = Map::new();
        map.insert("gate_id".into(), Value::String(self.gate_id.to_string()));
        map.insert("actor".into(), Value::String(self.actor.clone()));
        map.insert(
            "outcome".into(),
            Value::String(match self.outcome {
                FollowupOutcome::Approved => "approved".into(),
                FollowupOutcome::NeedsChanges => "needs_changes".into(),
                FollowupOutcome::Deferred => "deferred".into(),
            }),
        );
        if let Some(note) = &self.note {
            map.insert("note".into(), Value::String(note.clone()));
        }
        map.insert("details".into(), self.details.clone());
        map.insert(
            "recorded_at".into(),
            Value::String(self.recorded_at.to_rfc3339()),
        );
        Value::Object(map)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn base_request() -> ChangeGateRequest {
        ChangeGateRequest {
            change_id: "change-test".into(),
            diffs: vec![ChangeDiff {
                path: "core/runtime/src/scheduler.rs".into(),
                lines_added: 120,
                lines_deleted: 2,
                novelty_score: Some(0.42),
                risk_tags: vec!["runtime".into()],
                component: Some("runtime".into()),
            }],
            coverage: CoverageReport {
                overall_ratio: Some(0.82),
                minimum_ratio: Some(0.75),
                components: vec![CoverageComponent {
                    name: "runtime".into(),
                    coverage_ratio: Some(0.8),
                    required_ratio: Some(0.75),
                }],
            },
            evals: vec![EvalMetric {
                name: "shadow_replay".into(),
                slug: Some("shadow_replay".into()),
                score: 0.98,
                threshold: Some(0.95),
                direction: MetricDirection::HigherIsBetter,
                weight: None,
            }],
            budgets: vec![BudgetSignal {
                name: "score_per_token".into(),
                actual: 0.0075,
                limit: Some(0.01),
            }],
            telemetry: json!({
                "deploy": {
                    "window": "us-west",
                    "service": "runtime"
                },
                "replays": [{
                    "name": "shadow",
                    "attestation_match": true,
                    "token_drift": 0.0,
                    "tool_io_match": true
                }],
                "canary": [{
                    "name": "blue",
                    "attestation_match": true,
                    "attestation_ids": [Uuid::new_v4().to_string()]
                }]
            }),
            metadata: json!({"branch": "feature/changeops"}),
            ..Default::default()
        }
    }

    #[test]
    fn allows_when_within_thresholds() {
        let engine = ChangeGateEngine::default();
        let request = base_request();
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::Allow);
        assert!(decision.reasons.is_empty());
        assert!(decision.followups.is_empty());
        assert!(decision.scorecard.novelty.max_novelty > 0.0);
    }

    #[test]
    fn escalates_for_high_novelty() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        request.diffs[0].novelty_score = Some(0.9);
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::FollowUp);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason.contains("novelty_review")));
        assert!(!decision.followups.is_empty());
    }

    #[test]
    fn denies_for_eval_failures() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        request.evals.push(EvalMetric {
            name: "pii_blocker".into(),
            slug: Some("pii_blocker".into()),
            score: 0.2,
            threshold: Some(0.9),
            direction: MetricDirection::HigherIsBetter,
            weight: None,
        });
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::Deny);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason.contains("metric_below")));
    }

    #[test]
    fn denies_for_replay_attestation_mismatch() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        if let Some(replays) = request
            .telemetry
            .get_mut("replays")
            .and_then(Value::as_array_mut)
        {
            if let Some(first) = replays.first_mut() {
                first["attestation_match"] = Value::Bool(false);
            }
        }
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::Deny);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason.contains("replay_attestation_mismatch")));
    }

    #[test]
    fn followup_when_replays_missing() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        if let Value::Object(map) = &mut request.telemetry {
            map.remove("replays");
        }
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::FollowUp);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason == "replay_missing"));
        assert!(decision
            .followups
            .iter()
            .any(|f| f.slug == "replay_evidence"));
    }

    #[test]
    fn denies_for_canary_attestation_mismatch() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        if let Some(entries) = request
            .telemetry
            .get_mut("canary")
            .and_then(Value::as_array_mut)
        {
            if let Some(first) = entries.first_mut() {
                first["attestation_match"] = Value::Bool(false);
            }
        }
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::Deny);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason.contains("canary_attestation_mismatch")));
    }

    #[test]
    fn followup_when_canary_missing() {
        let engine = ChangeGateEngine::default();
        let mut request = base_request();
        if let Value::Object(map) = &mut request.telemetry {
            map.remove("canary");
        }
        let decision = engine.evaluate(&request).expect("decision");
        assert_eq!(decision.effect, ChangeDecisionEffect::FollowUp);
        assert!(decision
            .reasons
            .iter()
            .any(|reason| reason == "canary_missing"));
        assert!(decision
            .followups
            .iter()
            .any(|f| f.slug == "canary_attestations"));
    }

    #[test]
    fn denies_when_signal_set_empty() {
        let engine = ChangeGateEngine::default();
        let request = ChangeGateRequest {
            change_id: "empty".into(),
            ..Default::default()
        };
        let err = engine.evaluate(&request).expect_err("should fail");
        assert!(format!("{err}").contains("no diffs"));
    }

    #[test]
    fn followup_outcome_roundtrip() {
        let variants = [
            FollowupOutcome::Approved,
            FollowupOutcome::NeedsChanges,
            FollowupOutcome::Deferred,
        ];
        for outcome in variants {
            let label = outcome.as_str();
            let parsed = FollowupOutcome::from_str(label).expect("round-trip");
            assert_eq!(parsed, outcome);
        }
    }
}