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.

23.8 KB
Raw Blame
use std::collections::BTreeSet;

use hiroute_domain::{
    CanonicalDigest, CompiledPlanError, ComplexityBranch, ComplexityInputV1,
    ExactNativeReasoningV1, FreeFallbackPolicy, FreePoolMode, GatewayAuthenticationSemanticsV1,
    GatewayCriticalFactV1, GatewayOperationalTargetV1, MaterializedCostPolicyV1,
    MaterializedGroupId, MaterializedOrderingV1, RequestOwnedRouteV1, UpstreamProtocol,
};

use super::test_fixtures::*;
use super::*;

fn with_upstream_model_id(fact: &mut CandidateCompilationFactV1, id: &str) {
    fact.binding.upstream_model_id = id.to_owned();
    fact.capability.upstream_model_id = id.to_owned();
    fact.native_transport_model = id.to_owned();
    for profile in &mut fact.protocol_profiles {
        profile.capability.native_model = id.to_owned();
    }
}

#[test]
fn compiler_preserves_opaque_upstream_ids_in_every_materialized_protocol() {
    for id in [
        "内网模型".to_owned(),
        "vendor/模型:2026@alpha?revision#1".to_owned(),
        "Model A".to_owned(),
        "e\u{301}-模型".to_owned(),
        "\u{feff}模型\u{feff}".to_owned(),
        "\u{feff}".to_owned(),
        "模型🧠".to_owned(),
        "🧠".repeat(128),
        "x".repeat(512),
        "界".repeat(170) + "ab",
    ] {
        let mut facts = compilation_facts();
        let selected = facts
            .candidates
            .iter_mut()
            .find(|fact| fact.binding.binding_id == "binding/primary-b")
            .unwrap();
        with_upstream_model_id(selected, &id);
        selected.model.display_name = "中文显示名称".into();
        selected.binding.validate_shape().unwrap();
        facts.validate().unwrap();
        let materialized = materialize_agent_plan(&custom_desired(), &facts).unwrap();
        let candidate = &materialized.materialized.attempt_owned.groups[0].candidates[0];
        assert_eq!(candidate.binding_id, "binding/primary-b");
        assert_eq!(candidate.upstream_model_id, id);
        assert_eq!(candidate.native_transport_model, id);
        assert!(!candidate.protocol_profiles.is_empty());
        for profile in &candidate.protocol_profiles {
            assert_eq!(profile.capability.native_model, id);
        }
        materialized.materialized.validate().unwrap();
    }
}

#[test]
fn compiler_rejects_unsafe_upstream_ids_without_loosening_binding_identifiers() {
    for id in [
        String::new(),
        " 模型".into(),
        "模型\u{a0}".into(),
        "a\tb".into(),
        "a\0b".into(),
        "a\u{85}b".into(),
        "\u{85}模型".into(),
        "模型\u{85}".into(),
        "x".repeat(513),
        "界".repeat(171),
        "🧠".repeat(129),
    ] {
        let mut facts = compilation_facts();
        with_upstream_model_id(&mut facts.candidates[0], &id);
        assert!(facts.validate().is_err(), "accepted unsafe ID {id:?}");
    }
    let mut facts = compilation_facts();
    with_upstream_model_id(&mut facts.candidates[0], "内网模型");
    facts.candidates[0].binding.binding_id = "binding/内网模型".into();
    assert!(facts.validate().is_err());
}

#[test]
fn empty_options_snapshot_cannot_become_a_published_or_digested_plan() {
    let mut facts = compilation_facts();
    facts.candidates.clear();
    facts.refs.inventory_revision = 0;
    facts.validate_snapshot().unwrap();
    assert!(facts.refs.validate().is_err());
    assert_eq!(
        facts.validate(),
        Err(CompilerFactError::InvalidCandidateCount)
    );
    assert!(facts.digest().is_err());
    assert!(materialize_agent_plan(&custom_desired(), &facts).is_err());

    let mut nonempty = compilation_facts();
    nonempty.refs.inventory_revision = 0;
    assert_eq!(
        nonempty.validate_snapshot(),
        Err(CompilerFactError::InvalidCandidateCount)
    );
}

