car-verify 0.54.0

//! Monte Carlo rollout of a proposal — [`simulate`](crate::simulate) with the
//! tools allowed to fail.
//!
//! [`simulate`](crate::simulate) answers "what state does this plan leave
//! behind, assuming every dispatched tool succeeds?" That is the right question
//! for a single deterministic prediction, but it is not the question an
//! operator asks before running a plan against production. They ask "how often
//! does this actually work, and when it doesn't, what breaks first?"
//!
//! This module answers that by running the *same* rollout kernel N times with
//! one change: a `tool_call` succeeds with probability `p`, drawn per attempt.
//! Those probabilities are not invented — `car_planner::ToolFeedback` already
//! computes an empirical success rate per tool from the trajectory store
//! (`success / total` over recorded `action_succeeded` events). Today the
//! planner folds that into a scalar score multiplier; here it is sampled, so
//! the failure *cascades* the way it would at runtime.
//!
//! ## What is and isn't modelled
//!
//! Modelled, because the rollout mirrors [`simulate`](crate::simulate) exactly:
//!
//! * **Pre-dispatch gating.** A failing precondition or an unavailable state
//!   dependency makes the executor reject an action before the tool runs
//!   (`ActionStatus::Rejected`), so its effects never land — the same rule that
//!   fixed Parslee-ai/car#622.
//! * **The cascade.** A tool that fails contributes no effects, so its
//!   dependents find their dependencies missing and are rejected in turn. The
//!   blast radius emerges from the data dependencies rather than being
//!   stipulated.
//!
//! Not modelled, and deliberately so:
//!
//! * **`failure_behavior`.** Like [`simulate`](crate::simulate), an independent
//!   action alongside a failed one still runs here, whereas the executor's
//!   default `FailureBehavior::Abort` may stop the run before reaching it. Read
//!   the numbers as "assuming execution proceeds as far as the dependency graph
//!   allows".
//! * **Correlated failure.** Draws are independent. A tool that fails because
//!   an upstream API is down would in reality fail for every action that calls
//!   it in the same run; here each call is its own coin flip. This makes the
//!   estimates *optimistic* for plans that call one flaky tool repeatedly.
//! * **Partial effects.** An action either lands all of its
//!   `expected_effects` or none of them.
//! * **Non-`tool_call` actions.** A `state_write` has no tool to fail, so it
//!   succeeds whenever it is dispatched.
//!
//! ## Determinism
//!
//! CAR is a deterministic execution layer, so a "random" simulation that can't
//! be reproduced would be a poor fit. Sampling uses a seeded SplitMix64 stream
//! ([`MonteCarloConfig::seed`]) rather than thread RNG or wall-clock entropy:
//! the same proposal, rates, and seed always produce byte-identical output, and
//! every ordered collection in [`MonteCarloResult`] has a defined sort. A
//! surprising verdict can therefore be re-run and inspected.

use crate::goal::{evaluate_goal, GoalCondition, GoalInputs};
use crate::{apply_action_effects, StaticState};
use car_ir::precondition;
use car_ir::{dependency_edges, ActionProposal, ActionType};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::{HashMap, HashSet};

/// Knobs for a Monte Carlo run.
///
/// Every field carries a serde default, so a JSON caller can send
/// `{"trials": 5000}` and get the documented defaults for the rest rather than
/// a deserialization error.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct MonteCarloConfig {
    /// How many independent rollouts to run. More trials narrow the confidence
    /// interval on every reported probability (standard error ≈
    /// `sqrt(p(1-p)/trials)` — 1000 trials puts a probability near 0.5 within
    /// about ±1.6 points at 1σ).
    pub trials: u32,
    /// Seed for the sampling stream. Fixed by default so runs are reproducible;
    /// vary it to check that a verdict is not an artifact of one seed.
    pub seed: u64,
    /// Success probability assumed for a tool with no recorded history. Matches
    /// `car_planner::ToolFeedback`'s "no data = 0.5" convention rather than
    /// silently assuming a new tool is perfect.
    pub default_success_rate: f64,
    /// Retries per dispatched `tool_call` beyond the first attempt. Each
    /// attempt is an independent draw, so `retry_attempts: 2` gives an
    /// effective per-action success of `1 - (1-p)^3` at the cost of up to three
    /// entries in [`MonteCarloResult::tool_calls`].
    pub retry_attempts: u32,
}

