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.2 KB
Raw Blame
use std::collections::BTreeSet;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use super::*;
mod validation;
pub(super) use validation::{
    agent_access_grants_from_control, validate_external_components, validate_plan,
};
use validation::{
    registered_payload, validate_agent_access_grants, validate_agent_change_spec,
    validate_payload_value,
};
mod settings;
mod settings_publication;
pub use settings_publication::{
    settings_model_publication_intent, settings_model_publication_record,
    validate_settings_model_publication_intent,
};

const CONTROL_SCHEMA: &str = "hiroute.agent-connection-control/v1";
const EFFECT_SCHEMA: &str = "hiroute.agent-connection-effect/v1";
const MAX_REGISTERED_PAYLOAD_BYTES: usize = 1_048_576;

/// The registered AgentConnection commands that may enter the generic transaction engine.
///
/// This enum is intentionally only a planner-side value. It has no `Deserialize` implementation,
/// so a wire request cannot select a transaction variant without a registered typed handler.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentConnectionTransactionKindV1 {
    Apply,
    Restore,
    Settings,
}

impl AgentConnectionTransactionKindV1 {
    pub const fn command_id(self) -> &'static str {
        match self {
            Self::Apply => "agents.connect.apply",
            Self::Restore => "agents.restore.apply",
            Self::Settings => "agents.settings.apply",
        }
    }

    fn parse(value: &str) -> Result<Self, OperationValidationError> {
        match value {
            "apply" => Ok(Self::Apply),
            "restore" => Ok(Self::Restore),
            "settings" => Ok(Self::Settings),
            _ => Err(OperationValidationError::UnregisteredEffectPlan),
        }
    }
}

/// Exact, registry-resolved Agent/profile identity shared by control and every owned effect.
/// Private fields and the absence of `Deserialize` prevent caller-supplied JSON from becoming an
/// effects-plan identity.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct AgentConnectionTransactionSubjectV1 {
    agent_id: String,
    profile_id: String,
    integration_profile_ref: String,
}

impl AgentConnectionTransactionSubjectV1 {
    pub fn from_registered_profile(
        agent_id: impl Into<String>,
        profile_id: impl Into<String>,
        integration_profile_ref: impl Into<String>,
    ) -> Result<Self, OperationValidationError> {
        let subject = Self {
            agent_id: agent_id.into(),
            profile_id: profile_id.into(),
            integration_profile_ref: integration_profile_ref.into(),
        };
        validate_scope_identifier(&subject.agent_id)?;
        validate_scope_identifier(&subject.profile_id)?;
        validate_scope_identifier(&subject.integration_profile_ref)?;
        Ok(subject)
    }

    pub fn agent_id(&self) -> &str {
        &self.agent_id
    }

    pub fn profile_id(&self) -> &str {
        &self.profile_id
    }

    pub fn integration_profile_ref(&self) -> &str {
        &self.integration_profile_ref
    }
}

/// Server-owned control mutation for an AgentConnection transaction.
///
/// `payload` is produced by the downstream command-specific typed planner. It remains private,
/// is bound to the exact public ChangeSpec, and is checked for secret-bearing fields before it can
/// enter the durable journal.
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct AgentConnectionControlIntentV1 {
    schema: &'static str,
    transaction: AgentConnectionTransactionKindV1,
    subject: AgentConnectionTransactionSubjectV1,
    change_spec_digest: CanonicalDigest,
    payload_digest: CanonicalDigest,
    payload: Value,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    agent_access_grants: Vec<AgentAccessGrantMutationV1>,
    #[serde(skip_serializing_if = "Option::is_none")]
    agent_access_grants_digest: Option<CanonicalDigest>,
}

impl AgentConnectionControlIntentV1 {
    pub fn from_registered_planner<T: Serialize>(
        transaction: AgentConnectionTransactionKindV1,
        subject: AgentConnectionTransactionSubjectV1,
        spec: &ChangeSpecV1,
        payload: &T,
    ) -> Result<Self, OperationValidationError> {
        if spec.command_id != transaction.command_id() {
            return Err(OperationValidationError::UnregisteredEffectPlan);
        }
        validate_agent_change_spec(spec)?;
        let payload = registered_payload(payload)?;
        Ok(Self {
            schema: CONTROL_SCHEMA,
            transaction,
            subject,
            change_spec_digest: CanonicalDigest::of(spec)?,
            payload_digest: CanonicalDigest::of(&payload)?,
            payload,
            agent_access_grants: Vec::new(),
            agent_access_grants_digest: None,
        })
    }

