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.

72.9 KB
Raw Blame
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
mod decision_service;
pub use decision_service::DecisionServiceChangeV1;
use std::collections::BTreeSet;
use std::fmt;
use std::sync::Arc;
use thiserror::Error;
use zeroize::Zeroizing;

use crate::{
    CanonicalDigest, ChangeSpecV1, CredentialPoolMutationKind, CredentialPoolMutationV1,
    PortResult, RevisionMismatch, RevisionSetV1, RuntimeProbeAcquireOutcomeV1,
    RuntimeProbeLeaseRequestV1, RuntimeProbeLeaseV1, RuntimeStateIdentityV1, RuntimeStateV1,
    WorkspaceId,
};

mod agent_access_grant;
mod agent_config_permission;
mod agent_connection;
mod compute;
mod compute_management;
mod publication_checkpoint;
mod routing;
mod routing_content;
pub use publication_checkpoint::{
    PUBLICATION_CHECKPOINT_CHANGE_SCHEMA_V1, PublicationCheckpointChangeV1, checkpoint_publication,
};
mod routing_draft;
pub use routing_content::{ConsumedPlanDraftV1, PlanContentControlV2};
mod journal;
mod stored;
pub use stored::*;
mod agent_read;
pub use agent_read::*;
pub(crate) mod shared_input;
pub use journal::OperationJournalUpdate;
mod source_price;
mod subscription_check;
pub use agent_access_grant::{
    AGENT_ACCESS_GRANT_EFFECT_SCHEMA_V1, AgentAccessGrantMaterial,
    AgentAccessGrantMaterialActionV1, AgentAccessGrantMutationKindV1, AgentAccessGrantMutationV1,
    AgentAccessGrantRefV1, AgentAccessGrantScopeV1, is_agent_access_grant_effect,
    valid_user_agent_token,
};
pub use agent_config_permission::AgentConfigPermissionIntentV1;
pub use agent_connection::{
    ActiveAgentConnectionV1, AgentConnectionControlIntentV1, AgentConnectionEffectRoleV1,
    AgentConnectionTransactionKindV1, AgentConnectionTransactionSubjectV1,
    SETTINGS_SERVICE_COMPLETION_SCHEMA, SettingsServiceCompletionV1,
    agent_connection_publication_record, agent_connection_restore_publication_record,
    is_settings_managed_configuration, is_settings_publication, settings_model_publication_intent,
    settings_model_publication_record, validate_settings_model_publication_intent,
};
pub use compute::ComputeSourceMutationV1;
pub use routing::routing_publication_record;
pub use subscription_check::{
    COMPUTE_SUBSCRIPTION_CHECK_COMMAND_ID_V2, COMPUTE_SUBSCRIPTION_EFFECT_ID_V2,
    SubscriptionCheckIntentV2, decode_subscription_check_intent, is_subscription_check_effect,
};

pub const OPERATION_SCHEMA_VERSION: u16 = 2;

#[derive(
    schemars::JsonSchema, Clone, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(transparent)]
pub struct OperationId(String);

impl OperationId {
    pub fn derive(
        workspace: &WorkspaceId,
        scope: &IdempotencyScopeV1,
        request_digest: &CanonicalDigest,
    ) -> Self {
        let input = format!(
            "operation-v1\0{workspace}\0{}\0{}\0{}\0{request_digest}",
            scope.principal, scope.operation_kind, scope.key
        );
        let digest = CanonicalDigest::of_bytes(input.as_bytes());
        Self(format!("op_{}", &digest.as_str()[7..39]))
    }

    pub fn parse(value: impl Into<String>) -> Result<Self, OperationValidationError> {
        let value = value.into();
        let valid = value.len() == 35
            && value.starts_with("op_")
            && value[3..].bytes().all(|byte| byte.is_ascii_hexdigit());
        if valid {
            Ok(Self(value.to_ascii_lowercase()))
        } else {
            Err(OperationValidationError::InvalidOperationId)
        }
    }

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

impl fmt::Display for OperationId {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.0)
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
pub struct IdempotencyScopeV1 {
    pub principal: String,
    pub operation_kind: String,
    pub key: String,
}

impl IdempotencyScopeV1 {
    pub fn new(
        principal: impl Into<String>,
        operation_kind: impl Into<String>,
        key: impl Into<String>,
    ) -> Result<Self, OperationValidationError> {
        let scope = Self {
            principal: principal.into(),
            operation_kind: operation_kind.into(),
            key: key.into(),
        };
        validate_scope_identifier(&scope.principal)?;
        validate_scope_identifier(&scope.operation_kind)?;
        validate_idempotency_key(&scope.key)?;
        Ok(scope)
    }
}

#[derive(
    schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum OperationState {
    Accepted,
    Preparing,
    ApplyingSecrets,
    MaterializingSources,
    CompilingPublication,
    ApplyingAgentArtifacts,
    Activating,
    RollingBack,
    Succeeded,
    RolledBack,
    NeedsAttention,
}

impl OperationState {
    pub const fn is_terminal(self) -> bool {
        matches!(
            self,
            Self::Succeeded | Self::RolledBack | Self::NeedsAttention
        )
    }

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Accepted => "accepted",
            Self::Preparing => "preparing",
            Self::ApplyingSecrets => "applying_secrets",
            Self::MaterializingSources => "materializing_sources",
            Self::CompilingPublication => "compiling_publication",
            Self::ApplyingAgentArtifacts => "applying_agent_artifacts",
            Self::Activating => "activating",
            Self::RollingBack => "rolling_back",
            Self::Succeeded => "succeeded",
            Self::RolledBack => "rolled_back",
            Self::NeedsAttention => "needs_attention",
        }
    }

    pub const fn can_transition_to(self, next: Self) -> bool {
        matches!(
            (self, next),
            (Self::Accepted, Self::Preparing)
                | (Self::Preparing, Self::ApplyingSecrets)
                | (Self::ApplyingSecrets, Self::MaterializingSources)
                | (Self::MaterializingSources, Self::CompilingPublication)
                | (Self::CompilingPublication, Self::ApplyingAgentArtifacts)
                | (Self::ApplyingAgentArtifacts, Self::Activating)
                | (Self::Activating, Self::Succeeded)
                | (Self::Accepted, Self::RollingBack)
                | (Self::Preparing, Self::RollingBack)
                | (Self::ApplyingSecrets, Self::RollingBack)
                | (Self::MaterializingSources, Self::RollingBack)
                | (Self::CompilingPublication, Self::RollingBack)
                | (Self::ApplyingAgentArtifacts, Self::RollingBack)
                | (Self::Activating, Self::RollingBack)
                | (Self::RollingBack, Self::RolledBack)
                | (Self::RollingBack, Self::NeedsAttention)
                // An uncertain terminal rollback may be closed after a later exact recheck.
                | (Self::NeedsAttention, Self::RolledBack)
        )
    }
}

#[derive(
    schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum OperationStepKind {
    Prepare,
    ApplySecrets,
    MaterializeSources,
    CompilePublication,
    ApplyAgentArtifacts,
    Activate,
}

impl OperationStepKind {
    pub const ALL: [Self; 6] = [
        Self::Prepare,
        Self::ApplySecrets,
        Self::MaterializeSources,
        Self::CompilePublication,
        Self::ApplyAgentArtifacts,
        Self::Activate,
    ];

    pub const fn state(self) -> OperationState {
        match self {
            Self::Prepare => OperationState::Preparing,
            Self::ApplySecrets => OperationState::ApplyingSecrets,
            Self::MaterializeSources => OperationState::MaterializingSources,
            Self::CompilePublication => OperationState::CompilingPublication,
            Self::ApplyAgentArtifacts => OperationState::ApplyingAgentArtifacts,
            Self::Activate => OperationState::Activating,
        }
    }
}

#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OperationStepStatus {
    Pending,
    Started,
    Applied,
    Compensating,
    Compensated,
    Attention,
}

