openlatch-client 0.5.3

//! Canonical I-10 Anthropic Messages interventions.
//!
//! Each actuator builds a complete JSON value and validates that only its
//! narrow field boundary changed. Callers serialize last and retain the raw
//! request bytes as the sole fallback.

use std::collections::{HashMap, HashSet};
use std::sync::Mutex;
use std::time::{Duration, Instant};

use serde_json::{json, Value};

use crate::model_relay::billing::BillingMode;
use crate::zone_eval::types::OptimizeParams;

const CACHE_TTL: Duration = Duration::from_secs(60 * 60);
const PROTECTED_TOOLS: [&str; 3] = ["Edit", "Write", "Read"];

#[derive(Clone, Debug, PartialEq)]
pub struct AppliedIntervention {
    pub body: Value,
    pub lever: String,
    pub session_key: String,
    pub context_pair: Option<String>,
    pub effort_ceiling: Option<String>,
    pub changed: bool,
}

#[derive(Clone, Debug, Default)]
struct SessionInterventions {
    last_prefix: Option<u64>,
    last_seen: Option<Instant>,
    effort: Option<String>,
    rejected_context_pairs: HashSet<String>,
}

/// Bounded facts needed by relay actuators; prompt bytes are never retained.
#[derive(Default)]
pub struct InterventionSessions {
    sessions: Mutex<HashMap<String, SessionInterventions>>,
}

impl InterventionSessions {
    pub fn apply(
        &self,
        session_key: &str,
        body: &Value,
        params: &OptimizeParams,
        billing: BillingMode,
        prefix_churn: bool,
        now: Instant,
    ) -> Result<AppliedIntervention, &'static str> {
        let mut sessions = self.sessions.lock().map_err(|_| "guarded")?;
        if sessions.len() >= 1_024 && !sessions.contains_key(session_key) {
            return Err("guarded");
        }
        let state = sessions.entry(session_key.to_string()).or_default();
        match params {
            OptimizeParams::EffortClamp(params) => {
                effort_clamp(session_key, body, params, state, now)
            }
            OptimizeParams::ContextEdit(params) => context_edit(session_key, body, params, state),
            OptimizeParams::PrefixGuard(params) => {
                prefix_guard(session_key, body, params, billing, prefix_churn)
            }
            _ => Err("incapable"),
        }
    }

    pub fn accepted(&self, applied: &AppliedIntervention, now: Instant) {
        let Ok(mut sessions) = self.sessions.lock() else {
            return;
        };
        let state = sessions.entry(applied.session_key.clone()).or_default();
        state.last_seen = Some(now);
        state.last_prefix = Some(prefix_hash(&applied.body));
        if applied.lever == "effort_clamp" {
            state.effort = applied.effort_ceiling.clone();
        }
    }

    pub fn rejected(&self, applied: &AppliedIntervention) {
        let Some(pair) = applied.context_pair.as_ref() else {
            return;
        };
        let Ok(mut sessions) = self.sessions.lock() else {
            return;
        };
        sessions
            .entry(applied.session_key.clone())
            .or_default()
            .rejected_context_pairs
            .insert(pair.clone());
    }
}

fn effort_clamp(
    session_key: &str,
    body: &Value,
    params: &serde_json::Map<String, Value>,
    state: &SessionInterventions,
    now: Instant,
) -> Result<AppliedIntervention, &'static str> {
    let current = body
        .pointer("/output_config/effort")
        .and_then(Value::as_str)
        .ok_or("incapable")?;
    let requested = params
        .get("effort")
        .and_then(Value::as_str)
        .ok_or("guarded")?;
    let floor = params
        .get("quality_floor")
        .and_then(Value::as_str)
        .ok_or("guarded")?;
    let rank = |v: &str| match v {
        "low" => Some(0),
        "medium" => Some(1),
        "high" => Some(2),
        "max" => Some(3),
        _ => None,
    };
    let (Some(current_rank), Some(requested_rank), Some(floor_rank)) =
        (rank(current), rank(requested), rank(floor))
    else {
        return Err("guarded");
    };
    let cold = state.last_seen.is_none()
        || state
            .last_seen
            .is_some_and(|last| now.saturating_duration_since(last) >= CACHE_TTL)
        || is_compaction(body)
        || state
            .last_prefix
            .is_some_and(|hash| hash != prefix_hash(body));
    let selected_rank = requested_rank.max(floor_rank);
    let ceiling_rank = if cold {
        selected_rank
    } else {
        state.effort.as_deref().and_then(rank).ok_or("guarded")?
    };
    let target_rank = current_rank.min(ceiling_rank);
    let target = ["low", "medium", "high", "max"][target_rank as usize];
    let mut edited = body.clone();
    edited["output_config"]["effort"] = Value::String(target.to_string());
    Ok(AppliedIntervention {
        changed: target != current,
        body: edited,
        lever: "effort_clamp".into(),
        session_key: session_key.into(),
        context_pair: None,
        effort_ceiling: Some(["low", "medium", "high", "max"][ceiling_rank as usize].into()),
    })
}

