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.

37.1 KB
Raw Blame
//! Closed aggregate publication consumed by the Gateway boundary.
//!
//! It is the only persistent request authority; adapters may project it but may not join mutable
//! Registry, AgentConnection, or credential storage state.

use std::collections::{BTreeMap, BTreeSet};

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

use crate::{
    AGENT_PLAN_COMPILED_SCHEMA_V3, AGENT_PLAN_COMPILER_REVISION_V1,
    AGENT_PLAN_COMPILER_REVISION_V3, AgentIngressProtocolV1, AliasRegistryV1,
    AttemptOwnedCandidateV1, CanonicalDigest, CompiledAgentPlanV1, ConnectorRuntimeKind,
    GatewayAccessGrantV1, GatewayCandidateProtocolProfileV1, GatewayOperationalTargetV1,
    MaterializedGroupId, ModelAlias, PortResult, PublishedAgentPlanV1, RequestOwnedRouteV1,
    UpstreamProtocol, WorkspaceId,
};

mod plan_state;
mod projection;
mod record;
mod stored;
pub use record::PublicationRecordV1;
pub use stored::*;
mod snapshot;
#[cfg(test)]
mod validation_tests;
pub use plan_state::GATEWAY_PUBLICATION_SCHEMA_V3;
use projection::*;
pub use snapshot::{
    GatewayAdmissionStateV1, GatewayModelRouteV2, GatewayProjectedGrantV2,
    GatewayPublicationSnapshotProjectionV3,
};

pub(crate) const LEGACY_GATEWAY_PUBLICATION_SCHEMA_V2: &str = "hiroute.gateway-publication/v2";
#[cfg(test)]
const UNSUPPORTED_GATEWAY_PUBLICATION_SCHEMA_V1: &str = "hiroute.gateway-publication/v1";
pub const GATEWAY_SNAPSHOT_SCHEMA_V3: &str = "hiroute.gateway.publication-snapshot/v3";
pub const DEFAULT_CATALOG_RENDERER_REVISION: &str = "hiroute.gateway-catalog-renderer/v1";
const MAX_REQUEST_ATTEMPTS: u16 = 6;
const MAX_LOGICAL_REQUEST_DURATION_MS: u64 = 60 * 60 * 1_000;

#[derive(
    schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(transparent)]
pub struct GatewayPublicationRevision(u64);

impl GatewayPublicationRevision {
    pub fn new(value: u64) -> Result<Self, PublicationError> {
        if value == 0 {
            Err(PublicationError::InvalidRevision)
        } else {
            Ok(Self(value))
        }
    }

    pub const fn get(self) -> u64 {
        self.0
    }
}

/// Exact G0 candidate fields with aggregate-global deterministic `local_id` allocation.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayExecutableCandidateV2 {
    pub local_id: u32,
    pub stable_target_key: String,
    /// Original source membership, independent of a branch's reasoning-specific execution key.
    /// Derived from the stored Plan; absent on unchanged legacy/fixed projections.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_binding_id: Option<String>,
    /// Derived only in the executable projection; omitted in retained Product bytes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub billing_class: Option<crate::BillingClass>,
    pub adapter_id: String,
    pub credential_refs: Vec<String>,
    /// Exact Secret authority destination derived from the current connection option.
    pub credential_destination_ref: String,
    /// Current Registry model identity.
    pub upstream_model_id: String,
    /// Exact model identifier rendered on the operational transport.
    pub native_transport_model: String,
    /// Current Registry identity; never rewritten to the loopback transport target.
    /// Its Provider path may differ from a managed bridge's local request path.
    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,
    /// Non-secret actual-price lookup identity. Product publications keep the
    /// full source facts in their compiled Plans; `gateway_snapshot` adds this
    /// narrow projection without changing the durable Product record.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pricing_identity: Option<GatewayCandidatePricingIdentityV1>,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayCandidatePricingIdentityV1 {
    pub source_id: String,
    pub source_identity_digest: CanonicalDigest,
    pub model_configuration_id: String,
    pub actual_offer_ref: String,
}