#[test]
fn compiler_smart_saving_materializes_two_deterministic_branches() {
    let desired = smart_desired();
    let facts = compilation_facts();
    assert!(
        facts
            .candidates
            .iter()
            .find(|candidate| candidate.binding.binding_id == "binding/economy-c")
            .unwrap()
            .ordering_price
            .is_none()
    );
    let result = materialize_agent_plan(&desired, &facts).unwrap();
    let groups = &result.materialized.attempt_owned.groups;
    assert_eq!(groups[0].group_id, MaterializedGroupId::Economy);
    assert!(matches!(
        &groups[0].ordering_evidence,
        MaterializedOrderingV1::CheapestWithRatingGuard {
            quality_anchor_binding_id,
            maximum_score_gap_tenths: 2,
        } if quality_anchor_binding_id == "binding/economy-a"
    ));
    assert_eq!(
        binding_order(&groups[0]),
        vec!["binding/economy-a", "binding/economy-c"]
    );
    assert_eq!(groups[1].group_id, MaterializedGroupId::Primary);
    assert_eq!(
        binding_order(&groups[1]),
        vec!["binding/primary-a", "binding/primary-b"]
    );
    assert!(matches!(
        groups[0].candidates[0].exact_reasoning,
        ExactNativeReasoningV1::Profile { ref profile, .. } if profile == "low"
    ));
    assert!(matches!(
        groups[1].candidates[0].exact_reasoning,
        ExactNativeReasoningV1::Profile { ref profile, .. } if profile == "high"
    ));
    let RequestOwnedRouteV1::Classified {
        classifier,
        reselect_on_user_message,
        simple_groups,
        complex_groups,
        ..
    } = &result.materialized.request_owned
    else {
        panic!("smart-saving request phase");
    };
    assert!(!reselect_on_user_message);
    assert_eq!(
        simple_groups,
        &[MaterializedGroupId::Economy, MaterializedGroupId::Primary]
    );
    assert_eq!(complex_groups, &[MaterializedGroupId::Primary]);
    let decision = classifier
        .classify(&ComplexityInputV1 {
            human_text: Some("please investigate 性能回归".into()),
            ..ComplexityInputV1::default()
        })
        .unwrap();
    assert_eq!(decision.branch, ComplexityBranch::Complex);
}

#[test]
fn compiler_economy_all_unknown_costs_fall_back_to_pinned_quality_order() {
    let desired = smart_desired();
    let mut facts = compilation_facts();
    for candidate in &mut facts.candidates {
        if candidate.binding.binding_id.starts_with("binding/economy-") {
            candidate.ordering_price = None;
        }
    }
    let result = materialize_agent_plan(&desired, &facts).unwrap();
    assert_eq!(
        binding_order(&result.materialized.attempt_owned.groups[0]),
        vec!["binding/economy-c", "binding/economy-a"]
    );
}

#[test]
fn compiler_accepts_release_seed_rating_with_zero_observation_count() {
    let desired = smart_desired();
    let mut facts = compilation_facts();
    facts
        .candidates
        .iter_mut()
        .find(|candidate| candidate.binding.binding_id == "binding/economy-c")
        .unwrap()
        .rating
        .as_mut()
        .unwrap()
        .rating_count = 0;
    let result = materialize_agent_plan(&desired, &facts).unwrap();
    assert_eq!(
        binding_order(&result.materialized.attempt_owned.groups[0]),
        vec!["binding/economy-a", "binding/economy-c"]
    );
}