#[derive(
    schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum OwnedEffectKind {
    Control,
    Secret,
    RuntimeState,
    Publication,
    AgentArtifact,
    /// Host-executed resident-service registration. The Desktop host performs the action under
    /// the native confirmation; this side only owns the durable evidence and compensation
    /// decision, so daemon-side compensation is a deliberate no-op.
    LoginItem,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct OwnedEffectV1 {
    pub effect_id: String,
    pub kind: OwnedEffectKind,
    pub target: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before_fingerprint: Option<CanonicalDigest>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub after_fingerprint: Option<CanonicalDigest>,
    /// Bounded, non-secret adapter metadata. Secret ciphertext and source locators are forbidden.
    #[serde(default, with = "shared_input")]
    #[schemars(with = "Value")]
    pub compensation: Arc<Value>,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct OperationStepV1 {
    pub sequence: u16,
    pub kind: OperationStepKind,
    pub deterministic_input_digest: CanonicalDigest,
    pub status: OperationStepStatus,
    pub attempts: u32,
    #[serde(default)]
    pub effects: Vec<OwnedEffectV1>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub terminal_result: Option<String>,
}

#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SecretMutationKind {
    Upsert,
    Delete,
    Rebind,
}

#[derive(
    schemars::JsonSchema, Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize,
)]
#[serde(rename_all = "snake_case")]
pub enum SecretFingerprintAlgorithm {
    #[default]
    HmacSha256V1,
}

#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CredentialRefV1 {
    credential_id: String,
    owner_scope: String,
    subject: String,
    purpose: String,
    allowed_destinations: BTreeSet<String>,
    generation: u64,
}

impl CredentialRefV1 {
    pub fn new(
        credential_id: impl Into<String>,
        owner_scope: impl Into<String>,
        subject: impl Into<String>,
        purpose: impl Into<String>,
        allowed_destinations: impl IntoIterator<Item = String>,
        generation: u64,
    ) -> Result<Self, OperationValidationError> {
        let reference = Self {
            credential_id: credential_id.into(),
            owner_scope: owner_scope.into(),
            subject: subject.into(),
            purpose: purpose.into(),
            allowed_destinations: allowed_destinations.into_iter().collect(),
            generation,
        };
        validate_scope_identifier(&reference.credential_id)?;
        validate_scope_identifier(&reference.owner_scope)?;
        validate_scope_identifier(&reference.subject)?;
        validate_scope_identifier(&reference.purpose)?;
        if reference.allowed_destinations.is_empty()
            && !(reference.subject == "hirouted" && reference.purpose == "http-header")
        {
            return Err(OperationValidationError::InvalidCredentialRef);
        }
        for destination in &reference.allowed_destinations {
            validate_scope_identifier(destination)?;
        }
        Ok(reference)
    }

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

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

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

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

    pub fn allowed_destinations(&self) -> &BTreeSet<String> {
        &self.allowed_destinations
    }

    pub const fn generation(&self) -> u64 {
        self.generation
    }
}

/// Authenticated resolver identity. This type has no serde representation and therefore cannot
/// be supplied by a wire request.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VerifiedSecretSubjectV1 {
    subject: String,
    owner_scope: String,
}

impl VerifiedSecretSubjectV1 {
    pub fn from_authenticated_transport(
        subject: impl Into<String>,
        owner_scope: impl Into<String>,
    ) -> Result<Self, OperationValidationError> {
        let verified = Self {
            subject: subject.into(),
            owner_scope: owner_scope.into(),
        };
        validate_scope_identifier(&verified.subject)?;
        validate_scope_identifier(&verified.owner_scope)?;
        Ok(verified)
    }

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

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

#[derive(schemars::JsonSchema, Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SecretMutationV1 {
    kind: SecretMutationKind,
    credential: CredentialRefV1,
    expected_generation: u64,
    #[serde(default)]
    fingerprint_algorithm: SecretFingerprintAlgorithm,
    /// Safe logical slot resolved by the protected input adapter; never a path or locator.
    #[serde(skip_serializing_if = "Option::is_none")]
    input_slot: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    fingerprint: Option<CanonicalDigest>,
    #[serde(skip_serializing_if = "Option::is_none")]
    new_allowed_destinations: Option<BTreeSet<String>>,
}

impl SecretMutationV1 {
    pub fn upsert(
        credential: CredentialRefV1,
        expected_generation: u64,
        input_slot: impl Into<String>,
        fingerprint: Option<CanonicalDigest>,
    ) -> Result<Self, OperationValidationError> {
        let input_slot = input_slot.into();
        validate_scope_identifier(&input_slot)?;
        Ok(Self {
            kind: SecretMutationKind::Upsert,
            credential,
            expected_generation,
            fingerprint_algorithm: SecretFingerprintAlgorithm::HmacSha256V1,
            input_slot: Some(input_slot),
            fingerprint,
            new_allowed_destinations: None,
        })
    }

    pub fn delete(
        credential: CredentialRefV1,
        expected_generation: u64,
    ) -> Result<Self, OperationValidationError> {
        Ok(Self {
            kind: SecretMutationKind::Delete,
            credential,
            expected_generation,
            fingerprint_algorithm: SecretFingerprintAlgorithm::HmacSha256V1,
            input_slot: None,
            fingerprint: None,
            new_allowed_destinations: None,
        })
    }

    /// Re-encrypts the same protected Key for an edited exact endpoint set inside SecretStore.
    /// The old reference is the read authority; the new set is never accepted from the wire.
    pub fn rebind(
        credential: CredentialRefV1,
        new_allowed_destinations: BTreeSet<String>,
        fingerprint: CanonicalDigest,
    ) -> Result<Self, OperationValidationError> {
        if new_allowed_destinations == *credential.allowed_destinations() {
            return Err(OperationValidationError::InvalidCredentialRef);
        }
        CredentialRefV1::new(
            credential.credential_id(),
            credential.owner_scope(),
            credential.subject(),
            credential.purpose(),
            new_allowed_destinations.iter().cloned(),
            credential
                .generation()
                .checked_add(1)
                .ok_or(OperationValidationError::InvalidCredentialRef)?,
        )?;
        Ok(Self {
            kind: SecretMutationKind::Rebind,
            expected_generation: credential.generation(),
            credential,
            fingerprint_algorithm: SecretFingerprintAlgorithm::HmacSha256V1,
            input_slot: None,
            fingerprint: Some(fingerprint),
            new_allowed_destinations: Some(new_allowed_destinations),
        })
    }

    pub const fn kind(&self) -> SecretMutationKind {
        self.kind
    }

    pub fn credential(&self) -> &CredentialRefV1 {
        &self.credential
    }

    pub const fn expected_generation(&self) -> u64 {
        self.expected_generation
    }

    pub const fn fingerprint_algorithm(&self) -> SecretFingerprintAlgorithm {
        self.fingerprint_algorithm
    }

    pub fn input_slot(&self) -> Option<&str> {
        self.input_slot.as_deref()
    }

    pub fn fingerprint(&self) -> Option<&CanonicalDigest> {
        self.fingerprint.as_ref()
    }

    pub fn new_allowed_destinations(&self) -> Option<&BTreeSet<String>> {
        self.new_allowed_destinations.as_ref()
    }

    pub fn bind_fingerprint(&mut self, fingerprint: CanonicalDigest) {
        self.fingerprint = Some(fingerprint);
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, PartialEq, Serialize)]
pub struct RuntimeMutationV1 {
    key: String,
    value: Value,
    expected_generation: u64,
}

impl RuntimeMutationV1 {
    pub fn from_registered_planner(
        key: impl Into<String>,
        value: Value,
        expected_generation: u64,
    ) -> Result<Self, OperationValidationError> {
        let key = key.into();
        if key != "active/setup" || value != json!({"ready": true}) {
            return Err(OperationValidationError::UnregisteredEffectPlan);
        }
        Ok(Self {
            key,
            value,
            expected_generation,
        })
    }

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

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

    pub const fn expected_generation(&self) -> u64 {
        self.expected_generation
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Serialize)]
pub struct ExternalEffectIntentV1 {
    effect_id: String,
    kind: OwnedEffectKind,
    /// Adapter-relative stable target, never an arbitrary user-supplied URL.
    target: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    before_fingerprint: Option<CanonicalDigest>,
    #[serde(serialize_with = "shared_input::serialize")]
    desired: Arc<Value>,
    desired_mode: u32,
    sensitive: bool,
    #[serde(skip)]
    content_publication: Option<std::sync::Arc<routing_content::ContentEffectV2>>,
}