    pub const fn transaction(&self) -> AgentConnectionTransactionKindV1 {
        self.transaction
    }

    pub fn subject(&self) -> &AgentConnectionTransactionSubjectV1 {
        &self.subject
    }

    pub fn change_spec_digest(&self) -> &CanonicalDigest {
        &self.change_spec_digest
    }

    pub fn payload_digest(&self) -> &CanonicalDigest {
        &self.payload_digest
    }

    pub fn payload(&self) -> &Value {
        &self.payload
    }

    fn bind_agent_access_grants(
        &mut self,
        spec: &ChangeSpecV1,
        mutations: Vec<AgentAccessGrantMutationV1>,
    ) -> Result<(), OperationValidationError> {
        validate_agent_access_grants(spec, self.transaction, &mutations)?;
        self.agent_access_grants_digest = (!mutations.is_empty())
            .then(|| CanonicalDigest::of(&mutations))
            .transpose()?;
        self.agent_access_grants = mutations;
        Ok(())
    }
}

/// Exact external ownership slots available to the AgentConnection typed handler.
///
/// Grant and AccessPoint facts stay in one aggregate publication effect so activation cannot
/// expose a grant/publication split. Native-routing artifacts are an all-or-none trio; the spawn
/// guidance rewrite remains an optional, separately owned optimization.
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentConnectionEffectRoleV1 {
    GrantScopedPublication,
    ManagedConfiguration,
    ModelCatalog,
    RoutingSkill,
    ManagementSkill,
    CollaborationSkill,
    HermesPluginModule,
    HermesPluginManifest,
    InstructionOverlay,
    SpawnGuidanceRewrite,
    /// The host-executed resident login item for the first managed connection. Unlike the
    /// artifact roles, the action runs in the Desktop host under the native confirmation; the
    /// Operation records the checked before/after state and the host compensates creations.
    LoginItem,
}

impl AgentConnectionEffectRoleV1 {
    /// Preserve RoutingSkill's original file binding; the second resource has its own role.
    pub fn settings_skill(context: &str, facet: crate::AgentSettingsFacet) -> Option<Self> {
        use crate::AgentSettingsFacet::*;
        match (context.starts_with("agent-context/hermes/"), facet) {
            (true, ManagementSkill) | (false, Collaboration) => Some(Self::RoutingSkill),
            (false, ManagementSkill) => Some(Self::ManagementSkill),
            (true, Collaboration) => Some(Self::CollaborationSkill),
            (_, Model) => None,
        }
    }

    pub fn settings_skill_facet(self, context: &str) -> Option<crate::AgentSettingsFacet> {
        [
            crate::AgentSettingsFacet::ManagementSkill,
            crate::AgentSettingsFacet::Collaboration,
        ]
        .into_iter()
        .find(|facet| Self::settings_skill(context, *facet) == Some(self))
    }