impl Default for MonteCarloConfig {
    fn default() -> Self {
        Self {
            trials: 1000,
            seed: 0x0CA1_0CA1_0CA1_0CA1,
            default_success_rate: 0.5,
            retry_attempts: 0,
        }
    }
}

/// Summary statistics for a per-trial count.
///
/// Percentiles use the nearest-rank method on the sorted samples, so every
/// reported value is one that actually occurred in some trial rather than an
/// interpolation between two that did.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct Distribution {
    pub mean: f64,
    pub min: u32,
    pub p50: u32,
    pub p95: u32,
    pub max: u32,
}

impl Distribution {
    /// `samples` is consumed and sorted in place.
    fn from_samples(samples: &mut [u32]) -> Self {
        if samples.is_empty() {
            return Self::default();
        }
        samples.sort_unstable();
        let n = samples.len();
        let sum: u64 = samples.iter().map(|&v| u64::from(v)).sum();
        Self {
            mean: sum as f64 / n as f64,
            min: samples[0],
            p50: samples[nearest_rank(n, 0.50)],
            p95: samples[nearest_rank(n, 0.95)],
            max: samples[n - 1],
        }
    }
}

/// Index into a sorted sample of length `n` for the given quantile.
fn nearest_rank(n: usize, q: f64) -> usize {
    debug_assert!(n > 0);
    let rank = (q * n as f64).ceil() as usize;
    rank.saturating_sub(1).min(n - 1)
}

/// How one state key came out across the run.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct KeyOutcome {
    pub key: String,
    /// Fraction of trials in which the key was present in the final state.
    /// Below 1.0 means the key's writer was gated or failed in some trials —
    /// exactly the uncertainty [`simulate`](crate::simulate) cannot express.
    pub p_present: f64,
    /// Distinct final values and how often each occurred, most frequent first
    /// (ties broken by the value's JSON encoding, for stable output).
    pub values: Vec<ValueFrequency>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ValueFrequency {
    pub value: Value,
    /// Fraction of *all* trials — not of the trials where the key was present —
    /// so these sum to [`KeyOutcome::p_present`].
    pub probability: f64,
}

/// How one action came out across the run.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionOutcome {
    pub action_id: String,
    /// Fraction of trials in which the action was rejected before dispatch —
    /// a failing precondition or a dependency that never arrived. A high value
    /// here points *upstream*: this action is a victim, not a cause.
    pub p_rejected: f64,
    /// Fraction of trials in which the action was dispatched but every attempt
    /// failed. This is where the plan actually breaks.
    pub p_failed: f64,
    /// Fraction of trials in which the action's `expected_effects` landed.
    pub p_effects_landed: f64,
    /// Mean number of transitive dependents rejected in the trials where this
    /// action failed — its blast radius.
    ///
    /// Attribution is per failing action: when two independent failures share a
    /// dependent, that dependent is counted for both, so these do not sum to
    /// the number of rejected actions. Use it to rank *which* failure hurts
    /// most, not to decompose a total.
    pub mean_blast_radius: f64,
}

/// The outcome distribution over `trials` rollouts.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MonteCarloResult {
    pub trials: u32,
    /// Echoed so a result carries everything needed to reproduce it.
    pub seed: u64,
    /// Fraction of trials in which the supplied goal condition held against the
    /// final state. `None` when no goal was supplied.
    ///
    /// Read it together with [`Self::goal_underivable_conditions`]: a goal that
    /// depends on signals a simulation cannot produce fails closed, and a `0.0`
    /// from that is a statement about the *condition*, not the plan.
    pub p_goal_reached: Option<f64>,
    /// Condition kinds in the supplied goal that cannot be decided from a
    /// simulated state (tool receipts, command exits, model judges, and the
    /// plan/transaction checks). Deduplicated, sorted. Non-empty means
    /// [`Self::p_goal_reached`] is a lower bound.
    pub goal_underivable_conditions: Vec<String>,
    /// Fraction of trials in which every action's effects landed — the
    /// probability the plan runs clean end to end.
    pub p_all_effects_landed: f64,
    /// Dispatch attempts per trial, retries included. The cost proxy: this is
    /// what you pay per run, and its p95 is what capacity planning needs.
    pub tool_calls: Distribution,
    /// Actions whose effects landed, per trial.
    pub actions_executed: Distribution,
    /// Per-key outcome, sorted by key.
    pub state_distribution: Vec<KeyOutcome>,
    /// Per-action outcome, in proposal order.
    pub action_outcomes: Vec<ActionOutcome>,
}

