car-memgine 0.48.0

//! Self-evolution governor — *when* and *what* to evolve (arXiv 2507.21046,
//! *A Survey of Self-Evolving Agents: What, When, How, and Where to Evolve*).
//!
//! See `docs/proposals/self-evolution-governor.md`. CAR already implements a lot
//! of the survey's ***how***: skill distillation/evolution/repair and lifecycle
//! degradation, the harness Evolution Agent (`harness_evolution`), the U-Mem
//! knowledge cascade (`cascade`), `consolidate()`/`reflect()`, and the
//! localized-vs-global memory-maintenance decision (`maintenance`). What it
//! lacks is the survey's ***when*** + ***what/where*** dimension as a single
//! cross-component decision: given signals from every evolvable component, which
//! are *due* to evolve **now**, in what priority, under one budget — instead of
//! each subsystem firing its own evolution ad hoc.
//!
//! This is that governor, as a pure decision core (like [`crate::maintenance`]
//! and [`crate::cascade`]). It sits *above* the existing mechanisms: it decides
//! whether/when to fire them; they do the evolving. Two survey insights are
//! encoded deterministically:
//!
//! 1. **Evolve under pressure, not on a blind schedule.** A component with no
//!    observed failure/regression/drift is skipped — churn without cause degrades
//!    a working system (the *Governance-Decay* risk the eviction module also
//!    guards).
//! 2. **Don't evolve on too little evidence.** A component under pressure but
//!    without enough accumulated evidence since its last evolution is *deferred*,
//!    not evolved — premature adaptation overfits to noise.
//!
//! Admitted candidates are prioritized by value density (`pressure / cost`) and
//! greedily packed into the cycle's budget; what doesn't fit is deferred, so the
//! spend goes where it buys the most correction (the survey's *where to invest*).

use serde::{Deserialize, Serialize};

/// An evolvable part of the agent — the survey's *what/where to evolve*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EvolvableComponent {
    /// The memory graph (consolidate / reorganize).
    Memory,
    /// Learned skills (distill / evolve / repair).
    Skills,
    /// The harness config (the Evolution Agent).
    Harness,
    /// Context-assembly policy (eviction / budget tuning).
    Context,
    /// Tool set / connectors.
    Tools,
}

/// The evolution signals for one component.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionSignals {
    /// Observed pressure to evolve — failure / regression / drift rate, in
    /// `[0,1]`. `0` = the component is performing fine; `1` = failing hard.
    #[serde(default)]
    pub pressure: f64,
    /// New evidence accumulated since this component last evolved (outcomes,
    /// interactions, corrections). Evolving on too little overfits.
    #[serde(default)]
    pub evidence: u64,
    /// Minimum evidence required before evolving this component is trustworthy.
    #[serde(default)]
    pub min_evidence: u64,
    /// Relative cost to evolve this component (must be `> 0`; a `<= 0` cost is
    /// treated as `1.0`).
    #[serde(default = "default_cost")]
    pub cost: f64,
}

fn default_cost() -> f64 {
    1.0
}

/// One component's state fed to the governor.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ComponentState {
    pub component: EvolvableComponent,
    #[serde(flatten)]
    pub signals: EvolutionSignals,
}

/// What the governor decides for a component.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EvolutionAction {
    /// Evolve this component this cycle.
    EvolveNow,
    /// Under pressure but not yet — insufficient evidence, or budget spent on
    /// higher-value components. Revisit next cycle.
    Defer,
    /// No pressure — leave it alone.
    Skip,
}

/// Why a component was deferred (when `action == Defer`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DeferReason {
    /// Not enough evidence accumulated to evolve without overfitting.
    InsufficientEvidence,
    /// Budget was exhausted by higher-value components this cycle.
    BudgetExhausted,
}

/// The governor's decision for one component.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionDecision {
    pub component: EvolvableComponent,
    pub action: EvolutionAction,
    /// Value density `pressure / cost` used for prioritization; `0.0` unless the
    /// component was a genuine evolve candidate.
    pub priority: f64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub defer_reason: Option<DeferReason>,
    pub reason: String,
}