    pub const fn is_skill(self) -> bool {
        matches!(
            self,
            Self::RoutingSkill | Self::ManagementSkill | Self::CollaborationSkill
        )
    }

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::GrantScopedPublication => "grant_scoped_publication",
            Self::ManagedConfiguration => "managed_configuration",
            Self::ModelCatalog => "model_catalog",
            Self::RoutingSkill => "routing_skill",
            Self::ManagementSkill => "management_skill",
            Self::CollaborationSkill => "collaboration_skill",
            Self::HermesPluginModule => "hermes_plugin_module",
            Self::HermesPluginManifest => "hermes_plugin_manifest",
            Self::InstructionOverlay => "instruction_overlay",
            Self::SpawnGuidanceRewrite => "spawn_guidance_rewrite",
            Self::LoginItem => "login_item",
        }
    }

    /// Derives the immutable ownership target used by the registered renderer. Adapters use
    /// this only to observe the exact pre-Preview fingerprint; the sealed planner still fixes
    /// every target when it creates the effect intent.
    pub fn target_for(
        self,
        subject: &AgentConnectionTransactionSubjectV1,
    ) -> Result<String, OperationValidationError> {
        effect_target(subject, self)
    }

    pub fn settings_target_for(
        self,
        subject: &AgentConnectionTransactionSubjectV1,
    ) -> Result<String, OperationValidationError> {
        effect_target(subject, self)
    }

    /// The payload digest also names a settings catalog artifact, so fact capture can observe
    /// that exact existing target before Preview without inventing a second path convention.
    pub fn settings_payload_target_for(
        self,
        subject: &AgentConnectionTransactionSubjectV1,
        payload_digest: &CanonicalDigest,
    ) -> Result<String, OperationValidationError> {
        let target = self.settings_target_for(subject)?;
        if self == Self::ModelCatalog {
            return Ok(format!("{target}/{}", &payload_digest.as_str()[7..]));
        }
        Ok(target)
    }

    const fn effect_id(self) -> &'static str {
        match self {
            Self::GrantScopedPublication => "agent-connection-grant-publication",
            Self::ManagedConfiguration => "agent-connection-managed-configuration",
            Self::ModelCatalog => "agent-connection-model-catalog",
            Self::RoutingSkill => "agent-connection-routing-skill",
            Self::ManagementSkill => "agent-connection-management-skill",
            Self::CollaborationSkill => "agent-connection-collaboration-skill",
            Self::HermesPluginModule => "agent-connection-hermes-plugin-module",
            Self::HermesPluginManifest => "agent-connection-hermes-plugin-manifest",
            Self::InstructionOverlay => "agent-connection-instruction-overlay",
            Self::SpawnGuidanceRewrite => "agent-connection-spawn-guidance",
            Self::LoginItem => "agent-connection-login-item",
        }
    }

    const fn target_name(self) -> &'static str {
        match self {
            Self::GrantScopedPublication => "publication/current",
            Self::ManagedConfiguration => "managed-configuration",
            Self::ModelCatalog => "model-catalog",
            Self::RoutingSkill => "routing-skill",
            Self::ManagementSkill => "management-skill",
            Self::CollaborationSkill => "collaboration-skill",
            Self::HermesPluginModule => "hermes-plugin-module",
            Self::HermesPluginManifest => "hermes-plugin-manifest",
            Self::InstructionOverlay => "instruction-overlay",
            Self::SpawnGuidanceRewrite => "spawn-guidance",
            Self::LoginItem => "login-item",
        }
    }

    const fn owned_kind(self) -> OwnedEffectKind {
        match self {
            Self::GrantScopedPublication => OwnedEffectKind::Publication,
            Self::ManagedConfiguration
            | Self::ModelCatalog
            | Self::RoutingSkill
            | Self::ManagementSkill
            | Self::CollaborationSkill
            | Self::HermesPluginModule
            | Self::HermesPluginManifest
            | Self::InstructionOverlay
            | Self::SpawnGuidanceRewrite => OwnedEffectKind::AgentArtifact,
            Self::LoginItem => OwnedEffectKind::LoginItem,
        }
    }

    fn parse(value: &str) -> Result<Self, OperationValidationError> {
        match value {
            "grant_scoped_publication" => Ok(Self::GrantScopedPublication),
            "managed_configuration" => Ok(Self::ManagedConfiguration),
            "model_catalog" => Ok(Self::ModelCatalog),
            "routing_skill" => Ok(Self::RoutingSkill),
            "management_skill" => Ok(Self::ManagementSkill),
            "collaboration_skill" => Ok(Self::CollaborationSkill),
            "hermes_plugin_module" => Ok(Self::HermesPluginModule),
            "hermes_plugin_manifest" => Ok(Self::HermesPluginManifest),
            "instruction_overlay" => Ok(Self::InstructionOverlay),
            "spawn_guidance_rewrite" => Ok(Self::SpawnGuidanceRewrite),
            "login_item" => Ok(Self::LoginItem),
            _ => Err(OperationValidationError::UnregisteredEffectPlan),
        }
    }
}

/// The settings-transaction client model file: the only B effect whose activation follows the
/// gateway publication, so a client file is never switched before its service is serving.
pub fn is_settings_managed_configuration(intent: &ExternalEffectIntentV1) -> bool {
    intent.kind() == OwnedEffectKind::AgentArtifact
        && intent.desired()["transaction"] == "settings"
        && intent.desired()["role"] == "managed_configuration"
}

/// The settings-transaction model publication: B's service segment.
pub fn is_settings_publication(intent: &ExternalEffectIntentV1) -> bool {
    intent.kind() == OwnedEffectKind::Publication && intent.desired()["transaction"] == "settings"
}

pub const SETTINGS_SERVICE_COMPLETION_SCHEMA: &str = "hiroute.settings-service-completion/v2";