/// Exact request-owned route and group membership projected to the Gateway.
/// Candidate ordering is already frozen by the Application compiler; the
/// Gateway may filter for request capability but must not reconstruct groups.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayExecutableGroupV2 {
    pub group_id: MaterializedGroupId,
    pub candidate_local_ids: Vec<u32>,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayExecutableRoutingV2 {
    pub agent_plan_id: String,
    /// Safe plan display text frozen into new publications; absent on legacy snapshots.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub plan_display_name: Option<String>,
    pub request_owned: RequestOwnedRouteV1,
    pub groups: Vec<GatewayExecutableGroupV2>,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayExecutableAliasV2 {
    pub served_model_id: ModelAlias,
    pub purpose: String,
    pub agent_plan_revision: u64,
    pub protocols: Vec<AgentIngressProtocolV1>,
    pub overall_timeout_ms: u64,
    pub max_attempts: u32,
    /// Request-owned routing metadata was added after the first G0 publication revision. `None`
    /// remains readable only so an already-durable publication can be upgraded by the next
    /// Application-owned publish; newly materialized aliases always carry the closed projection.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub routing: Option<GatewayExecutableRoutingV2>,
    pub candidates: Vec<GatewayExecutableCandidateV2>,
}

/// G0-compatible, non-secret grant projection derived from an exact AgentConnection Plan grant.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayExecutableGrantV2 {
    pub grant_id: String,
    pub generation: u64,
    pub bearer_token_sha256: CanonicalDigest,
    pub model_grant: crate::AgentModelGrantV2,
}