/// Policy governing an evolution cycle.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionPolicy {
    /// Minimum pressure to consider evolving a component at all; below this →
    /// `Skip`. Default `0.2`.
    #[serde(default = "default_pressure_threshold")]
    pub pressure_threshold: f64,
    /// Total evolution budget for this cycle (sum of `cost` over `EvolveNow`
    /// components). Default `f64::INFINITY` (no budget cap).
    #[serde(default = "default_budget")]
    pub budget: f64,
}

fn default_pressure_threshold() -> f64 {
    0.2
}

fn default_budget() -> f64 {
    f64::INFINITY
}

impl Default for EvolutionPolicy {
    fn default() -> Self {
        Self {
            pressure_threshold: default_pressure_threshold(),
            budget: default_budget(),
        }
    }
}

/// The full plan for an evolution cycle.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionPlan {
    pub decisions: Vec<EvolutionDecision>,
    /// Total cost of the `EvolveNow` decisions.
    pub spent: f64,
    /// Components chosen to evolve now, highest-priority first.
    pub evolve_now: Vec<EvolvableComponent>,
}

fn effective_cost(cost: f64) -> f64 {
    if cost > 0.0 {
        cost
    } else {
        1.0
    }
}

/// Decide which components to evolve this cycle (the survey's *when + what*).
///
/// - `pressure < threshold` → `Skip` (no cause to evolve).
/// - `evidence < min_evidence` → `Defer(InsufficientEvidence)` (would overfit).
/// - otherwise a candidate, priority `pressure / cost`; candidates are admitted
///   highest-priority-first until the `budget` can't fit the next → the rest
///   `Defer(BudgetExhausted)`.
pub fn plan_evolution(components: &[ComponentState], policy: &EvolutionPolicy) -> EvolutionPlan {
    // First pass: classify each component and compute candidate priority.
    struct Candidate {
        idx: usize,
        priority: f64,
        cost: f64,
    }
    let mut decisions: Vec<Option<EvolutionDecision>> = vec![None; components.len()];
    let mut candidates: Vec<Candidate> = Vec::new();

    for (idx, c) in components.iter().enumerate() {
        let s = &c.signals;
        if s.pressure < policy.pressure_threshold {
            decisions[idx] = Some(EvolutionDecision {
                component: c.component,
                action: EvolutionAction::Skip,
                priority: 0.0,
                defer_reason: None,
                reason: format!(
                    "pressure {:.2} below threshold {:.2} — no cause to evolve",
                    s.pressure, policy.pressure_threshold
                ),
            });
            continue;
        }
        if s.evidence < s.min_evidence {
            decisions[idx] = Some(EvolutionDecision {
                component: c.component,
                action: EvolutionAction::Defer,
                priority: 0.0,
                defer_reason: Some(DeferReason::InsufficientEvidence),
                reason: format!(
                    "under pressure ({:.2}) but only {} of {} evidence — deferring to avoid \
                     overfitting",
                    s.pressure, s.evidence, s.min_evidence
                ),
            });
            continue;
        }
        let cost = effective_cost(s.cost);
        candidates.push(Candidate {
            idx,
            priority: s.pressure / cost,
            cost,
        });
    }

    // Highest value density first. Ties broken by declaration order (stable) so
    // the plan is deterministic.
    candidates.sort_by(|a, b| {
        b.priority
            .partial_cmp(&a.priority)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then(a.idx.cmp(&b.idx))
    });

    let mut spent = 0.0;
    let mut evolve_now: Vec<EvolvableComponent> = Vec::new();
    for cand in &candidates {
        let c = &components[cand.idx];
        if spent + cand.cost <= policy.budget {
            spent += cand.cost;
            evolve_now.push(c.component);
            decisions[cand.idx] = Some(EvolutionDecision {
                component: c.component,
                action: EvolutionAction::EvolveNow,
                priority: cand.priority,
                defer_reason: None,
                reason: format!(
                    "pressure {:.2}, evidence sufficient, priority {:.3} — evolve now",
                    c.signals.pressure, cand.priority
                ),
            });
        } else {
            decisions[cand.idx] = Some(EvolutionDecision {
                component: c.component,
                action: EvolutionAction::Defer,
                priority: cand.priority,
                defer_reason: Some(DeferReason::BudgetExhausted),
                reason: format!(
                    "priority {:.3} but cost {:.2} exceeds remaining budget {:.2} — deferring",
                    cand.priority,
                    cand.cost,
                    policy.budget - spent
                ),
            });
        }
    }

    EvolutionPlan {
        decisions: decisions.into_iter().map(|d| d.unwrap()).collect(),
        spent,
        evolve_now,
    }
}