#[test]
fn compiler_free_first_closes_strict_free_and_primary_fallback_separately() {
    let facts = compilation_facts();
    let strict =
        materialize_agent_plan(&free_desired(FreeFallbackPolicy::FreeOnly), &facts).unwrap();
    assert_eq!(strict.materialized.attempt_owned.groups.len(), 1);
    assert_eq!(
        binding_order(&strict.materialized.attempt_owned.groups[0]),
        vec!["binding/free-a", "binding/free-b"]
    );
    assert!(strict.excluded_candidates.iter().any(|value| {
        value.binding_id == "binding/free-toggle"
            && value.reason == CandidateExclusionReason::ReasoningSelectionRequired
    }));
    assert!(strict.excluded_candidates.iter().any(|value| {
        value.binding_id == "binding/free-budget"
            && value.reason == CandidateExclusionReason::ReasoningBudgetRequired
    }));
    let RequestOwnedRouteV1::Ordered {
        cost_policy,
        ordered_groups,
    } = &strict.materialized.request_owned
    else {
        panic!("free-first request phase");
    };
    assert_eq!(cost_policy, &MaterializedCostPolicyV1::StrictFree);
    assert_eq!(ordered_groups, &[MaterializedGroupId::Free]);

    let fallback =
        materialize_agent_plan(&free_desired(FreeFallbackPolicy::PrimaryFallback), &facts).unwrap();
    assert_eq!(fallback.materialized.attempt_owned.groups.len(), 2);
    assert_eq!(
        binding_order(&fallback.materialized.attempt_owned.groups[1]),
        vec!["binding/primary-a", "binding/primary-b"]
    );
}

#[test]
fn compiler_free_first_manual_preserves_order_and_empty_pool_fails_closed() {
    let facts = compilation_facts();
    let mut desired = free_desired(FreeFallbackPolicy::FreeOnly);
    {
        let hiroute_domain::AgentPlanStrategyV1::FreeFirst { free_pool, .. } =
            &mut desired.strategy
        else {
            unreachable!()
        };
        free_pool.mode = FreePoolMode::Manual;
        free_pool.candidates = vec![
            hiroute_domain::CandidateSelectionV1 {
                binding_id: "binding/free-b".into(),
                reasoning: None,
            },
            hiroute_domain::CandidateSelectionV1 {
                binding_id: "binding/free-a".into(),
                reasoning: Some(hiroute_domain::ReasoningSelectionV1::Profile {
                    profile: "low".into(),
                }),
            },
        ];
    }
    let manual = materialize_agent_plan(&desired, &facts).unwrap();
    assert_eq!(
        binding_order(&manual.materialized.attempt_owned.groups[0]),
        vec!["binding/free-b", "binding/free-a"]
    );

    let hiroute_domain::AgentPlanStrategyV1::FreeFirst { free_pool, .. } = &mut desired.strategy
    else {
        unreachable!()
    };
    free_pool.candidates.clear();
    assert_eq!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::NoFreeCandidates
    );
}

#[test]
fn compiler_free_first_automatic_accepts_exact_toggle_and_budget_choices() {
    let facts = compilation_facts();
    let mut desired = free_desired(FreeFallbackPolicy::FreeOnly);
    let hiroute_domain::AgentPlanStrategyV1::FreeFirst { free_pool, .. } = &mut desired.strategy
    else {
        unreachable!()
    };
    free_pool.automatic_reasoning.insert(
        "binding/free-toggle".into(),
        hiroute_domain::ReasoningSelectionV1::Toggle { enabled: true },
    );
    free_pool.automatic_reasoning.insert(
        "binding/free-budget".into(),
        hiroute_domain::ReasoningSelectionV1::Budget { tokens: 1_024 },
    );
    let result = materialize_agent_plan(&desired, &facts).unwrap();
    assert_eq!(
        binding_order(&result.materialized.attempt_owned.groups[0]),
        vec![
            "binding/free-a",
            "binding/free-toggle",
            "binding/free-budget",
            "binding/free-b",
        ]
    );
    assert!(result.excluded_candidates.iter().all(|candidate| {
        candidate.binding_id != "binding/free-toggle"
            && candidate.binding_id != "binding/free-budget"
    }));
}

#[test]
fn compiler_custom_preserves_only_the_explicit_candidate_order() {
    let result = materialize_agent_plan(&custom_desired(), &compilation_facts()).unwrap();
    assert_eq!(
        binding_order(&result.materialized.attempt_owned.groups[0]),
        vec!["binding/primary-b", "binding/primary-a"]
    );
}

