car-server-core 0.47.0

//! The live [`AbFixer`](super::ab_loop::AbFixer): apply the coder A/B's
//! harness-addressable interventions through the SAME governed path
//! `evolution.run` uses (`car_memgine::harness_evolution`), HITL-gated on the
//! shared `ApprovalLedger`.
//!
//! Three honest realities shape this (see the map in the proposal):
//!
//! 1. **No built-in bridge.** The A/B produces `HarnessIntervention`s
//!    (`car_eventlog::harness_adapt`); the gated apply path consumes
//!    `HarnessMutation` + a `HarnessConfigPatch`. [`mutations_from_interventions`]
//!    is that bridge — and it can only translate the interventions that map onto
//!    a real tunable knob.
//! 2. **Budgets auto-apply; the prompt does not.** `HarnessConfig` carries
//!    `{max_retries, retry_backoff_ms, planning_max_replans}` plus, since
//!    car#708, a `prompt_overlay`. The overlay closed the gap this note used to
//!    describe — a prompt change was previously not applyable *at all*, so even
//!    a correct proposal had nowhere to live and could never be measured or
//!    rolled back. It is still **not auto-applied**: `HarnessComponent::Prompt`
//!    is safety-affecting, because prompt text can talk a model out of rules the
//!    prose rather than the policy layer is holding, so it routes through the
//!    human-approval gate on the ledger. What changed is that an approved prompt
//!    change now lands through the same governed apply/rollback path as a budget
//!    bump instead of waiting on a hand-authored code change.
//! 3. **The coder doesn't read `HarnessConfig` directly.** That gap is closed by
//!    [`NativeLoopConfig::merge_harness`](super::native_loop::NativeLoopConfig::merge_harness),
//!    which folds the applied knobs onto the coder's own budgets at the loop
//!    build site — otherwise an applied patch would never change coder behavior
//!    and the loop could not converge.
//!
//! The regression gate is the loop's own next A/B round (`run_improvement_loop`):
//! a non-safety budget bump is applied optimistically and the re-measurement
//! confirms or refutes it — the paper's "falsifying eval" made concrete.

use std::collections::HashSet;

use async_trait::async_trait;
use car_eventlog::harness_adapt::{HarnessIntervention, InterventionLayer};
use car_memgine::harness_evolution::{
    mutation_fingerprint, ChangeContract, Governance, HarnessComponent, HarnessConfig,
    HarnessConfigPatch, HarnessMutation, PromotionDecision,
};
use car_policy::permission::ApprovalDecision;

use super::ab_loop::{AbFixer, FixResult};

/// Bridge the A/B's harness-addressable interventions into concrete, applyable
/// [`HarnessMutation`]s, relative to the `current` config (so a bump is
/// `current + evidence`, not a fixed absolute). Only `TrajectoryRegulation`
/// interventions map onto a tunable knob — retry thrash → `max_retries`,
/// everything else trajectory-shaped (runtime failure / replan exhaustion /
/// turn exhaustion) → `planning_max_replans`. `EnvironmentContract` /
/// `ActionRealization` / `ProceduralSkill` interventions have no `HarnessConfig`
/// knob and are deliberately dropped here (a human designs those). Duplicate
/// mutations (same knob + target) collapse by fingerprint.
pub fn mutations_from_interventions(
    interventions: &[HarnessIntervention],
    current: &HarnessConfig,
) -> Vec<HarnessMutation> {
    let mut out = Vec::new();
    let mut seen = HashSet::new();
    for iv in interventions {
        // The prompt layer (car#708). `EnvironmentContract` is diagnosed when
        // the model keeps proposing something the rules forbid — a recurring
        // pattern that guidance can address and a budget cannot. Before the
        // overlay existed these were reported as pending human design and went
        // nowhere; now they become a real, applyable mutation.
        //
        // Still not auto-applied: `HarnessComponent::Prompt` is safety-affecting,
        // so this proposal routes through the ledger's human-approval gate. What
        // changed is that an approved one lands through the governed path
        // instead of waiting on a hand-authored code change.
        if iv.layer == InterventionLayer::EnvironmentContract {
            if let Some(mutation) = prompt_overlay_mutation(iv, current) {
                if seen.insert(mutation_fingerprint(&mutation)) {
                    out.push(mutation);
                }
            }
            continue;
        }
        if iv.layer != InterventionLayer::TrajectoryRegulation {
            continue;
        }
        // Bump scaled by evidence, bounded so one noisy signal can't blow up a budget.
        let bump = (iv.evidence_count as u32).clamp(1, 4);
        let trig = iv.trigger.to_lowercase();
        let (component, patch, predicted) = if trig.contains("retried") {
            let target = current.max_retries.saturating_add(bump);
            (
                HarnessComponent::RetryConfig,
                HarnessConfigPatch {
                    max_retries: Some(target),
                    ..Default::default()
                },
                format!(
                    "raise max_retries {} → {} to absorb retry thrash on '{}'",
                    current.max_retries, target, iv.target
                ),
            )
        } else {
            let target = current.planning_max_replans.saturating_add(bump);
            (
                HarnessComponent::PlanningConfig,
                HarnessConfigPatch {
                    planning_max_replans: Some(target),
                    ..Default::default()
                },
                format!(
                    "raise planning_max_replans {} → {} for recurring failure on '{}'",
                    current.planning_max_replans, target, iv.target
                ),
            )
        };
        let mutation = HarnessMutation {
            id: format!("ab:{}:{}", component_slug(component), iv.target),
            contract: ChangeContract {
                component,
                target_failure: iv.trigger.clone(),
                predicted_improvement: predicted,
                invariants: vec![
                    "no new tool, permission, or validator surface".to_string(),
                    "coder's contract remains the trust boundary".to_string(),
                ],
                falsifying_eval: "the next coder A/B round's paired pass-rate does not improve"
                    .to_string(),
                rollback: "apply the inverse patch (restore the prior knob value)".to_string(),
            },
            rationale: format!(
                "coder A/B attribution: {} (evidence {})",
                iv.intervention, iv.evidence_count
            ),
            patch: Some(patch),
        };
        if seen.insert(mutation_fingerprint(&mutation)) {
            out.push(mutation);
        }
    }
    out
}