/// Durable proof that a settings operation's service segment (secrets, control, runtime,
/// non-client artifacts, publication and protected revocations) finished. It authorizes the
/// client-file tail to be retried or parked without replaying the service segment, and never
/// authorizes an expired publication to keep serving.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct SettingsServiceCompletionV1 {
    pub schema: String,
    pub publication_revision: u64,
    pub publication_digest: CanonicalDigest,
    pub completed_effects_digest: CanonicalDigest,
}

impl SettingsServiceCompletionV1 {
    pub fn parse(value: &str) -> Option<Self> {
        serde_json::from_str(value)
            .ok()
            .filter(|receipt: &Self| receipt.schema == SETTINGS_SERVICE_COMPLETION_SCHEMA)
    }
}

#[derive(Serialize)]
struct AgentConnectionEffectEnvelopeV1<'a> {
    schema: &'static str,
    transaction: AgentConnectionTransactionKindV1,
    subject: &'a AgentConnectionTransactionSubjectV1,
    change_spec_digest: &'a CanonicalDigest,
    role: AgentConnectionEffectRoleV1,
    payload_digest: CanonicalDigest,
    payload: Value,
}

impl ExternalEffectIntentV1 {
    /// Builds one exact field-owned AgentConnection effect from a registered typed renderer.
    /// The caller cannot choose an effect ID, ownership kind, target, or sensitivity bit.
    pub fn from_agent_connection_planner<T: Serialize>(
        control: &AgentConnectionControlIntentV1,
        role: AgentConnectionEffectRoleV1,
        before_fingerprint: Option<CanonicalDigest>,
        payload: &T,
        desired_mode: u32,
    ) -> Result<Self, OperationValidationError> {
        if !matches!(desired_mode, 0o600 | 0o640 | 0o644)
            || (role == AgentConnectionEffectRoleV1::GrantScopedPublication
                && desired_mode != 0o644)
        {
            return Err(OperationValidationError::InvalidArtifactMode);
        }
        let payload = registered_payload(payload)?;
        let envelope = AgentConnectionEffectEnvelopeV1 {
            schema: EFFECT_SCHEMA,
            transaction: control.transaction,
            subject: &control.subject,
            change_spec_digest: &control.change_spec_digest,
            role,
            payload_digest: CanonicalDigest::of(&payload)?,
            payload,
        };
        let desired = crate::canonicalize_json(serde_json::to_value(&envelope)?);
        let target = if control.transaction == AgentConnectionTransactionKindV1::Settings {
            role.settings_payload_target_for(&control.subject, &envelope.payload_digest)?
        } else {
            effect_target(&control.subject, role)?
        };
        let intent = Self {
            content_publication: None,
            effect_id: role.effect_id().to_owned(),
            kind: role.owned_kind(),
            target,
            before_fingerprint,
            desired: desired.into(),
            desired_mode,
            sensitive: false,
        };
        validate_external_components(
            &intent.effect_id,
            intent.kind,
            &intent.target,
            &intent.desired,
            intent.desired_mode,
            intent.sensitive,
        )?;
        Ok(intent)
    }
}

impl TransactionPlanV1 {
    /// Sealed registration seam for PROCESS-25005's command-specific typed handler.
    ///
    /// The handler supplies a control intent and exact owned effects; this constructor fixes all
    /// other mutation channels to empty and enforces the AgentConnection effect-set invariant.
    pub fn from_agent_connection_planner(
        spec: ChangeSpecV1,
        control: AgentConnectionControlIntentV1,
        external: Vec<ExternalEffectIntentV1>,
    ) -> Result<Self, OperationValidationError> {
        Self::from_agent_connection_planner_with_agent_access_grants(
            spec,
            control,
            Vec::new(),
            external,
        )
    }

    /// Sealed AgentConnection plan carrying a dedicated local grant mutation. The mutation is
    /// embedded in the authenticated control envelope so durable recovery reconstructs one source
    /// of truth without teaching generic storage about planner-private types.
    pub fn from_agent_connection_planner_with_agent_access_grants(
        spec: ChangeSpecV1,
        mut control: AgentConnectionControlIntentV1,
        agent_access_grants: Vec<AgentAccessGrantMutationV1>,
        external: Vec<ExternalEffectIntentV1>,
    ) -> Result<Self, OperationValidationError> {
        control.bind_agent_access_grants(&spec, agent_access_grants)?;
        let grants = control.agent_access_grants.clone();
        let control = serde_json::to_value(control)?;
        validate_plan(&spec, &control, &[], &[], &external)?;
        Ok(Self {
            spec,
            control,
            credential_pool: None,
            worker_dependency_selection: None,
            secrets: Vec::new(),
            agent_access_grants: grants,
            runtime: Vec::new(),
            external,
        })
    }