impl PartialEq for ExternalEffectIntentV1 {
    fn eq(&self, other: &Self) -> bool {
        self.effect_id == other.effect_id
            && self.kind == other.kind
            && self.target == other.target
            && self.before_fingerprint == other.before_fingerprint
            && self.desired_mode == other.desired_mode
            && self.sensitive == other.sensitive
            && (Arc::ptr_eq(&self.desired, &other.desired) || self.desired == other.desired)
    }
}

impl ExternalEffectIntentV1 {
    #[allow(clippy::too_many_arguments)]
    pub fn from_registered_adapter(
        effect_id: impl Into<String>,
        kind: OwnedEffectKind,
        target: impl Into<String>,
        before_fingerprint: Option<CanonicalDigest>,
        desired: Value,
        desired_mode: u32,
        sensitive: bool,
    ) -> Result<Self, OperationValidationError> {
        let effect_id = effect_id.into();
        let target = target.into();
        let desired = crate::canonicalize_json(desired);
        if !matches!(desired_mode, 0o600 | 0o640 | 0o644) {
            return Err(OperationValidationError::InvalidArtifactMode);
        }
        let setup_registered = match kind {
            OwnedEffectKind::Publication => {
                effect_id == "publication-setup"
                    && target == "publication/current"
                    && desired == json!({"setup": "active"})
                    && desired_mode == 0o644
                    && !sensitive
            }
            OwnedEffectKind::AgentArtifact => {
                effect_id == "agent-setup"
                    && target == "agents/codex"
                    && desired == json!({"configured": true})
                    && desired_mode == 0o640
                    && !sensitive
            }
            _ => false,
        };
        let agent_connection_registered = agent_connection::validate_external_components(
            &effect_id,
            kind,
            &target,
            &desired,
            desired_mode,
            sensitive,
        )
        .is_ok();
        let routing_registered = routing::validate_external_components(
            &effect_id,
            kind,
            &target,
            &desired,
            desired_mode,
            sensitive,
        )
        .is_ok();
        let permission_registered = agent_config_permission::validate_external_components(
            &effect_id,
            kind,
            &target,
            before_fingerprint.as_ref(),
            &desired,
            desired_mode,
            sensitive,
        )
        .is_ok();
        let subscription_registered = subscription_check::validate_external_components(
            &effect_id,
            kind,
            &target,
            before_fingerprint.as_ref(),
            &desired,
            desired_mode,
            sensitive,
        )
        .is_ok();
        if !setup_registered
            && !agent_connection_registered
            && !routing_registered
            && !permission_registered
            && !subscription_registered
        {
            return Err(OperationValidationError::UnregisteredEffectPlan);
        }
        let content_publication = if routing_content::is_effect(&desired) {
            Some(std::sync::Arc::new(routing_content::decode_external(
                &effect_id,
                kind,
                &target,
                &desired,
                desired_mode,
                sensitive,
            )?))
        } else {
            None
        };
        Ok(Self {
            content_publication,
            effect_id,
            kind,
            target,
            before_fingerprint,
            desired: desired.into(),
            desired_mode,
            sensitive,
        })
    }

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

    pub const fn kind(&self) -> OwnedEffectKind {
        self.kind
    }

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

    pub fn before_fingerprint(&self) -> Option<&CanonicalDigest> {
        self.before_fingerprint.as_ref()
    }

    pub fn set_before_fingerprint(&mut self, fingerprint: Option<CanonicalDigest>) {
        self.before_fingerprint = fingerprint;
    }

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

    pub const fn desired_mode(&self) -> u32 {
        self.desired_mode
    }

    pub const fn sensitive(&self) -> bool {
        self.sensitive
    }
}

/// One complete daemon-local installation tuple selected for a Worker harness. Paths are
/// metadata inputs, not executable identities or ambient authority.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencySelectionRecordV1 {
    pub harness: crate::delegation::WorkerHarnessV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub adapter_path: Option<String>,
    pub cli_path: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_path: Option<String>,
}

impl WorkerDependencySelectionRecordV1 {
    pub fn new(
        harness: crate::delegation::WorkerHarnessV1,
        adapter_path: Option<String>,
        cli_path: impl Into<String>,
        node_path: Option<String>,
    ) -> Result<Self, OperationValidationError> {
        let selection = Self {
            harness,
            adapter_path,
            cli_path: cli_path.into(),
            node_path,
        };
        selection.validated_launch()?;
        Ok(selection)
    }

    pub fn validated_launch(
        &self,
    ) -> Result<crate::delegation::WorkerLaunchFormV1<'_>, OperationValidationError> {
        crate::delegation::WorkerLaunchFormV1::validate(
            self.harness,
            self.adapter_path.as_deref(),
            &self.cli_path,
            self.node_path.as_deref(),
        )
    }
}

/// Compare-and-select input owned by the protected Worker dependency management operation.
#[derive(schemars::JsonSchema, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencySelectionChangeV1 {
    pub before_revision: u64,
    pub after_selection: WorkerDependencySelectionRecordV1,
}

impl WorkerDependencySelectionChangeV1 {
    pub fn new(
        before_revision: u64,
        after_selection: WorkerDependencySelectionRecordV1,
    ) -> Result<Self, OperationValidationError> {
        before_revision
            .checked_add(1)
            .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
        Ok(Self {
            before_revision,
            after_selection,
        })
    }

    pub const fn after_revision(&self) -> Option<u64> {
        self.before_revision.checked_add(1)
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, PartialEq, Serialize)]
pub struct TransactionPlanV1 {
    spec: ChangeSpecV1,
    control: Value,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    credential_pool: Option<CredentialPoolMutationV1>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    worker_dependency_selection: Option<WorkerDependencySelectionChangeV1>,
    #[serde(default)]
    secrets: Vec<SecretMutationV1>,
    /// Reconstructed from the authenticated AgentConnection control envelope. Keeping this out
    /// of the outer serde shape avoids two durable sources for one mutation.
    #[serde(skip)]
    agent_access_grants: Vec<AgentAccessGrantMutationV1>,
    #[serde(default)]
    runtime: Vec<RuntimeMutationV1>,
    #[serde(default)]
    external: Vec<ExternalEffectIntentV1>,
}

impl TransactionPlanV1 {
    pub fn from_registered_typed_planner(
        spec: ChangeSpecV1,
        control: Value,
        credential_pool: Option<CredentialPoolMutationV1>,
        secrets: Vec<SecretMutationV1>,
        runtime: Vec<RuntimeMutationV1>,
        external: Vec<ExternalEffectIntentV1>,
    ) -> Result<Self, OperationValidationError> {
        validate_registered_plan(
            &spec,
            &control,
            credential_pool.as_ref(),
            &secrets,
            &runtime,
            &external,
        )?;
        let agent_access_grants = if matches!(
            spec.command_id.as_str(),
            "agents.connect.apply" | "agents.restore.apply" | "agents.settings.apply"
        ) {
            agent_connection::agent_access_grants_from_control(&control)?
        } else {
            Vec::new()
        };
        Ok(Self {
            spec,
            control,
            credential_pool,
            worker_dependency_selection: None,
            secrets,
            agent_access_grants,
            runtime,
            external,
        })
    }