impl MonteCarloResult {
    /// What kind of check produced these numbers — see
    /// [`crate::EvidenceTier`]. Always [`crate::EvidenceTier::Sampled`], and
    /// this is the crate's clearest case of the tier.
    ///
    /// Every field here is an estimate from `trials` draws. `p_goal_reached`
    /// is a sample proportion, not a probability the plan works;
    /// `p_all_effects_landed` is the same; the [`Distribution`] percentiles are
    /// order statistics of the sample. Nothing is decided — a rollout that
    /// never sampled a particular failure interleaving reports nothing about
    /// it, and no number of trials turns that into coverage.
    ///
    /// Determinism does not change the tier. A seeded run is reproducible, so
    /// the *same* sample comes back every time; reproducing a sample is not
    /// enlarging it. And the per-tool rates fed in are themselves empirical
    /// (`success / total` over recorded events), with the independence and
    /// partial-effect simplifications the module docs list above — read those
    /// before quoting any of these numbers.
    pub const fn evidence_tier(&self) -> crate::EvidenceTier {
        crate::EvidenceTier::Sampled
    }
}

/// Run `config.trials` sampled rollouts of `proposal`.
///
/// `tool_success_rates` maps tool name to its empirical success probability —
/// pass `car_planner::ToolFeedback::tool_success_rates` straight in. Tools
/// absent from the map use [`MonteCarloConfig::default_success_rate`]. Rates
/// outside `0.0..=1.0` are clamped rather than rejected, so a caller computing
/// them from noisy counts can't produce a panic.
///
/// `goal` is optional; when supplied it is evaluated against each trial's final
/// state to produce [`MonteCarloResult::p_goal_reached`].
///
/// With `trials: 0` every field is zero or empty — there is nothing to average.
pub fn simulate_monte_carlo(
    proposal: &ActionProposal,
    initial_state: Option<&HashMap<String, Value>>,
    tool_success_rates: &HashMap<String, f64>,
    goal: Option<&GoalCondition>,
    config: &MonteCarloConfig,
) -> MonteCarloResult {
    let n_actions = proposal.actions.len();
    let goal_underivable_conditions = goal.map(underivable_kinds).unwrap_or_default();

    let mut result = MonteCarloResult {
        trials: config.trials,
        seed: config.seed,
        p_goal_reached: goal.map(|_| 0.0),
        goal_underivable_conditions,
        p_all_effects_landed: 0.0,
        tool_calls: Distribution::default(),
        actions_executed: Distribution::default(),
        state_distribution: Vec::new(),
        action_outcomes: Vec::new(),
    };

    if config.trials == 0 {
        result.action_outcomes = proposal
            .actions
            .iter()
            .map(|a| ActionOutcome {
                action_id: a.id.clone(),
                p_rejected: 0.0,
                p_failed: 0.0,
                p_effects_landed: 0.0,
                mean_blast_radius: 0.0,
            })
            .collect();
        return result;
    }

    // Execution order and the transitive dependent sets are properties of the
    // proposal, not of a trial — hoist them out of the loop. `dependency_edges`
    // is the same source of truth the executor sequences on, so blast radius
    // can't drift from real ordering.
    let levels = car_ir::build_dag(&proposal.actions);
    let descendants = transitive_dependents(&proposal.actions);
    let attempts = config.retry_attempts.saturating_add(1);
    let default_rate = config.default_success_rate.clamp(0.0, 1.0);

    let trials = config.trials as usize;
    let mut rng = SplitMix64::new(config.seed);

    let mut tool_call_samples: Vec<u32> = Vec::with_capacity(trials);
    let mut executed_samples: Vec<u32> = Vec::with_capacity(trials);
    let mut rejected_counts = vec![0u32; n_actions];
    let mut failed_counts = vec![0u32; n_actions];
    let mut landed_counts = vec![0u32; n_actions];
    let mut blast_totals = vec![0u64; n_actions];
    let mut clean_runs = 0u32;
    let mut goal_met = 0u32;
    // key -> canonical JSON of the value -> count. Value is not `Hash`, so the
    // encoding is the map key and the parsed form is restored on the way out.
    let mut key_values: HashMap<String, HashMap<String, u32>> = HashMap::new();

    for _ in 0..trials {
        let mut state = match initial_state {
            Some(s) => StaticState::from_map(s.clone()),
            None => StaticState::new(),
        };
        let mut tool_calls = 0u32;
        let mut executed = 0u32;
        let mut landed = vec![false; n_actions];
        let mut rejected = vec![false; n_actions];
        let mut failed = vec![false; n_actions];

        for level in &levels {
            for &idx in level {
                let action = &proposal.actions[idx];

                // Pre-dispatch gating, identical to `EffectMode::ExecutionFaithful`.
                let gated = action
                    .preconditions
                    .iter()
                    .any(|pre| precondition::check_precondition(pre, &state).is_some())
                    || action
                        .state_dependencies
                        .iter()
                        .any(|dep| !state.exists(dep) && !state.is_unknown(dep));

                if gated {
                    rejected[idx] = true;
                    continue;
                }

                if action.action_type == ActionType::ToolCall {
                    // A `tool_call` naming no tool is structurally malformed;
                    // the executor rejects it before dispatch, so it never
                    // reaches a coin flip.
                    let Some(tool) = action.tool.as_deref() else {
                        rejected[idx] = true;
                        continue;
                    };
                    let p = tool_success_rates
                        .get(tool)
                        .copied()
                        .unwrap_or(default_rate)
                        .clamp(0.0, 1.0);

                    let mut succeeded = false;
                    for _ in 0..attempts {
                        tool_calls += 1;
                        if rng.next_f64() < p {
                            succeeded = true;
                            break;
                        }
                    }
                    if !succeeded {
                        failed[idx] = true;
                        continue;
                    }
                }

                apply_action_effects(action, &mut state);
                landed[idx] = true;
                executed += 1;
            }
        }

        for idx in 0..n_actions {
            if rejected[idx] {
                rejected_counts[idx] += 1;
            }
            if failed[idx] {
                failed_counts[idx] += 1;
                blast_totals[idx] +=
                    descendants[idx].iter().filter(|&&d| rejected[d]).count() as u64;
            }
            if landed[idx] {
                landed_counts[idx] += 1;
            }
        }

        if n_actions > 0 && landed.iter().all(|&l| l) {
            clean_runs += 1;
        } else if n_actions == 0 {
            // A proposal with no actions trivially ran clean.
            clean_runs += 1;
        }

        if let Some(condition) = goal {
            let inputs = GoalInputs {
                state: state.known.clone(),
                ..Default::default()
            };
            if evaluate_goal(condition, &inputs).met {
                goal_met += 1;
            }
        }

        for (key, value) in &state.known {
            *key_values
                .entry(key.clone())
                .or_default()
                .entry(canonical(value))
                .or_insert(0) += 1;
        }

        tool_call_samples.push(tool_calls);
        executed_samples.push(executed);
    }

    let t = trials as f64;
    result.p_all_effects_landed = f64::from(clean_runs) / t;
    result.p_goal_reached = goal.map(|_| f64::from(goal_met) / t);
    result.tool_calls = Distribution::from_samples(&mut tool_call_samples);
    result.actions_executed = Distribution::from_samples(&mut executed_samples);

    result.action_outcomes = proposal
        .actions
        .iter()
        .enumerate()
        .map(|(i, a)| ActionOutcome {
            action_id: a.id.clone(),
            p_rejected: f64::from(rejected_counts[i]) / t,
            p_failed: f64::from(failed_counts[i]) / t,
            p_effects_landed: f64::from(landed_counts[i]) / t,
            mean_blast_radius: if failed_counts[i] == 0 {
                0.0
            } else {
                blast_totals[i] as f64 / f64::from(failed_counts[i])
            },
        })
        .collect();

    let mut state_distribution: Vec<KeyOutcome> = key_values
        .into_iter()
        .map(|(key, counts)| {
            let present: u32 = counts.values().sum();
            let mut values: Vec<ValueFrequency> = counts
                .into_iter()
                .map(|(encoded, count)| ValueFrequency {
                    // Re-parsing what `canonical` wrote; a failure here would
                    // mean serde_json can't read its own output.
                    value: serde_json::from_str(&encoded).unwrap_or(Value::Null),
                    probability: f64::from(count) / t,
                })
                .collect();
            values.sort_by(|a, b| {
                b.probability
                    .partial_cmp(&a.probability)
                    .unwrap_or(std::cmp::Ordering::Equal)
                    .then_with(|| canonical(&a.value).cmp(&canonical(&b.value)))
            });
            KeyOutcome {
                key,
                p_present: f64::from(present) / t,
                values,
            }
        })
        .collect();
    state_distribution.sort_by(|a, b| a.key.cmp(&b.key));
    result.state_distribution = state_distribution;

    result
}