    /// Extracts the exact non-secret AgentConnection state from the sealed control envelope.
    /// This is a read projection of the authenticated Operation input, not another persistence
    /// format, and is intentionally unavailable for any other command family.
    pub fn agent_connection_projection(
        &self,
    ) -> Result<Option<ActiveAgentConnectionV1>, OperationValidationError> {
        if self.spec.command_id != AgentConnectionTransactionKindV1::Apply.command_id() {
            return Ok(None);
        }
        validate_plan(
            &self.spec,
            &self.control,
            &self.secrets,
            &self.runtime,
            &self.external,
        )?;
        connection_projection(&self.spec, &self.control)
    }
}

pub(super) fn connection_projection(
    spec: &ChangeSpecV1,
    control: &Value,
) -> Result<Option<ActiveAgentConnectionV1>, OperationValidationError> {
    if spec.command_id != AgentConnectionTransactionKindV1::Apply.command_id() {
        return Ok(None);
    }
    let control = decode_control(control)?;
    let subject = decode_subject(control.subject)?;
    let payload: DurableAgentConnectionPayloadV1 = serde_json::from_value(control.payload)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    payload
        .connection
        .validate()
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let desired = spec
        .desired_state
        .as_object()
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let connection_id = spec
        .resource_id
        .clone()
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let installed_version = desired
        .get("installed_version")
        .and_then(Value::as_str)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?
        .to_owned();
    let desired_digest = |field: &str| {
        desired
            .get(field)
            .and_then(Value::as_str)
            .and_then(|value| CanonicalDigest::parse(value.to_owned()).ok())
            .ok_or(OperationValidationError::UnregisteredEffectPlan)
    };
    let observation_digest = desired_digest("observation_digest")?;
    if connection_id
        != format!(
            "agent-connection/{}/{}",
            payload.connection.agent_id, payload.connection.profile_id
        )
        || subject.agent_id() != payload.connection.agent_id
        || subject.profile_id() != payload.connection.profile_id
        || subject.integration_profile_ref() != payload.connection.integration_profile_ref
        || desired.get("agent_id").and_then(Value::as_str)
            != Some(payload.connection.agent_id.as_str())
        || desired.get("profile_id").and_then(Value::as_str)
            != Some(payload.connection.profile_id.as_str())
        || desired
            .get("integration_profile_ref")
            .and_then(Value::as_str)
            != Some(payload.connection.integration_profile_ref.as_str())
        || desired_digest("grant_digest")? != payload.connection.grant.digest
        || desired_digest("publication_digest")? != payload.publication_digest
        || desired_digest("config_change_digest")? != payload.config_change_digest
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    Ok(Some(ActiveAgentConnectionV1 {
        connection_id,
        installed_version,
        observation_digest,
        source_publication_digest: payload.publication_digest,
        connection: payload.connection,
    }))
}

/// Durable non-secret view used by daemon status, descriptor, and raw-grant joins.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ActiveAgentConnectionV1 {
    pub connection_id: String,
    pub installed_version: String,
    pub observation_digest: CanonicalDigest,
    pub source_publication_digest: CanonicalDigest,
    pub connection: crate::AgentConnectionV1,
}