    /// Constructs the only registered plan that can mutate a daemon-local Worker installation
    /// selection. The selected paths remain data until the daemon adapter performs its bounded
    /// metadata validation; this constructor prevents arbitrary wire JSON from becoming a
    /// generic Control effect.
    pub fn from_worker_dependency_selection_planner(
        spec: ChangeSpecV1,
        change: WorkerDependencySelectionChangeV1,
    ) -> Result<Self, OperationValidationError> {
        change.after_selection.validated_launch()?;
        let harness = change.after_selection.harness;
        let resource = match harness {
            crate::delegation::WorkerHarnessV1::OpenCode => "worker-dependency-selection/opencode",
            crate::delegation::WorkerHarnessV1::QoderCli => "worker-dependency-selection/qoder_cli",
            crate::delegation::WorkerHarnessV1::Pi => "worker-dependency-selection/pi",
            crate::delegation::WorkerHarnessV1::DeepseekHarness => {
                "worker-dependency-selection/deepseek_harness"
            }
            crate::delegation::WorkerHarnessV1::CodexCli => "worker-dependency-selection/codex_cli",
            crate::delegation::WorkerHarnessV1::ClaudeCode => {
                "worker-dependency-selection/claude_code"
            }
        };
        if spec.schema_version.major != crate::CHANGE_SPEC_SCHEMA_V1.major
            || spec.command_id != "worker.dependencies.select"
            || spec.resource_id.as_deref() != Some(resource)
            || spec.desired_state != serde_json::to_value(&change.after_selection)?
            || change.after_revision().is_none()
        {
            return Err(OperationValidationError::UnregisteredEffectPlan);
        }
        Ok(Self {
            spec,
            control: json!({}),
            credential_pool: None,
            worker_dependency_selection: Some(change),
            secrets: Vec::new(),
            agent_access_grants: Vec::new(),
            runtime: Vec::new(),
            external: Vec::new(),
        })
    }

    pub fn spec(&self) -> &ChangeSpecV1 {
        &self.spec
    }

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

    pub fn credential_pool(&self) -> Option<&CredentialPoolMutationV1> {
        self.credential_pool.as_ref()
    }

    pub fn worker_dependency_selection(&self) -> Option<&WorkerDependencySelectionChangeV1> {
        self.worker_dependency_selection.as_ref()
    }

    pub fn compute_source(&self) -> Option<ComputeSourceMutationV1> {
        (self.spec.command_id == "compute.connection.apply")
            .then(|| compute::decode_source_mutation(&self.spec, &self.control).ok())
            .flatten()
    }

    pub fn secrets(&self) -> &[SecretMutationV1] {
        &self.secrets
    }

    pub fn agent_access_grants(&self) -> &[AgentAccessGrantMutationV1] {
        &self.agent_access_grants
    }

    pub fn runtime(&self) -> &[RuntimeMutationV1] {
        &self.runtime
    }

    pub fn external(&self) -> &[ExternalEffectIntentV1] {
        &self.external
    }
}

/// Keeps the cross-crate planner seam fail-closed until formal command DTO owners add another
/// registered variant. Public callers cannot turn arbitrary JSON into an internal effects DSL.
fn validate_registered_plan(
    spec: &ChangeSpecV1,
    control: &Value,
    credential_pool: Option<&CredentialPoolMutationV1>,
    secrets: &[SecretMutationV1],
    runtime: &[RuntimeMutationV1],
    external: &[ExternalEffectIntentV1],
) -> Result<(), OperationValidationError> {
    if spec.schema_version.major != crate::CHANGE_SPEC_SCHEMA_V1.major
        // Routing content has its own exact, typed validator. A REST classifier
        // endpoint is legitimate there and must survive durable reconstruction.
        || (!matches!(spec.command_id.as_str(), "routing.apply" | "decision.services.apply") && contains_disabled_or_url(&spec.desired_state))
        || spec
            .resource_id
            .as_deref()
            .is_some_and(|resource| resource.contains("://") || resource.contains("//"))
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    match spec.command_id.as_str() {
        "decision.services.apply" => decision_service::validate_plan(
            spec,
            control,
            credential_pool,
            secrets,
            runtime,
            external,
        ),
        "setup.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            validate_registered_setup_plan(spec, control, secrets, runtime, external)
        }
        "compute.connection.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            compute::validate_connection_plan(spec, control, secrets, runtime, external)
        }
        "compute.credential.add" | "compute.credential.replace" | "compute.credential.remove" => {
            compute::validate_credential_plan(
                spec,
                control,
                credential_pool,
                secrets,
                runtime,
                external,
            )
        }
        "compute.key-pool.apply" => compute::validate_control_only_plan(
            spec,
            control,
            credential_pool,
            secrets,
            runtime,
            external,
        ),
        "prices.override.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            if spec.desired_state.get("schema").and_then(Value::as_str)
                == Some(crate::SOURCE_PRICE_CHANGE_SCHEMA_V2)
            {
                source_price::validate_plan(spec, control, secrets, runtime, external)
            } else {
                compute::validate_control_only_plan(spec, control, None, secrets, runtime, external)
            }
        }
        "agents.connect.apply" | "agents.restore.apply" | "agents.settings.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            agent_connection::validate_plan(spec, control, secrets, runtime, external)
        }
        "agents.config-permissions.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            agent_config_permission::validate_plan(spec, control, secrets, runtime, external)
        }
        "routing.apply" => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            routing::validate_plan(spec, control, secrets, runtime, external)
        }
        "routing.classifier.secret.apply" => validate_classifier_header_secret_plan(
            spec,
            control,
            credential_pool,
            secrets,
            runtime,
            external,
        ),
        COMPUTE_SUBSCRIPTION_CHECK_COMMAND_ID_V2 => {
            if credential_pool.is_some() {
                return Err(OperationValidationError::UnregisteredEffectPlan);
            }
            subscription_check::validate_plan(spec, control, secrets, runtime, external)
        }
        _ => Err(OperationValidationError::UnregisteredEffectPlan),
    }
}

fn validate_classifier_header_secret_plan(
    spec: &ChangeSpecV1,
    control: &Value,
    credential_pool: Option<&CredentialPoolMutationV1>,
    secrets: &[SecretMutationV1],
    runtime: &[RuntimeMutationV1],
    external: &[ExternalEffectIntentV1],
) -> Result<(), OperationValidationError> {
    let input = spec
        .desired_state
        .as_object()
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    if input.len() != 3
        || input.keys().any(|key| {
            !matches!(
                key.as_str(),
                "secret_id" | "input_slot" | "expected_generation"
            )
        })
        || spec.resource_id.as_deref() != Some("personal/default")
        || credential_pool.is_some()
        || !runtime.is_empty()
        || !external.is_empty()
        || secrets.len() != 1
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let secret_id = input
        .get("secret_id")
        .and_then(Value::as_str)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let input_slot = input
        .get("input_slot")
        .and_then(Value::as_str)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let expected_generation = input
        .get("expected_generation")
        .and_then(Value::as_u64)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    validate_scope_identifier(secret_id)?;
    validate_scope_identifier(input_slot)?;
    let mutation = &secrets[0];
    let credential = mutation.credential();
    if mutation.kind() != SecretMutationKind::Upsert
        || mutation.input_slot() != Some(input_slot)
        || mutation.expected_generation() != expected_generation
        || credential.credential_id() != secret_id
        || credential.owner_scope() != "personal/default"
        || credential.subject() != "hirouted"
        || credential.purpose() != "http-header"
        || !credential.allowed_destinations().is_empty()
        || credential.generation() != expected_generation
        || control != &json!({"classifier_header_secret": secret_id})
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    Ok(())
}