/// Stable JSON encoding used as a hash key for value frequencies.
fn canonical(value: &Value) -> String {
    serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
}

/// For each action, the set of actions that transitively depend on it.
///
/// Built from [`car_ir::dependency_edges`] — the edges the executor itself
/// sequences on — so "downstream" here means the same thing it does at runtime.
fn transitive_dependents(actions: &[car_ir::Action]) -> Vec<HashSet<usize>> {
    let deps = dependency_edges(actions);
    let n = actions.len();
    let mut descendants: Vec<HashSet<usize>> = vec![HashSet::new(); n];

    // `deps[i]` only ever contains indices < i (declaration order is enforced
    // in `dependency_edges`), so a single descending pass closes transitively:
    // when i is processed, every j > i already has its full descendant set.
    for i in (0..n).rev() {
        for &parent in &deps[i] {
            descendants[parent].insert(i);
            let closure: Vec<usize> = descendants[i].iter().copied().collect();
            descendants[parent].extend(closure);
        }
    }
    descendants
}

/// Condition kinds that a simulated state cannot decide. These fail closed in
/// [`evaluate_goal`], so they are surfaced rather than silently depressing
/// `p_goal_reached`.
fn underivable_kinds(condition: &GoalCondition) -> Vec<String> {
    let mut found = Vec::new();
    collect_underivable(condition, &mut found);
    found.sort();
    found.dedup();
    found
}