fn context_edit(
    session_key: &str,
    body: &Value,
    params: &serde_json::Map<String, Value>,
    state: &SessionInterventions,
) -> Result<AppliedIntervention, &'static str> {
    if is_compaction(body) {
        return Err("guarded");
    }
    let cm = body
        .get("context_management")
        .and_then(Value::as_object)
        .ok_or("incapable")?;
    let edits = cm
        .get("edits")
        .and_then(Value::as_array)
        .ok_or("incapable")?;
    let edit_index = edits
        .iter()
        .position(|edit| {
            edit.get("type").and_then(Value::as_str) == Some("clear_tool_uses_20250919")
        })
        .ok_or("incapable")?;
    let edit = edits[edit_index].as_object().ok_or("guarded")?;
    let mut edited_cm = cm.clone();
    let incoming_trigger = number(params, "trigger")?;
    let incoming_keep = number(params, "keep")?;
    let incoming_clear = number(params, "clear_at_least")?;
    if !context_edit_net_positive(body, incoming_keep, incoming_clear, params)? {
        return Err("guarded");
    }
    let current_trigger = typed_control(edit.get("trigger"), "input_tokens")?;
    let current_keep = typed_control(edit.get("keep"), "tool_uses")?;
    let current_clear = typed_control(edit.get("clear_at_least"), "input_tokens")?;
    let mut edited_edit = edit.clone();
    edited_edit.insert(
        "trigger".into(),
        json!({"type":"input_tokens","value":incoming_trigger.min(current_trigger)}),
    );
    edited_edit.insert(
        "keep".into(),
        json!({"type":"tool_uses","value":incoming_keep.min(current_keep)}),
    );
    edited_edit.insert(
        "clear_at_least".into(),
        json!({"type":"input_tokens","value":incoming_clear.max(current_clear)}),
    );
    let mut excluded: Vec<String> = edit
        .get("exclude_tools")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(Value::as_str)
        .map(str::to_string)
        .collect();
    excluded.extend(
        params
            .get("exclude_tools")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
            .filter_map(Value::as_str)
            .map(str::to_string),
    );
    excluded.extend(PROTECTED_TOOLS.map(str::to_string));
    excluded.sort();
    excluded.dedup();
    edited_edit.insert("exclude_tools".into(), json!(excluded));
    let mut edited_edits = edits.clone();
    edited_edits[edit_index] = Value::Object(edited_edit);
    edited_cm.insert("edits".into(), Value::Array(edited_edits));
    let pair = Value::Object(edited_cm.clone()).to_string();
    if state.rejected_context_pairs.contains(&pair) {
        return Err("guarded");
    }
    let mut edited = body.clone();
    edited["context_management"] = Value::Object(edited_cm);
    if edited == *body {
        return Err("guarded");
    }
    if !context_edit_is_structurally_valid(body, &edited, edit_index) {
        return Err("guarded");
    }
    Ok(AppliedIntervention {
        changed: true,
        body: edited,
        lever: "context_edit".into(),
        session_key: session_key.into(),
        context_pair: Some(pair),
        effort_ceiling: None,
    })
}

fn prefix_guard(
    session_key: &str,
    body: &Value,
    params: &serde_json::Map<String, Value>,
    billing: BillingMode,
    prefix_churn: bool,
) -> Result<AppliedIntervention, &'static str> {
    if billing != BillingMode::ApiKey {
        return Err("guarded");
    }
    if !prefix_churn {
        return Err("guarded");
    }
    let ttl = params
        .get("pin_ttl")
        .and_then(Value::as_str)
        .unwrap_or("1h");
    if ttl != "1h" {
        return Err("guarded");
    }
    let blocks = body
        .get("system")
        .and_then(Value::as_array)
        .ok_or("incapable")?;
    let index = blocks
        .iter()
        .rposition(|block| block.get("cache_control").is_some())
        .ok_or("guarded")?;
    let mut edited = body.clone();
    edited["system"][index]["cache_control"] = json!({"type":"ephemeral", "ttl":"1h"});
    if edited == *body {
        return Err("guarded");
    }
    Ok(AppliedIntervention {
        changed: true,
        body: edited,
        lever: "prefix_guard".into(),
        session_key: session_key.into(),
        context_pair: None,
        effort_ceiling: None,
    })
}