fn validate_registered_setup_plan(
    spec: &ChangeSpecV1,
    control: &Value,
    secrets: &[SecretMutationV1],
    runtime: &[RuntimeMutationV1],
    external: &[ExternalEffectIntentV1],
) -> Result<(), OperationValidationError> {
    let input = spec
        .desired_state
        .as_object()
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    if input.keys().any(|key| {
        !matches!(
            key.as_str(),
            "connection_option_id" | "secret" | "runtime_expected_generation"
        )
    }) {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let connection_option_id = input
        .get("connection_option_id")
        .and_then(Value::as_str)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    validate_scope_identifier(connection_option_id)?;
    if control != &json!({"connection_option_id": connection_option_id}) {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let expected_runtime_generation = match input.get("runtime_expected_generation") {
        Some(value) => value
            .as_u64()
            .ok_or(OperationValidationError::UnregisteredEffectPlan)?,
        None => 0,
    };
    if runtime.len() != 1
        || runtime[0].key != "active/setup"
        || runtime[0].value != json!({"ready": true})
        || runtime[0].expected_generation != expected_runtime_generation
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    if external.len() != 2
        || !external.iter().any(is_registered_setup_publication)
        || !external.iter().any(is_registered_setup_agent)
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    validate_registered_setup_secret(connection_option_id, input.get("secret"), secrets)
}

fn validate_registered_setup_secret(
    connection_option_id: &str,
    input: Option<&Value>,
    secrets: &[SecretMutationV1],
) -> Result<(), OperationValidationError> {
    let Some(input) = input.filter(|value| !value.is_null()) else {
        return if secrets.is_empty() {
            Ok(())
        } else {
            Err(OperationValidationError::UnregisteredEffectPlan)
        };
    };
    let input = input
        .as_object()
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    if input
        .keys()
        .any(|key| !matches!(key.as_str(), "input_slot" | "expected_generation"))
        || secrets.len() != 1
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    let input_slot = input
        .get("input_slot")
        .and_then(Value::as_str)
        .ok_or(OperationValidationError::UnregisteredEffectPlan)?;
    let expected_generation = match input.get("expected_generation") {
        Some(value) => value
            .as_u64()
            .ok_or(OperationValidationError::UnregisteredEffectPlan)?,
        None => 0,
    };
    let secret = &secrets[0];
    let credential = secret.credential();
    if secret.kind() != SecretMutationKind::Upsert
        || secret.expected_generation() != expected_generation
        || secret.input_slot() != Some(input_slot)
        || credential.credential_id() != format!("credential/{connection_option_id}")
        || credential.owner_scope() != format!("connection/{connection_option_id}")
        || credential.subject() != "hirouted"
        || credential.purpose() != "provider-auth"
        || credential.allowed_destinations() != &BTreeSet::from(["provider-api".to_owned()])
        || credential.generation() != expected_generation
    {
        return Err(OperationValidationError::UnregisteredEffectPlan);
    }
    Ok(())
}

fn is_registered_setup_publication(effect: &ExternalEffectIntentV1) -> bool {
    effect.kind == OwnedEffectKind::Publication
        && effect.effect_id == "publication-setup"
        && effect.target == "publication/current"
        && *effect.desired == json!({"setup": "active"})
        && effect.desired_mode == 0o644
        && !effect.sensitive
}

fn is_registered_setup_agent(effect: &ExternalEffectIntentV1) -> bool {
    effect.kind == OwnedEffectKind::AgentArtifact
        && effect.effect_id == "agent-setup"
        && effect.target == "agents/codex"
        && *effect.desired == json!({"configured": true})
        && effect.desired_mode == 0o640
        && !effect.sensitive
}

fn contains_disabled_or_url(value: &Value) -> bool {
    match value {
        Value::Object(object) => object.iter().any(|(key, value)| {
            disabled_plan_token(key)
                || contains_disabled_or_url(value)
                || value.as_str().is_some_and(|text| {
                    disabled_plan_token(text) || text.contains("://") || text.starts_with("//")
                })
        }),
        Value::Array(values) => values.iter().any(contains_disabled_or_url),
        Value::String(value) => {
            disabled_plan_token(value) || value.contains("://") || value.starts_with("//")
        }
        _ => false,
    }
}

fn disabled_plan_token(value: &str) -> bool {
    let normalized = value
        .chars()
        .filter(|character| character.is_ascii_alphanumeric())
        .flat_map(char::to_lowercase)
        .collect::<String>();
    matches!(
        normalized.as_str(),
        "budgetedpaid"
            | "paidbudgetspec"
            | "budgetquote"
            | "budgetlease"
            | "cashbudget"
            | "cashbudgetlimit"
            | "debt"
            | "externalsource"
    )
}

/// A bearer capability received over the authenticated local transport. The bytes are
/// zeroized and this type intentionally has no serde or cloning surface.
pub struct ProtectedApplyCapability(Zeroizing<Vec<u8>>);

impl ProtectedApplyCapability {
    pub fn new(value: String) -> Result<Self, OperationValidationError> {
        if value.is_empty() || value.len() > 4096 {
            return Err(OperationValidationError::InvalidApplyCapability);
        }
        Ok(Self(Zeroizing::new(value.into_bytes())))
    }

    pub fn expose(&self) -> &[u8] {
        self.0.as_slice()
    }
}

/// Exact authorization established by a trusted capability verifier. The absence of serde and
/// private fields keep raw wire principals/capabilities out of the transaction engine.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VerifiedApplyAuthorizationV1 {
    capability_digest: CanonicalDigest,
    principal: String,
    workspace_id: WorkspaceId,
    operation_kind: String,
    accepted_digest: CanonicalDigest,
    expected_revisions_digest: CanonicalDigest,
    scope: String,
    expires_at_unix: i64,
}

impl VerifiedApplyAuthorizationV1 {
    #[allow(clippy::too_many_arguments)]
    pub fn from_capability_verifier(
        capability_digest: CanonicalDigest,
        principal: impl Into<String>,
        workspace_id: WorkspaceId,
        operation_kind: impl Into<String>,
        accepted_digest: CanonicalDigest,
        expected_revisions_digest: CanonicalDigest,
        scope: impl Into<String>,
        expires_at_unix: i64,
    ) -> Result<Self, OperationValidationError> {
        let verified = Self {
            capability_digest,
            principal: principal.into(),
            workspace_id,
            operation_kind: operation_kind.into(),
            accepted_digest,
            expected_revisions_digest,
            scope: scope.into(),
            expires_at_unix,
        };
        validate_scope_identifier(&verified.principal)?;
        validate_scope_identifier(&verified.operation_kind)?;
        validate_scope_identifier(&verified.scope)?;
        Ok(verified)
    }

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

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

    pub fn workspace_id(&self) -> &WorkspaceId {
        &self.workspace_id
    }

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

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

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

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

    pub const fn expires_at_unix(&self) -> i64 {
        self.expires_at_unix
    }

    pub fn matches_operation(&self, operation: &OperationV1) -> bool {
        self.principal == operation.idempotency.principal
            && self.workspace_id == operation.workspace_id
            && self.operation_kind == operation.idempotency.operation_kind
            && self.accepted_digest == operation.accepted_digest
            && CanonicalDigest::of(&operation.expected_revisions)
                .is_ok_and(|digest| digest == self.expected_revisions_digest)
    }
}

#[derive(schemars::JsonSchema, Clone, Debug, Serialize)]
pub struct OperationV1 {
    #[serde(skip)]
    journal_checkpoint: Option<Arc<journal::JournalCheckpoint>>,
    pub schema_version: u16,
    pub operation_id: OperationId,
    pub workspace_id: WorkspaceId,
    pub idempotency: IdempotencyScopeV1,
    pub request_digest: CanonicalDigest,
    pub accepted_digest: CanonicalDigest,
    pub expected_revisions: RevisionSetV1,
    #[serde(serialize_with = "stored::serialize_plan")]
    #[schemars(with = "StoredOperationInputV1")]
    pub plan: Arc<TransactionPlanV1>,
    pub state: OperationState,
    pub generation: u64,
    pub steps: Vec<OperationStepV1>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub safe_error_code: Option<String>,
}

/// Read-only status, deliberately insufficient to execute or authorize an Operation.
#[derive(Clone, Debug, PartialEq)]
pub struct OperationStatus {
    pub model_budget_conflict: Option<crate::AgentModelBudgetConflictV1>,
    pub operation_id: OperationId,
    pub state: OperationState,
    pub generation: u64,
    pub accepted_digest: CanonicalDigest,
    pub safe_error_code: Option<String>,
}

impl OperationV1 {
    pub fn model_budget_conflict(&self) -> Option<crate::AgentModelBudgetConflictV1> {
        if !matches!(
            self.safe_error_code.as_deref(),
            Some("QODER_MODEL_BUDGET_CONFLICT" | "AGENT_MODEL_BUDGET_CONFLICT")
        ) {
            return None;
        }
        self.steps
            .iter()
            .filter_map(|step| step.terminal_result.as_deref())
            .find_map(crate::AgentModelBudgetConflictV1::parse)
    }

    #[allow(clippy::too_many_arguments)]
    pub fn new(
        operation_id: OperationId,
        workspace_id: WorkspaceId,
        idempotency: IdempotencyScopeV1,
        request_digest: CanonicalDigest,
        accepted_digest: CanonicalDigest,
        expected_revisions: RevisionSetV1,
        plan: TransactionPlanV1,
    ) -> Result<Self, OperationValidationError> {
        let facts = StoredOperationInputV1::freeze(&plan)?;
        let step_inputs = facts.step_inputs(
            &accepted_digest,
            &expected_revisions,
            &plan.agent_access_grants,
        )?;
        let steps = OperationStepKind::ALL
            .into_iter()
            .zip(step_inputs)
            .enumerate()
            .map(|(index, (kind, input))| {
                Ok(OperationStepV1 {
                    sequence: u16::try_from(index).expect("six steps fit in u16"),
                    kind,
                    deterministic_input_digest: CanonicalDigest::of(&(
                        "hiroute.operation-step-input/v1",
                        kind,
                        input,
                    ))?,
                    status: OperationStepStatus::Pending,
                    attempts: 0,
                    effects: Vec::new(),
                    terminal_result: None,
                })
            })
            .collect::<Result<Vec<_>, OperationValidationError>>()?;
        let mut operation = Self {
            journal_checkpoint: None,
            schema_version: OPERATION_SCHEMA_VERSION,
            operation_id,
            workspace_id,
            idempotency,
            request_digest,
            accepted_digest,
            expected_revisions,
            plan: Arc::new(plan),
            state: OperationState::Accepted,
            generation: 0,
            steps,
            safe_error_code: None,
        };
        operation.establish_journal_checkpoint()?;
        Ok(operation)
    }

    pub fn stable_input_digest(&self) -> Result<CanonicalDigest, OperationValidationError> {
        StoredOperationInputV1::freeze(&self.plan)?.digest()
    }

    pub fn transition(&mut self, next: OperationState) -> Result<(), OperationValidationError> {
        if !self.state.can_transition_to(next) {
            return Err(OperationValidationError::InvalidTransition {
                from: self.state,
                to: next,
            });
        }
        self.state = next;
        Ok(())
    }

    pub fn step(&self, kind: OperationStepKind) -> &OperationStepV1 {
        self.steps
            .iter()
            .find(|step| step.kind == kind)
            .expect("every operation has the fixed six-step journal")
    }

    pub fn step_mut(&mut self, kind: OperationStepKind) -> &mut OperationStepV1 {
        self.steps
            .iter_mut()
            .find(|step| step.kind == kind)
            .expect("every operation has the fixed six-step journal")
    }

    /// Restores journal-only mutable fields after an owner-controlled durable decoder has
    /// reconstructed and validated the immutable operation inputs.
    pub fn restore_durable_state(
        &mut self,
        state: OperationState,
        generation: u64,
        steps: Vec<OperationStepV1>,
        safe_error_code: Option<String>,
    ) -> Result<(), OperationValidationError> {
        if steps.len() != OperationStepKind::ALL.len()
            || steps
                .iter()
                .zip(OperationStepKind::ALL)
                .enumerate()
                .any(|(index, (step, kind))| {
                    step.sequence != u16::try_from(index).expect("six steps fit in u16")
                        || step.kind != kind
                        || step.deterministic_input_digest
                            != self.steps[index].deterministic_input_digest
                })
        {
            return Err(OperationValidationError::InvalidDurableJournal);
        }
        self.state = state;
        self.generation = generation;
        self.steps = steps;
        self.safe_error_code = safe_error_code;
        self.establish_journal_checkpoint()?;
        Ok(())
    }
}

pub fn validate_idempotency_key(value: &str) -> Result<(), OperationValidationError> {
    let valid = !value.is_empty()
        && value.len() <= 200
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b':' | b'-'));
    if valid {
        Ok(())
    } else {
        Err(OperationValidationError::InvalidIdempotencyKey)
    }
}