// ---------------------------------------------------------------------------
// Slice 3 — cycle orchestrator: plan, then dispatch each EvolveNow component to
// an injected async runner. Execution stays OUT of this crate — the daemon
// injects a runner that maps Memory→consolidate(), Skills→evolve_skills(),
// Harness→the (HITL-gated) harness_evolution loop, etc. (all async +
// inference-backed). The orchestration (plan → ordered dispatch → per-step
// outcome → report) is the verifiable core, exactly like
// `cascade::run_cascade_async`.
// ---------------------------------------------------------------------------

/// What a component's runner reports back: a human-readable summary plus
/// whether it **actually changed anything**. A runner that completed but
/// applied nothing (nothing needed evolving, every mutation still pending
/// human approval, a dry run) reports `applied == false` so the cycle's
/// `evolved` list means "something changed", not "the runner returned Ok"
/// (kernel review S2).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionOutcome {
    pub summary: String,
    pub applied: bool,
}

impl EvolutionOutcome {
    /// The runner changed something (consolidated, evolved skills, applied a
    /// harness patch, …).
    pub fn applied(summary: impl Into<String>) -> Self {
        Self {
            summary: summary.into(),
            applied: true,
        }
    }

    /// The runner completed without error but changed nothing.
    pub fn no_op(summary: impl Into<String>) -> Self {
        Self {
            summary: summary.into(),
            applied: false,
        }
    }
}

/// The outcome of executing one component's evolution (from the injected runner).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionStep {
    pub component: EvolvableComponent,
    /// True if the runner completed without error.
    pub ran: bool,
    /// True if the runner actually changed something (see [`EvolutionOutcome`]).
    #[serde(default)]
    pub applied: bool,
    /// The runner's summary on success, or the error message when `ran == false`.
    pub outcome: String,
}

/// The result of a full evolution cycle.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvolutionCycleReport {
    /// The plan the cycle acted on.
    pub plan: EvolutionPlan,
    /// One step per `EvolveNow` component, in priority order.
    pub steps: Vec<EvolutionStep>,
    /// Components whose runner **applied a change** — not merely returned Ok
    /// (kernel review S2).
    pub evolved: Vec<EvolvableComponent>,
}