fn number(params: &serde_json::Map<String, Value>, key: &str) -> Result<u64, &'static str> {
    params.get(key).and_then(Value::as_u64).ok_or("guarded")
}

fn typed_control(value: Option<&Value>, expected_type: &str) -> Result<u64, &'static str> {
    let value = value.and_then(Value::as_object).ok_or("guarded")?;
    if value.get("type").and_then(Value::as_str) != Some(expected_type) {
        return Err("guarded");
    }
    value.get("value").and_then(Value::as_u64).ok_or("guarded")
}

/**
 * Measure only tool-result blocks the configured strategy can actually clear,
 * then feed those gross/retained token estimates into the shared net equation.
 */
fn context_edit_net_positive(
    body: &Value,
    keep: u64,
    clear_at_least: u64,
    params: &serde_json::Map<String, Value>,
) -> Result<bool, &'static str> {
    let messages = body
        .get("messages")
        .and_then(Value::as_array)
        .ok_or("guarded")?;
    let excluded: HashSet<&str> = params
        .get("exclude_tools")
        .and_then(Value::as_array)
        .ok_or("guarded")?
        .iter()
        .filter_map(Value::as_str)
        .chain(PROTECTED_TOOLS)
        .collect();
    let mut tool_names: HashMap<&str, &str> = HashMap::new();
    for message in messages {
        for block in message
            .get("content")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if block.get("type").and_then(Value::as_str) == Some("tool_use") {
                if let (Some(id), Some(name)) = (
                    block.get("id").and_then(Value::as_str),
                    block.get("name").and_then(Value::as_str),
                ) {
                    tool_names.insert(id, name);
                }
            }
        }
    }
    let mut eligible: Vec<(usize, u64)> = Vec::new();
    for (message_index, message) in messages.iter().enumerate() {
        for block in message
            .get("content")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if block.get("type").and_then(Value::as_str) != Some("tool_result") {
                continue;
            }
            let id = block
                .get("tool_use_id")
                .and_then(Value::as_str)
                .ok_or("guarded")?;
            let name = tool_names.get(id).copied().ok_or("guarded")?;
            if !excluded.contains(name) {
                let bytes = serde_json::to_vec(block).map_err(|_| "guarded")?.len() as u64;
                eligible.push((message_index, bytes.div_ceil(4)));
            }
        }
    }
    let removable = eligible.len().saturating_sub(keep as usize);
    if removable == 0 {
        return Ok(false);
    }
    let gross: u64 = eligible[..removable]
        .iter()
        .map(|(_, tokens)| *tokens)
        .sum();
    if gross < clear_at_least {
        return Ok(false);
    }
    let first_removed = eligible[0].0;
    let retained_bytes = serde_json::to_vec(&messages[first_removed + 1..])
        .map_err(|_| "guarded")?
        .len() as u64;
    Ok(super::net::tokens_net_hundredths(
        gross,
        retained_bytes.div_ceil(4),
        super::net::write_multiplier_for(body),
    ) > 0)
}

fn context_edit_is_structurally_valid(original: &Value, edited: &Value, index: usize) -> bool {
    let (Some(before), Some(after)) = (original.as_object(), edited.as_object()) else {
        return false;
    };
    if before.len() != after.len()
        || before
            .iter()
            .any(|(key, value)| key != "context_management" && after.get(key) != Some(value))
    {
        return false;
    }
    let (Some(before_cm), Some(after_cm)) = (
        before.get("context_management").and_then(Value::as_object),
        after.get("context_management").and_then(Value::as_object),
    ) else {
        return false;
    };
    if before_cm.len() != after_cm.len()
        || before_cm
            .iter()
            .any(|(key, value)| key != "edits" && after_cm.get(key) != Some(value))
    {
        return false;
    }
    let (Some(before_edits), Some(after_edits)) = (
        before_cm.get("edits").and_then(Value::as_array),
        after_cm.get("edits").and_then(Value::as_array),
    ) else {
        return false;
    };
    if before_edits.len() != after_edits.len()
        || before_edits
            .iter()
            .enumerate()
            .any(|(i, value)| i != index && after_edits.get(i) != Some(value))
    {
        return false;
    }
    let (Some(before_edit), Some(after_edit)) = (
        before_edits.get(index).and_then(Value::as_object),
        after_edits.get(index).and_then(Value::as_object),
    ) else {
        return false;
    };
    before_edit.len() == after_edit.len()
        && before_edit.iter().all(|(key, value)| {
            matches!(
                key.as_str(),
                "trigger" | "keep" | "clear_at_least" | "exclude_tools"
            ) || after_edit.get(key) == Some(value)
        })
        && after_edit.get("type").and_then(Value::as_str) == Some("clear_tool_uses_20250919")
        && typed_control(after_edit.get("trigger"), "input_tokens").is_ok()
        && typed_control(after_edit.get("keep"), "tool_uses").is_ok()
        && typed_control(after_edit.get("clear_at_least"), "input_tokens").is_ok()
}