/// One guidance line for the prompt overlay, derived from a diagnosis.
///
/// Kept mechanical rather than model-authored: this is a *proposal* a human
/// reads and approves, and a line that faithfully echoes the observed pattern is
/// far easier to judge than one a second model paraphrased. Generating better
/// prose (the GEPA reflection loop) is separate work — this is the path that
/// carries it once it exists.
fn overlay_guidance_line(iv: &HarnessIntervention) -> String {
    format!(
        "- {} (recurring: {})",
        iv.intervention.trim(),
        iv.trigger.trim()
    )
}

/// Propose an overlay that appends this diagnosis's guidance to whatever is
/// already in force.
///
/// Appending, not replacing: two diagnoses in one round must both survive, and
/// an overlay that replaced the current text would silently drop guidance a
/// human already approved. Returns `None` when the line is already present, so
/// a pattern that recurs across rounds does not accrete duplicates.
fn prompt_overlay_mutation(
    iv: &HarnessIntervention,
    current: &HarnessConfig,
) -> Option<HarnessMutation> {
    let line = overlay_guidance_line(iv);
    let existing = current.prompt_overlay.clone().unwrap_or_default();
    if existing.contains(&line) {
        return None;
    }
    let next = if existing.trim().is_empty() {
        line.clone()
    } else {
        format!("{existing}\n{line}")
    };

    Some(HarnessMutation {
        id: format!("ab:prompt:{}", iv.target),
        contract: ChangeContract {
            component: HarnessComponent::Prompt,
            target_failure: iv.trigger.clone(),
            predicted_improvement: format!(
                "add prompt guidance for the recurring pattern on '{}'",
                iv.target
            ),
            invariants: vec![
                "the base prompt is unchanged; guidance is appended only".to_string(),
                "no new tool, permission, or validator surface".to_string(),
                "coder's contract remains the trust boundary".to_string(),
            ],
            falsifying_eval: "the next coder A/B round's paired pass-rate does not improve"
                .to_string(),
            rollback: "apply the inverse patch (restore the prior overlay, or clear it)"
                .to_string(),
        },
        rationale: format!(
            "coder A/B attribution: {} (evidence {})",
            iv.intervention, iv.evidence_count
        ),
        patch: Some(HarnessConfigPatch {
            prompt_overlay: Some(next),
            ..Default::default()
        }),
    })
}

fn component_slug(c: HarnessComponent) -> &'static str {
    match c {
        HarnessComponent::RetryConfig => "retry",
        HarnessComponent::PlanningConfig => "planning",
        HarnessComponent::ToolSchema => "tool_schema",
        HarnessComponent::RetrievalPolicy => "retrieval",
        HarnessComponent::ContextBudget => "context",
        HarnessComponent::WorkflowTopology => "topology",
        HarnessComponent::PermissionRule => "permission",
        HarnessComponent::Validator => "validator",
        HarnessComponent::Prompt => "prompt",
    }
}