/// Materializes the one product publication owned by an AgentConnection Operation after the
/// SecretStore has produced its authenticated, non-secret grant reference.
pub fn agent_connection_publication_record(
    operation: &OperationV1,
    intent: &ExternalEffectIntentV1,
    active_record: &crate::PublicationRecordV1,
    grant_effect: &OwnedEffectV1,
) -> Result<Option<crate::PublicationRecordV1>, OperationValidationError> {
    if intent.effect_id != AgentConnectionEffectRoleV1::GrantScopedPublication.effect_id() {
        return Ok(None);
    }
    if !operation
        .plan
        .external
        .iter()
        .any(|registered| registered == intent)
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let projection = operation
        .plan
        .agent_connection_projection()?
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let envelope = decode_effect(&intent.desired)?;
    if AgentConnectionEffectRoleV1::parse(&envelope.role)?
        != AgentConnectionEffectRoleV1::GrantScopedPublication
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let payload: DurableGrantPublicationPayloadV1 = serde_json::from_value(envelope.payload)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let active = active_record
        .verify()
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let active_digest = active
        .digest()
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let [mutation] = operation.plan.agent_access_grants.as_slice() else {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    };
    let reference = AgentAccessGrantRefV1::from_ensure_effect(grant_effect, mutation)?;
    let scope = reference.scope();
    let model_grant = crate::AgentModelGrantV2::from_plan_ids(
        projection.connection.protocol,
        projection.connection.grant.allowed_agent_plan_ids.clone(),
        &active,
    )
    .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    if payload.connection != projection.connection
        || payload.publication_digest != projection.source_publication_digest
        || payload.publication_digest != active_digest
        || intent.before_fingerprint.as_ref() != Some(&active_digest)
        || payload.access_point_ref != "access-point/local/default"
        || reference.owner_scope() != operation.workspace_id.as_str()
        || reference.connection_id() != projection.connection_id
        || scope.protocol() != projection.connection.protocol
        || scope.model_grant() != &model_grant
        || operation.plan.spec().desired_state["model_grant_digest"]
            != serde_json::to_value(&model_grant.digest)?
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let exact_active_grant = active.grants.iter().any(|grant| {
        grant.grant_id == reference.grant_id()
            && grant.generation == reference.generation()
            && grant.bearer_token_sha256 == *reference.material_sha256()
            && grant.model_grant == model_grant
    });
    if exact_active_grant {
        return Ok(Some(active_record.clone()));
    }
    let access_grant = crate::GatewayAccessGrantV1::new(
        reference.grant_id(),
        reference.generation(),
        reference.material_sha256().clone(),
        scope.protocol(),
        model_grant,
    )
    .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let revision = crate::GatewayPublicationRevision::new(
        active
            .publication_revision
            .get()
            .checked_add(1)
            .ok_or(OperationValidationError::UnregisteredEffectPlan)?,
    )
    .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let publication = active
        .next_with_access_grant(revision, access_grant)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    crate::PublicationRecordV1::from_publication(operation.workspace_id.clone(), &publication)
        .map(Some)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)
}

/// Materializes the publication side of an exact AgentConnection restore. The caller supplies
/// the non-secret reference reconstructed from the last succeeded Apply journal; the restore
/// mutation and active publication must bind every field before this removes its verifier.
pub fn agent_connection_restore_publication_record(
    operation: &OperationV1,
    intent: &ExternalEffectIntentV1,
    active_record: &crate::PublicationRecordV1,
    active_grant: &AgentAccessGrantRefV1,
) -> Result<Option<crate::PublicationRecordV1>, OperationValidationError> {
    if intent.effect_id != AgentConnectionEffectRoleV1::GrantScopedPublication.effect_id() {
        return Ok(None);
    }
    validate_plan(
        operation.plan.spec(),
        operation.plan.control(),
        operation.plan.secrets(),
        operation.plan.runtime(),
        operation.plan.external(),
    )?;
    if operation.plan.spec().command_id != AgentConnectionTransactionKindV1::Restore.command_id()
        || !operation
            .plan
            .external
            .iter()
            .any(|registered| registered == intent)
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let envelope = decode_effect(&intent.desired)?;
    if AgentConnectionTransactionKindV1::parse(&envelope.transaction)?
        != AgentConnectionTransactionKindV1::Restore
        || AgentConnectionEffectRoleV1::parse(&envelope.role)?
            != AgentConnectionEffectRoleV1::GrantScopedPublication
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let payload: DurableGrantRestorePayloadV1 = serde_json::from_value(envelope.payload)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let active = active_record
        .verify()
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let active_digest = active
        .digest()
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let [mutation] = operation.plan.agent_access_grants.as_slice() else {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    };
    active_grant.validate()?;
    let scope = active_grant.scope();
    let exact_active_grant = active.grants.iter().any(|grant| {
        grant.grant_id == active_grant.grant_id()
            && grant.generation == active_grant.generation()
            && grant.bearer_token_sha256 == *active_grant.material_sha256()
            && &grant.model_grant == scope.model_grant()
    });
    if payload.role != AgentConnectionEffectRoleV1::GrantScopedPublication.as_str()
        || payload.previous_digest.is_none()
        || payload.remove_if_absent
        || intent.before_fingerprint.as_ref() != Some(&active_digest)
        || mutation.kind() != AgentAccessGrantMutationKindV1::Revoke
        || mutation.owner_scope() != operation.workspace_id.as_str()
        || mutation.connection_id() != active_grant.connection_id()
        || mutation.expected_generation() != active_grant.generation()
        || scope.connection_id() != active_grant.connection_id()
        || !exact_active_grant
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let revision = crate::GatewayPublicationRevision::new(
        active
            .publication_revision
            .get()
            .checked_add(1)
            .ok_or(OperationValidationError::UnregisteredEffectPlan)?,
    )
    .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    let publication = active
        .next_without_access_grant(revision, active_grant.grant_id())
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
    crate::PublicationRecordV1::from_publication(operation.workspace_id.clone(), &publication)
        .map(Some)
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)
}