pub(super) fn validate_scope_identifier(value: &str) -> Result<(), OperationValidationError> {
    let valid = !value.is_empty()
        && value.len() <= 256
        && !value.contains("..")
        && !value.contains("//")
        && value.bytes().all(|byte| {
            byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'.' | b'_' | b':' | b'-')
        });
    if valid {
        Ok(())
    } else {
        Err(OperationValidationError::InvalidIdempotencyScope)
    }
}

#[derive(Debug, Error)]
pub enum OperationValidationError {
    #[error("operation id is malformed")]
    InvalidOperationId,
    #[error("idempotency scope contains an invalid principal or operation kind")]
    InvalidIdempotencyScope,
    #[error("idempotency key is not a bounded portable identifier")]
    InvalidIdempotencyKey,
    #[error("protected Secret input must not be empty")]
    EmptyProtectedSecret,
    #[error("apply capability is empty or unbounded")]
    InvalidApplyCapability,
    #[error("CredentialRef is incomplete or has no allowed destination")]
    InvalidCredentialRef,
    #[error("AgentAccessGrant material is not canonical 256-bit base64url")]
    InvalidAgentAccessGrantMaterial,
    #[error("AgentAccessGrant scope is incomplete or invalid")]
    InvalidAgentAccessGrantScope,
    #[error("AgentAccessGrant mutation is inconsistent")]
    InvalidAgentAccessGrantMutation,
    #[error("AgentAccessGrantRef is incomplete or invalid")]
    InvalidAgentAccessGrantRef,
    #[error("effect intent is not owned by the registered adapter")]
    InvalidExternalEffect,
    #[error("internal effects do not match a registered typed planner")]
    UnregisteredEffectPlan,
    #[error("artifact mode is outside the supported POSIX policy")]
    InvalidArtifactMode,
    #[error("durable Operation journal does not match its immutable plan")]
    InvalidDurableJournal,
    #[error("invalid operation transition from {from:?} to {to:?}")]
    InvalidTransition {
        from: OperationState,
        to: OperationState,
    },
    #[error("operation plan cannot be serialized: {0}")]
    Serialization(#[from] serde_json::Error),
    #[error("operation step digest cannot be computed: {0}")]
    Digest(#[from] crate::CanonicalDigestError),
}

#[derive(Clone, Debug, PartialEq)]
pub enum BeginOperationOutcome {
    Created,
    ExistingSame(Box<OperationV1>),
    ExistingDifferent,
    RevisionChanged(RevisionMismatch),
}

#[derive(Clone, Debug, PartialEq)]
pub enum EffectReconciliation {
    Missing,
    /// An immutable Operation-owned version exists, but is not yet visible through committed
    /// readers. Only the Activate step may publish it.
    Staged(OwnedEffectV1),
    Applied(OwnedEffectV1),
    /// The durable marker identifies the exact effect, but the target fingerprint no longer
    /// proves that this Operation owns the current bytes/state.
    OwnershipLost(OwnedEffectV1),
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CompensationOutcome {
    Compensated,
    AlreadyCompensated,
    OwnershipLost,
}

/// Secret bytes never implement `Debug`, `Clone`, `Serialize`, or `Deserialize`.
pub struct ProtectedSecret(Zeroizing<Vec<u8>>);

impl ProtectedSecret {
    pub fn new(bytes: Vec<u8>) -> Result<Self, OperationValidationError> {
        if bytes.is_empty() {
            return Err(OperationValidationError::EmptyProtectedSecret);
        }
        Ok(Self(Zeroizing::new(bytes)))
    }

    pub fn expose(&self) -> &[u8] {
        self.0.as_slice()
    }
}

pub trait ControlRepositoryPort {
    fn current_revisions(&self, workspace: &WorkspaceId) -> PortResult<RevisionSetV1>;
    fn operation_for_idempotency(
        &self,
        workspace: &WorkspaceId,
        scope: &IdempotencyScopeV1,
    ) -> PortResult<Option<OperationV1>>;
    fn verify_apply_authorization(
        &self,
        capability: &ProtectedApplyCapability,
        workspace: &WorkspaceId,
        principal: &str,
        operation_kind: &str,
        accepted_digest: &CanonicalDigest,
        expected_revisions: &RevisionSetV1,
    ) -> PortResult<VerifiedApplyAuthorizationV1>;
    /// Consumes the capability and admits the Operation in the same durable transaction.
    fn begin_operation(
        &self,
        operation: &OperationV1,
        authorization: &VerifiedApplyAuthorizationV1,
    ) -> PortResult<BeginOperationOutcome>;
    /// Admits one Released mutation after the owner-only Local Control transport has verified the
    /// peer UID. Implementations must preserve the same atomic writer claim, revision CAS, and
    /// idempotency checks as capability-backed admission.
    fn begin_local_operation(&self, _operation: &OperationV1) -> PortResult<BeginOperationOutcome> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "control.local_operation.unsupported",
        ))
    }
    /// Check a value loaded or committed by this writer against the current durable generation.
    /// This does not authorize an Operation or substitute for cold recovery decoding.
    fn operation_is_current(&self, operation: &OperationV1) -> PortResult<bool>;
    fn load_operation(&self, operation_id: &OperationId) -> PortResult<Option<OperationV1>>;
    fn recoverable_operations(&self) -> PortResult<Vec<OperationV1>>;
    /// True until startup reconciliation has resolved every admitted writer claim.
    fn writer_recovery_required(&self) -> PortResult<bool>;
    fn save_operation(&self, operation: &mut OperationV1) -> PortResult<()>;
    /// Reads the independent CAS head for one daemon-local Worker harness. Unselected is revision
    /// zero; this head is deliberately not part of the workspace desired-state revision.
    fn worker_dependency_selection_revision(
        &self,
        _workspace: &WorkspaceId,
        _harness: crate::delegation::WorkerHarnessV1,
    ) -> PortResult<u64> {
        Err(crate::PortError::new(
            crate::PortErrorCode::Unavailable,
            "control.worker_dependency_selection.unsupported",
        ))
    }
    /// Stages the exact protected Worker dependency CAS as this Operation's Control effect.
    fn apply_worker_dependency_selection(
        &self,
        _operation_id: &OperationId,
        _workspace: &WorkspaceId,
        _change: &WorkerDependencySelectionChangeV1,
    ) -> PortResult<OwnedEffectV1> {
        Err(crate::PortError::new(
            crate::PortErrorCode::Unavailable,
            "control.worker_dependency_selection.unsupported",
        ))
    }
    fn apply_control(
        &self,
        operation_id: &OperationId,
        workspace: &WorkspaceId,
        expected_revision: u64,
        desired: &Value,
    ) -> PortResult<OwnedEffectV1>;
    fn observe_control(
        &self,
        operation_id: &OperationId,
        workspace: &WorkspaceId,
    ) -> PortResult<EffectReconciliation>;
    fn activate_control(&self, effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1>;
    fn compensate_control(&self, effect: &OwnedEffectV1) -> PortResult<CompensationOutcome>;
    /// Converges exact managed-source references after authenticated Secret compensation,
    /// while this operation still owns the writer. Must be CAS-protected and idempotent.
    fn reconcile_compute_compensation(
        &self,
        _operation: &OperationV1,
        _references: &[CredentialRefV1],
    ) -> PortResult<()> {
        Err(crate::PortError::new(
            crate::PortErrorCode::Unavailable,
            "control.compute_compensation.unsupported",
        ))
    }
    /// Persists a terminal state and releases the durable single-writer claim when safe.
    fn finish_operation(&self, operation: &mut OperationV1) -> PortResult<u64>;
    /// Persists a non-terminal settings tail and atomically releases this operation's writer
    /// claim in the same control transaction. Fails when another operation holds the claim.
    fn save_operation_tail(&self, operation: &mut OperationV1) -> PortResult<()>;
    /// Re-acquires the durable writer claim for an explicit same-operation retry when the claim
    /// is free or already owned by this operation.
    fn reclaim_operation_writer(&self, operation_id: &OperationId) -> PortResult<()>;
    /// Persists the current trusted live-check result for one settings context and surface.
    /// The write is silently dropped (returning false) when the installed publication no longer
    /// matches the checked revision, so a stale check never pollutes a newer publication.
    fn save_agent_surface_check(
        &self,
        workspace: &WorkspaceId,
        record: &crate::AgentSurfaceCheckRecordV1,
    ) -> PortResult<bool>;
    /// Reads the current live-check records for one settings context, one per surface.
    fn agent_surface_checks(
        &self,
        workspace: &WorkspaceId,
        context_id: &str,
    ) -> PortResult<Vec<crate::AgentSurfaceCheckRecordV1>>;
}

/// Typed staging seam for a CredentialPool control CAS. The resulting effect remains the single
/// Control effect in the Operation journal, so Secret and pool changes share activation/rollback.
pub trait CredentialPoolControlPort {
    fn apply_credential_pool(
        &self,
        operation_id: &OperationId,
        workspace: &WorkspaceId,
        expected_target_revision: u64,
        mutation: &CredentialPoolMutationV1,
    ) -> PortResult<OwnedEffectV1>;
}

/// Typed staging seam for the sealed compute-source CAS. Storage must stage this mutation in the
/// same Control effect as workspace desired state and activate or compensate both together.
pub trait ComputeSourceControlPort {
    fn apply_compute_source(
        &self,
        operation_id: &OperationId,
        workspace: &WorkspaceId,
        expected_target_revision: u64,
        mutation: &ComputeSourceMutationV1,
    ) -> PortResult<OwnedEffectV1>;
}

pub trait SecretStorePort {
    fn generation(&self, credential: &CredentialRefV1) -> PortResult<u64>;
    fn fingerprint(&self, secret: &ProtectedSecret) -> PortResult<CanonicalDigest>;
    fn resolve_secret(
        &self,
        subject: &VerifiedSecretSubjectV1,
        credential: &CredentialRefV1,
        purpose: &str,
        destination: &str,
        expected_generation: u64,
    ) -> PortResult<ProtectedSecret>;
    fn apply_secret(
        &self,
        operation_id: &OperationId,
        mutation: &SecretMutationV1,
        input: Option<&ProtectedSecret>,
    ) -> PortResult<OwnedEffectV1>;
    fn observe_secret(
        &self,
        operation_id: &OperationId,
        mutation: &SecretMutationV1,
    ) -> PortResult<EffectReconciliation>;
    fn activate_secret(&self, effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1>;
    fn compensate_secret(&self, effect: &OwnedEffectV1) -> PortResult<CompensationOutcome>;
    /// Proves the currently restored reference using this exact compensated effect.
    /// Missing/unactivated effects may retain the original generation; a newer owner fails.
    fn compensated_secret_reference(
        &self,
        _operation_id: &OperationId,
        _mutation: &SecretMutationV1,
    ) -> PortResult<Option<CredentialRefV1>> {
        Err(crate::PortError::new(
            crate::PortErrorCode::Unavailable,
            "secret.compensation_reference.unsupported",
        ))
    }

    /// Reads only non-secret metadata for one exact canonical connection. Adapters that have not
    /// implemented the dedicated grant store fail closed instead of treating it as a Provider
    /// CredentialRef.
    fn inspect_agent_access_grant(
        &self,
        _owner_scope: &str,
        _connection_id: &str,
    ) -> PortResult<Option<AgentAccessGrantRefV1>> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.inspect.unsupported",
        ))
    }

    fn resolve_agent_access_grant(
        &self,
        _reference: &AgentAccessGrantRefV1,
    ) -> PortResult<AgentAccessGrantMaterial> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.resolve.unsupported",
        ))
    }

    fn apply_agent_access_grant(
        &self,
        _operation_id: &OperationId,
        _mutation: &AgentAccessGrantMutationV1,
        _input: Option<&ProtectedSecret>,
    ) -> PortResult<OwnedEffectV1> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.apply.unsupported",
        ))
    }

    fn observe_agent_access_grant(
        &self,
        _operation_id: &OperationId,
        _mutation: &AgentAccessGrantMutationV1,
    ) -> PortResult<EffectReconciliation> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.observe.unsupported",
        ))
    }

    fn activate_agent_access_grant(&self, _effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.activate.unsupported",
        ))
    }

    fn compensate_agent_access_grant(
        &self,
        _effect: &OwnedEffectV1,
    ) -> PortResult<CompensationOutcome> {
        Err(crate::PortError::new(
            crate::PortErrorCode::PermissionDenied,
            "agent_access_grant.compensate.unsupported",
        ))
    }
}