/// Run one evolution cycle: [`plan_evolution`], then dispatch each `EvolveNow`
/// component — in the plan's priority order — to the injected async `run`.
///
/// Execution is injected, not owned here: the daemon supplies a `run` that maps
/// each component onto its real (async, inference-backed) evolution mechanism.
/// A runner error is recorded (`ran == false`) and the cycle **continues** to the
/// next component, so one failing subsystem doesn't abort the rest. Mirrors
/// [`crate::cascade::run_cascade_async`].
pub async fn run_evolution_cycle<F, Fut>(
    components: &[ComponentState],
    policy: &EvolutionPolicy,
    mut run: F,
) -> EvolutionCycleReport
where
    F: FnMut(EvolvableComponent) -> Fut,
    Fut: std::future::Future<Output = Result<EvolutionOutcome, String>>,
{
    let plan = plan_evolution(components, policy);
    let mut steps = Vec::new();
    let mut evolved = Vec::new();
    // `evolve_now` is already highest-priority-first.
    for &component in &plan.evolve_now {
        match run(component).await {
            Ok(outcome) => {
                if outcome.applied {
                    evolved.push(component);
                }
                steps.push(EvolutionStep {
                    component,
                    ran: true,
                    applied: outcome.applied,
                    outcome: outcome.summary,
                });
            }
            Err(e) => steps.push(EvolutionStep {
                component,
                ran: false,
                applied: false,
                outcome: e,
            }),
        }
    }
    EvolutionCycleReport {
        plan,
        steps,
        evolved,
    }
}

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

    fn comp(
        component: EvolvableComponent,
        pressure: f64,
        evidence: u64,
        min: u64,
        cost: f64,
    ) -> ComponentState {
        ComponentState {
            component,
            signals: EvolutionSignals {
                pressure,
                evidence,
                min_evidence: min,
                cost,
            },
        }
    }

    fn action_for(plan: &EvolutionPlan, c: EvolvableComponent) -> &EvolutionDecision {
        plan.decisions.iter().find(|d| d.component == c).unwrap()
    }

    #[test]
    fn no_pressure_is_skipped() {
        let plan = plan_evolution(
            &[comp(EvolvableComponent::Memory, 0.05, 100, 10, 1.0)],
            &EvolutionPolicy::default(),
        );
        assert_eq!(
            action_for(&plan, EvolvableComponent::Memory).action,
            EvolutionAction::Skip
        );
        assert!(plan.evolve_now.is_empty());
    }

    #[test]
    fn under_pressure_but_thin_evidence_defers() {
        let plan = plan_evolution(
            &[comp(EvolvableComponent::Skills, 0.8, 3, 20, 1.0)],
            &EvolutionPolicy::default(),
        );
        let d = action_for(&plan, EvolvableComponent::Skills);
        assert_eq!(d.action, EvolutionAction::Defer);
        assert_eq!(d.defer_reason, Some(DeferReason::InsufficientEvidence));
    }

    #[test]
    fn pressure_with_evidence_evolves() {
        let plan = plan_evolution(
            &[comp(EvolvableComponent::Skills, 0.8, 50, 20, 1.0)],
            &EvolutionPolicy::default(),
        );
        assert_eq!(
            action_for(&plan, EvolvableComponent::Skills).action,
            EvolutionAction::EvolveNow
        );
        assert_eq!(plan.evolve_now, vec![EvolvableComponent::Skills]);
        assert_eq!(plan.spent, 1.0);
    }

    #[test]
    fn budget_admits_highest_value_density_first() {
        // Both eligible; Skills has higher pressure/cost than Memory. Budget fits
        // only one → Skills evolves, Memory defers (budget).
        let plan = plan_evolution(
            &[
                comp(EvolvableComponent::Memory, 0.5, 100, 10, 5.0), // density 0.10
                comp(EvolvableComponent::Skills, 0.9, 100, 10, 3.0), // density 0.30
            ],
            &EvolutionPolicy {
                pressure_threshold: 0.2,
                budget: 3.0,
            },
        );
        assert_eq!(plan.evolve_now, vec![EvolvableComponent::Skills]);
        let mem = action_for(&plan, EvolvableComponent::Memory);
        assert_eq!(mem.action, EvolutionAction::Defer);
        assert_eq!(mem.defer_reason, Some(DeferReason::BudgetExhausted));
        assert_eq!(plan.spent, 3.0);
    }

    #[test]
    fn unbounded_budget_evolves_all_eligible() {
        let plan = plan_evolution(
            &[
                comp(EvolvableComponent::Memory, 0.5, 100, 10, 5.0),
                comp(EvolvableComponent::Skills, 0.9, 100, 10, 3.0),
                comp(EvolvableComponent::Harness, 0.1, 100, 10, 1.0), // skipped: low pressure
            ],
            &EvolutionPolicy::default(),
        );
        assert_eq!(plan.evolve_now.len(), 2);
        // Highest density first.
        assert_eq!(plan.evolve_now[0], EvolvableComponent::Skills);
        assert_eq!(
            action_for(&plan, EvolvableComponent::Harness).action,
            EvolutionAction::Skip
        );
    }

    #[test]
    fn nonpositive_cost_is_treated_as_unit() {
        let plan = plan_evolution(
            &[comp(EvolvableComponent::Tools, 0.6, 100, 0, 0.0)],
            &EvolutionPolicy::default(),
        );
        let d = action_for(&plan, EvolvableComponent::Tools);
        assert_eq!(d.action, EvolutionAction::EvolveNow);
        assert!((d.priority - 0.6).abs() < 1e-9, "0.6 / 1.0");
    }

    // --- run_evolution_cycle: plan → injected async dispatch ---

    #[tokio::test]
    async fn cycle_dispatches_evolve_now_in_priority_order() {
        let components = [
            comp(EvolvableComponent::Memory, 0.5, 100, 10, 5.0), // density 0.10
            comp(EvolvableComponent::Skills, 0.9, 100, 10, 3.0), // density 0.30
            comp(EvolvableComponent::Harness, 0.1, 100, 10, 1.0), // skipped
        ];
        let report =
            run_evolution_cycle(&components, &EvolutionPolicy::default(), |c| async move {
                Ok(EvolutionOutcome::applied(format!("ran {c:?}")))
            })
            .await;
        // Highest density first; harness skipped (never dispatched).
        assert_eq!(
            report.evolved,
            vec![EvolvableComponent::Skills, EvolvableComponent::Memory]
        );
        assert_eq!(report.steps.len(), 2);
        assert!(report.steps.iter().all(|s| s.ran && s.applied));
    }

    #[tokio::test]
    async fn cycle_continues_past_a_failing_runner() {
        let components = [
            comp(EvolvableComponent::Skills, 0.9, 100, 10, 1.0),
            comp(EvolvableComponent::Memory, 0.5, 100, 10, 1.0),
        ];
        let report =
            run_evolution_cycle(&components, &EvolutionPolicy::default(), |c| async move {
                if c == EvolvableComponent::Skills {
                    Err("evolve_skills failed".into())
                } else {
                    Ok(EvolutionOutcome::applied("consolidated"))
                }
            })
            .await;
        // Skills failed but Memory still ran.
        assert_eq!(report.evolved, vec![EvolvableComponent::Memory]);
        let skills_step = report
            .steps
            .iter()
            .find(|s| s.component == EvolvableComponent::Skills)
            .unwrap();
        assert!(!skills_step.ran);
        assert_eq!(skills_step.outcome, "evolve_skills failed");
    }

    #[tokio::test]
    async fn a_no_op_runner_is_not_counted_as_evolved() {
        // Kernel review S2: Ok-but-changed-nothing (nothing to evolve, all
        // pending approval) must not appear in `evolved`.
        let components = [
            comp(EvolvableComponent::Skills, 0.9, 100, 10, 1.0),
            comp(EvolvableComponent::Memory, 0.5, 100, 10, 1.0),
        ];
        let report =
            run_evolution_cycle(&components, &EvolutionPolicy::default(), |c| async move {
                if c == EvolvableComponent::Skills {
                    Ok(EvolutionOutcome::no_op("all mutations pending approval"))
                } else {
                    Ok(EvolutionOutcome::applied("consolidated"))
                }
            })
            .await;
        assert_eq!(report.evolved, vec![EvolvableComponent::Memory]);
        let skills = report
            .steps
            .iter()
            .find(|s| s.component == EvolvableComponent::Skills)
            .unwrap();
        assert!(skills.ran && !skills.applied, "{skills:?}");
    }

    #[tokio::test]
    async fn cycle_with_nothing_to_do_runs_nothing() {
        let components = [comp(EvolvableComponent::Memory, 0.05, 100, 10, 1.0)];
        let report =
            run_evolution_cycle(&components, &EvolutionPolicy::default(), |_c| async move {
                Ok(EvolutionOutcome::applied("should not run"))
            })
            .await;
        assert!(report.evolved.is_empty() && report.steps.is_empty());
    }
}