fn effect_target(
    subject: &AgentConnectionTransactionSubjectV1,
    role: AgentConnectionEffectRoleV1,
) -> Result<String, OperationValidationError> {
    if role == AgentConnectionEffectRoleV1::GrantScopedPublication {
        return Ok(role.target_name().to_owned());
    }
    let digest = CanonicalDigest::of(&("agent-connection-target/v1", subject))?;
    let digest = digest
        .as_str()
        .strip_prefix("sha256:")
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    Ok(format!(
        "agent-connections/{}/{}",
        digest,
        role.target_name()
    ))
}

fn valid_digest(digest: &CanonicalDigest) -> bool {
    CanonicalDigest::parse(digest.as_str().to_owned()).is_ok()
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableSubject {
    agent_id: String,
    profile_id: String,
    integration_profile_ref: String,
}

pub(super) fn subject_projection(
    spec: &ChangeSpecV1,
    control: &Value,
) -> Result<Option<AgentConnectionTransactionSubjectV1>, OperationValidationError> {
    if !matches!(
        spec.command_id.as_str(),
        "agents.connect.apply" | "agents.restore.apply" | "agents.settings.apply"
    ) {
        return Ok(None);
    }
    let control = decode_control(control)?;
    if control.schema != CONTROL_SCHEMA
        || AgentConnectionTransactionKindV1::parse(&control.transaction)?.command_id()
            != spec.command_id
        || control.change_spec_digest != CanonicalDigest::of(spec)?
        || control.payload_digest != CanonicalDigest::of(&control.payload)?
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    decode_subject(control.subject).map(Some)
}

fn decode_subject(
    subject: DurableSubject,
) -> Result<AgentConnectionTransactionSubjectV1, OperationValidationError> {
    AgentConnectionTransactionSubjectV1::from_registered_profile(
        subject.agent_id,
        subject.profile_id,
        subject.integration_profile_ref,
    )
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableControl {
    schema: String,
    transaction: String,
    subject: DurableSubject,
    change_spec_digest: CanonicalDigest,
    payload_digest: CanonicalDigest,
    payload: Value,
    #[serde(default)]
    agent_access_grants: Vec<AgentAccessGrantMutationV1>,
    #[serde(default)]
    agent_access_grants_digest: Option<CanonicalDigest>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableAgentConnectionPayloadV1 {
    connection: crate::AgentConnectionV1,
    publication_digest: CanonicalDigest,
    config_change_digest: CanonicalDigest,
    #[serde(default, rename = "catalog_delivery")]
    _catalog_delivery: Option<crate::CatalogDeliveryV1>,
    #[serde(rename = "guidance_disposition")]
    _guidance_disposition: crate::GuidanceRewriteDispositionV1,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableGrantPublicationPayloadV1 {
    connection: crate::AgentConnectionV1,
    publication_digest: CanonicalDigest,
    access_point_ref: String,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableGrantRestorePayloadV1 {
    #[serde(rename = "restore_point_ref")]
    _restore_point_ref: String,
    role: String,
    previous_digest: Option<CanonicalDigest>,
    remove_if_absent: bool,
}

fn decode_control(value: &Value) -> Result<DurableControl, OperationValidationError> {
    serde_json::from_value(value.clone())
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableEffect {
    schema: String,
    transaction: String,
    subject: DurableSubject,
    change_spec_digest: CanonicalDigest,
    role: String,
    payload_digest: CanonicalDigest,
    payload: Value,
}

fn decode_effect(value: &Value) -> Result<DurableEffect, OperationValidationError> {
    serde_json::from_value(value.clone())
        .map_err(|_| OperationValidationError::UnregisteredEffectPlan)
}

#[cfg(test)]
mod tests;