Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

34.9 KB
Raw Blame
use std::collections::{BTreeMap, BTreeSet};
use std::sync::Arc;

use serde::{Deserialize, Serialize};
use thiserror::Error;

use crate::{
    AgentPlanId, AgentPlanIdentityV1, BillingClass, CanonicalDigest, ConnectorRuntimeKind,
    ExactNativeReasoningV1, FreeAccess, GatewayAuthenticationSemanticsV1, GatewayCriticalFactV1,
    ModelAlias, UpstreamProtocol,
};

use super::gateway_execution::{GatewayCandidateProtocolProfileV1, GatewayOperationalTargetV1};
use super::{
    AGENT_PLAN_COMPILED_SCHEMA_V1, AGENT_PLAN_COMPILED_SCHEMA_V3, AGENT_PLAN_COMPILER_REVISION_V1,
    AGENT_PLAN_COMPILER_REVISION_V3, ComplexityClassifierV1, RoutingLimitsV1,
};

const LEGACY_MATERIALIZED_ROUTE_DIGEST_SCHEMA_V1: &str = "hiroute.materialized-route-digest/v1";

#[cfg(test)]
thread_local! {
    pub(crate) static CANDIDATE_VALIDATIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

#[derive(
    schemars::JsonSchema,
    Clone,
    Copy,
    Debug,
    Deserialize,
    Eq,
    Hash,
    Ord,
    PartialEq,
    PartialOrd,
    Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum MaterializedGroupId {
    Economy,
    Primary,
    Free,
    Custom,
    Branch(u16),
    BranchPrimary(u16),
}

impl MaterializedGroupId {
    pub fn as_name(self) -> String {
        match self {
            Self::Economy => "economy".into(),
            Self::Primary => "primary".into(),
            Self::Free => "free".into(),
            Self::Custom => "custom".into(),
            Self::Branch(index) => format!("branch_{index}"),
            Self::BranchPrimary(index) => format!("branch_primary_{index}"),
        }
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MaterializedBranchV1 {
    pub id: String,
    pub name: String,
    pub condition: String,
    pub group: MaterializedGroupId,
    pub primary_group: Option<MaterializedGroupId>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub judgment: Option<super::JudgmentSettingsV1>,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "strategy", rename_all = "snake_case", deny_unknown_fields)]
pub enum RequestOwnedRouteV1 {
    Branches {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        native_protocol: Option<super::FrozenNativeProtocolV1>,
        classifier: ComplexityClassifierV1,
        branches: Vec<MaterializedBranchV1>,
        default_branch_id: String,
        reselect_on_user_message: bool,
    },
    Classified {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        native_protocol: Option<super::FrozenNativeProtocolV1>,
        classifier: ComplexityClassifierV1,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        judgment: Option<super::JudgmentSettingsV1>,
        reselect_on_user_message: bool,
        simple_groups: Vec<MaterializedGroupId>,
        complex_groups: Vec<MaterializedGroupId>,
    },
    Ordered {
        cost_policy: MaterializedCostPolicyV1,
        ordered_groups: Vec<MaterializedGroupId>,
    },
}

#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MaterializedCostPolicyV1 {
    ApiEquivalent,
    StrictFree,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum MaterializedOrderingV1 {
    QualityFirst,
    CheapestWithRatingGuard {
        quality_anchor_binding_id: String,
        maximum_score_gap_tenths: u8,
    },
    FreeScoreDescending,
    ExplicitOrder,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MaterializedModelGroupV1 {
    pub group_id: MaterializedGroupId,
    /// Evidence for how Application materialized this array. Runtime must not execute it as a
    /// sorting policy; `candidates` is already the final immutable order.
    pub ordering_evidence: MaterializedOrderingV1,
    /// Exact pinned ratings used for quality provenance and guard validation. Runtime consumes
    /// `candidates` as-is; it never folds these facts into a new score or re-sorts the array.
    #[serde(default)]
    pub pinned_ratings: BTreeMap<String, MaterializedRatingFactV1>,
    pub candidates: Vec<AttemptOwnedCandidateV1>,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MaterializedRatingFactV1 {
    pub model_configuration_id: String,
    pub overall_score_tenths: u8,
    pub rating_count: u64,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MaterializedFreeOfferRefV1 {
    pub free_offer_id: String,
    pub free_offer_revision: u64,
    pub offer_ref: String,
    pub access: FreeAccess,
    pub evidence_digest: CanonicalDigest,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AttemptOwnedCandidateV1 {
    pub binding_id: String,
    pub binding_revision: u64,
    pub binding_digest: CanonicalDigest,
    pub source_id: String,
    pub source_revision: u64,
    pub source_identity_digest: CanonicalDigest,
    pub connection_option_id: String,
    pub offer_ref: String,
    pub offer_revision: u64,
    pub offer_evidence_digest: CanonicalDigest,
    pub billing_class: BillingClass,
    pub model_configuration_id: String,
    pub model_configuration_revision: u64,
    pub upstream_model_id: String,
    /// Exact model identifier written to the operational connector request.
    /// Managed CPA targets may use an account-scoped alias that intentionally
    /// differs from the catalog-bound logical `upstream_model_id`.
    pub native_transport_model: String,
    pub capability_id: String,
    pub capability_revision: u64,
    pub capability_evidence_digest: CanonicalDigest,
    pub connector_id: String,
    pub connector_revision: u64,
    pub endpoint_profile_id: String,
    pub endpoint_profile_revision: u64,
    pub protocol_endpoint_id: String,
    /// Exact registered destination. Runtime may resolve DNS only after grant and alias checks;
    /// it must never reconstruct this value from an EndpointProfile or another store.
    pub endpoint: String,
    pub connector_runtime: ConnectorRuntimeKind,
    pub operational_target: GatewayOperationalTargetV1,
    pub operational_target_digest: CanonicalDigest,
    pub protocol_profiles: Vec<GatewayCandidateProtocolProfileV1>,
    pub protocol_profile_digest: CanonicalDigest,
    pub upstream_protocol: UpstreamProtocol,
    pub adapter_ref: String,
    pub adapter_revision: u64,
    /// Frozen order of stable, non-secret selectors understood by CredentialResolver. Credential
    /// material and store locators are intentionally absent from the publication.
    pub credential_refs: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub credential_destination_ref: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub credential_pool_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub free_offer: Option<MaterializedFreeOfferRefV1>,
    pub exact_reasoning: ExactNativeReasoningV1,
}

impl AttemptOwnedCandidateV1 {
    pub fn validate(&self) -> Result<(), CompiledPlanError> {
        #[cfg(test)]
        CANDIDATE_VALIDATIONS.with(|count| count.set(count.get() + 1));
        for value in [
            &self.binding_id,
            &self.source_id,
            &self.connection_option_id,
            &self.offer_ref,
            &self.model_configuration_id,
            &self.capability_id,
            &self.connector_id,
            &self.endpoint_profile_id,
            &self.protocol_endpoint_id,
            &self.adapter_ref,
        ] {
            if !super::strategy::valid_reference(value) {
                return Err(CompiledPlanError::InvalidCandidate);
            }
        }
        if !crate::valid_upstream_model_id(&self.upstream_model_id)
            || !crate::valid_upstream_model_id(&self.native_transport_model)
            || self.binding_revision == 0
            || self.source_revision == 0
            || self.offer_revision == 0
            || self.model_configuration_revision == 0
            || self.capability_revision == 0
            || self.connector_revision == 0
            || self.endpoint_profile_revision == 0
            || self.adapter_revision == 0
            || self.billing_class == BillingClass::Unknown
            || !self
                .operational_target
                .validate_for(self.connector_runtime, &self.endpoint)
            || !matches!(
                CanonicalDigest::of(&self.operational_target),
                Ok(digest) if digest == self.operational_target_digest
            )
            || !matches!(
                CanonicalDigest::of(&self.protocol_profiles),
                Ok(digest) if digest == self.protocol_profile_digest
            )
            || self.protocol_profiles.is_empty()
            || (self.connector_runtime == ConnectorRuntimeKind::BuiltinNative
                && self.native_transport_model != self.upstream_model_id)
            || invalid_digest(&self.binding_digest)
            || invalid_digest(&self.source_identity_digest)
            || invalid_digest(&self.offer_evidence_digest)
            || invalid_digest(&self.capability_evidence_digest)
            || self.credential_refs.is_empty()
            || self.credential_refs.len() > 64
            || self
                .credential_refs
                .iter()
                .any(|value| !super::strategy::valid_reference(value))
            || self.credential_refs.iter().collect::<BTreeSet<_>>().len()
                != self.credential_refs.len()
            || self
                .credential_destination_ref
                .as_deref()
                .is_some_and(|value| {
                    !value.starts_with("compute-target/")
                        || !super::strategy::valid_reference(value)
                })
            || self
                .credential_pool_id
                .as_deref()
                .is_some_and(|value| !super::strategy::valid_reference(value))
        {
            return Err(CompiledPlanError::InvalidCandidate);
        }
        let mut ingress_protocols = BTreeSet::new();
        for profile in &self.protocol_profiles {
            if !ingress_protocols.insert(profile.ingress_protocol) {
                return Err(CompiledPlanError::InvalidCandidate);
            }
            profile.validate_for_candidate(self)?;
        }
        let requires_credential = self.protocol_profiles.iter().any(|profile| {
            !matches!(
                profile.connector.authentication,
                GatewayCriticalFactV1::Exact(GatewayAuthenticationSemanticsV1::None)
            )
        });
        if requires_credential
            && self.billing_class != BillingClass::Free
            && self.credential_pool_id.is_none()
        {
            return Err(CompiledPlanError::InvalidCandidate);
        }
        match (&self.free_offer, self.billing_class) {
            (Some(free), BillingClass::Free) => {
                if !super::strategy::valid_reference(&free.free_offer_id)
                    || free.free_offer_revision == 0
                    || free.offer_ref != self.offer_ref
                    || invalid_digest(&free.evidence_digest)
                    || (free.access == FreeAccess::ApiKeyRequired
                        && self.credential_pool_id.is_none())
                {
                    return Err(CompiledPlanError::InvalidCandidate);
                }
            }
            (None, BillingClass::Free) | (Some(_), _) => {
                return Err(CompiledPlanError::InvalidCandidate);
            }
            (None, _) => {}
        }
        self.exact_reasoning
            .validate()
            .map_err(|_| CompiledPlanError::InvalidReasoning)
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AttemptOwnedRouteV1 {
    pub limits: RoutingLimitsV1,
    pub groups: Vec<MaterializedModelGroupV1>,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PriceTrackingMode {
    FollowLatest,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentPlanFactRefsV1 {
    pub connector_registry_version: String,
    pub connector_registry_digest: CanonicalDigest,
    pub model_data_bundle_version: String,
    pub model_data_digest: CanonicalDigest,
    pub capability_slice_version: String,
    pub capability_slice_digest: CanonicalDigest,
    pub ratings_slice_version: String,
    pub ratings_slice_digest: CanonicalDigest,
    pub free_offers_slice_version: String,
    pub free_offers_slice_digest: CanonicalDigest,
    pub inventory_revision: u64,
    pub inventory_digest: CanonicalDigest,
    pub price_tracking: PriceTrackingMode,
}

impl AgentPlanFactRefsV1 {
    pub fn validate(&self) -> Result<(), CompiledPlanError> {
        if self.inventory_revision == 0 {
            return Err(CompiledPlanError::InvalidFactReference);
        }
        self.validate_snapshot()
    }

    /// An empty read-only inventory has revision zero; published facts still require a revision.
    pub fn validate_snapshot(&self) -> Result<(), CompiledPlanError> {
        for value in [
            &self.connector_registry_version,
            &self.model_data_bundle_version,
            &self.capability_slice_version,
            &self.ratings_slice_version,
            &self.free_offers_slice_version,
        ] {
            if !super::strategy::valid_reference(value) {
                return Err(CompiledPlanError::InvalidFactReference);
            }
        }
        if [
            &self.connector_registry_digest,
            &self.model_data_digest,
            &self.capability_slice_digest,
            &self.ratings_slice_digest,
            &self.free_offers_slice_digest,
            &self.inventory_digest,
        ]
        .into_iter()
        .any(invalid_digest)
        {
            Err(CompiledPlanError::InvalidFactReference)
        } else {
            Ok(())
        }
    }

    /// Price-only changes are consumed by the next Turn's value ledger. They do not mutate an
    /// ACTIVE AgentPlan or independently request a replan.
    pub fn replan_reasons(&self, newer: &Self) -> Vec<ReplanReason> {
        let mut reasons = BTreeSet::new();
        if self.connector_registry_digest != newer.connector_registry_digest {
            reasons.insert(ReplanReason::ConnectorRegistryChanged);
        }
        if self.model_data_digest != newer.model_data_digest {
            reasons.insert(ReplanReason::ModelDataChanged);
        }
        if self.capability_slice_digest != newer.capability_slice_digest {
            reasons.insert(ReplanReason::CapabilityChanged);
        }
        if self.ratings_slice_digest != newer.ratings_slice_digest {
            reasons.insert(ReplanReason::RatingChanged);
        }
        if self.free_offers_slice_digest != newer.free_offers_slice_digest {
            reasons.insert(ReplanReason::FreeOfferChanged);
        }
        if self.inventory_digest != newer.inventory_digest {
            reasons.insert(ReplanReason::InventoryChanged);
        }
        reasons.into_iter().collect()
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ReplanReason {
    ConnectorRegistryChanged,
    ModelDataChanged,
    CapabilityChanged,
    RatingChanged,
    FreeOfferChanged,
    InventoryChanged,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MaterializedAgentPlanV1 {
    pub fact_refs: AgentPlanFactRefsV1,
    pub request_owned: RequestOwnedRouteV1,
    pub attempt_owned: AttemptOwnedRouteV1,
}

impl MaterializedAgentPlanV1 {
    pub fn validate(&self) -> Result<(), CompiledPlanError> {
        self.fact_refs.validate()?;
        self.attempt_owned
            .limits
            .validate()
            .map_err(|_| CompiledPlanError::InvalidLimits)?;
        if self.attempt_owned.groups.is_empty() || self.attempt_owned.groups.len() > 32 {
            return Err(CompiledPlanError::InvalidGroups);
        }
        let mut groups = BTreeMap::new();
        for group in &self.attempt_owned.groups {
            if group.candidates.is_empty()
                || group.candidates.len() > 128
                || groups.insert(group.group_id, group).is_some()
            {
                return Err(CompiledPlanError::InvalidGroups);
            }
            let mut bindings = BTreeSet::new();
            for candidate in &group.candidates {
                candidate.validate()?;
                if !bindings.insert(&candidate.binding_id) {
                    return Err(CompiledPlanError::DuplicateCandidate);
                }
            }
            super::ordering::validate_ordering_facts(group)?;
        }
        if self.attempt_owned.limits.context_window_tokens.is_some() {
            self.context_window_tokens()?;
        }
        validate_request_groups(&self.request_owned, &groups)
    }

    /// V2 freezes only selected executable inputs. Advisory catalog snapshots remain audit
    /// provenance, so a rating/price/new-offer refresh cannot silently change a saved route.
    pub fn route_digest(&self) -> Result<CanonicalDigest, CompiledPlanError> {
        self.validate()?;
        self.route_digest_for_sealing()
    }

    /// Calculates the frozen-fact hash without claiming validation. A newly assembled
    /// stored Plan passes full validation in seal_current before receiving its proof.
    pub(super) fn route_digest_for_sealing(&self) -> Result<CanonicalDigest, CompiledPlanError> {
        if self.attempt_owned.groups.iter().any(|group| {
            group.ordering_evidence != MaterializedOrderingV1::ExplicitOrder
                || !group.pinned_ratings.is_empty()
        }) {
            return Err(CompiledPlanError::InvalidOrderingFacts);
        }
        let groups = self
            .attempt_owned
            .groups
            .iter()
            .map(|g| {
                Ok(super::StoredGroupV1 {
                    group_id: g.group_id,
                    ordering_evidence: g.ordering_evidence.clone(),
                    pinned_ratings: g.pinned_ratings.clone(),
                    candidates: g
                        .candidates
                        .iter()
                        .map(super::StoredCandidateV1::freeze_validated)
                        .collect::<Result<_, _>>()?,
                })
            })
            .collect::<Result<Vec<_>, CompiledPlanError>>()?;
        CanonicalDigest::of(&(
            super::STABLE_ROUTE_SCHEMA,
            &self.request_owned,
            &self.attempt_owned.limits,
            groups,
        ))
        .map_err(|_| CompiledPlanError::Encoding)
    }

    /// Digests executable Plan semantics. Display metadata is excluded; the already-materialized
    /// candidate order and pinned rating/capability/free facts remain part of the digest. Exact
    /// price inputs stay compiler-only because runtime price tracking is follow-latest.
    pub fn legacy_route_digest(&self) -> Result<CanonicalDigest, CompiledPlanError> {
        self.validate()?;
        CanonicalDigest::of(&MaterializedRouteDigestInputV1 {
            schema: LEGACY_MATERIALIZED_ROUTE_DIGEST_SCHEMA_V1,
            connector_registry_version: &self.fact_refs.connector_registry_version,
            connector_registry_digest: &self.fact_refs.connector_registry_digest,
            model_data_bundle_version: &self.fact_refs.model_data_bundle_version,
            model_data_digest: &self.fact_refs.model_data_digest,
            capability_slice_version: &self.fact_refs.capability_slice_version,
            capability_slice_digest: &self.fact_refs.capability_slice_digest,
            ratings_slice_version: &self.fact_refs.ratings_slice_version,
            ratings_slice_digest: &self.fact_refs.ratings_slice_digest,
            free_offers_slice_version: &self.fact_refs.free_offers_slice_version,
            free_offers_slice_digest: &self.fact_refs.free_offers_slice_digest,
            inventory_revision: self.fact_refs.inventory_revision,
            inventory_digest: &self.fact_refs.inventory_digest,
            price_tracking: &self.fact_refs.price_tracking,
            request_owned: &self.request_owned,
            attempt_owned: &self.attempt_owned,
        })
        .map_err(|_| CompiledPlanError::Encoding)
    }
}

#[derive(Serialize)]
struct MaterializedRouteDigestInputV1<'a> {
    schema: &'static str,
    connector_registry_version: &'a str,
    connector_registry_digest: &'a CanonicalDigest,
    model_data_bundle_version: &'a str,
    model_data_digest: &'a CanonicalDigest,
    capability_slice_version: &'a str,
    capability_slice_digest: &'a CanonicalDigest,
    ratings_slice_version: &'a str,
    ratings_slice_digest: &'a CanonicalDigest,
    free_offers_slice_version: &'a str,
    free_offers_slice_digest: &'a CanonicalDigest,
    inventory_revision: u64,
    inventory_digest: &'a CanonicalDigest,
    price_tracking: &'a PriceTrackingMode,
    request_owned: &'a RequestOwnedRouteV1,
    attempt_owned: &'a AttemptOwnedRouteV1,
}

fn validate_request_groups(
    request: &RequestOwnedRouteV1,
    groups: &BTreeMap<MaterializedGroupId, &MaterializedModelGroupV1>,
) -> Result<(), CompiledPlanError> {
    let exact = |ids: &[MaterializedGroupId]| {
        ids.iter().all(|id| groups.contains_key(id))
            && ids.iter().copied().collect::<BTreeSet<_>>().len() == ids.len()
    };
    match request {
        RequestOwnedRouteV1::Branches {
            native_protocol,
            classifier,
            branches,
            default_branch_id,
            ..
        } => {
            if let Some(p) = native_protocol {
                p.validate_branches(branches, default_branch_id)
                    .map_err(CompiledPlanError::NativeProtocol)?;
                if !super::native_mode(&classifier.mode) {
                    return Err(CompiledPlanError::InvalidClassifier);
                }
            }
            classifier
                .validate()
                .map_err(|_| CompiledPlanError::InvalidClassifier)?;
            let ids: BTreeSet<_> = branches.iter().map(|b| &b.id).collect();
            let used: BTreeSet<_> = branches
                .iter()
                .flat_map(|b| [Some(b.group), b.primary_group])
                .flatten()
                .collect();
            if !(2..=16).contains(&branches.len())
                || ids.len() != branches.len()
                || !ids.contains(default_branch_id)
                || used != groups.keys().copied().collect()
                || branches.iter().any(|b| {
                    !super::valid_task_category_id(&b.id)
                        || b.name.trim().is_empty()
                        || b.condition.trim().is_empty()
                        || b.name.len() > 512
                        || if classifier.mode.extension_identity().is_some() {
                            b.judgment.is_some()
                        } else {
                            b.judgment.as_ref().is_none_or(|j| !j.validate())
                        }
                })
            {
                return Err(CompiledPlanError::InvalidGroups);
            }
            Ok(())
        }
        RequestOwnedRouteV1::Classified {
            native_protocol,
            classifier,
            judgment,
            simple_groups,
            complex_groups,
            ..
        } => {
            if let Some(p) = native_protocol {
                p.validate_smart(
                    judgment
                        .as_ref()
                        .ok_or(CompiledPlanError::InvalidClassifier)?,
                )
                .map_err(CompiledPlanError::NativeProtocol)?;
                if !super::native_mode(&classifier.mode) {
                    return Err(CompiledPlanError::InvalidClassifier);
                }
            }
            classifier
                .validate()
                .map_err(|_| CompiledPlanError::InvalidClassifier)?;
            if (if classifier.mode.extension_identity().is_some() {
                judgment.is_some()
            } else {
                judgment.as_ref().is_none_or(|j| !j.validate())
            }) || (simple_groups.as_slice() != [MaterializedGroupId::Economy]
                && simple_groups.as_slice()
                    != [MaterializedGroupId::Economy, MaterializedGroupId::Primary])
                || complex_groups.as_slice() != [MaterializedGroupId::Primary]
                || groups.keys().copied().collect::<BTreeSet<_>>()
                    != BTreeSet::from([MaterializedGroupId::Economy, MaterializedGroupId::Primary])
            {
                return Err(CompiledPlanError::InvalidGroups);
            }
            Ok(())
        }
        RequestOwnedRouteV1::Ordered {
            cost_policy,
            ordered_groups,
        } => {
            if !exact(ordered_groups) || groups.len() != ordered_groups.len() {
                return Err(CompiledPlanError::InvalidGroups);
            }
            match (cost_policy, ordered_groups.as_slice()) {
                (MaterializedCostPolicyV1::StrictFree, [MaterializedGroupId::Free])
                | (
                    MaterializedCostPolicyV1::ApiEquivalent,
                    [MaterializedGroupId::Free, MaterializedGroupId::Primary],
                ) => {
                    if groups[&MaterializedGroupId::Free]
                        .candidates
                        .iter()
                        .any(|candidate| candidate.billing_class != BillingClass::Free)
                    {
                        Err(CompiledPlanError::StrictFreeViolation)
                    } else {
                        Ok(())
                    }
                }
                (MaterializedCostPolicyV1::ApiEquivalent, [MaterializedGroupId::Custom]) => Ok(()),
                _ => Err(CompiledPlanError::InvalidGroups),
            }
        }
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CompiledAgentPlanBodyV1 {
    pub schema: String,
    pub compiler_revision: String,
    pub identity: AgentPlanIdentityV1,
    pub agent_plan_revision: u64,
    pub materialized_route_digest: CanonicalDigest,
    pub materialized: MaterializedAgentPlanV1,
}

/// A sealed body is shared immutably. Copy-on-write edits detach from the proof and must
/// pass full validation again; deserialization never imports an in-memory proof.
#[derive(schemars::JsonSchema, Clone, Debug, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CompiledAgentPlanV1 {
    #[serde(serialize_with = "crate::operation::shared_input::serialize")]
    pub body: Arc<CompiledAgentPlanBodyV1>,
    pub digest: CanonicalDigest,
    #[serde(skip)]
    verified_body: Arc<CompiledAgentPlanBodyV1>,
    #[serde(skip)]
    verified_digest: CanonicalDigest,
}

impl PartialEq for CompiledAgentPlanV1 {
    fn eq(&self, other: &Self) -> bool {
        self.body == other.body && self.digest == other.digest
    }
}
impl Eq for CompiledAgentPlanV1 {}

impl<'de> Deserialize<'de> for CompiledAgentPlanV1 {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Encoded {
            body: CompiledAgentPlanBodyV1,
            digest: CanonicalDigest,
        }
        let encoded = Encoded::deserialize(deserializer)?;
        Self::authenticate_persisted(encoded.body, encoded.digest).map_err(serde::de::Error::custom)
    }
}

impl CompiledAgentPlanV1 {
    /// Seals the sole live compiled-plan contract. Historical bodies must enter through the
    /// authenticated persisted-record reader and are converted before any new publication write.
    pub fn seal_current(body: CompiledAgentPlanBodyV1) -> Result<Self, CompiledPlanError> {
        if body.schema != AGENT_PLAN_COMPILED_SCHEMA_V3 {
            return Err(CompiledPlanError::UnsupportedSchema);
        }
        Self::seal_compatible(body)
    }

    /// Authenticates an already-persisted record without minting a replacement legacy digest.
    pub fn authenticate_persisted(
        body: CompiledAgentPlanBodyV1,
        digest: CanonicalDigest,
    ) -> Result<Self, CompiledPlanError> {
        validate_body(&body)?;
        if CanonicalDigest::of(&body).map_err(|_| CompiledPlanError::Encoding)? != digest {
            return Err(CompiledPlanError::DigestMismatch);
        }
        Ok(Self::from_validated(body, digest))
    }

    fn seal_compatible(body: CompiledAgentPlanBodyV1) -> Result<Self, CompiledPlanError> {
        validate_body(&body)?;
        let digest = CanonicalDigest::of(&body).map_err(|_| CompiledPlanError::Encoding)?;
        Ok(Self::from_validated(body, digest))
    }

    fn from_validated(body: CompiledAgentPlanBodyV1, digest: CanonicalDigest) -> Self {
        let body = Arc::new(body);
        Self {
            verified_body: body.clone(),
            verified_digest: digest.clone(),
            body,
            digest,
        }
    }

    pub fn validate(&self) -> Result<(), CompiledPlanError> {
        if Arc::ptr_eq(&self.body, &self.verified_body) && self.digest == self.verified_digest {
            return Ok(());
        }
        validate_body(&self.body)?;
        let digest =
            CanonicalDigest::of(self.body.as_ref()).map_err(|_| CompiledPlanError::Encoding)?;
        if digest != self.digest {
            return Err(CompiledPlanError::DigestMismatch);
        }
        Ok(())
    }

    /// Converts an authenticated pre-v2 compiled plan without changing its executable arrays.
    /// The old ordering evidence is audit provenance; v2 records the already-frozen array as the
    /// explicit order and computes the one current route digest.
    pub fn into_current(mut self) -> Result<Self, CompiledPlanError> {
        self.validate()?;
        if self.body.schema == AGENT_PLAN_COMPILED_SCHEMA_V3 {
            return Ok(self);
        }
        let body = Arc::make_mut(&mut self.body);
        for group in &mut body.materialized.attempt_owned.groups {
            group.ordering_evidence = MaterializedOrderingV1::ExplicitOrder;
            group.pinned_ratings.clear();
        }
        body.schema = AGENT_PLAN_COMPILED_SCHEMA_V3.to_owned();
        body.compiler_revision = AGENT_PLAN_COMPILER_REVISION_V3.to_owned();
        body.materialized_route_digest = body.materialized.route_digest()?;
        Self::seal_current((*self.body).clone())
    }

    pub fn agent_plan_id(&self) -> &AgentPlanId {
        &self.body.identity.agent_plan_id
    }

    pub fn model_alias(&self) -> &ModelAlias {
        &self.body.identity.model_alias
    }
}

fn validate_body(body: &CompiledAgentPlanBodyV1) -> Result<(), CompiledPlanError> {
    let expected_revision = match body.schema.as_str() {
        AGENT_PLAN_COMPILED_SCHEMA_V1 => AGENT_PLAN_COMPILER_REVISION_V1,
        AGENT_PLAN_COMPILED_SCHEMA_V3 => AGENT_PLAN_COMPILER_REVISION_V3,
        _ => return Err(CompiledPlanError::UnsupportedSchema),
    };
    if body.compiler_revision != expected_revision {
        return Err(CompiledPlanError::UnsupportedCompilerRevision);
    }
    body.identity
        .validate()
        .map_err(|_| CompiledPlanError::InvalidIdentity)?;
    if body.agent_plan_revision == 0 {
        return Err(CompiledPlanError::InvalidIdentity);
    }
    // Both digest methods fully validate the borrowed materialized route.
    let route_digest = if body.schema == AGENT_PLAN_COMPILED_SCHEMA_V3 {
        body.materialized.route_digest()?
    } else {
        body.materialized.legacy_route_digest()?
    };
    if route_digest != body.materialized_route_digest {
        return Err(CompiledPlanError::MaterializedRouteDigestMismatch);
    }
    Ok(())
}

fn invalid_digest(value: &CanonicalDigest) -> bool {
    value == &CanonicalDigest::of_bytes(&[])
        || !matches!(CanonicalDigest::parse(value.as_str()), Ok(parsed) if &parsed == value)
}

#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum CompiledPlanError {
    #[error(transparent)]
    NativeProtocol(super::NativeProtocolError),
    #[error("compiled AgentPlan schema is unsupported")]
    UnsupportedSchema,
    #[error("compiled AgentPlan compiler revision is unsupported")]
    UnsupportedCompilerRevision,
    #[error("compiled AgentPlan identity or revision is invalid")]
    InvalidIdentity,
    #[error("compiled AgentPlan fact reference is invalid")]
    InvalidFactReference,
    #[error("compiled AgentPlan request groups are not closed")]
    InvalidGroups,
    #[error("compiled AgentPlan contains a duplicate candidate")]
    DuplicateCandidate,
    #[error("compiled AgentPlan candidate is not closed")]
    InvalidCandidate,
    #[error("compiled AgentPlan exact reasoning is invalid")]
    InvalidReasoning,
    #[error("compiled AgentPlan ordering facts do not justify the materialized order")]
    InvalidOrderingFacts,
    #[error("compiled AgentPlan limits are invalid")]
    InvalidLimits,
    #[error("compiled AgentPlan classifier is invalid")]
    InvalidClassifier,
    #[error("strict-free compiled route contains a non-free attempt")]
    StrictFreeViolation,
    #[error("compiled AgentPlan canonical encoding failed")]
    Encoding,
    #[error("compiled AgentPlan digest does not match its body")]
    DigestMismatch,
    #[error("compiled AgentPlan materialized route digest does not match executable semantics")]
    MaterializedRouteDigestMismatch,
}

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

    fn refs() -> AgentPlanFactRefsV1 {
        AgentPlanFactRefsV1 {
            connector_registry_version: "registry.v1".into(),
            connector_registry_digest: CanonicalDigest::of_bytes(b"registry"),
            model_data_bundle_version: "model-data.v1".into(),
            model_data_digest: CanonicalDigest::of_bytes(b"model-data"),
            capability_slice_version: "capabilities.v1".into(),
            capability_slice_digest: CanonicalDigest::of_bytes(b"capabilities"),
            ratings_slice_version: "ratings.v1".into(),
            ratings_slice_digest: CanonicalDigest::of_bytes(b"ratings"),
            free_offers_slice_version: "free.v1".into(),
            free_offers_slice_digest: CanonicalDigest::of_bytes(b"free"),
            inventory_revision: 1,
            inventory_digest: CanonicalDigest::of_bytes(b"inventory"),
            price_tracking: PriceTrackingMode::FollowLatest,
        }
    }

    #[test]
    fn routing_price_only_change_does_not_request_replan() {
        let current = refs();
        let mut newer = current.clone();
        assert!(current.replan_reasons(&newer).is_empty());
        newer.ratings_slice_digest = CanonicalDigest::of_bytes(b"ratings-2");
        assert_eq!(
            current.replan_reasons(&newer),
            vec![ReplanReason::RatingChanged]
        );
    }
}