pub trait RuntimeStatePort {
    fn generation(&self, key: &str) -> PortResult<u64>;
    fn apply_runtime(
        &self,
        operation_id: &OperationId,
        mutation: &RuntimeMutationV1,
    ) -> PortResult<OwnedEffectV1>;
    fn observe_runtime(
        &self,
        operation_id: &OperationId,
        mutation: &RuntimeMutationV1,
    ) -> PortResult<EffectReconciliation>;
    fn activate_runtime(&self, effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1>;
    fn compensate_runtime(&self, effect: &OwnedEffectV1) -> PortResult<CompensationOutcome>;
}

/// Versioned adapter boundary for the sole writable compute-runtime authority.
pub trait ComputeRuntimeStateStoreV1 {
    fn runtime_state(
        &self,
        identity: &RuntimeStateIdentityV1,
    ) -> PortResult<Option<RuntimeStateV1>>;

    fn compare_and_set_runtime_state(
        &self,
        expected_generation: u64,
        state: &RuntimeStateV1,
    ) -> PortResult<()>;

    fn acquire_runtime_probe(
        &self,
        identity: &RuntimeStateIdentityV1,
        expected_generation: u64,
        request: &RuntimeProbeLeaseRequestV1,
    ) -> PortResult<RuntimeProbeAcquireOutcomeV1>;