fn is_compaction(body: &Value) -> bool {
    body.pointer("/context_management/compaction")
        .is_some_and(|v| v != &Value::Null && v != &Value::Bool(false))
        || body.get("is_compaction").and_then(Value::as_bool) == Some(true)
        || body
            .pointer("/context_management/edits")
            .and_then(Value::as_array)
            .is_some_and(|edits| {
                edits.iter().any(|edit| {
                    edit.get("type").and_then(Value::as_str) == Some("compact_20260112")
                })
            })
}

fn prefix_hash(body: &Value) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    body.get("model").hash(&mut hasher);
    body.get("tools").hash(&mut hasher);
    body.get("system").hash(&mut hasher);
    hasher.finish()
}

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

    #[test]
    fn effort_clamp_never_raises_and_only_changes_a_cold_session() {
        let sessions = InterventionSessions::default();
        let body = json!({"model":"claude-opus-4-8","output_config":{"effort":"high"},"system":[],"messages":[]});
        let params = OptimizeParams::EffortClamp(
            json!({"effort":"low","quality_floor":"medium"})
                .as_object()
                .unwrap()
                .clone(),
        );
        let applied = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        assert_eq!(applied.body["output_config"]["effort"], "medium");
        sessions.accepted(&applied, Instant::now());
        let warm = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        assert_eq!(warm.body["output_config"]["effort"], "medium");

        let lower = json!({"model":"claude-opus-4-8","output_config":{"effort":"low"},"system":[],"messages":[]});
        let warm_lower = sessions
            .apply(
                "s",
                &lower,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        assert_eq!(warm_lower.body["output_config"]["effort"], "low");
        assert!(!warm_lower.changed, "a lower caller effort is never raised");
    }

    #[test]
    fn prefix_guard_only_rewrites_the_last_existing_breakpoint() {
        let sessions = InterventionSessions::default();
        let body = json!({"system":[
            {"type":"text","text":"a","cache_control":{"type":"ephemeral"}},
            {"type":"text","text":"b"},
            {"type":"text","text":"c","cache_control":{"type":"ephemeral"}}
        ],"messages":[]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let applied = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                true,
                Instant::now(),
            )
            .unwrap();
        assert_eq!(applied.body["system"][0], body["system"][0]);
        assert_eq!(applied.body["system"][1], body["system"][1]);
        assert_eq!(
            applied.body["system"][2]["cache_control"],
            json!({"type":"ephemeral","ttl":"1h"})
        );
    }

    #[test]
    fn context_edit_is_monotone_and_protects_file_and_thinking_tools() {
        let sessions = InterventionSessions::default();
        let body = json!({
            "context_management":{"edits":[
                {"type":"clear_thinking_20251015","keep":{"type":"thinking_turns","value":2}},
                {"type":"clear_tool_uses_20250919","trigger":{"type":"input_tokens","value":100},"keep":{"type":"tool_uses","value":1},"clear_at_least":{"type":"input_tokens","value":20},"exclude_tools":["memory"]}
            ]},
            "messages":[
                {"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"Search","input":{}}]},
                {"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"x".repeat(4000)}]},
                {"role":"user","content":"tail"}
            ]
        });
        let params = OptimizeParams::ContextEdit(
            json!({"trigger":80,"keep":0,"clear_at_least":20,"exclude_tools":[]})
                .as_object()
                .unwrap()
                .clone(),
        );
        let applied = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        let edit = &applied.body["context_management"]["edits"][1];
        assert_eq!(edit["trigger"], json!({"type":"input_tokens","value":80}));
        assert_eq!(edit["keep"], json!({"type":"tool_uses","value":0}));
        assert_eq!(
            edit["clear_at_least"],
            json!({"type":"input_tokens","value":20})
        );
        let excluded = edit["exclude_tools"].as_array().unwrap();
        for protected in ["Edit", "Write", "Read", "memory"] {
            assert!(excluded.contains(&json!(protected)));
        }
        assert_eq!(
            applied.body["context_management"]["edits"][0],
            body["context_management"]["edits"][0]
        );
    }

    // ── Coverage added: risk-ranked gap fill ──────────────────────────
    //
    // The three tests above only walk the happy path of each lever. Every
    // actuator here mutates a live request to the model provider, so a wrong
    // turn is not a cosmetic bug — it either ships a request the customer
    // never asked for, or (more dangerous) it silently stops guarding
    // something (a "guarded"/"incapable" branch that should reject an input
    // but doesn't). What follows is deliberately organised around the guard
    // clauses themselves: each one is the difference between "forwards the
    // original bytes" and "forwards something else", which is the module's
    // whole reason to exist (`.claude/rules/model-relay.md`).

    fn effort_body(current: &str) -> Value {
        json!({"model":"claude-opus-4-8","output_config":{"effort":current},"system":[],"messages":[]})
    }

    fn ec_params(effort: &str, floor: &str) -> OptimizeParams {
        OptimizeParams::EffortClamp(
            json!({"effort":effort,"quality_floor":floor})
                .as_object()
                .unwrap()
                .clone(),
        )
    }

    fn context_edit_body(
        trigger: u64,
        keep: u64,
        clear_at_least: u64,
        exclude: &[&str],
        tool_result_len: usize,
    ) -> Value {
        json!({
            "context_management": {"edits": [
                {"type":"clear_tool_uses_20250919",
                 "trigger":{"type":"input_tokens","value":trigger},
                 "keep":{"type":"tool_uses","value":keep},
                 "clear_at_least":{"type":"input_tokens","value":clear_at_least},
                 "exclude_tools": exclude}
            ]},
            "messages": [
                {"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"Search","input":{}}]},
                {"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"x".repeat(tool_result_len)}]}
            ]
        })
    }

    /// `keep: 0, clear_at_least: 0` against [`context_edit_body`]'s single
    /// tool-result-as-last-message shape always nets positive (nothing is
    /// retained after the one removable block), so tests that need to reach
    /// PAST the net-positive guard — to exercise the deeper checks — use this.
    fn ce_params(trigger: u64, keep: u64, clear_at_least: u64, exclude: &[&str]) -> OptimizeParams {
        OptimizeParams::ContextEdit(
            json!({"trigger":trigger,"keep":keep,"clear_at_least":clear_at_least,"exclude_tools":exclude})
                .as_object()
                .unwrap()
                .clone(),
        )
    }

    fn ce_map(exclude: &[&str]) -> serde_json::Map<String, Value> {
        json!({"exclude_tools": exclude})
            .as_object()
            .unwrap()
            .clone()
    }

    // ── apply(): the dispatcher's own guards ──────────────────────────

    #[test]
    fn apply_is_incapable_for_a_lever_this_relay_does_not_yet_actuate() {
        let sessions = InterventionSessions::default();
        let params = OptimizeParams::LoopStop(serde_json::Map::new());
        let err = sessions
            .apply(
                "s",
                &json!({}),
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "incapable");
    }

    /// The capacity guard is about table GROWTH, not about refusing every
    /// session once full — an already-tracked session keeps being served.
    #[test]
    fn apply_guards_a_new_session_at_capacity_but_still_serves_a_known_one() {
        let sessions = InterventionSessions::default();
        let params = OptimizeParams::LoopStop(serde_json::Map::new());
        let now = Instant::now();
        for i in 0..1024 {
            let key = format!("k{i}");
            let _ = sessions.apply(&key, &json!({}), &params, BillingMode::ApiKey, false, now);
        }
        let err = sessions
            .apply(
                "brand-new",
                &json!({}),
                &params,
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap_err();
        assert_eq!(
            err, "guarded",
            "a new session must not grow the table past the cap"
        );

        let err2 = sessions
            .apply("k0", &json!({}), &params, BillingMode::ApiKey, false, now)
            .unwrap_err();
        assert_eq!(
            err2, "incapable",
            "an already-tracked session is still evaluated, just by the lever, not the cap"
        );
    }

    // ── effort_clamp guards ────────────────────────────────────────────

    #[test]
    fn effort_clamp_is_incapable_without_a_current_effort_to_read() {
        let sessions = InterventionSessions::default();
        let err = sessions
            .apply(
                "s",
                &json!({"model":"m"}),
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "incapable");
    }

    #[test]
    fn effort_clamp_is_guarded_without_the_requested_effort_param() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let params = OptimizeParams::EffortClamp(
            json!({"quality_floor":"low"}).as_object().unwrap().clone(),
        );
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn effort_clamp_is_guarded_without_the_quality_floor_param() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let params =
            OptimizeParams::EffortClamp(json!({"effort":"low"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn effort_clamp_is_guarded_on_an_unrecognised_rank_word() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let err = sessions
            .apply(
                "s",
                &body,
                &ec_params("ultra", "low"),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// The ratchet property: once a session is clamped, a LATER, STRONGER
    /// request on the same session must not reopen the ceiling. If this ever
    /// regresses to "always honour the latest request", a session could
    /// un-clamp itself simply by asking again.
    #[test]
    fn effort_clamp_never_lets_a_later_request_on_the_same_session_raise_the_ceiling() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let now = Instant::now();

        let first = sessions
            .apply(
                "s",
                &body,
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        assert_eq!(first.effort_ceiling.as_deref(), Some("low"));
        sessions.accepted(&first, now);

        let second = sessions
            .apply(
                "s",
                &body,
                &ec_params("max", "max"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        assert_eq!(
            second.effort_ceiling.as_deref(),
            Some("low"),
            "a warm session must not let a stronger request raise its ceiling"
        );
        assert_eq!(second.body["output_config"]["effort"], "low");
    }

    /// A compaction turn is treated as cold even on an otherwise-warm session
    /// — the ceiling is recomputed, not reused.
    #[test]
    fn effort_clamp_treats_a_compaction_turn_as_cold() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let now = Instant::now();

        let first = sessions
            .apply(
                "s",
                &body,
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        sessions.accepted(&first, now);

        let mut compaction_body = body.clone();
        compaction_body["is_compaction"] = json!(true);
        let second = sessions
            .apply(
                "s",
                &compaction_body,
                &ec_params("high", "high"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        assert_eq!(
            second.effort_ceiling.as_deref(),
            Some("high"),
            "a compaction turn must recompute the ceiling instead of reusing the cached one"
        );
    }

    /// A changed prefix (different model/tools/system) is also treated as
    /// cold, even within the TTL and on the same session key.
    #[test]
    fn effort_clamp_treats_a_changed_prefix_as_cold() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let now = Instant::now();

        let first = sessions
            .apply(
                "s",
                &body,
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        sessions.accepted(&first, now);

        let mut changed = body.clone();
        changed["system"] = json!([{"type":"text","text":"a new system prompt"}]);
        let second = sessions
            .apply(
                "s",
                &changed,
                &ec_params("high", "high"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        assert_eq!(second.effort_ceiling.as_deref(), Some("high"));
    }

    /// Past the cache TTL the session is cold again, even with an unchanged
    /// prefix and no compaction.
    #[test]
    fn effort_clamp_treats_ttl_expiry_as_cold() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let now = Instant::now();

        let first = sessions
            .apply(
                "s",
                &body,
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                now,
            )
            .unwrap();
        sessions.accepted(&first, now);

        let later = now + Duration::from_secs(60 * 60 + 1);
        let second = sessions
            .apply(
                "s",
                &body,
                &ec_params("high", "high"),
                BillingMode::ApiKey,
                false,
                later,
            )
            .unwrap();
        assert_eq!(second.effort_ceiling.as_deref(), Some("high"));
    }

    // ── context_edit guards ────────────────────────────────────────────

    #[test]
    fn context_edit_is_guarded_on_a_compaction_turn() {
        let sessions = InterventionSessions::default();
        let mut body = context_edit_body(100, 1, 20, &["memory"], 4000);
        body["is_compaction"] = json!(true);
        let err = sessions
            .apply(
                "s",
                &body,
                &ce_params(80, 0, 0, &[]),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn context_edit_is_incapable_without_context_management() {
        let sessions = InterventionSessions::default();
        let err = sessions
            .apply(
                "s",
                &json!({"messages": []}),
                &ce_params(80, 0, 0, &[]),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "incapable");
    }

    #[test]
    fn context_edit_is_incapable_without_a_clear_tool_uses_edit() {
        let sessions = InterventionSessions::default();
        let body = json!({
            "context_management": {"edits": [
                {"type":"clear_thinking_20251015","keep":{"type":"thinking_turns","value":2}}
            ]},
            "messages": []
        });
        let err = sessions
            .apply(
                "s",
                &body,
                &ce_params(80, 0, 0, &[]),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "incapable");
    }

    #[test]
    fn context_edit_is_guarded_on_a_missing_numeric_param() {
        let sessions = InterventionSessions::default();
        let body = context_edit_body(100, 1, 20, &["memory"], 4000);
        // No "trigger" key at all.
        let params = OptimizeParams::ContextEdit(
            json!({"keep":0,"clear_at_least":0,"exclude_tools":[]})
                .as_object()
                .unwrap()
                .clone(),
        );
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// Asking to keep more tool results than exist leaves nothing removable —
    /// the guard that stops the lever proposing an edit with no effect.
    #[test]
    fn context_edit_is_guarded_when_nothing_would_be_removed() {
        let sessions = InterventionSessions::default();
        let body = context_edit_body(100, 1, 20, &["memory"], 4000);
        let err = sessions
            .apply(
                "s",
                &body,
                &ce_params(80, 99, 20, &[]),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// A current edit whose stored fields do not carry the type tag this
    /// module expects is rejected rather than trusted — reading a
    /// platform-composed edit that turns out malformed must fail toward the
    /// original bytes, not guess.
    #[test]
    fn context_edit_is_guarded_on_a_malformed_current_edit() {
        let sessions = InterventionSessions::default();
        let body = json!({
            "context_management": {"edits": [
                {"type":"clear_tool_uses_20250919",
                 "trigger":{"type":"tokens","value":100},
                 "keep":{"type":"tool_uses","value":1},
                 "clear_at_least":{"type":"input_tokens","value":20},
                 "exclude_tools":["memory"]}
            ]},
            "messages": [
                {"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"Search","input":{}}]},
                {"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"x".repeat(4000)}]}
            ]
        });
        let err = sessions
            .apply(
                "s",
                &body,
                &ce_params(80, 0, 0, &[]),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// Once a proposed edit is rejected downstream, the identical edit must
    /// never be re-proposed for that session.
    #[test]
    fn a_rejected_context_edit_is_never_reproposed_for_the_same_session() {
        let sessions = InterventionSessions::default();
        let body = context_edit_body(100, 1, 20, &["memory"], 4000);
        let params = ce_params(80, 0, 0, &[]);

        let applied = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        sessions.rejected(&applied);

        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// An intervention with no context pair (effort_clamp) must not panic or
    /// register a phantom rejection when handed to `rejected`.
    #[test]
    fn rejected_is_a_noop_for_an_intervention_with_no_context_pair() {
        let sessions = InterventionSessions::default();
        let body = effort_body("high");
        let applied = sessions
            .apply(
                "s",
                &body,
                &ec_params("low", "low"),
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap();
        assert!(applied.context_pair.is_none());
        sessions.rejected(&applied);

        let second = sessions.apply(
            "s",
            &body,
            &ec_params("low", "low"),
            BillingMode::ApiKey,
            false,
            Instant::now(),
        );
        assert!(second.is_ok());
    }

    // ── prefix_guard guards ─────────────────────────────────────────────

    #[test]
    fn prefix_guard_is_guarded_for_a_non_api_key_caller() {
        let sessions = InterventionSessions::default();
        let body =
            json!({"system":[{"type":"text","text":"a","cache_control":{"type":"ephemeral"}}]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::Subscription,
                true,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn prefix_guard_is_guarded_when_no_churn_was_observed() {
        let sessions = InterventionSessions::default();
        let body =
            json!({"system":[{"type":"text","text":"a","cache_control":{"type":"ephemeral"}}]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                false,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn prefix_guard_is_guarded_on_a_non_default_pin_ttl() {
        let sessions = InterventionSessions::default();
        let body =
            json!({"system":[{"type":"text","text":"a","cache_control":{"type":"ephemeral"}}]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"5m"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                true,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    #[test]
    fn prefix_guard_is_incapable_without_a_system_array() {
        let sessions = InterventionSessions::default();
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &json!({}),
                &params,
                BillingMode::ApiKey,
                true,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "incapable");
    }

    #[test]
    fn prefix_guard_is_guarded_without_an_existing_cache_breakpoint() {
        let sessions = InterventionSessions::default();
        let body = json!({"system":[{"type":"text","text":"a"}]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                true,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    /// A breakpoint already pinned to the target shape is a no-op, and a
    /// no-op is guarded rather than reported as an applied change.
    #[test]
    fn prefix_guard_is_guarded_when_the_breakpoint_already_matches() {
        let sessions = InterventionSessions::default();
        let body = json!({"system":[
            {"type":"text","text":"a","cache_control":{"type":"ephemeral","ttl":"1h"}}
        ]});
        let params =
            OptimizeParams::PrefixGuard(json!({"pin_ttl":"1h"}).as_object().unwrap().clone());
        let err = sessions
            .apply(
                "s",
                &body,
                &params,
                BillingMode::ApiKey,
                true,
                Instant::now(),
            )
            .unwrap_err();
        assert_eq!(err, "guarded");
    }

    // ── Private helpers, tested directly ────────────────────────────────

    #[test]
    fn structural_validity_only_allows_the_deciding_edits_four_fields_to_change() {
        let original = json!({
            "context_management": {"edits": [
                {"type":"clear_tool_uses_20250919",
                 "trigger":{"type":"input_tokens","value":100},
                 "keep":{"type":"tool_uses","value":1},
                 "clear_at_least":{"type":"input_tokens","value":20},
                 "exclude_tools":["memory"]}
            ]},
            "messages": []
        });

        let mut valid_edit = original.clone();
        valid_edit["context_management"]["edits"][0]["trigger"] =
            json!({"type":"input_tokens","value":80});
        assert!(context_edit_is_structurally_valid(
            &original,
            &valid_edit,
            0
        ));

        // Changing a field outside the allowed set is rejected even though
        // the new value looks harmless.
        let mut invalid_edit = original.clone();
        invalid_edit["context_management"]["edits"][0]["type"] = json!("something_else");
        assert!(!context_edit_is_structurally_valid(
            &original,
            &invalid_edit,
            0
        ));

        // Touching any top-level key besides `context_management` is
        // rejected outright.
        let mut invalid_top = original.clone();
        invalid_top["messages"] = json!([{"role":"user","content":"hi"}]);
        assert!(!context_edit_is_structurally_valid(
            &original,
            &invalid_top,
            0
        ));
    }

    #[test]
    fn is_compaction_detects_all_three_shapes_and_only_those() {
        assert!(!is_compaction(&json!({})));
        assert!(is_compaction(&json!({"is_compaction": true})));
        assert!(!is_compaction(&json!({"is_compaction": false})));
        assert!(is_compaction(
            &json!({"context_management":{"compaction":true}})
        ));
        assert!(!is_compaction(
            &json!({"context_management":{"compaction":false}})
        ));
        assert!(is_compaction(&json!({
            "context_management":{"edits":[{"type":"compact_20260112"}]}
        })));
        assert!(!is_compaction(&json!({
            "context_management":{"edits":[{"type":"clear_tool_uses_20250919"}]}
        })));
    }

    #[test]
    fn prefix_hash_only_depends_on_model_tools_and_system() {
        let a = json!({"model":"m1","tools":[1],"system":[2],"messages":["ignored"]});
        let b = json!({"model":"m1","tools":[1],"system":[2],"messages":["a different tail"]});
        assert_eq!(prefix_hash(&a), prefix_hash(&b));

        let c = json!({"model":"m2","tools":[1],"system":[2],"messages":["ignored"]});
        assert_ne!(prefix_hash(&a), prefix_hash(&c));
    }

    #[test]
    fn number_and_typed_control_reject_the_wrong_shape() {
        let params = json!({"trigger": 5, "keep": "not-a-number"})
            .as_object()
            .unwrap()
            .clone();
        assert_eq!(number(&params, "trigger"), Ok(5));
        assert_eq!(number(&params, "keep"), Err("guarded"));
        assert_eq!(number(&params, "absent"), Err("guarded"));

        let good = json!({"type":"input_tokens","value":42});
        assert_eq!(typed_control(Some(&good), "input_tokens"), Ok(42));
        let wrong_type = json!({"type":"tool_uses","value":42});
        assert_eq!(
            typed_control(Some(&wrong_type), "input_tokens"),
            Err("guarded")
        );
        assert_eq!(typed_control(None, "input_tokens"), Err("guarded"));
    }

    #[test]
    fn net_positive_is_false_when_nothing_is_removable() {
        let body = context_edit_body(100, 1, 0, &[], 100);
        let params = ce_map(&[]);
        // `keep` (5) already covers the only eligible tool result.
        assert_eq!(context_edit_net_positive(&body, 5, 0, &params), Ok(false));
    }

    #[test]
    fn net_positive_is_false_when_the_gross_is_under_the_floor() {
        let body = context_edit_body(100, 1, 0, &[], 4);
        let params = ce_map(&[]);
        assert_eq!(
            context_edit_net_positive(&body, 0, 1_000_000, &params),
            Ok(false)
        );
    }

    #[test]
    fn net_positive_errors_on_a_tool_result_with_no_matching_tool_use() {
        let body = json!({
            "messages": [
                {"role":"user","content":[{"type":"tool_result","tool_use_id":"ghost","content":"x"}]}
            ]
        });
        let params = ce_map(&[]);
        assert_eq!(
            context_edit_net_positive(&body, 0, 0, &params),
            Err("guarded")
        );
    }

    #[test]
    fn net_positive_requires_the_exclude_tools_param_to_be_present() {
        let body = context_edit_body(100, 1, 0, &[], 100);
        let params = serde_json::Map::new();
        assert_eq!(
            context_edit_net_positive(&body, 0, 0, &params),
            Err("guarded")
        );
    }
}