#[test]
fn compiler_preserves_exact_ordered_credential_refs_and_rejects_duplicates() {
    let mut facts = compilation_facts();
    let selected = facts
        .candidates
        .iter_mut()
        .find(|candidate| candidate.binding.binding_id == "binding/primary-b")
        .unwrap();
    selected.credential_refs = vec!["credential/key-a".into(), "credential/key-b".into()];
    let compiled = materialize_agent_plan(&custom_desired(), &facts).unwrap();
    let candidate = &compiled.materialized.attempt_owned.groups[0].candidates[0];
    assert_eq!(
        candidate.credential_refs,
        ["credential/key-a", "credential/key-b"]
    );

    let mut duplicate = facts;
    duplicate
        .candidates
        .iter_mut()
        .find(|candidate| candidate.binding.binding_id == "binding/primary-b")
        .unwrap()
        .credential_refs = vec!["credential/key-a".into(), "credential/key-a".into()];
    assert!(matches!(
        materialize_agent_plan(&custom_desired(), &duplicate),
        Err(AgentPlanCompilerError::Facts(
            CompilerFactError::CrossReference
        ))
    ));
}

#[test]
fn compiler_unknown_fact_revision_and_unqualified_capability_fail_closed() {
    let desired = smart_desired();
    let mut facts = compilation_facts();
    facts.compiler_revision = "agent-plan-compiler/v3".into();
    assert!(matches!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::Facts(CompilerFactError::UnsupportedCompilerRevision)
    ));

    let mut facts = compilation_facts();
    facts
        .candidates
        .iter_mut()
        .find(|value| value.binding.binding_id == "binding/primary-a")
        .unwrap()
        .model
        .capabilities
        .tool = false;
    assert_eq!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::CapabilityUnqualified("binding/primary-a".into())
    );

    let mut facts = compilation_facts();
    facts.candidates[0].protocol_endpoint.adapter_ref = "adapter.untrusted".into();
    assert!(matches!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::Facts(CompilerFactError::CrossReference)
    ));

    let mut facts = compilation_facts();
    facts.candidates[0].credential_refs.clear();
    assert!(matches!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::Facts(CompilerFactError::CrossReference)
    ));

    let mut facts = compilation_facts();
    facts.candidates[0].protocol_profiles[0]
        .capability
        .native_model = "drifted-native-model".into();
    assert_eq!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::InvalidCompiledPlan
    );

    let mut facts = compilation_facts();
    facts.candidates[0].protocol_profiles.clear();
    assert!(matches!(
        materialize_agent_plan(&desired, &facts).unwrap_err(),
        AgentPlanCompilerError::Facts(CompilerFactError::CrossReference)
    ));
}

#[test]
fn compiler_compiled_revision_is_immutable_and_unknown_compiler_revision_is_rejected() {
    let mut publication = compiled_publication(11);
    let plan = &mut publication.plans[0];
    std::sync::Arc::make_mut(&mut plan.body).agent_plan_revision += 1;
    assert_eq!(
        plan.validate().unwrap_err(),
        CompiledPlanError::DigestMismatch
    );

    let mut publication = compiled_publication(11);
    let plan = &mut publication.plans[0];
    assert_eq!(
        plan.body.compiler_revision,
        hiroute_domain::AGENT_PLAN_COMPILER_REVISION_V3
    );
    std::sync::Arc::make_mut(&mut plan.body).compiler_revision =
        "unsupported-compiler-revision".into();
    assert_eq!(
        plan.validate().unwrap_err(),
        CompiledPlanError::UnsupportedCompilerRevision
    );
}

#[test]
fn compiler_publication_verifier_rejects_reordered_materialized_candidates() {
    let mut publication = compiled_publication(11);
    let plan = publication
        .plans
        .iter_mut()
        .find(|plan| plan.agent_plan_id().as_str() == "plan/smart")
        .unwrap();
    let primary = std::sync::Arc::make_mut(&mut plan.body)
        .materialized
        .attempt_owned
        .groups
        .iter_mut()
        .find(|group| group.group_id == MaterializedGroupId::Primary)
        .unwrap();
    primary.candidates.swap(0, 1);
    assert_eq!(
        plan.validate().unwrap_err(),
        CompiledPlanError::MaterializedRouteDigestMismatch
    );
}