fn collect_underivable(condition: &GoalCondition, out: &mut Vec<String>) {
    match condition {
        GoalCondition::AllOf { conditions } | GoalCondition::AnyOf { conditions } => {
            for c in conditions {
                collect_underivable(c, out);
            }
        }
        // The one condition a rollout genuinely decides: it reads final state.
        GoalCondition::StatePredicate { .. } => {}
        GoalCondition::ToolReceiptsGrounded => out.push("tool_receipts_grounded".into()),
        GoalCondition::PlanAchieved => out.push("plan_achieved".into()),
        GoalCondition::StateConsistent => out.push("state_consistent".into()),
        GoalCondition::Command { id, .. } => out.push(format!("command:{id}")),
        GoalCondition::ModelJudge { id } => out.push(format!("model_judge:{id}")),
    }
}

/// SplitMix64 — the sampling stream.
///
/// Chosen over pulling in `rand`: car-verify's entire dependency set is
/// `car-ir` + serde, and a verification crate is a bad place to grow a
/// dependency tree. SplitMix64 passes BigCrush, is ~10 lines, and — the point
/// here — is exactly reproducible from a `u64` seed across platforms and
/// compiler versions.
struct SplitMix64 {
    state: u64,
}

impl SplitMix64 {
    fn new(seed: u64) -> Self {
        Self { state: seed }
    }