/// The daemon-side seam the fixer drives: look up a prior human decision for a
/// mutation fingerprint on the shared ledger, and apply a mutation to the live
/// harness config. Injected so [`EvolutionAbFixer`] is testable without a
/// `ServerState`/runtime; the daemon impl reads `state.approval_ledger` and
/// calls `runtime.update_harness_config(|c| c.apply(m, gov))`.
#[async_trait]
pub trait HarnessApply: Send + Sync {
    async fn approval(&self, fingerprint: &str) -> Option<ApprovalDecision>;
    async fn apply(&self, mutation: &HarnessMutation, governance: Governance)
        -> Result<(), String>;
}

/// The live fixer. `optimistic` = apply a non-safety budget bump without a prior
/// human approval (the next A/B round is the regression gate — the honest reading
/// of the evolution governance for reversible non-safety knobs); when `false`,
/// an un-approved mutation is left pending on the ledger.
pub struct EvolutionAbFixer<A: HarnessApply> {
    pub current: HarnessConfig,
    pub backend: A,
    pub optimistic: bool,
}

#[async_trait]
impl<A: HarnessApply> AbFixer for EvolutionAbFixer<A> {
    async fn apply(&self, interventions: &[HarnessIntervention]) -> FixResult {
        let mutations = mutations_from_interventions(interventions, &self.current);
        let patchless = interventions
            .iter()
            .filter(|i| i.layer != InterventionLayer::TrajectoryRegulation)
            .count();
        if mutations.is_empty() {
            return FixResult {
                applied: false,
                note: format!(
                    "no auto-applicable budget knob among {} intervention(s); {} need human design (prompt/validator/permission changes are code, not knobs)",
                    interventions.len(),
                    patchless
                ),
            };
        }
        let mut applied = 0usize;
        let mut pending = 0usize;
        let mut blocked = 0usize;
        for m in &mutations {
            let fp = mutation_fingerprint(m);
            match self.backend.approval(&fp).await {
                Some(ApprovalDecision::Rejected) => blocked += 1,
                Some(ApprovalDecision::Approved) => {
                    if self
                        .backend
                        .apply(m, Governance::HumanApproved)
                        .await
                        .is_ok()
                    {
                        applied += 1;
                    } else {
                        blocked += 1;
                    }
                }
                None => {
                    // Safety-affecting mutations can never be optimistic; they
                    // are always pending a human. (The bridge only emits
                    // Retry/Planning, so this stays defensive.)
                    if self.optimistic && !m.requires_human_approval() {
                        let gov = Governance::Promoted(PromotionDecision::Promote {
                            reason:
                                "non-safety budget bump; the next A/B round regression-gates it"
                                    .into(),
                        });
                        if self.backend.apply(m, gov).await.is_ok() {
                            applied += 1;
                        } else {
                            pending += 1;
                        }
                    } else {
                        pending += 1;
                    }
                }
            }
        }
        FixResult {
            applied: applied > 0,
            note: format!(
                "{applied} applied, {pending} pending approval, {blocked} blocked ({} mutation(s), {patchless} non-knob intervention(s) deferred to human design)",
                mutations.len()
            ),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashMap;
    use std::sync::Mutex;

    fn iv(
        layer: InterventionLayer,
        target: &str,
        trigger: &str,
        evidence: usize,
    ) -> HarnessIntervention {
        HarnessIntervention {
            layer,
            target: target.into(),
            trigger: trigger.into(),
            intervention: "do the thing".into(),
            evidence_count: evidence,
        }
    }

    /// Renamed and widened for car#708: `EnvironmentContract` used to have no
    /// knob and was dropped here. It now maps onto a prompt-overlay proposal,
    /// so this pins which layers map onto *what* rather than asserting that
    /// only one layer maps at all.
    #[test]
    fn bridge_maps_trajectory_onto_knobs_and_environment_contract_onto_the_prompt() {
        let cur = HarnessConfig::default(); // {3, 0, 2}
        let ivs = vec![
            iv(
                InterventionLayer::TrajectoryRegulation,
                "run_command",
                "action 'run_command' retried 3×",
                3,
            ),
            iv(
                InterventionLayer::TrajectoryRegulation,
                "proposal:p1",
                "replanning exhausted 2× for proposal 'p1'",
                2,
            ),
            // Maps onto a prompt overlay (car#708) — it used to be dropped.
            iv(
                InterventionLayer::EnvironmentContract,
                "edit_file",
                "rejected before execution 2×",
                2,
            ),
            // Still has no knob → dropped.
            iv(
                InterventionLayer::ActionRealization,
                "tool_x",
                "no tool 'tool_x'",
                4,
            ),
        ];
        let muts = mutations_from_interventions(&ivs, &cur);
        assert_eq!(
            muts.len(),
            3,
            "two trajectory knobs plus one prompt overlay; ActionRealization \
             still has nothing to turn"
        );
        assert_eq!(
            muts.iter()
                .filter(|m| m.contract.component == HarnessComponent::Prompt)
                .count(),
            1
        );
        // retry thrash → max_retries bumped by evidence (3) → 6.
        let retry = muts
            .iter()
            .find(|m| m.contract.component == HarnessComponent::RetryConfig)
            .unwrap();
        assert_eq!(retry.patch.as_ref().unwrap().max_retries, Some(6));
        // replan exhaustion → planning_max_replans bumped by evidence (2) → 4.
        let plan = muts
            .iter()
            .find(|m| m.contract.component == HarnessComponent::PlanningConfig)
            .unwrap();
        assert_eq!(plan.patch.as_ref().unwrap().planning_max_replans, Some(4));
        // Every mutation carries a falsifying eval (the A/B re-measure).
        assert!(muts
            .iter()
            .all(|m| m.contract.falsifying_eval.contains("A/B")));
    }

    #[test]
    fn bridge_dedups_identical_bumps() {
        let cur = HarnessConfig::default();
        // Two runtime-failure interventions on the SAME target + evidence →
        // identical planning patch → one mutation.
        let ivs = vec![
            iv(
                InterventionLayer::TrajectoryRegulation,
                "t",
                "action 't' failed 2×",
                2,
            ),
            iv(
                InterventionLayer::TrajectoryRegulation,
                "t",
                "action 't' failed 2×",
                2,
            ),
        ];
        assert_eq!(mutations_from_interventions(&ivs, &cur).len(), 1);
    }

    /// A scriptable HarnessApply: preset ledger decisions + a record of applies.
    struct FakeApply {
        decisions: HashMap<String, ApprovalDecision>,
        applied: Mutex<Vec<String>>,
        fail_apply: bool,
    }
    #[async_trait]
    impl HarnessApply for FakeApply {
        async fn approval(&self, fp: &str) -> Option<ApprovalDecision> {
            self.decisions.get(fp).cloned()
        }
        async fn apply(&self, m: &HarnessMutation, _g: Governance) -> Result<(), String> {
            if self.fail_apply {
                return Err("apply failed".into());
            }
            self.applied.lock().unwrap().push(mutation_fingerprint(m));
            Ok(())
        }
    }

    fn traj(target: &str, evidence: usize) -> HarnessIntervention {
        iv(
            InterventionLayer::TrajectoryRegulation,
            target,
            &format!("action '{target}' failed {evidence}×"),
            evidence,
        )
    }

    #[tokio::test]
    async fn optimistic_applies_non_safety_budget_bumps() {
        let fixer = EvolutionAbFixer {
            current: HarnessConfig::default(),
            backend: FakeApply {
                decisions: HashMap::new(),
                applied: Mutex::new(vec![]),
                fail_apply: false,
            },
            optimistic: true,
        };
        let r = fixer.apply(&[traj("a", 2), traj("b", 1)]).await;
        assert!(r.applied, "{}", r.note);
        assert_eq!(fixer.backend.applied.lock().unwrap().len(), 2);
    }

    #[tokio::test]
    async fn non_optimistic_leaves_everything_pending() {
        let fixer = EvolutionAbFixer {
            current: HarnessConfig::default(),
            backend: FakeApply {
                decisions: HashMap::new(),
                applied: Mutex::new(vec![]),
                fail_apply: false,
            },
            optimistic: false,
        };
        let r = fixer.apply(&[traj("a", 2)]).await;
        assert!(!r.applied);
        assert!(r.note.contains("1 pending"), "{}", r.note);
        assert!(fixer.backend.applied.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn ledger_approval_and_rejection_are_honored() {
        let cur = HarnessConfig::default();
        let approved = &mutations_from_interventions(&[traj("a", 2)], &cur)[0];
        let rejected = &mutations_from_interventions(&[traj("b", 3)], &cur)[0];
        let mut decisions = HashMap::new();
        decisions.insert(mutation_fingerprint(approved), ApprovalDecision::Approved);
        decisions.insert(mutation_fingerprint(rejected), ApprovalDecision::Rejected);
        let fixer = EvolutionAbFixer {
            current: cur,
            backend: FakeApply {
                decisions,
                applied: Mutex::new(vec![]),
                fail_apply: false,
            },
            // Non-optimistic: only ledger-approved lands; rejected is blocked.
            optimistic: false,
        };
        let r = fixer.apply(&[traj("a", 2), traj("b", 3)]).await;
        assert!(r.applied);
        assert!(
            r.note.contains("1 applied") && r.note.contains("1 blocked"),
            "{}",
            r.note
        );
        assert_eq!(fixer.backend.applied.lock().unwrap().len(), 1);
    }

    #[tokio::test]
    async fn no_knob_interventions_report_not_applied() {
        let fixer = EvolutionAbFixer {
            current: HarnessConfig::default(),
            backend: FakeApply {
                decisions: HashMap::new(),
                applied: Mutex::new(vec![]),
                fail_apply: false,
            },
            optimistic: true,
        };
        let r = fixer
            .apply(&[iv(
                InterventionLayer::EnvironmentContract,
                "x",
                "rejected 2×",
                2,
            )])
            .await;
        assert!(!r.applied);
        assert!(r.note.contains("human design"), "{}", r.note);
    }
}

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

    fn intervention(layer: InterventionLayer, target: &str) -> HarnessIntervention {
        HarnessIntervention {
            layer,
            target: target.to_string(),
            trigger: "model proposed a denied git commit".to_string(),
            intervention: "State that committing is never the agent's job".to_string(),
            evidence_count: 3,
        }
    }

    /// car#708: an `EnvironmentContract` diagnosis — the model repeatedly doing
    /// something the rules forbid — now becomes a real prompt mutation instead
    /// of being reported as pending human design and going nowhere.
    #[test]
    fn an_environment_contract_diagnosis_proposes_a_prompt_overlay() {
        let ivs = [intervention(
            InterventionLayer::EnvironmentContract,
            "proposal:1",
        )];
        let muts = mutations_from_interventions(&ivs, &HarnessConfig::default());

        assert_eq!(muts.len(), 1);
        assert_eq!(muts[0].contract.component, HarnessComponent::Prompt);
        let overlay = muts[0]
            .patch
            .as_ref()
            .unwrap()
            .prompt_overlay
            .as_ref()
            .unwrap();
        assert!(overlay.contains("State that committing is never the agent's job"));
        assert!(overlay.contains("recurring:"));
    }

    /// It must never auto-apply: prompt text can talk a model out of rules the
    /// prose rather than the policy layer is holding.
    #[test]
    fn a_prompt_mutation_requires_human_approval() {
        let ivs = [intervention(InterventionLayer::EnvironmentContract, "p")];
        let muts = mutations_from_interventions(&ivs, &HarnessConfig::default());
        assert!(
            muts[0].requires_human_approval(),
            "a prompt change must route through the ledger, not the optimistic path"
        );
    }

    /// Appending, not replacing — guidance a human already approved must not be
    /// silently dropped by the next proposal.
    #[test]
    fn a_proposal_appends_to_the_existing_overlay() {
        let current = HarnessConfig {
            prompt_overlay: Some("- Existing approved guidance (recurring: x)".into()),
            ..Default::default()
        };
        let ivs = [intervention(InterventionLayer::EnvironmentContract, "p")];
        let muts = mutations_from_interventions(&ivs, &current);

        let overlay = muts[0]
            .patch
            .as_ref()
            .unwrap()
            .prompt_overlay
            .clone()
            .unwrap();
        assert!(overlay.contains("Existing approved guidance"));
        assert!(overlay.contains("State that committing is never the agent's job"));
    }

    /// A pattern that recurs across rounds must not accrete duplicate lines.
    #[test]
    fn an_already_present_line_proposes_nothing() {
        let iv = intervention(InterventionLayer::EnvironmentContract, "p");
        let first =
            mutations_from_interventions(std::slice::from_ref(&iv), &HarnessConfig::default());
        let applied = HarnessConfig {
            prompt_overlay: first[0].patch.as_ref().unwrap().prompt_overlay.clone(),
            ..Default::default()
        };
        assert!(
            mutations_from_interventions(std::slice::from_ref(&iv), &applied).is_empty(),
            "the same diagnosis must not propose the same line twice"
        );
    }

    /// Trajectory diagnoses keep proposing budget bumps — this adds a layer, it
    /// does not redirect the existing one.
    #[test]
    fn trajectory_diagnoses_still_propose_budget_bumps() {
        let mut iv = intervention(InterventionLayer::TrajectoryRegulation, "action:9");
        iv.trigger = "action retried repeatedly".into();
        let muts = mutations_from_interventions(&[iv], &HarnessConfig::default());
        assert_eq!(muts[0].contract.component, HarnessComponent::RetryConfig);
    }
}