impl GatewayExecutableGrantV2 {
    pub fn permits_plan(&self, alias: &ModelAlias) -> bool {
        matches!(self.model_grant.routes.get(alias.as_str()), Some(crate::AgentModelRouteV2::Plan { alias: permitted, .. }) if permitted == alias)
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GatewayPublicationV1 {
    pub schema: String,
    pub compiler_revision: String,
    pub workspace_id: WorkspaceId,
    pub authority_id: String,
    pub authority_epoch: u64,
    pub publication_revision: GatewayPublicationRevision,
    pub catalog_renderer_revision: String,
    pub alias_registry: AliasRegistryV1,
    pub plans: Vec<CompiledAgentPlanV1>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub plan_heads: Vec<crate::PlanHeadV1>,
    pub aliases: Vec<GatewayExecutableAliasV2>,
    pub grants: Vec<GatewayExecutableGrantV2>,
}

impl GatewayPublicationV1 {
    /// Creates an empty durable bootstrap record. Executable publications must use `seal`.
    pub fn new(
        workspace_id: WorkspaceId,
        publication_revision: GatewayPublicationRevision,
        alias_registry: AliasRegistryV1,
        plans: Vec<CompiledAgentPlanV1>,
    ) -> Result<Self, PublicationError> {
        if !plans.is_empty() {
            return Err(PublicationError::PublicationNotClosed);
        }
        let authority_id = workspace_id.as_str().to_owned();
        Self::from_parts(
            workspace_id,
            authority_id,
            1,
            publication_revision,
            DEFAULT_CATALOG_RENDERER_REVISION.to_owned(),
            alias_registry,
            plans,
            Vec::new(),
        )
    }

    #[allow(clippy::too_many_arguments)]
    pub fn seal(
        workspace_id: WorkspaceId,
        authority_id: impl Into<String>,
        authority_epoch: u64,
        publication_revision: GatewayPublicationRevision,
        catalog_renderer_revision: impl Into<String>,
        alias_registry: AliasRegistryV1,
        mut plans: Vec<CompiledAgentPlanV1>,
        access_grants: Vec<GatewayAccessGrantV1>,
    ) -> Result<Self, PublicationError> {
        plans.sort_by(|left, right| left.agent_plan_id().cmp(right.agent_plan_id()));
        let grants = materialize_grants(access_grants)?;
        Self::from_parts(
            workspace_id,
            authority_id.into(),
            authority_epoch,
            publication_revision,
            catalog_renderer_revision.into(),
            alias_registry,
            plans,
            grants,
        )
    }

    /// Produces the next publication after creating or revising one independent AgentPlan.
    ///
    /// A Plan may exist before any AgentConnection grants it. Such a catalog-only publication
    /// is durable but deliberately cannot be projected into a Gateway request authority. Adding
    /// a matching grant later makes only the granted aliases executable.
    pub fn next_with_plan(
        &self,
        publication_revision: GatewayPublicationRevision,
        alias_registry: AliasRegistryV1,
        plan: CompiledAgentPlanV1,
    ) -> Result<Self, PublicationError> {
        self.validate()?;
        let mut plans = self
            .plans
            .iter()
            .filter(|current| current.agent_plan_id() != plan.agent_plan_id())
            .cloned()
            .collect::<Vec<_>>();
        plans.push(
            plan.into_current()
                .map_err(|_| PublicationError::InvalidPlan)?,
        );
        plans.sort_by(|left, right| left.agent_plan_id().cmp(right.agent_plan_id()));
        Self::from_parts(
            self.workspace_id.clone(),
            self.authority_id.clone(),
            self.authority_epoch,
            publication_revision,
            self.catalog_renderer_revision.clone(),
            alias_registry,
            plans,
            self.grants.clone(),
        )?
        .preserve_heads(self)
    }

    /// Produces the next closed request authority after ensuring one AgentConnection grant.
    pub fn next_with_access_grant(
        &self,
        publication_revision: GatewayPublicationRevision,
        access_grant: GatewayAccessGrantV1,
    ) -> Result<Self, PublicationError> {
        self.validate()?;
        let replacement = materialize_grants(vec![access_grant])?
            .pop()
            .ok_or(PublicationError::InvalidGrant)?;
        let mut grants = self
            .grants
            .iter()
            .filter(|current| current.grant_id != replacement.grant_id)
            .cloned()
            .collect::<Vec<_>>();
        grants.push(replacement);
        grants.sort_by(|left, right| left.grant_id.cmp(&right.grant_id));
        Self::from_parts(
            self.workspace_id.clone(),
            self.authority_id.clone(),
            self.authority_epoch,
            publication_revision,
            self.catalog_renderer_revision.clone(),
            self.alias_registry.clone(),
            self.plans.clone(),
            grants,
        )?
        .preserve_heads(self)
    }

    /// Produces the next closed publication after revoking one exact AgentConnection grant.
    /// Plans remain independently published; removing the last grant therefore yields a durable,
    /// deliberately non-executable plan-only publication.
    pub fn next_without_access_grant(
        &self,
        publication_revision: GatewayPublicationRevision,
        grant_id: &str,
    ) -> Result<Self, PublicationError> {
        self.validate()?;
        let grants = self
            .grants
            .iter()
            .filter(|current| current.grant_id != grant_id)
            .cloned()
            .collect::<Vec<_>>();
        if grants.len() == self.grants.len() {
            return Err(PublicationError::InvalidGrant);
        }
        Self::from_parts(
            self.workspace_id.clone(),
            self.authority_id.clone(),
            self.authority_epoch,
            publication_revision,
            self.catalog_renderer_revision.clone(),
            self.alias_registry.clone(),
            self.plans.clone(),
            grants,
        )?
        .preserve_heads(self)
    }

    #[allow(clippy::too_many_arguments)]
    fn from_parts(
        workspace_id: WorkspaceId,
        authority_id: String,
        authority_epoch: u64,
        publication_revision: GatewayPublicationRevision,
        catalog_renderer_revision: String,
        alias_registry: AliasRegistryV1,
        plans: Vec<CompiledAgentPlanV1>,
        grants: Vec<GatewayExecutableGrantV2>,
    ) -> Result<Self, PublicationError> {
        let plans = plans
            .into_iter()
            .map(|plan| {
                plan.into_current()
                    .map_err(|_| PublicationError::InvalidPlan)
            })
            .collect::<Result<Vec<_>, _>>()?;
        // Sealing upgrades pre-v2 Plans to the current compiler contract; every grant route
        // bound to such a Plan follows the upgraded digest so a sealed publication is always
        // internally consistent.
        let grants = grants
            .into_iter()
            .map(|grant| rebind_current_grant_routes(grant, &plans))
            .collect::<Result<Vec<_>, _>>()?;
        let aliases = materialize_aliases(&plans, &grants)?;
        let value = Self {
            schema: GATEWAY_PUBLICATION_SCHEMA_V3.to_owned(),
            compiler_revision: AGENT_PLAN_COMPILER_REVISION_V3.to_owned(),
            workspace_id,
            authority_id,
            authority_epoch,
            publication_revision,
            catalog_renderer_revision,
            alias_registry,
            plans,
            plan_heads: Vec::new(),
            aliases,
            grants,
        };
        value.validate()?;
        Ok(value)
    }

    pub fn validate(&self) -> Result<(), PublicationError> {
        if self.schema != LEGACY_GATEWAY_PUBLICATION_SCHEMA_V2
            && self.schema != GATEWAY_PUBLICATION_SCHEMA_V3
        {
            return Err(PublicationError::UnsupportedSchema);
        }
        let current_contract = self.schema == GATEWAY_PUBLICATION_SCHEMA_V3
            && self.compiler_revision == AGENT_PLAN_COMPILER_REVISION_V3
            && self
                .plans
                .iter()
                .all(|plan| plan.body.schema == AGENT_PLAN_COMPILED_SCHEMA_V3);
        // Preserve the separately registered unversioned publication recovery boundary.
        let persisted_compatibility = matches!(
            self.compiler_revision.as_str(),
            AGENT_PLAN_COMPILER_REVISION_V1
        ) && self.plans.iter().all(|plan| {
            matches!(
                plan.body.schema.as_str(),
                crate::AGENT_PLAN_COMPILED_SCHEMA_V1 | AGENT_PLAN_COMPILED_SCHEMA_V3
            )
        });
        if !current_contract && !persisted_compatibility {
            return Err(PublicationError::UnsupportedCompilerRevision);
        }
        WorkspaceId::parse(self.workspace_id.as_str())
            .map_err(|_| PublicationError::InvalidWorkspace)?;
        GatewayPublicationRevision::new(self.publication_revision.get())?;
        if !valid_reference(&self.authority_id)
            || self.authority_epoch == 0
            || !valid_reference(&self.catalog_renderer_revision)
        {
            return Err(PublicationError::InvalidAuthority);
        }
        self.alias_registry
            .validate()
            .map_err(|_| PublicationError::InvalidAliasRegistry)?;

        let mut plan_ids = BTreeSet::new();
        let mut aliases = BTreeSet::new();
        let mut previous = None;
        for plan in &self.plans {
            plan.validate().map_err(|_| PublicationError::InvalidPlan)?;
            if previous.is_some_and(|value| value >= plan.agent_plan_id())
                || !plan_ids.insert(plan.agent_plan_id())
                || !aliases.insert(plan.model_alias())
                || self.alias_registry.alias_for(plan.agent_plan_id()) != Some(plan.model_alias())
            {
                return Err(PublicationError::InvalidPlanSet);
            }
            previous = Some(plan.agent_plan_id());
        }
        if self.alias_registry.active.len() != self.plans.len()
            || self
                .alias_registry
                .active
                .keys()
                .any(|plan_id| !plan_ids.contains(plan_id))
        {
            return Err(PublicationError::PublicationNotClosed);
        }

        self.validate_plan_heads()?;
        validate_grants(&self.grants, &aliases)?;
        // Independent Plans may be saved before an Agent grants them. Only aliases reached by at
        // least one grant are executable; the Gateway projection remains closed over that subset.
        let enabled_grants = self.enabled_grants()?;
        let mut expected_aliases = materialize_aliases(&self.plans, &enabled_grants)?;
        // Older aggregates omit source membership on every execution projection.
        // Authenticate their complete old projection before rebuilding from Plans.
        if self.aliases.iter().all(|alias| {
            alias
                .candidates
                .iter()
                .all(|candidate| candidate.source_binding_id.is_none())
        }) {
            for candidate in expected_aliases
                .iter_mut()
                .flat_map(|alias| &mut alias.candidates)
            {
                candidate.source_binding_id = None;
            }
        }
        if expected_aliases != self.aliases {
            // Publications written after request-owned routing but before the safe Plan display
            // name was frozen remain exact legacy records. The next Application-owned publish
            // deterministically upgrades every active alias.
            let mut legacy_named_aliases = expected_aliases.clone();
            for alias in &mut legacy_named_aliases {
                if let Some(routing) = &mut alias.routing {
                    routing.plan_display_name = None;
                }
            }
            if legacy_named_aliases == self.aliases {
                return Ok(());
            }
            // Publications emitted before request-owned routing became part of the executable
            // alias remain valid exact records. Accept only the complete legacy projection (all
            // routing fields absent and every other field identical); the next publication
            // deterministically upgrades it to the closed routing projection.
            let mut legacy_aliases = legacy_named_aliases;
            for alias in &mut legacy_aliases {
                alias.routing = None;
            }
            if self.aliases.iter().any(|alias| alias.routing.is_some())
                || legacy_aliases != self.aliases
            {
                return Err(PublicationError::InvalidExecutableProjection);
            }
        }
        Ok(())
    }

    pub fn validate_current_contract(&self) -> Result<(), PublicationError> {
        self.validate()?;
        self.check_current_schema()
    }

    fn check_current_schema(&self) -> Result<(), PublicationError> {
        if self.schema != GATEWAY_PUBLICATION_SCHEMA_V3
            || self.compiler_revision != AGENT_PLAN_COMPILER_REVISION_V3
            || self
                .plans
                .iter()
                .any(|plan| plan.body.schema != AGENT_PLAN_COMPILED_SCHEMA_V3)
        {
            return Err(PublicationError::UnsupportedSchema);
        }
        Ok(())
    }

    /// Authenticates a persisted publication and deterministically upgrades its complete
    /// Product-owned projection to the sole current contract before live use.
    pub fn into_current(mut self) -> Result<Self, PublicationError> {
        self.validate()?;
        // Every plan route binds the compiled plan it names in its persisted form; the plan
        // upgrade below re-derives the V2 route digest, so authenticate the persisted binding
        // first and rebind it afterwards instead of accepting a stale provenance digest.
        for grant in &self.grants {
            for route in grant.model_grant.routes.values() {
                if let crate::AgentModelRouteV2::Plan {
                    plan_id,
                    alias,
                    revision,
                    semantic_digest,
                } = route
                {
                    let plan = self
                        .plans
                        .iter()
                        .find(|plan| plan.agent_plan_id() == plan_id && plan.model_alias() == alias)
                        .ok_or(PublicationError::InvalidGrant)?;
                    if *revision > plan.body.agent_plan_revision
                        || (*revision == plan.body.agent_plan_revision
                            && semantic_digest != &plan.body.materialized_route_digest)
                    {
                        return Err(PublicationError::InvalidGrant);
                    }
                }
            }
        }
        if self.check_current_schema().is_ok() {
            // The complete aggregate and exact grant bindings were checked above. Current
            // Plans need no migration or resealing; only upgrade any persisted alias projection.
            self.aliases = materialize_aliases(&self.plans, &self.enabled_grants()?)?;
            return Ok(self);
        }
        self.schema = GATEWAY_PUBLICATION_SCHEMA_V3.to_owned();
        self.compiler_revision = AGENT_PLAN_COMPILER_REVISION_V3.to_owned();
        self.plans = self
            .plans
            .into_iter()
            .map(|plan| {
                plan.into_current()
                    .map_err(|_| PublicationError::InvalidPlan)
            })
            .collect::<Result<Vec<_>, _>>()?;
        self.grants = self
            .grants
            .into_iter()
            .map(|grant| rebind_current_grant_routes(grant, &self.plans))
            .collect::<Result<Vec<_>, _>>()?;
        self.aliases = materialize_aliases(&self.plans, &self.enabled_grants()?)?;
        self.validate_current_contract()?;
        Ok(self)
    }

    pub fn canonical_bytes(&self) -> Result<Vec<u8>, PublicationError> {
        self.validate()?;
        serde_json::to_vec(&StoredPublicationV1::freeze(self)?)
            .map_err(|_| PublicationError::Encoding)
    }

    /// Validates publication, authority, grant-generation, and per-Plan revision monotonicity
    /// against the exact active aggregate.
    pub fn validate_transition_from(&self, active: &Self) -> Result<(), PublicationError> {
        self.validate()?;
        active.validate()?;
        self.validate_head_transition(active)?;
        if self.workspace_id != active.workspace_id
            || self.authority_id != active.authority_id
            || self.authority_epoch < active.authority_epoch
            || self.publication_revision.get() <= active.publication_revision.get()
            || self.alias_registry.next_sequence < active.alias_registry.next_sequence
            || !self
                .alias_registry
                .tombstones
                .is_superset(&active.alias_registry.tombstones)
            || !self
                .alias_registry
                .retired_plan_ids
                .is_superset(&active.alias_registry.retired_plan_ids)
        {
            return Err(PublicationError::InvalidTransition);
        }
        for (plan_id, alias) in &active.alias_registry.active {
            match self.alias_registry.active.get(plan_id) {
                Some(current) if current == alias => {}
                Some(_) => return Err(PublicationError::AliasLifecycleConflict),
                None if self.alias_registry.tombstones.contains(alias)
                    && self.alias_registry.retired_plan_ids.contains(plan_id) => {}
                None => return Err(PublicationError::AliasLifecycleConflict),
            }
        }
        for plan in &self.plans {
            if let Some(previous) = active
                .plans
                .iter()
                .find(|previous| previous.agent_plan_id() == plan.agent_plan_id())
            {
                if plan.body.agent_plan_revision < previous.body.agent_plan_revision {
                    return Err(PublicationError::InvalidTransition);
                }
                if plan.body.agent_plan_revision == previous.body.agent_plan_revision
                    && crate::StoredPlanV1::freeze(plan).ok()
                        != previous
                            .clone()
                            .into_current()
                            .ok()
                            .and_then(|p| crate::StoredPlanV1::freeze(&p).ok())
                {
                    return Err(PublicationError::ImmutablePlanRevisionConflict);
                }
            }
        }
        // A same-generation Grant may differ from its persisted form only by the deterministic
        // current-contract upgrade of the Plan routes it binds; any other change requires a new
        // generation.
        let mut active_current: Option<Option<Self>> = None;
        for grant in &self.grants {
            let Some(previous) = active
                .grants
                .iter()
                .find(|previous| previous.grant_id == grant.grant_id)
            else {
                continue;
            };
            if grant.generation < previous.generation {
                return Err(PublicationError::ImmutableGrantGenerationConflict);
            }
            if grant.generation == previous.generation && grant != previous {
                let current = match active_current
                    .get_or_insert_with(|| active.clone().into_current().ok())
                {
                    Some(publication) => publication
                        .grants
                        .iter()
                        .find(|candidate| candidate.grant_id == grant.grant_id),
                    None => None,
                };
                if !current.is_some_and(|candidate| candidate == grant) {
                    return Err(PublicationError::ImmutableGrantGenerationConflict);
                }
            }
        }
        Ok(())
    }

    pub fn digest(&self) -> Result<CanonicalDigest, PublicationError> {
        Ok(CanonicalDigest::of_bytes(&self.canonical_bytes()?))
    }

    pub fn decode(bytes: &[u8]) -> Result<Self, PublicationError> {
        let stored: StoredPublicationV1 =
            serde_json::from_slice(bytes).map_err(|_| PublicationError::Decoding)?;
        let publication = stored.build()?;
        if publication.canonical_bytes()?.as_slice() != bytes {
            return Err(PublicationError::NonCanonicalEncoding);
        }
        Ok(publication)
    }

    /// Recovery reader for a persisted publication aggregate. Current bodies use the strict
    /// decoder; persisted legacy aggregates keep their name-set grants, which are
    /// authenticated here and re-derived into the sole current model-grant route mapping
    /// before any live use. New writes never emit the legacy shape.
    pub fn decode_persisted(bytes: &[u8]) -> Result<Self, PublicationError> {
        if let Ok(current) = Self::decode(bytes) {
            return Ok(current);
        }
        if let Ok(persisted) = serde_json::from_slice::<Self>(bytes) {
            persisted.validate()?;
            if serde_json::to_vec(&persisted)
                .map_err(|_| PublicationError::Encoding)?
                .as_slice()
                != bytes
            {
                return Err(PublicationError::NonCanonicalEncoding);
            }
            return Ok(persisted);
        }
        let legacy: LegacyGatewayPublicationV2 =
            serde_json::from_slice(bytes).map_err(|_| PublicationError::Decoding)?;
        let plans = legacy.plans;
        let grants = legacy
            .grants
            .into_iter()
            .map(|grant| recover_legacy_grant(grant, &plans))
            .collect::<Result<Vec<_>, PublicationError>>()?;
        let publication = Self {
            schema: legacy.schema,
            compiler_revision: legacy.compiler_revision,
            workspace_id: legacy.workspace_id,
            authority_id: legacy.authority_id,
            authority_epoch: legacy.authority_epoch,
            publication_revision: legacy.publication_revision,
            catalog_renderer_revision: legacy.catalog_renderer_revision,
            alias_registry: legacy.alias_registry,
            plans,
            plan_heads: legacy.plan_heads,
            aliases: legacy.aliases,
            grants,
        };
        publication.validate()?;
        Ok(publication)
    }

    /// Produces the frozen Gateway DTO solely from the verified product publication.
    pub fn gateway_snapshot(
        &self,
    ) -> Result<GatewayPublicationSnapshotProjectionV3, PublicationError> {
        let current = self.clone().into_current()?;
        let enabled_grants = current.enabled_grants()?;
        if enabled_grants.is_empty() {
            return GatewayPublicationSnapshotProjectionV3::no_new_calls(
                current.workspace_id.as_str().into(),
                current.authority_id,
                current.authority_epoch,
                current.publication_revision.get(),
                current.catalog_renderer_revision,
            );
        }
        let mut aliases = current.aliases;
        snapshot::project_pricing_identities(&current.plans, &mut aliases)?;
        let enabled_grants = snapshot::project_grants(enabled_grants, &aliases, &current.plans)?;
        GatewayPublicationSnapshotProjectionV3::seal(
            current.workspace_id.as_str().to_owned(),
            current.authority_id,
            current.authority_epoch,
            current.publication_revision.get(),
            current.catalog_renderer_revision,
            aliases,
            enabled_grants,
        )
    }

    /// Projects the independent, durable AgentPlan catalog without requiring an
    /// AgentConnection grant. A protocol is advertised only when every ordered candidate has
    /// one exact renderer for that ingress; grant material never participates in this catalog.
    pub fn published_agent_plans(&self) -> Result<Vec<PublishedAgentPlanV1>, PublicationError> {
        self.project_published_agent_plans(false)
    }

    pub(crate) fn published_hermes_agent_plans(
        &self,
    ) -> Result<Vec<PublishedAgentPlanV1>, PublicationError> {
        self.project_published_agent_plans(true)
    }

    fn project_published_agent_plans(
        &self,
        include_chat: bool,
    ) -> Result<Vec<PublishedAgentPlanV1>, PublicationError> {
        self.validate()?;
        self.plans
            .iter()
            .filter_map(|plan| {
                let candidates = match ordered_candidates(plan) {
                    Ok(candidates) => candidates,
                    Err(error) => return Some(Err(error)),
                };
                let supported_ingress = [
                    (
                        AgentIngressProtocolV1::Responses,
                        UpstreamProtocol::Responses,
                    ),
                    (AgentIngressProtocolV1::Messages, UpstreamProtocol::Messages),
                    (
                        AgentIngressProtocolV1::ChatCompletions,
                        UpstreamProtocol::ChatCompletions,
                    ),
                ]
                .into_iter()
                .filter(|(protocol, _)| {
                    include_chat || *protocol != AgentIngressProtocolV1::ChatCompletions
                })
                .filter(|(_, ingress)| {
                    candidates.iter().all(|candidate| {
                        candidate
                            .protocol_profiles
                            .iter()
                            .filter(|profile| profile.ingress_protocol == *ingress)
                            .count()
                            == 1
                    })
                })
                .map(|(protocol, _)| protocol)
                .collect::<BTreeSet<_>>();
                if supported_ingress.is_empty() {
                    return None;
                }
                Some(Ok(PublishedAgentPlanV1 {
                    agent_plan_id: plan.body.identity.agent_plan_id.clone(),
                    model_alias: plan.body.identity.model_alias.clone(),
                    display_name: plan.body.identity.display_name.clone(),
                    purpose: plan.body.identity.purpose.clone(),
                    agent_plan_revision: plan.body.agent_plan_revision,
                    active: self
                        .plan_heads
                        .iter()
                        .find(|h| h.reference.plan_id == *plan.agent_plan_id())
                        .is_none_or(|h| h.status == crate::PlanLifecycleV1::Enabled),
                    supported_ingress,
                }))
            })
            .collect()
    }
}

/// Recovery-only mirror of a persisted legacy `hiroute.gateway-publication/v2` aggregate.
/// The V2 writer sealed exactly one ingress protocol and a set of published aliases per
/// grant; recovery re-derives the current route mapping from those facts and never
/// re-persists the legacy shape.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct LegacyGatewayPublicationV2 {
    schema: String,
    compiler_revision: String,
    workspace_id: WorkspaceId,
    authority_id: String,
    authority_epoch: u64,
    publication_revision: GatewayPublicationRevision,
    catalog_renderer_revision: String,
    alias_registry: AliasRegistryV1,
    plans: Vec<CompiledAgentPlanV1>,
    #[serde(default)]
    plan_heads: Vec<crate::PlanHeadV1>,
    aliases: Vec<GatewayExecutableAliasV2>,
    grants: Vec<LegacyGatewayExecutableGrantV2>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct LegacyGatewayExecutableGrantV2 {
    grant_id: String,
    generation: u64,
    bearer_token_sha256: CanonicalDigest,
    allowed_protocols: Vec<AgentIngressProtocolV1>,
    allowed_aliases: Vec<ModelAlias>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PreparePublicationOutcome {
    Created,
    ExistingSame,
}

/// Durable state: prepare is transactional and activation atomically retains the prior LKG.
pub trait PublicationRepositoryPort {
    fn prepare_publication(
        &self,
        record: &PublicationRecordV1,
        expected_active_revision: Option<GatewayPublicationRevision>,
    ) -> PortResult<PreparePublicationOutcome>;

    fn prepared_publication(
        &self,
        workspace: &WorkspaceId,
    ) -> PortResult<Option<PublicationRecordV1>>;

    fn active_publication(
        &self,
        workspace: &WorkspaceId,
    ) -> PortResult<Option<PublicationRecordV1>>;

    fn last_known_good_publication(
        &self,
        workspace: &WorkspaceId,
    ) -> PortResult<Option<PublicationRecordV1>>;

    fn mark_publication_active(
        &self,
        workspace: &WorkspaceId,
        publication_revision: GatewayPublicationRevision,
        digest: &CanonicalDigest,
    ) -> PortResult<()>;
}

#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum PublicationError {
    #[error("Gateway publication schema is unsupported")]
    UnsupportedSchema,
    #[error("AgentPlan compiler revision is unsupported")]
    UnsupportedCompilerRevision,
    #[error("Gateway publication revision must be non-zero")]
    InvalidRevision,
    #[error("Gateway publication workspace is invalid or does not match its record")]
    InvalidWorkspace,
    #[error("Gateway authority or catalog renderer identity is invalid")]
    InvalidAuthority,
    #[error("Gateway publication alias registry is invalid")]
    InvalidAliasRegistry,
    #[error("Gateway publication contains an invalid compiled AgentPlan")]
    InvalidPlan,
    #[error("Gateway publication AgentPlans are duplicated, unsorted, or alias-inconsistent")]
    InvalidPlanSet,
    #[error("Gateway publication grant is invalid or does not close over published aliases")]
    InvalidGrant,
    #[error("Gateway publication does not close every active alias")]
    PublicationNotClosed,
    #[error("Gateway publication executable alias projection does not match compiled Plans")]
    InvalidExecutableProjection,
    #[error("Gateway publication execution limits exceed the frozen G0 contract")]
    InvalidExecutionLimits,
    #[error("Gateway publication executable candidate IDs collide")]
    CandidateIdCollision,
    #[error("empty publication cannot be projected as executable Gateway authority")]
    PublicationNotExecutable,
    #[error("Gateway publication canonical encoding failed")]
    Encoding,
    #[error("Gateway publication could not be decoded")]
    Decoding,
    #[error("Gateway publication bytes are not the canonical encoding")]
    NonCanonicalEncoding,
    #[error("Gateway publication digest does not match its bytes")]
    DigestMismatch,
    #[error("Gateway publication transition is stale or crosses authorities/workspaces")]
    InvalidTransition,
    #[error("an immutable AgentPlan revision was reused for different compiled bytes")]
    ImmutablePlanRevisionConflict,
    #[error("an immutable grant generation was reused for different verifier or scope")]
    ImmutableGrantGenerationConflict,
    #[error("an active alias was renamed, removed without a tombstone, or lifecycle state rewound")]
    AliasLifecycleConflict,
}

#[cfg(test)]
mod routing_publication_tests;