#[test]
fn compiler_retired_alias_is_tombstoned_and_cannot_be_reallocated() {
    let publication = compiled_publication(11);
    let retired_id = publication.plans[0].agent_plan_id().clone();
    let retired_alias = publication.plans[0].model_alias().clone();
    let mut registry = publication.alias_registry.clone();
    assert_eq!(registry.retire(&retired_id).unwrap(), retired_alias);
    assert!(registry.tombstones.contains(&retired_alias));
    assert!(registry.allocate(retired_id).is_err());

    let remaining = publication
        .plans
        .iter()
        .filter(|plan| plan.model_alias() != &retired_alias)
        .cloned()
        .collect::<Vec<_>>();
    let grants = publication_grants(&remaining);
    let next = compile_publication(
        hiroute_domain::WorkspaceId::default(),
        "workspace/personal/default/gateway",
        1,
        hiroute_domain::GatewayPublicationRevision::new(12).unwrap(),
        hiroute_domain::DEFAULT_CATALOG_RENDERER_REVISION,
        registry,
        remaining,
        grants,
    )
    .unwrap();
    assert!(next.alias_registry.tombstones.contains(&retired_alias));
    for alias in &next.aliases {
        assert_eq!(
            Some(alias),
            publication
                .aliases
                .iter()
                .find(|previous| previous.served_model_id == alias.served_model_id)
        );
    }
}

#[test]
fn compiler_equivalent_fact_order_produces_identical_preview_digest() {
    let desired = smart_desired();
    let mut first = compilation_facts();
    let first_digest = first.digest().unwrap();
    first.candidates.reverse();
    assert_eq!(first.digest().unwrap(), first_digest);
    let first_plan = materialize_agent_plan(&desired, &first).unwrap();
    let second_plan = materialize_agent_plan(&desired, &compilation_facts()).unwrap();
    assert_eq!(first_plan, second_plan);
}

#[test]
fn compiler_materialized_route_digest_excludes_price_provenance_when_order_is_unchanged() {
    let desired = smart_desired();
    let first = materialize_agent_plan(&desired, &compilation_facts())
        .unwrap()
        .materialized;
    let mut changed = compilation_facts();
    changed.ordering_price_version = "prices.v2".into();
    changed.ordering_price_digest = hiroute_domain::CanonicalDigest::of_bytes(b"prices-v2");
    for fact in &mut changed.candidates {
        if let Some(price) = &mut fact.ordering_price {
            price.price_rate_revision += 1;
            price.input_micros_per_million += 1_000;
            price.output_micros_per_million += 1_000;
            price.frozen_digest = hiroute_domain::CanonicalDigest::of_bytes(
                format!("{}-v2", price.price_rate_id).as_bytes(),
            );
        }
    }
    let second = materialize_agent_plan(&desired, &changed)
        .unwrap()
        .materialized;
    assert_eq!(first, second);
    assert_eq!(
        first.legacy_route_digest().unwrap(),
        second.legacy_route_digest().unwrap()
    );
}