    fn complete_runtime_probe(
        &self,
        lease: &RuntimeProbeLeaseV1,
        state: &RuntimeStateV1,
    ) -> PortResult<()>;
}

pub trait ExternalEffectPort {
    /// Install committed source prices before the coordinator reports success. Only the
    /// production control adapter can rebuild this process-local immutable snapshot.
    fn install_source_price_snapshot(
        &self,
        _operation: &OperationV1,
    ) -> PortResult<crate::PriceGenerationRefV1> {
        Err(crate::PortError::new(
            crate::PortErrorCode::Unavailable,
            "prices.snapshot.unwired",
        ))
    }

    fn validate_external_admission(&self, _intent: &ExternalEffectIntentV1) -> PortResult<()> {
        Ok(())
    }
    /// Close new publication pins before activating any of this operation's effects.
    fn begin_publication_activation(&self, _operation: &OperationV1) -> PortResult<()> {
        Ok(())
    }
    /// The coordinator persists this checkpoint before asking the adapter to install it.
    fn prepare_publication_activation(
        &self,
        _operation: &OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1> {
        Ok(effect.clone())
    }
    /// Return a durable abort checkpoint only when rollback cannot invalidate a live target.
    /// Unavailable preserves the running journal for restart; Conflict requires repair.
    fn prepare_publication_rollback(
        &self,
        _operation: &OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1> {
        Ok(effect.clone())
    }
    fn finish_publication_activation(&self, _operation: &OperationV1) -> PortResult<()> {
        Ok(())
    }
    /// Persist adapter-owned activation metadata from the admitted plan. Runs under the
    /// existing writer, including replay of an artifact that is already applied.
    fn prepare_agent_artifact_activation(
        &self,
        _operation: &OperationV1,
        _intent: &ExternalEffectIntentV1,
    ) -> PortResult<()> {
        Ok(())
    }
    fn current_external_fingerprint(&self, target: &str) -> PortResult<Option<CanonicalDigest>>;
    fn apply_external(
        &self,
        operation: &OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<OwnedEffectV1>;
    fn observe_external(
        &self,
        operation: &OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<EffectReconciliation>;
    fn activate_external(
        &self,
        _operation: &OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1>;
    fn compensate_external(
        &self,
        _operation: &OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<CompensationOutcome>;
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeMap;

    use serde_json::json;

    use super::*;
    use crate::{CHANGE_SPEC_SCHEMA_V1, RevisionSetV1};

    fn operation() -> OperationV1 {
        let workspace = WorkspaceId::default();
        let request_digest = CanonicalDigest::of_bytes(b"operation-request");
        let accepted_digest = CanonicalDigest::of_bytes(b"operation-change");
        let scope = IdempotencyScopeV1::new("interactive-user", "ApplySetup", "idem-1")
            .expect("valid scope");
        OperationV1::new(
            OperationId::derive(&workspace, &scope, &request_digest),
            workspace,
            scope,
            request_digest,
            accepted_digest,
            RevisionSetV1 {
                target: 0,
                dependencies: BTreeMap::new(),
            },
            TransactionPlanV1::from_registered_typed_planner(
                ChangeSpecV1 {
                    schema_version: CHANGE_SPEC_SCHEMA_V1,
                    command_id: "setup.apply".to_owned(),
                    resource_id: None,
                    desired_state: json!({"connection_option_id": "source-a"}),
                },
                json!({"connection_option_id": "source-a"}),
                None,
                Vec::new(),
                vec![
                    RuntimeMutationV1::from_registered_planner(
                        "active/setup",
                        json!({"ready": true}),
                        0,
                    )
                    .unwrap(),
                ],
                vec![
                    ExternalEffectIntentV1::from_registered_adapter(
                        "publication-setup",
                        OwnedEffectKind::Publication,
                        "publication/current",
                        None,
                        json!({"setup": "active"}),
                        0o644,
                        false,
                    )
                    .unwrap(),
                    ExternalEffectIntentV1::from_registered_adapter(
                        "agent-setup",
                        OwnedEffectKind::AgentArtifact,
                        "agents/codex",
                        None,
                        json!({"configured": true}),
                        0o640,
                        false,
                    )
                    .unwrap(),
                ],
            )
            .unwrap(),
        )
        .unwrap()
    }

    #[test]
    fn operation_has_exact_deterministic_step_plan() {
        let first = operation();
        let second = operation();
        assert_eq!(first.steps, second.steps);
        assert_eq!(
            first.steps.iter().map(|step| step.kind).collect::<Vec<_>>(),
            OperationStepKind::ALL
        );
    }

    #[test]
    fn operation_id_is_scoped_to_principal_kind_key_and_request() {
        let operation = operation();
        let mut different = operation.idempotency.clone();
        different.principal = "desktop".to_owned();
        assert_ne!(
            operation.operation_id,
            OperationId::derive(
                &operation.workspace_id,
                &different,
                &operation.request_digest
            )
        );
    }

    #[test]
    fn operation_terminal_state_is_unique_and_transition_checked() {
        let mut operation = operation();
        for state in [
            OperationState::Preparing,
            OperationState::ApplyingSecrets,
            OperationState::MaterializingSources,
            OperationState::CompilingPublication,
            OperationState::ApplyingAgentArtifacts,
            OperationState::Activating,
            OperationState::Succeeded,
        ] {
            operation.transition(state).unwrap();
        }
        assert!(operation.state.is_terminal());
        assert!(operation.transition(OperationState::RolledBack).is_err());
    }

    #[test]
    fn operation_rollback_can_only_end_rolled_back_or_attention() {
        for terminal in [OperationState::RolledBack, OperationState::NeedsAttention] {
            let mut operation = operation();
            operation.transition(OperationState::RollingBack).unwrap();
            operation.transition(terminal).unwrap();
            assert!(operation.state.is_terminal());
        }
    }

    #[test]
    fn protected_secret_has_a_distinct_empty_input_error_and_no_debug_surface() {
        assert!(matches!(
            ProtectedSecret::new(Vec::new()),
            Err(OperationValidationError::EmptyProtectedSecret)
        ));
    }

    #[test]
    fn generic_effect_values_are_not_a_registered_plan() {
        assert!(matches!(
            RuntimeMutationV1::from_registered_planner(
                "active/setup",
                json!({"target": "https://example.invalid"}),
                0,
            ),
            Err(OperationValidationError::UnregisteredEffectPlan)
        ));
        assert!(matches!(
            ExternalEffectIntentV1::from_registered_adapter(
                "agent-setup",
                OwnedEffectKind::AgentArtifact,
                "agents/codex",
                None,
                json!({"url": "https://example.invalid"}),
                0o640,
                false,
            ),
            Err(OperationValidationError::UnregisteredEffectPlan)
        ));
    }
}