    fn next_u64(&mut self) -> u64 {
        self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15);
        let mut z = self.state;
        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
        z ^ (z >> 31)
    }

    /// Uniform in `[0, 1)` from the top 53 bits — the full mantissa, so no
    /// value in the range is unreachable.
    fn next_f64(&mut self) -> f64 {
        (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use car_ir::{Action, ActionProposal, Precondition};

    fn bare(id: &str, action_type: ActionType) -> Action {
        {
            let mut a = Action::new(action_type);
            a.id = id.to_string();
            a
        }
    }

    fn tool_action(id: &str, tool: &str, deps: &[&str], effects: &[(&str, Value)]) -> Action {
        let mut a = bare(id, ActionType::ToolCall);
        a.tool = Some(tool.to_string());
        a.state_dependencies = deps.iter().map(|d| d.to_string()).collect();
        a.expected_effects = effects
            .iter()
            .map(|(k, v)| (k.to_string(), v.clone()))
            .collect();
        a
    }

    fn proposal(actions: Vec<Action>) -> ActionProposal {
        ActionProposal {
            id: "mc-test".to_string(),
            source: "test".to_string(),
            actions,
            timestamp: chrono::Utc::now(),
            context: HashMap::new(),
        }
    }

    fn rates(pairs: &[(&str, f64)]) -> HashMap<String, f64> {
        pairs.iter().map(|(k, v)| (k.to_string(), *v)).collect()
    }

    #[test]
    fn certain_tools_reproduce_deterministic_simulate() {
        let p = proposal(vec![
            tool_action("a", "fetch", &[], &[("data", Value::from(1))]),
            tool_action("b", "write", &["data"], &[("done", Value::from(true))]),
        ]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("fetch", 1.0), ("write", 1.0)]),
            None,
            &MonteCarloConfig::default(),
        );

        assert_eq!(r.p_all_effects_landed, 1.0);
        // With p=1 the rollout must agree with `simulate` exactly.
        let deterministic = crate::simulate(&p, None);
        for key in deterministic.keys() {
            let outcome = r
                .state_distribution
                .iter()
                .find(|k| &k.key == key)
                .expect("key present in monte carlo output");
            assert_eq!(outcome.p_present, 1.0);
        }
        assert_eq!(r.tool_calls.p50, 2);
        assert_eq!(r.tool_calls.p95, 2);
    }

    #[test]
    fn impossible_tool_blocks_itself_and_its_dependent() {
        let p = proposal(vec![
            tool_action("a", "flaky", &[], &[("data", Value::from(1))]),
            tool_action("b", "write", &["data"], &[("done", Value::from(true))]),
        ]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("flaky", 0.0), ("write", 1.0)]),
            None,
            &MonteCarloConfig::default(),
        );

        assert_eq!(r.action_outcomes[0].p_failed, 1.0);
        assert_eq!(r.action_outcomes[0].p_effects_landed, 0.0);
        // `b` never gets dispatched — it is a cascade victim, not a failure.
        assert_eq!(r.action_outcomes[1].p_rejected, 1.0);
        assert_eq!(r.action_outcomes[1].p_failed, 0.0);
        // One dependent lost per failure.
        assert_eq!(r.action_outcomes[0].mean_blast_radius, 1.0);
        // `b` never ran, so it never dispatched a tool: 1 call per trial, not 2.
        assert_eq!(r.tool_calls.max, 1);
        assert!(r.state_distribution.is_empty());
    }

    #[test]
    fn probability_lands_near_the_configured_rate() {
        let p = proposal(vec![tool_action(
            "a",
            "coin",
            &[],
            &[("data", Value::from(1))],
        )]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("coin", 0.7)]),
            None,
            &MonteCarloConfig {
                trials: 20_000,
                ..Default::default()
            },
        );
        // 20k trials puts the 1σ standard error at ~0.003; 0.02 is ~6σ.
        assert!(
            (r.action_outcomes[0].p_effects_landed - 0.7).abs() < 0.02,
            "expected ≈0.7, got {}",
            r.action_outcomes[0].p_effects_landed
        );
        assert!((r.p_all_effects_landed - 0.7).abs() < 0.02);
    }

    #[test]
    fn same_seed_reproduces_byte_identical_output() {
        let p = proposal(vec![
            tool_action("a", "coin", &[], &[("data", Value::from(1))]),
            tool_action("b", "coin2", &["data"], &[("done", Value::from(true))]),
        ]);
        let rates = rates(&[("coin", 0.6), ("coin2", 0.4)]);
        let cfg = MonteCarloConfig {
            trials: 500,
            seed: 42,
            ..Default::default()
        };
        let a = simulate_monte_carlo(&p, None, &rates, None, &cfg);
        let b = simulate_monte_carlo(&p, None, &rates, None, &cfg);
        assert_eq!(a, b);

        let c = simulate_monte_carlo(
            &p,
            None,
            &rates,
            None,
            &MonteCarloConfig { seed: 43, ..cfg },
        );
        assert_ne!(a, c, "a different seed should produce a different sample");
    }

    #[test]
    fn retries_raise_effective_success() {
        let p = proposal(vec![tool_action(
            "a",
            "coin",
            &[],
            &[("data", Value::from(1))],
        )]);
        let rates = rates(&[("coin", 0.5)]);
        let base = MonteCarloConfig {
            trials: 20_000,
            ..Default::default()
        };
        let with_retries = simulate_monte_carlo(
            &p,
            None,
            &rates,
            None,
            &MonteCarloConfig {
                retry_attempts: 2,
                ..base
            },
        );
        // 1 - 0.5^3 = 0.875
        assert!(
            (with_retries.action_outcomes[0].p_effects_landed - 0.875).abs() < 0.02,
            "got {}",
            with_retries.action_outcomes[0].p_effects_landed
        );
        // Retries are not free — they show up in the cost proxy.
        assert!(with_retries.tool_calls.max > 1);
        assert!(with_retries.tool_calls.mean > 1.0);
    }

    #[test]
    fn unknown_tool_uses_the_default_rate() {
        let p = proposal(vec![tool_action(
            "a",
            "never-seen",
            &[],
            &[("data", Value::from(1))],
        )]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &HashMap::new(),
            None,
            &MonteCarloConfig {
                trials: 20_000,
                default_success_rate: 0.25,
                ..Default::default()
            },
        );
        assert!(
            (r.action_outcomes[0].p_effects_landed - 0.25).abs() < 0.02,
            "got {}",
            r.action_outcomes[0].p_effects_landed
        );
    }

    #[test]
    fn state_distribution_reports_a_split() {
        // `a` writes data=1 always; `b` overwrites it with 2 half the time.
        let p = proposal(vec![
            tool_action("a", "always", &[], &[("data", Value::from(1))]),
            tool_action("b", "coin", &["data"], &[("data", Value::from(2))]),
        ]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("always", 1.0), ("coin", 0.5)]),
            None,
            &MonteCarloConfig {
                trials: 20_000,
                ..Default::default()
            },
        );
        let data = &r.state_distribution[0];
        assert_eq!(data.key, "data");
        assert_eq!(data.p_present, 1.0);
        assert_eq!(data.values.len(), 2);
        // Frequencies sum to p_present, and both outcomes are near 0.5.
        let total: f64 = data.values.iter().map(|v| v.probability).sum();
        assert!((total - 1.0).abs() < 1e-9);
        for v in &data.values {
            assert!((v.probability - 0.5).abs() < 0.02, "got {}", v.probability);
        }
    }

    #[test]
    fn goal_probability_tracks_a_state_predicate() {
        let p = proposal(vec![tool_action(
            "a",
            "coin",
            &[],
            &[("deployed", Value::from(true))],
        )]);
        let goal = GoalCondition::StatePredicate {
            key: "deployed".into(),
            equals: Value::from(true),
        };
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("coin", 0.8)]),
            Some(&goal),
            &MonteCarloConfig {
                trials: 20_000,
                ..Default::default()
            },
        );
        let p_goal = r.p_goal_reached.expect("goal supplied");
        assert!((p_goal - 0.8).abs() < 0.02, "got {p_goal}");
        assert!(r.goal_underivable_conditions.is_empty());
    }

    #[test]
    fn underivable_goal_conditions_are_surfaced_not_silently_zero() {
        let p = proposal(vec![tool_action(
            "a",
            "always",
            &[],
            &[("deployed", Value::from(true))],
        )]);
        let goal = GoalCondition::AllOf {
            conditions: vec![
                GoalCondition::StatePredicate {
                    key: "deployed".into(),
                    equals: Value::from(true),
                },
                GoalCondition::ToolReceiptsGrounded,
                GoalCondition::Command {
                    id: "tests".into(),
                    expect_exit: 0,
                },
            ],
        };
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("always", 1.0)]),
            Some(&goal),
            &MonteCarloConfig::default(),
        );
        // Fails closed — but the caller is told exactly why, so a 0.0 is not
        // mistaken for "this plan cannot work".
        assert_eq!(r.p_goal_reached, Some(0.0));
        assert_eq!(
            r.goal_underivable_conditions,
            vec![
                "command:tests".to_string(),
                "tool_receipts_grounded".to_string()
            ]
        );
    }

    #[test]
    fn blast_radius_counts_transitive_dependents() {
        // a → b → c, plus an independent d that must not be attributed to a.
        let p = proposal(vec![
            tool_action("a", "flaky", &[], &[("x", Value::from(1))]),
            tool_action("b", "ok", &["x"], &[("y", Value::from(1))]),
            tool_action("c", "ok", &["y"], &[("z", Value::from(1))]),
            tool_action("d", "ok", &[], &[("w", Value::from(1))]),
        ]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("flaky", 0.0), ("ok", 1.0)]),
            None,
            &MonteCarloConfig::default(),
        );
        assert_eq!(r.action_outcomes[0].mean_blast_radius, 2.0);
        // The independent branch is unaffected.
        assert_eq!(r.action_outcomes[3].p_effects_landed, 1.0);
    }

    #[test]
    fn zero_trials_is_empty_not_a_divide_by_zero() {
        let p = proposal(vec![tool_action("a", "t", &[], &[])]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &HashMap::new(),
            None,
            &MonteCarloConfig {
                trials: 0,
                ..Default::default()
            },
        );
        assert_eq!(r.trials, 0);
        assert_eq!(r.p_all_effects_landed, 0.0);
        assert_eq!(r.action_outcomes.len(), 1);
        assert!(r.state_distribution.is_empty());
        assert_eq!(r.tool_calls, Distribution::default());
    }

    #[test]
    fn out_of_range_rates_are_clamped() {
        let p = proposal(vec![tool_action(
            "a",
            "weird",
            &[],
            &[("x", Value::from(1))],
        )]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("weird", 5.0)]),
            None,
            &MonteCarloConfig::default(),
        );
        assert_eq!(r.action_outcomes[0].p_effects_landed, 1.0);

        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("weird", -2.0)]),
            None,
            &MonteCarloConfig::default(),
        );
        assert_eq!(r.action_outcomes[0].p_effects_landed, 0.0);
    }

    #[test]
    fn precondition_gating_rejects_before_any_coin_flip() {
        let mut blocked = tool_action("a", "coin", &[], &[("x", Value::from(1))]);
        blocked.preconditions = vec![Precondition {
            key: "ready".into(),
            operator: "eq".into(),
            value: Value::from(true),
            description: String::new(),
        }];
        let p = proposal(vec![blocked]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &rates(&[("coin", 1.0)]),
            None,
            &MonteCarloConfig::default(),
        );
        // Rejected, never dispatched — so it costs nothing and isn't a "failure".
        assert_eq!(r.action_outcomes[0].p_rejected, 1.0);
        assert_eq!(r.action_outcomes[0].p_failed, 0.0);
        assert_eq!(r.tool_calls.max, 0);
    }

    #[test]
    fn non_tool_actions_do_not_flip_coins() {
        let mut write = bare("w", ActionType::StateWrite);
        write.parameters = [
            ("key".to_string(), Value::from("k")),
            ("value".to_string(), Value::from(9)),
        ]
        .into();
        let p = proposal(vec![write]);
        let r = simulate_monte_carlo(
            &p,
            None,
            &HashMap::new(),
            None,
            &MonteCarloConfig::default(),
        );
        assert_eq!(r.action_outcomes[0].p_effects_landed, 1.0);
        assert_eq!(r.tool_calls.max, 0);
    }
}