#[test]
fn compiler_publication_is_a_closed_g0_authority_projection() {
    let publication = compiled_publication(11);
    assert_eq!(
        publication.schema,
        hiroute_domain::GATEWAY_PUBLICATION_SCHEMA_V3
    );
    publication.validate_current_contract().unwrap();
    assert_eq!(
        publication.authority_id,
        "workspace/personal/default/gateway"
    );
    assert_eq!(publication.authority_epoch, 1);
    assert_eq!(
        publication.catalog_renderer_revision,
        hiroute_domain::DEFAULT_CATALOG_RENDERER_REVISION
    );
    assert_eq!(publication.plans.len(), publication.aliases.len());
    assert_eq!(publication.grants.len(), 2);

    let snapshot = publication.gateway_snapshot().unwrap();
    assert_eq!(
        snapshot.schema_version,
        hiroute_domain::GATEWAY_SNAPSHOT_SCHEMA_V3
    );
    assert_eq!(
        snapshot.canonical_digest().unwrap().as_str(),
        snapshot.payload_digest
    );
    let local_ids = snapshot
        .aliases
        .iter()
        .flat_map(|alias| alias.candidates.iter().map(|candidate| candidate.local_id))
        .collect::<Vec<_>>();
    assert!(local_ids.iter().all(|local_id| *local_id > 0));
    assert_eq!(
        local_ids.iter().copied().collect::<BTreeSet<_>>().len(),
        local_ids.len()
    );
    for candidate in snapshot.aliases.iter().flat_map(|alias| &alias.candidates) {
        assert!(candidate.endpoint.starts_with("https://"));
        assert!(candidate.adapter_id.ends_with("@1"));
        assert!(!candidate.credential_refs.is_empty());
        assert!(
            candidate
                .credential_destination_ref
                .starts_with("connection-option/")
        );
        assert!(matches!(
            candidate.operational_target,
            GatewayOperationalTargetV1::RegisteredHttps { ref uri } if uri == &candidate.endpoint
        ));
        assert_eq!(
            CanonicalDigest::of(&candidate.operational_target).unwrap(),
            candidate.operational_target_digest
        );
        assert_eq!(
            CanonicalDigest::of(&candidate.protocol_profiles).unwrap(),
            candidate.protocol_profile_digest
        );
        assert!(candidate.protocol_profiles.iter().all(|profile| {
            profile.capability.native_model == candidate.native_transport_model
                && candidate.upstream_model_id == candidate.native_transport_model
                && profile.connector.request_path == "/v1/responses"
                && profile.connector.authentication
                    == GatewayCriticalFactV1::Exact(GatewayAuthenticationSemanticsV1::Bearer)
                && profile.capability.upstream_protocol == UpstreamProtocol::Responses
        }));
    }

    let smart_alias = publication
        .plans
        .iter()
        .find(|plan| plan.agent_plan_id().as_str() == "plan/smart")
        .unwrap()
        .model_alias();
    let grants_for_smart = snapshot
        .grants
        .iter()
        .filter(|grant| {
            matches!(grant.routes.get(smart_alias.as_str()),
            Some(hiroute_domain::GatewayModelRouteV2::Plan { alias, .. }) if alias == smart_alias)
        })
        .collect::<Vec<_>>();
    assert_eq!(grants_for_smart.len(), 2);
    assert_ne!(
        grants_for_smart[0].bearer_token_sha256,
        grants_for_smart[1].bearer_token_sha256
    );
    assert_ne!(grants_for_smart[0].protocol, grants_for_smart[1].protocol);
}

#[test]
fn compiler_publication_bytes_are_current_deterministic_and_secret_free() {
    let first = compiled_publication(11);
    let second = compiled_publication(11);
    let bytes = first.canonical_bytes().unwrap();
    assert_eq!(bytes, second.canonical_bytes().unwrap());
    assert_eq!(first.digest().unwrap(), second.digest().unwrap());
    let lowercase = String::from_utf8(bytes.clone()).unwrap().to_lowercase();
    assert!(lowercase.contains("\"mode\":{\"kind\":\"local_rules\"}"));
    assert!(!lowercase.contains("\"smart_saving\""));
    assert!(!lowercase.contains("\"free_first\""));
    assert!(!lowercase.contains("ordering_price_version"));
    assert!(!lowercase.contains("price_rate_id"));
    assert!(lowercase.contains("\"bearer_token_sha256\""));
    assert!(!lowercase.contains("\"catalog_renderer_revision\""));
    assert!(lowercase.contains("\"credential_refs\""));
    assert!(lowercase.contains("\"endpoint\""));
    assert!(!lowercase.contains("\"authorization\":"));
    for forbidden in [
        "api_key_value",
        "api_key_secret",
        "codex-grant-verifier",
        "claude-grant-verifier",
        "endpoint_url",
        "secret",
        "rating_service",
        "price_service",
    ] {
        assert!(
            !lowercase.contains(forbidden),
            "forbidden field {forbidden}"
        );
    }

    let restored = hiroute_domain::GatewayPublicationV1::decode(&bytes).unwrap();
    assert_eq!(restored.canonical_bytes().unwrap(), bytes);
    assert_eq!(
        hiroute_domain::StoredPublicationV1::freeze(&restored).unwrap(),
        hiroute_domain::StoredPublicationV1::freeze(&first).unwrap()
    );
}

fn binding_order(group: &hiroute_domain::MaterializedModelGroupV1) -> Vec<&str> {
    group
        .candidates
        .iter()
        .map(|candidate| candidate.binding_id.as_str())
        .collect()
}