feat: complete Epic 1 production foundation

crates/crank-runtime/src/auth.rs

@@ -6,7 +6,7 @@ use serde_json::Value;
 
 use crate::{PreparedRequest, RuntimeError};
 
-#[derive(Clone, Debug, PartialEq, Eq)]
+#[derive(Clone, PartialEq, Eq)]
 pub enum ResolvedAuth {
     Bearer { header_name: String, token: String },
     Basic { username: String, password: String },
@@ -14,11 +14,34 @@ pub enum ResolvedAuth {
     ApiKeyQuery { param_name: String, value: String },
 }
 
+impl std::fmt::Debug for ResolvedAuth {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let kind = match self {
+            Self::Bearer { .. } => "bearer",
+            Self::Basic { .. } => "basic",
+            Self::ApiKeyHeader { .. } => "api_key_header",
+            Self::ApiKeyQuery { .. } => "api_key_query",
+        };
+        formatter
+            .debug_struct("ResolvedAuth")
+            .field("kind", &kind)
+            .field("material", &"[REDACTED]")
+            .finish()
+    }
+}
+
 impl ResolvedAuth {
     pub fn from_profile(
         profile: &AuthProfile,
         secrets: &BTreeMap<SecretId, Value>,
     ) -> Result<Self, RuntimeError> {
+        if profile.kind != profile.config.kind() {
+            return Err(RuntimeError::InvalidAuthProfileConfig {
+                auth_profile_id: profile.id.as_str().to_owned(),
+                reason: "auth kind and config kind do not match".to_owned(),
+            });
+        }
+
         match &profile.config {
             AuthConfig::Bearer(config) => Ok(Self::Bearer {
                 header_name: config.header_name.clone(),
@@ -50,20 +73,32 @@ impl ResolvedAuth {
     pub fn apply(&self, prepared_request: &mut PreparedRequest) {
         match self {
             Self::Bearer { header_name, token } => {
+                remove_header_case_insensitive(&mut prepared_request.headers, header_name);
                 prepared_request
                     .headers
                     .insert(header_name.clone(), format!("Bearer {token}"));
+                prepared_request
+                    .trusted_header_names
+                    .insert(header_name.to_ascii_lowercase());
             }
             Self::Basic { username, password } => {
                 let credentials = STANDARD.encode(format!("{username}:{password}"));
+                remove_header_case_insensitive(&mut prepared_request.headers, "Authorization");
                 prepared_request
                     .headers
                     .insert("Authorization".to_owned(), format!("Basic {credentials}"));
+                prepared_request
+                    .trusted_header_names
+                    .insert("authorization".to_owned());
             }
             Self::ApiKeyHeader { header_name, value } => {
+                remove_header_case_insensitive(&mut prepared_request.headers, header_name);
                 prepared_request
                     .headers
                     .insert(header_name.clone(), value.clone());
+                prepared_request
+                    .trusted_header_names
+                    .insert(header_name.to_ascii_lowercase());
             }
             Self::ApiKeyQuery { param_name, value } => {
                 prepared_request
@@ -74,6 +109,17 @@ impl ResolvedAuth {
     }
 }
 
+fn remove_header_case_insensitive(headers: &mut BTreeMap<String, String>, header_name: &str) {
+    let existing = headers
+        .keys()
+        .filter(|candidate| candidate.eq_ignore_ascii_case(header_name))
+        .cloned()
+        .collect::<Vec<_>>();
+    for existing in existing {
+        headers.remove(&existing);
+    }
+}
+
 pub(crate) fn apply_resolved_auth(
     mut prepared_request: PreparedRequest,
     resolved_auth: Option<&ResolvedAuth>,
@@ -167,6 +213,95 @@ mod tests {
         );
     }
 
+    #[test]
+    fn bearer_auth_overwrites_untrusted_mapped_header_and_marks_it_trusted() {
+        let auth = ResolvedAuth::Bearer {
+            header_name: "Authorization".to_owned(),
+            token: "system-token".to_owned(),
+        };
+        let mut request = PreparedRequest {
+            headers: BTreeMap::from([
+                ("authorization".to_owned(), "Bearer attacker".to_owned()),
+                (
+                    "AUTHORIZATION".to_owned(),
+                    "Bearer second-attacker".to_owned(),
+                ),
+            ]),
+            ..PreparedRequest::default()
+        };
+
+        auth.apply(&mut request);
+
+        assert_eq!(
+            request.headers.get("Authorization").map(String::as_str),
+            Some("Bearer system-token")
+        );
+        assert!(!request.headers.contains_key("authorization"));
+        assert!(!request.headers.contains_key("AUTHORIZATION"));
+        assert!(request.trusted_header_names.contains("authorization"));
+    }
+
+    #[test]
+    fn api_key_header_auth_overwrites_untrusted_mapped_header_and_marks_it_trusted() {
+        let auth = ResolvedAuth::ApiKeyHeader {
+            header_name: "X-Api-Key".to_owned(),
+            value: "system-key".to_owned(),
+        };
+        let mut request = PreparedRequest {
+            headers: BTreeMap::from([
+                ("x-api-key".to_owned(), "attacker".to_owned()),
+                ("X-API-KEY".to_owned(), "second-attacker".to_owned()),
+            ]),
+            ..PreparedRequest::default()
+        };
+
+        auth.apply(&mut request);
+
+        assert_eq!(
+            request.headers.get("X-Api-Key").map(String::as_str),
+            Some("system-key")
+        );
+        assert!(!request.headers.contains_key("x-api-key"));
+        assert!(!request.headers.contains_key("X-API-KEY"));
+        assert!(request.trusted_header_names.contains("x-api-key"));
+    }
+
+    #[test]
+    fn rejects_auth_profile_kind_config_mismatch_before_secret_use() {
+        let error = ResolvedAuth::from_profile(
+            &AuthProfile {
+                id: "auth_01".into(),
+                workspace_id: WorkspaceId::new("ws_default"),
+                name: "mismatch".to_owned(),
+                kind: AuthKind::Bearer,
+                config: AuthConfig::ApiKeyHeader(ApiKeyHeaderAuthConfig {
+                    header_name: "X-Api-Key".to_owned(),
+                    secret_id: SecretId::new("secret_api_key"),
+                }),
+                created_at: timestamp("2026-04-07T00:00:00Z"),
+                updated_at: timestamp("2026-04-07T00:00:00Z"),
+            },
+            &BTreeMap::from([(SecretId::new("secret_api_key"), json!("key-123"))]),
+        )
+        .unwrap_err();
+
+        assert!(matches!(
+            error,
+            crate::RuntimeError::InvalidAuthProfileConfig { .. }
+        ));
+    }
+
+    #[test]
+    fn resolved_auth_debug_never_exposes_secret_material() {
+        let auth = ResolvedAuth::Bearer {
+            header_name: "Authorization".to_owned(),
+            token: "story18-secret-canary".to_owned(),
+        };
+        let rendered = format!("{auth:?}");
+        assert!(!rendered.contains("story18-secret-canary"));
+        assert!(rendered.contains("[REDACTED]"));
+    }
+
     #[test]
     fn applies_basic_auth_to_headers() {
         let auth = ResolvedAuth::from_profile(

crates/crank-runtime/src/error.rs

@@ -1,19 +1,28 @@
-use crank_adapter_rest::RestAdapterError;
-use crank_core::{ExecutionMode, OperationSafetyClass, Protocol};
+use crank_core::{ExecutionMode, OperationSafetyClass, Protocol, ProtocolAdapterError};
 use crank_mapping::MappingError;
 use crank_schema::SchemaError;
 use thiserror::Error;
 
 #[derive(Debug, Error)]
 pub enum RuntimeError {
+    #[error("execution request is invalid")]
+    InvalidExecutionRequest,
+    #[error("execution deadline elapsed")]
+    ExecutionDeadlineElapsed { may_have_dispatched: bool },
     #[error(transparent)]
     Schema(#[from] SchemaError),
     #[error(transparent)]
+    InputSchema(SchemaError),
+    #[error(transparent)]
+    OutputSchema(SchemaError),
+    #[error(transparent)]
     Mapping(#[from] MappingError),
     #[error(transparent)]
-    RestAdapter(#[from] RestAdapterError),
-    #[error("{0}")]
-    ProtocolAdapter(String),
+    InputMapping(MappingError),
+    #[error(transparent)]
+    OutputMapping(MappingError),
+    #[error(transparent)]
+    ProtocolAdapter(#[from] ProtocolAdapterError),
     #[error("protocol {protocol:?} is not supported by runtime")]
     UnsupportedProtocol { protocol: Protocol },
     #[error("operation {operation_id} does not support requested execution mode {mode:?}")]
@@ -46,8 +55,17 @@ pub enum RuntimeError {
     IdempotencyConflict { operation_id: String },
     #[error("the outcome of operation {operation_id} is unknown; automatic retry is unsafe")]
     IdempotencyOutcomeUnknown { operation_id: String },
+    #[error("idempotency completion is unavailable after operation {operation_id} dispatch")]
+    IdempotencyCompletionUnknown { operation_id: String },
+    #[error("authorization storage is unavailable")]
+    AuthorizationStoreUnavailable,
     #[error("auth profile {auth_profile_id} was not found")]
     MissingAuthProfile { auth_profile_id: String },
+    #[error("auth profile {auth_profile_id} is invalid: {reason}")]
+    InvalidAuthProfileConfig {
+        auth_profile_id: String,
+        reason: String,
+    },
     #[error("secret {secret_id} was not found")]
     MissingSecret { secret_id: String },
     #[error("secret {secret_id} does not have current version {version}")]

crates/crank-runtime/src/execution_failure.rs

@@ -0,0 +1,234 @@
+use crank_core::{
+    CorrelationContext, DispatchEvidence, ExecutionErrorCode, ExecutionFailure,
+    ProtocolAdapterError,
+};
+
+use crate::{RuntimeError, RuntimeOperation};
+
+pub fn normalize_runtime_error(
+    error: &RuntimeError,
+    correlation: &CorrelationContext,
+) -> ExecutionFailure {
+    normalize_runtime_error_with_effect(error, correlation, false)
+}
+
+pub fn normalize_runtime_error_for_operation(
+    error: &RuntimeError,
+    correlation: &CorrelationContext,
+    operation: &RuntimeOperation,
+) -> ExecutionFailure {
+    let may_mutate = matches!(
+        &operation.target,
+        crank_core::Target::Rest(target)
+            if matches!(
+                target.method,
+                crank_core::HttpMethod::Post
+                    | crank_core::HttpMethod::Put
+                    | crank_core::HttpMethod::Patch
+                    | crank_core::HttpMethod::Delete
+            )
+    );
+    normalize_runtime_error_with_effect(error, correlation, may_mutate)
+}
+
+fn normalize_runtime_error_with_effect(
+    error: &RuntimeError,
+    correlation: &CorrelationContext,
+    may_mutate: bool,
+) -> ExecutionFailure {
+    let mut failure = ExecutionFailure::new(error_code(error), correlation.clone());
+    match error {
+        RuntimeError::ProtocolAdapter(ProtocolAdapterError::UnexpectedStatus {
+            status, ..
+        }) => {
+            failure = failure.with_upstream_status(*status);
+        }
+        RuntimeError::ProtocolAdapter(adapter)
+            if may_mutate && ambiguous_after_dispatch(adapter) =>
+        {
+            failure = failure.with_dispatch_uncertainty();
+        }
+        RuntimeError::ExecutionDeadlineElapsed {
+            may_have_dispatched: true,
+        }
+        | RuntimeError::IdempotencyCompletionUnknown { .. } => {
+            failure = failure.with_dispatch_uncertainty();
+        }
+        RuntimeError::ConfirmationRequired {
+            confirmation_token,
+            expires_in_ms,
+            ..
+        } => {
+            if let Ok(with_confirmation) = failure
+                .clone()
+                .try_with_confirmation(confirmation_token, *expires_in_ms)
+            {
+                failure = with_confirmation;
+            }
+        }
+        _ => {}
+    }
+    failure
+}
+
+fn ambiguous_after_dispatch(error: &ProtocolAdapterError) -> bool {
+    match error {
+        ProtocolAdapterError::Transport {
+            dispatch: DispatchEvidence::MayHaveDispatched,
+        }
+        | ProtocolAdapterError::Timeout {
+            dispatch: DispatchEvidence::MayHaveDispatched,
+        }
+        | ProtocolAdapterError::ResponseTooLarge {
+            dispatch: DispatchEvidence::MayHaveDispatched,
+        }
+        | ProtocolAdapterError::InvalidResponse {
+            dispatch: DispatchEvidence::MayHaveDispatched,
+        } => true,
+        ProtocolAdapterError::UnexpectedStatus {
+            status,
+            dispatch: DispatchEvidence::MayHaveDispatched,
+        } => matches!(status, 408 | 429 | 500..=599),
+        _ => false,
+    }
+}
+
+fn error_code(error: &RuntimeError) -> ExecutionErrorCode {
+    match error {
+        RuntimeError::InvalidExecutionRequest => ExecutionErrorCode::RuntimeInternal,
+        RuntimeError::ExecutionDeadlineElapsed { .. } => ExecutionErrorCode::UpstreamTimeout,
+        RuntimeError::Schema(_) | RuntimeError::InputSchema(_) => {
+            ExecutionErrorCode::InputSchemaInvalid
+        }
+        RuntimeError::OutputSchema(_) => ExecutionErrorCode::OutputSchemaInvalid,
+        RuntimeError::Mapping(_) | RuntimeError::InputMapping(_) => {
+            ExecutionErrorCode::InputMappingInvalid
+        }
+        RuntimeError::OutputMapping(_) => ExecutionErrorCode::OutputMappingInvalid,
+        RuntimeError::ProtocolAdapter(adapter) => protocol_error_code(adapter),
+        RuntimeError::UnsupportedProtocol { .. } => ExecutionErrorCode::ProtocolUnsupported,
+        RuntimeError::UnsupportedExecutionMode { .. } => {
+            ExecutionErrorCode::ExecutionModeUnsupported
+        }
+        RuntimeError::ConcurrencyLimitExceeded { .. } => ExecutionErrorCode::ExecutionOverloaded,
+        RuntimeError::InvalidPreparedRequest { .. } => ExecutionErrorCode::PreparedRequestInvalid,
+        RuntimeError::ConfirmationRequired { .. } => ExecutionErrorCode::ConfirmationRequired,
+        RuntimeError::InvalidConfirmationToken { .. } => ExecutionErrorCode::ConfirmationInvalid,
+        RuntimeError::ConfirmationStoreUnavailable { .. }
+        | RuntimeError::IdempotencyStoreUnavailable { .. } => {
+            ExecutionErrorCode::SafetyStoreUnavailable
+        }
+        RuntimeError::IdempotencyInProgress { .. } => ExecutionErrorCode::IdempotencyInProgress,
+        RuntimeError::IdempotencyConflict { .. } => ExecutionErrorCode::IdempotencyConflict,
+        RuntimeError::IdempotencyOutcomeUnknown { .. } => {
+            ExecutionErrorCode::IdempotencyOutcomeUnknown
+        }
+        RuntimeError::IdempotencyCompletionUnknown { .. } => {
+            ExecutionErrorCode::IdempotencyOutcomeUnknown
+        }
+        RuntimeError::MissingAuthProfile { .. } => ExecutionErrorCode::AuthProfileNotFound,
+        RuntimeError::InvalidAuthProfileConfig { .. } => ExecutionErrorCode::SecretInvalid,
+        RuntimeError::AuthorizationStoreUnavailable => ExecutionErrorCode::SafetyStoreUnavailable,
+        RuntimeError::MissingSecret { .. } | RuntimeError::MissingSecretVersion { .. } => {
+            ExecutionErrorCode::SecretNotFound
+        }
+        RuntimeError::InvalidAuthSecretValue { .. } | RuntimeError::SecretCrypto { .. } => {
+            ExecutionErrorCode::SecretInvalid
+        }
+    }
+}
+
+fn protocol_error_code(error: &ProtocolAdapterError) -> ExecutionErrorCode {
+    match error {
+        ProtocolAdapterError::UnsupportedMode { .. } => {
+            ExecutionErrorCode::ExecutionModeUnsupported
+        }
+        ProtocolAdapterError::InvalidConfiguration => {
+            ExecutionErrorCode::AdapterConfigurationInvalid
+        }
+        ProtocolAdapterError::InvalidPreparedRequest => ExecutionErrorCode::PreparedRequestInvalid,
+        ProtocolAdapterError::RequestTooLarge => ExecutionErrorCode::UpstreamRequestTooLarge,
+        ProtocolAdapterError::TargetRejected => ExecutionErrorCode::OutboundTargetRejected,
+        ProtocolAdapterError::Transport { .. } => ExecutionErrorCode::UpstreamTransportError,
+        ProtocolAdapterError::Timeout { .. } => ExecutionErrorCode::UpstreamTimeout,
+        ProtocolAdapterError::ResponseTooLarge { .. } => {
+            ExecutionErrorCode::UpstreamResponseTooLarge
+        }
+        ProtocolAdapterError::UnexpectedStatus { status, .. } => match status {
+            401 | 403 => ExecutionErrorCode::UpstreamAuthError,
+            404 => ExecutionErrorCode::UpstreamNotFound,
+            408 | 429 => ExecutionErrorCode::UpstreamRateLimited,
+            500..=599 => ExecutionErrorCode::UpstreamServerError,
+            _ => ExecutionErrorCode::UpstreamStatusError,
+        },
+        ProtocolAdapterError::InvalidResponse { .. } => ExecutionErrorCode::UpstreamStatusError,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crank_core::{
+        CorrelationContext, DispatchEvidence, ExecutionErrorCode, OutcomeCertainty,
+        ProtocolAdapterError, Retryability,
+    };
+
+    use super::*;
+
+    #[test]
+    fn status_and_dispatch_evidence_drive_closed_semantics() {
+        let correlation = CorrelationContext::generate();
+        let rate_limit = normalize_runtime_error(
+            &RuntimeError::ProtocolAdapter(ProtocolAdapterError::UnexpectedStatus {
+                status: 429,
+                dispatch: DispatchEvidence::MayHaveDispatched,
+            }),
+            &correlation,
+        );
+        assert_eq!(
+            rate_limit.error_code(),
+            ExecutionErrorCode::UpstreamRateLimited
+        );
+        assert_eq!(rate_limit.upstream_status(), Some(429));
+        assert_eq!(rate_limit.retryability(), Retryability::AfterDelay);
+        assert_eq!(rate_limit.outcome_certainty(), OutcomeCertainty::Certain);
+
+        let ambiguous = normalize_runtime_error(
+            &RuntimeError::ProtocolAdapter(ProtocolAdapterError::Timeout {
+                dispatch: DispatchEvidence::MayHaveDispatched,
+            }),
+            &correlation,
+        );
+        assert_eq!(ambiguous.error_code(), ExecutionErrorCode::UpstreamTimeout);
+        assert_eq!(ambiguous.retryability(), Retryability::AfterDelay);
+        assert_eq!(ambiguous.outcome_certainty(), OutcomeCertainty::Certain);
+    }
+
+    #[test]
+    fn raw_internal_details_never_enter_normalized_failure() {
+        let canary = "story18-secret-url-canary";
+        let failure = normalize_runtime_error(
+            &RuntimeError::SecretCrypto {
+                operation: "decrypt",
+                details: canary.to_owned(),
+            },
+            &CorrelationContext::generate(),
+        );
+        assert_eq!(failure.error_code(), ExecutionErrorCode::SecretInvalid);
+        assert!(!format!("{failure:?}").contains(canary));
+    }
+
+    #[test]
+    fn authorization_store_failures_use_typed_safety_store_outcome() {
+        let failure = normalize_runtime_error(
+            &RuntimeError::AuthorizationStoreUnavailable,
+            &CorrelationContext::generate(),
+        );
+
+        assert_eq!(
+            failure.error_code(),
+            ExecutionErrorCode::SafetyStoreUnavailable
+        );
+        assert_eq!(failure.retryability(), Retryability::AfterDelay);
+        assert_eq!(failure.outcome_certainty(), OutcomeCertainty::Certain);
+    }
+}

crates/crank-runtime/src/execution_request.rs

@@ -0,0 +1,230 @@
+use std::time::Instant;
+
+use crank_core::{AgentId, ExecutionOrigin, InvocationSource, WorkspaceId};
+use serde_json::Value;
+
+use crate::{ResolvedAuth, RuntimeOperation, RuntimeRequestContext};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ExecutionAuthorization {
+    Authorized,
+}
+
+#[derive(Clone, Copy)]
+pub struct RuntimeExecutionRequest<'a> {
+    workspace_id: &'a WorkspaceId,
+    origin: ExecutionOrigin,
+    agent_id: Option<&'a AgentId>,
+    operation: &'a RuntimeOperation,
+    input: &'a Value,
+    authorization: ExecutionAuthorization,
+    resolved_auth: Option<&'a ResolvedAuth>,
+    request_context: &'a RuntimeRequestContext,
+    deadline: Instant,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
+pub enum ExecutionRequestError {
+    #[error("execution origin and agent identity are incompatible")]
+    InvalidOrigin,
+    #[error("operation version must be positive")]
+    InvalidOperationVersion,
+    #[error("execution deadline has already elapsed")]
+    DeadlineElapsed,
+    #[error("execution metering scope is missing or incompatible")]
+    InvalidMeteringScope,
+}
+
+impl<'a> RuntimeExecutionRequest<'a> {
+    #[allow(clippy::too_many_arguments)]
+    pub fn try_new(
+        workspace_id: &'a WorkspaceId,
+        origin: ExecutionOrigin,
+        agent_id: Option<&'a AgentId>,
+        operation: &'a RuntimeOperation,
+        input: &'a Value,
+        authorization: ExecutionAuthorization,
+        resolved_auth: Option<&'a ResolvedAuth>,
+        request_context: &'a RuntimeRequestContext,
+        deadline: Instant,
+    ) -> Result<Self, ExecutionRequestError> {
+        origin
+            .validate_agent(agent_id)
+            .map_err(|_| ExecutionRequestError::InvalidOrigin)?;
+        if operation.operation_version == 0 {
+            return Err(ExecutionRequestError::InvalidOperationVersion);
+        }
+        if deadline <= Instant::now() {
+            return Err(ExecutionRequestError::DeadlineElapsed);
+        }
+        let expected_source = match origin {
+            ExecutionOrigin::AdminDraft => InvocationSource::AdminTestRun,
+            ExecutionOrigin::AgentSnapshot => InvocationSource::AgentToolCall,
+        };
+        let metering = request_context
+            .metering_context()
+            .ok_or(ExecutionRequestError::InvalidMeteringScope)?;
+        if &metering.workspace_id != workspace_id
+            || metering.source != expected_source
+            || metering.agent_id.as_ref() != agent_id
+        {
+            return Err(ExecutionRequestError::InvalidMeteringScope);
+        }
+
+        Ok(Self {
+            workspace_id,
+            origin,
+            agent_id,
+            operation,
+            input,
+            authorization,
+            resolved_auth,
+            request_context,
+            deadline,
+        })
+    }
+
+    pub(crate) fn operation(&self) -> &'a RuntimeOperation {
+        self.operation
+    }
+
+    pub(crate) fn workspace_id(&self) -> &'a WorkspaceId {
+        self.workspace_id
+    }
+
+    pub(crate) fn agent_id(&self) -> Option<&'a AgentId> {
+        self.agent_id
+    }
+
+    pub(crate) fn authorization(&self) -> ExecutionAuthorization {
+        self.authorization
+    }
+
+    pub(crate) fn input(&self) -> &'a Value {
+        self.input
+    }
+
+    pub(crate) fn origin(&self) -> ExecutionOrigin {
+        self.origin
+    }
+
+    pub(crate) fn resolved_auth(&self) -> Option<&'a ResolvedAuth> {
+        self.resolved_auth
+    }
+
+    pub(crate) fn request_context(&self) -> &'a RuntimeRequestContext {
+        self.request_context
+    }
+
+    pub(crate) fn deadline(&self) -> Instant {
+        self.deadline
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{collections::BTreeMap, time::Duration};
+
+    use crank_core::{
+        AgentId, ExecutionConfig, HttpMethod, OperationId, RestTarget, Target, ToolDescription,
+    };
+    use crank_mapping::MappingSet;
+    use crank_schema::{Schema, SchemaKind};
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn rejects_origin_or_scope_mismatch_before_execution() {
+        let operation = operation();
+        let input = json!({});
+        let workspace = WorkspaceId::new("ws_01");
+        let foreign = WorkspaceId::new("ws_02");
+        let agent = AgentId::new("agent_01");
+        let context = RuntimeRequestContext::from_request_id("req_01").with_metering_context(
+            workspace.clone(),
+            None,
+            InvocationSource::AdminTestRun,
+        );
+        let deadline = Instant::now() + Duration::from_secs(1);
+
+        assert_eq!(
+            RuntimeExecutionRequest::try_new(
+                &workspace,
+                ExecutionOrigin::AdminDraft,
+                Some(&agent),
+                &operation,
+                &input,
+                ExecutionAuthorization::Authorized,
+                None,
+                &context,
+                deadline,
+            )
+            .err()
+            .expect("origin mismatch"),
+            ExecutionRequestError::InvalidOrigin
+        );
+        assert_eq!(
+            RuntimeExecutionRequest::try_new(
+                &foreign,
+                ExecutionOrigin::AdminDraft,
+                None,
+                &operation,
+                &input,
+                ExecutionAuthorization::Authorized,
+                None,
+                &context,
+                deadline,
+            )
+            .err()
+            .expect("scope mismatch"),
+            ExecutionRequestError::InvalidMeteringScope
+        );
+    }
+
+    fn operation() -> RuntimeOperation {
+        let schema = Schema {
+            kind: SchemaKind::Object,
+            description: None,
+            required: true,
+            nullable: false,
+            default_value: None,
+            fields: BTreeMap::new(),
+            items: None,
+            enum_values: Vec::new(),
+            variants: Vec::new(),
+        };
+        RuntimeOperation {
+            operation_id: OperationId::new("op_01"),
+            operation_version: 1,
+            tool_name: "tool".to_owned(),
+            protocol: crank_core::Protocol::Rest,
+            target: Target::Rest(RestTarget {
+                base_url: "https://example.invalid".to_owned(),
+                method: HttpMethod::Post,
+                path_template: "/".to_owned(),
+                static_headers: BTreeMap::new(),
+            }),
+            input_schema: schema.clone(),
+            output_schema: schema,
+            input_mapping: MappingSet::default(),
+            output_mapping: MappingSet::default(),
+            execution_config: ExecutionConfig {
+                timeout_ms: 1_000,
+                retry_policy: None,
+                response_cache: None,
+                idempotency: None,
+                safety: None,
+                approval_policy: None,
+                auth_profile_ref: None,
+                headers: BTreeMap::new(),
+            },
+            tool_description: ToolDescription {
+                title: "Tool".to_owned(),
+                description: "Tool".to_owned(),
+                tags: Vec::new(),
+                examples: Vec::new(),
+            },
+        }
+    }
+}

crates/crank-runtime/src/executor.rs

@@ -1,5 +1,8 @@
-use std::sync::Arc;
-use std::time::Instant;
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
+use std::time::{Duration, Instant};
 
 use crank_core::{
     AdapterRegistry, CoordinationStateStore, ExecutionMode, InvocationSource, InvocationStatus,
@@ -11,18 +14,15 @@ use crank_metrics::{
     ToolOutcome, record_cache_outcome, record_confirmation_outcome, record_idempotency_outcome,
     record_limit_rejection,
 };
-use crank_trace::{
-    ErrorCategory, Stage, StageOutcome, set_parent_from_trace_context, trace_context_for_span,
-};
+use crank_trace::{ErrorCategory, Stage, StageOutcome, set_parent_from_trace_context};
 use serde_json::{Map, Value, json};
 use time::OffsetDateTime;
 use tokio::sync::{OwnedSemaphorePermit, Semaphore};
 use tracing::{Instrument, Span, debug, warn};
-use uuid::Uuid;
 
 use crate::{
-    AdapterResponse, PreparedRequest, ResolvedAuth, RuntimeError, RuntimeLimits, RuntimeOperation,
-    RuntimeRequestContext,
+    AdapterResponse, ExecutionAuthorization, PreparedRequest, RuntimeError,
+    RuntimeExecutionRequest, RuntimeLimits, RuntimeOperation, RuntimeRequestContext,
     auth::apply_resolved_auth,
     request_preparation::adapter_prepared_request,
     response_cache::{
@@ -41,14 +41,6 @@ pub struct RuntimeExecutor {
     metering_sink: SharedMeteringSink,
 }
 
-#[derive(Clone, Copy)]
-pub struct RuntimeExecutionRequest<'a> {
-    pub operation: &'a RuntimeOperation,
-    pub input: &'a Value,
-    pub resolved_auth: Option<&'a ResolvedAuth>,
-    pub request_context: Option<&'a RuntimeRequestContext>,
-}
-
 struct IdempotencyCancellationGuard {
     cleanup: Option<IdempotencyCancellationCleanup>,
     runtime: tokio::runtime::Handle,
@@ -58,6 +50,7 @@ struct IdempotencyCancellationCleanup {
     store: Arc<dyn CoordinationStateStore>,
     operation: RuntimeOperation,
     reservation: crate::idempotency::IdempotencyReservation,
+    dispatch_started: Arc<AtomicBool>,
 }
 
 impl IdempotencyCancellationGuard {
@@ -65,12 +58,14 @@ impl IdempotencyCancellationGuard {
         store: Arc<dyn CoordinationStateStore>,
         operation: RuntimeOperation,
         reservation: crate::idempotency::IdempotencyReservation,
+        dispatch_started: Arc<AtomicBool>,
     ) -> Self {
         Self {
             cleanup: Some(IdempotencyCancellationCleanup {
                 store,
                 operation,
                 reservation,
+                dispatch_started,
             }),
             runtime: tokio::runtime::Handle::current(),
         }
@@ -87,14 +82,25 @@ impl Drop for IdempotencyCancellationGuard {
             return;
         };
         self.runtime.spawn(async move {
-            let result = crate::idempotency::mark_outcome_unknown(
-                cleanup.store.as_ref(),
-                &cleanup.operation,
-                &cleanup.reservation,
-            )
-            .await;
+            let may_have_dispatched = cleanup.dispatch_started.load(Ordering::Acquire);
+            let result = if may_have_dispatched {
+                crate::idempotency::mark_outcome_unknown(
+                    cleanup.store.as_ref(),
+                    &cleanup.operation,
+                    &cleanup.reservation,
+                )
+                .await
+            } else {
+                crate::idempotency::release(
+                    cleanup.store.as_ref(),
+                    &cleanup.operation,
+                    &cleanup.reservation,
+                )
+                .await
+            };
             record_idempotency_outcome(match &result {
-                Ok(()) => IdempotencyOutcome::OutcomeUnknown,
+                Ok(()) if may_have_dispatched => IdempotencyOutcome::OutcomeUnknown,
+                Ok(()) => IdempotencyOutcome::Completed,
                 Err(error) => idempotency_error_outcome(error),
             });
             if result.is_err() {
@@ -108,40 +114,6 @@ impl Drop for IdempotencyCancellationGuard {
     }
 }
 
-impl<'a> RuntimeExecutionRequest<'a> {
-    pub fn new(operation: &'a RuntimeOperation, input: &'a Value) -> Self {
-        Self {
-            operation,
-            input,
-            resolved_auth: None,
-            request_context: None,
-        }
-    }
-
-    pub fn with_auth(mut self, resolved_auth: &'a ResolvedAuth) -> Self {
-        self.resolved_auth = Some(resolved_auth);
-        self
-    }
-
-    pub fn with_optional_auth(mut self, resolved_auth: Option<&'a ResolvedAuth>) -> Self {
-        self.resolved_auth = resolved_auth;
-        self
-    }
-
-    pub fn with_context(mut self, request_context: &'a RuntimeRequestContext) -> Self {
-        self.request_context = Some(request_context);
-        self
-    }
-
-    pub fn with_optional_context(
-        mut self,
-        request_context: Option<&'a RuntimeRequestContext>,
-    ) -> Self {
-        self.request_context = request_context;
-        self
-    }
-}
-
 impl Default for RuntimeExecutor {
     fn default() -> Self {
         Self::new()
@@ -192,106 +164,76 @@ impl RuntimeExecutor {
         self
     }
 
-    pub async fn execute(
-        &self,
-        operation: &RuntimeOperation,
-        input: &Value,
-    ) -> Result<Value, RuntimeError> {
-        self.execute_request(RuntimeExecutionRequest::new(operation, input))
-            .await
-    }
-
-    pub async fn execute_with_auth(
-        &self,
-        operation: &RuntimeOperation,
-        input: &Value,
-        resolved_auth: Option<&ResolvedAuth>,
-    ) -> Result<Value, RuntimeError> {
-        self.execute_request(
-            RuntimeExecutionRequest::new(operation, input).with_optional_auth(resolved_auth),
-        )
-        .await
-    }
-
-    pub async fn execute_with_context(
-        &self,
-        operation: &RuntimeOperation,
-        input: &Value,
-        request_context: Option<&RuntimeRequestContext>,
-    ) -> Result<Value, RuntimeError> {
-        self.execute_request(
-            RuntimeExecutionRequest::new(operation, input).with_optional_context(request_context),
-        )
-        .await
-    }
-
-    pub async fn execute_with_auth_and_context(
-        &self,
-        operation: &RuntimeOperation,
-        input: &Value,
-        resolved_auth: Option<&ResolvedAuth>,
-        request_context: Option<&RuntimeRequestContext>,
-    ) -> Result<Value, RuntimeError> {
-        self.execute_request(
-            RuntimeExecutionRequest::new(operation, input)
-                .with_optional_auth(resolved_auth)
-                .with_optional_context(request_context),
-        )
-        .await
-    }
-
-    pub async fn execute_request(
+    pub(crate) async fn execute_request(
         &self,
         request: RuntimeExecutionRequest<'_>,
-    ) -> Result<Value, RuntimeError> {
-        let runtime_span = Stage::RuntimeExecute.span();
-        if let Some(context) = request.request_context {
-            set_parent_from_trace_context(&runtime_span, &context.trace_context);
-        }
-        let generated_context = request.request_context.is_none().then(|| {
-            RuntimeRequestContext::new(
-                crank_core::RequestId::generate(),
-                trace_context_for_span(&runtime_span)
-                    .unwrap_or_else(crank_core::TraceContext::generate),
-            )
-        });
-        let request_context = request.request_context.or(generated_context.as_ref());
-        log_runtime_event("unary.execute", request.operation, request_context);
-        let started_at = Instant::now();
-        let invocation_metrics = ToolInvocationMetrics::start_with_exemplar(
-            metric_invocation_source(request_context),
-            request_context.and_then(|context| {
-                context
-                    .trace_context
-                    .is_sampled()
-                    .then(|| {
-                        crank_metrics::ExemplarTraceId::parse(
-                            &context.trace_context.trace_id().to_string(),
-                        )
-                    })
-                    .flatten()
-            }),
+    ) -> Result<(Value, Value), RuntimeError> {
+        let operation = request.operation();
+        let input = request.input();
+        let request_context = request.request_context();
+        debug_assert_eq!(request.authorization(), ExecutionAuthorization::Authorized);
+        debug_assert_eq!(
+            request_context
+                .metering_context()
+                .map(|value| &value.workspace_id),
+            Some(request.workspace_id())
         );
-        let result = async {
-            let _permit = self.acquire_unary_permit(request.operation)?;
+        debug_assert_eq!(
+            request_context
+                .metering_context()
+                .and_then(|value| value.agent_id.as_ref()),
+            request.agent_id()
+        );
+        let operation_may_mutate = operation_may_mutate(operation);
+        let runtime_span = Stage::RuntimeExecute.span();
+        set_parent_from_trace_context(&runtime_span, &request_context.trace_context);
+        log_runtime_event("unary.execute", operation, Some(request_context));
+        let started_at = Instant::now();
+        let dispatch_started = Arc::new(AtomicBool::new(false));
+        let invocation_metrics = ToolInvocationMetrics::start_with_exemplar(
+            metric_invocation_source(Some(request_context)),
+            request_context
+                .trace_context
+                .is_sampled()
+                .then(|| {
+                    crank_metrics::ExemplarTraceId::parse(
+                        &request_context.trace_context.trace_id().to_string(),
+                    )
+                })
+                .flatten(),
+        );
+        let execution = async {
+            let _permit = self.acquire_unary_permit(operation)?;
             let _inflight = InFlightGuard::runtime();
             let mapping_span = Stage::RuntimeArgumentsMap.span();
-            let prepared_request =
-                mapping_span.in_scope(|| self.prepare_request(request.operation, request.input));
+            let prepared_request = mapping_span.in_scope(|| self.prepare_request(operation, input));
             record_runtime_result(&mapping_span, &prepared_request);
             drop(mapping_span);
             let prepared_request = prepared_request?;
-            let prepared_request = apply_resolved_auth(prepared_request, request.resolved_auth);
-            self.execute_prepared(
-                request.operation,
-                request.input,
-                prepared_request,
-                request_context,
-            )
-            .await
-        }
-        .instrument(runtime_span.clone())
-        .await;
+            let request_preview = sanitized_request_preview(&prepared_request);
+            let prepared_request = apply_resolved_auth(prepared_request, request.resolved_auth());
+            let output = self
+                .execute_prepared(
+                    operation,
+                    input,
+                    prepared_request,
+                    Some(request_context),
+                    Arc::clone(&dispatch_started),
+                )
+                .await?;
+            Ok((output, request_preview))
+        };
+        let result = tokio::time::timeout_at(
+            request.deadline().into(),
+            execution.instrument(runtime_span.clone()),
+        )
+        .await
+        .unwrap_or_else(|_| {
+            Err(RuntimeError::ExecutionDeadlineElapsed {
+                may_have_dispatched: operation_may_mutate
+                    && dispatch_started.load(Ordering::Acquire),
+            })
+        });
         record_runtime_result(&runtime_span, &result);
         drop(runtime_span);
         let (outcome, error_kind) = match &result {
@@ -299,23 +241,58 @@ impl RuntimeExecutor {
             Err(error) => (ToolOutcome::Error, runtime_error_kind(error)),
         };
         invocation_metrics.complete(outcome, error_kind);
-        self.record_metering(request.operation, request_context, &result, started_at)
+        self.record_metering(operation, Some(request_context), &result, started_at)
             .await;
         result
     }
 
-    pub fn prepare_request(
+    pub async fn execute_outcome(
+        &self,
+        request: RuntimeExecutionRequest<'_>,
+    ) -> Result<crank_core::ExecutionSuccess, crank_core::ExecutionFailure> {
+        let operation_id = request.operation().operation_id.clone();
+        let operation_version = request.operation().operation_version;
+        let operation = request.operation().clone();
+        let origin = request.origin();
+        let correlation = crank_core::CorrelationContext::new(
+            request.request_context().request_id.clone(),
+            request.request_context().trace_context.clone(),
+        );
+        match self.execute_request(request).await {
+            Ok((output, request_preview)) => Ok(crank_core::ExecutionSuccess {
+                operation_id,
+                operation_version,
+                origin,
+                correlation,
+                request_preview,
+                output,
+            }),
+            Err(error) => Err(crate::normalize_runtime_error_for_operation(
+                &error,
+                &correlation,
+                &operation,
+            )),
+        }
+    }
+
+    fn prepare_request(
         &self,
         operation: &RuntimeOperation,
         input: &Value,
     ) -> Result<PreparedRequest, RuntimeError> {
-        operation.input_schema.validate_shape(input)?;
+        operation
+            .input_schema
+            .validate_shape(input)
+            .map_err(RuntimeError::InputSchema)?;
 
         if operation.input_mapping.is_empty() {
             return Ok(PreparedRequest::default());
         }
 
-        let mapped_input = operation.input_mapping.apply(&json!({ "mcp": input }))?;
+        let mapped_input = operation
+            .input_mapping
+            .apply(&json!({ "mcp": input }))
+            .map_err(RuntimeError::InputMapping)?;
         PreparedRequest::from_mapping_output(&mapped_input)
     }
 
@@ -325,6 +302,7 @@ impl RuntimeExecutor {
         input: &Value,
         prepared_request: PreparedRequest,
         request_context: Option<&RuntimeRequestContext>,
+        dispatch_started: Arc<AtomicBool>,
     ) -> Result<Value, RuntimeError> {
         let mut prepared_request = prepared_request;
         let idempotency_applicable = crate::idempotency::policy(operation).is_some();
@@ -418,6 +396,7 @@ impl RuntimeExecutor {
                         Arc::clone(store),
                         operation.clone(),
                         reservation.clone(),
+                        Arc::clone(&dispatch_started),
                     )
                 })
             } else {
@@ -431,7 +410,16 @@ impl RuntimeExecutor {
             Some(response) => Ok(response),
             None => {
                 let adapter_response = self
-                    .execute_adapter(operation, prepared_request.clone(), request_context)
+                    .execute_adapter_with_retry(
+                        operation,
+                        &prepared_request,
+                        request_context,
+                        Arc::clone(&dispatch_started),
+                        crate::idempotency::verified_retry_key(
+                            operation,
+                            idempotency_key.as_deref(),
+                        ),
+                    )
                     .await;
                 if let Ok(response) = &adapter_response {
                     self.store_cached_adapter_response(
@@ -452,13 +440,20 @@ impl RuntimeExecutor {
                     && let Some(store) = self.coordination_store.as_deref()
                 {
                     let idempotency_span = Stage::RuntimeIdempotency.span();
-                    let cleanup_result =
+                    let may_have_dispatched = runtime_error_may_have_dispatched(&error);
+                    let cleanup_result = if may_have_dispatched {
                         crate::idempotency::mark_outcome_unknown(store, operation, reservation)
                             .instrument(idempotency_span.clone())
-                            .await;
+                            .await
+                    } else {
+                        crate::idempotency::release(store, operation, reservation)
+                            .instrument(idempotency_span.clone())
+                            .await
+                    };
                     record_runtime_result(&idempotency_span, &cleanup_result);
                     record_idempotency_outcome(match &cleanup_result {
-                        Ok(()) => IdempotencyOutcome::OutcomeUnknown,
+                        Ok(()) if may_have_dispatched => IdempotencyOutcome::OutcomeUnknown,
+                        Ok(()) => IdempotencyOutcome::Completed,
                         Err(error) => idempotency_error_outcome(error),
                     });
                     if let Some(guard) = &mut cancellation_guard {
@@ -485,7 +480,11 @@ impl RuntimeExecutor {
                 guard.disarm();
             }
             drop(idempotency_span);
-            completion_result?;
+            if completion_result.is_err() {
+                return Err(RuntimeError::IdempotencyCompletionUnknown {
+                    operation_id: operation.operation_id.as_str().to_owned(),
+                });
+            }
         }
         transform_response(operation, &adapter_response)
     }
@@ -524,6 +523,7 @@ impl RuntimeExecutor {
         operation: &RuntimeOperation,
         prepared_request: PreparedRequest,
         request_context: Option<&RuntimeRequestContext>,
+        dispatch_started: Arc<AtomicBool>,
     ) -> Result<AdapterResponse, RuntimeError> {
         log_runtime_event("adapter.dispatch", operation, request_context);
         let adapter = self.adapter_for(operation)?;
@@ -539,8 +539,8 @@ impl RuntimeExecutor {
             &prepared_request,
             operation.execution_config.timeout_ms,
         );
-        let adapter_context = adapter_request_context(request_context);
-
+        let adapter_context =
+            adapter_request_context(request_context, Arc::clone(&dispatch_started))?;
         adapter
             .invoke_unary(
                 &operation.target,
@@ -552,6 +552,39 @@ impl RuntimeExecutor {
             .map_err(|error| map_protocol_adapter_error(operation, error))
     }
 
+    async fn execute_adapter_with_retry(
+        &self,
+        operation: &RuntimeOperation,
+        prepared_request: &PreparedRequest,
+        request_context: Option<&RuntimeRequestContext>,
+        dispatch_started: Arc<AtomicBool>,
+        verified_idempotency: bool,
+    ) -> Result<AdapterResponse, RuntimeError> {
+        let max_attempts = retry_attempts(operation);
+        let mut attempt = 1;
+        loop {
+            let result = self
+                .execute_adapter(
+                    operation,
+                    prepared_request.clone(),
+                    request_context,
+                    Arc::clone(&dispatch_started),
+                )
+                .await;
+            match result {
+                Ok(response) => return Ok(response),
+                Err(error)
+                    if attempt < max_attempts
+                        && retry_is_allowed(operation, &error, verified_idempotency) =>
+                {
+                    attempt += 1;
+                    tokio::time::sleep(retry_backoff(attempt)).await;
+                }
+                Err(error) => return Err(error),
+            }
+        }
+    }
+
     fn acquire_unary_permit(
         &self,
         _operation: &RuntimeOperation,
@@ -654,12 +687,98 @@ impl RuntimeExecutor {
     }
 }
 
+fn sanitized_request_preview(prepared: &PreparedRequest) -> Value {
+    json!({
+        "path_parameter_count": prepared.path_params.len(),
+        "query_parameter_count": prepared.query_params.len(),
+        "header_count": prepared.headers.len(),
+        "body_configured": prepared.body.is_some(),
+    })
+}
+
+fn runtime_error_may_have_dispatched(error: &RuntimeError) -> bool {
+    matches!(
+        error,
+        RuntimeError::ProtocolAdapter(
+            crank_core::ProtocolAdapterError::Transport {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+            } | crank_core::ProtocolAdapterError::Timeout {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+            } | crank_core::ProtocolAdapterError::ResponseTooLarge {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+            } | crank_core::ProtocolAdapterError::UnexpectedStatus {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+                ..
+            } | crank_core::ProtocolAdapterError::InvalidResponse {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+            },
+        ) | RuntimeError::ExecutionDeadlineElapsed {
+            may_have_dispatched: true,
+        } | RuntimeError::IdempotencyCompletionUnknown { .. }
+    )
+}
+
+fn retry_attempts(operation: &RuntimeOperation) -> u32 {
+    operation
+        .execution_config
+        .retry_policy
+        .as_ref()
+        .map_or(1, |policy| policy.max_attempts.clamp(1, 5))
+}
+
+fn retry_backoff(attempt: u32) -> Duration {
+    Duration::from_millis(u64::from(attempt.saturating_sub(1)).min(4))
+}
+
+fn retry_is_allowed(
+    operation: &RuntimeOperation,
+    error: &RuntimeError,
+    verified_idempotency: bool,
+) -> bool {
+    let is_read = matches!(
+        &operation.target,
+        crank_core::Target::Rest(target) if target.method == crank_core::HttpMethod::Get
+    );
+    let safe_write = operation_may_mutate(operation) && verified_idempotency;
+    if !(is_read || safe_write) {
+        return false;
+    }
+    match error {
+        RuntimeError::ProtocolAdapter(
+            crank_core::ProtocolAdapterError::Transport { .. }
+            | crank_core::ProtocolAdapterError::Timeout { .. },
+        ) => true,
+        RuntimeError::ProtocolAdapter(crank_core::ProtocolAdapterError::UnexpectedStatus {
+            status,
+            ..
+        }) => matches!(status, 408 | 429 | 500..=599),
+        _ => false,
+    }
+}
+
+fn operation_may_mutate(operation: &RuntimeOperation) -> bool {
+    matches!(
+        &operation.target,
+        crank_core::Target::Rest(target)
+            if matches!(
+                target.method,
+                crank_core::HttpMethod::Post
+                    | crank_core::HttpMethod::Put
+                    | crank_core::HttpMethod::Patch
+                    | crank_core::HttpMethod::Delete
+            )
+    )
+}
+
 fn adapter_request_context(
     request_context: Option<&RuntimeRequestContext>,
-) -> crank_core::RuntimeRequestContext {
-    request_context.map(Into::into).unwrap_or_else(|| {
-        crank_core::RuntimeRequestContext::from_request_id(Uuid::now_v7().to_string())
-    })
+    dispatch_started: Arc<AtomicBool>,
+) -> Result<crank_core::RuntimeRequestContext, RuntimeError> {
+    request_context
+        .map(|context| {
+            crank_core::RuntimeRequestContext::from(context).with_dispatch_started(dispatch_started)
+        })
+        .ok_or(RuntimeError::InvalidExecutionRequest)
 }
 
 fn map_protocol_adapter_error(
@@ -673,9 +792,7 @@ fn map_protocol_adapter_error(
                 mode,
             }
         }
-        crank_core::ProtocolAdapterError::Message(message) => RuntimeError::ProtocolAdapter(
-            format!("operation {}: {message}", operation.operation_id),
-        ),
+        error => RuntimeError::ProtocolAdapter(error),
     }
 }
 
@@ -696,14 +813,17 @@ fn finalize_output(
     operation: &RuntimeOperation,
     response: &AdapterResponse,
 ) -> Result<Value, RuntimeError> {
-    let mapped = operation.output_mapping.apply(&json!({
-        "response": {
-            "body": response.body,
-            "data": response.data,
-            "headers": response.headers,
-            "status": response.status_code
-        }
-    }))?;
+    let mapped = operation
+        .output_mapping
+        .apply(&json!({
+            "response": {
+                "body": response.body,
+                "data": response.data,
+                "headers": response.headers,
+                "status": response.status_code
+            }
+        }))
+        .map_err(RuntimeError::OutputMapping)?;
 
     Ok(mapped
         .get("output")
@@ -718,7 +838,10 @@ fn transform_response(
     let span = Stage::RuntimeResponseTransform.span();
     let result = span.in_scope(|| {
         let finalized_output = finalize_output(operation, response)?;
-        operation.output_schema.validate_shape(&finalized_output)?;
+        operation
+            .output_schema
+            .validate_shape(&finalized_output)
+            .map_err(RuntimeError::OutputSchema)?;
         Ok(finalized_output)
     });
     match &result {
@@ -743,12 +866,16 @@ fn record_runtime_result<T>(span: &Span, result: &Result<T, RuntimeError>) {
 
 fn runtime_error_category(error: &RuntimeError) -> ErrorCategory {
     match error {
-        RuntimeError::Schema(_) => ErrorCategory::Schema,
-        RuntimeError::Mapping(_) | RuntimeError::InvalidPreparedRequest { .. } => {
-            ErrorCategory::Mapping
+        RuntimeError::InvalidExecutionRequest => ErrorCategory::Configuration,
+        RuntimeError::ExecutionDeadlineElapsed { .. } => ErrorCategory::Upstream,
+        RuntimeError::Schema(_) | RuntimeError::InputSchema(_) | RuntimeError::OutputSchema(_) => {
+            ErrorCategory::Schema
         }
-        RuntimeError::RestAdapter(_)
-        | RuntimeError::ProtocolAdapter(_)
+        RuntimeError::Mapping(_)
+        | RuntimeError::InputMapping(_)
+        | RuntimeError::OutputMapping(_)
+        | RuntimeError::InvalidPreparedRequest { .. } => ErrorCategory::Mapping,
+        RuntimeError::ProtocolAdapter(_)
         | RuntimeError::UnsupportedProtocol { .. }
         | RuntimeError::UnsupportedExecutionMode { .. } => ErrorCategory::Upstream,
         RuntimeError::ConcurrencyLimitExceeded { .. } => ErrorCategory::Concurrency,
@@ -758,8 +885,11 @@ fn runtime_error_category(error: &RuntimeError) -> ErrorCategory {
         RuntimeError::IdempotencyStoreUnavailable { .. }
         | RuntimeError::IdempotencyInProgress { .. }
         | RuntimeError::IdempotencyConflict { .. }
-        | RuntimeError::IdempotencyOutcomeUnknown { .. } => ErrorCategory::Idempotency,
+        | RuntimeError::IdempotencyOutcomeUnknown { .. }
+        | RuntimeError::IdempotencyCompletionUnknown { .. } => ErrorCategory::Idempotency,
         RuntimeError::MissingAuthProfile { .. }
+        | RuntimeError::InvalidAuthProfileConfig { .. }
+        | RuntimeError::AuthorizationStoreUnavailable
         | RuntimeError::MissingSecret { .. }
         | RuntimeError::MissingSecretVersion { .. }
         | RuntimeError::InvalidAuthSecretValue { .. }
@@ -793,9 +923,14 @@ fn metric_invocation_source(
 
 fn runtime_error_kind(error: &RuntimeError) -> ToolErrorKind {
     match error {
-        RuntimeError::Schema(_) => ToolErrorKind::Schema,
-        RuntimeError::Mapping(_) => ToolErrorKind::Mapping,
-        RuntimeError::RestAdapter(_) => ToolErrorKind::RestAdapter,
+        RuntimeError::InvalidExecutionRequest => ToolErrorKind::InvalidPreparedRequest,
+        RuntimeError::ExecutionDeadlineElapsed { .. } => ToolErrorKind::RestAdapter,
+        RuntimeError::Schema(_) | RuntimeError::InputSchema(_) | RuntimeError::OutputSchema(_) => {
+            ToolErrorKind::Schema
+        }
+        RuntimeError::Mapping(_)
+        | RuntimeError::InputMapping(_)
+        | RuntimeError::OutputMapping(_) => ToolErrorKind::Mapping,
         RuntimeError::ProtocolAdapter(_) => ToolErrorKind::ProtocolAdapter,
         RuntimeError::UnsupportedProtocol { .. } => ToolErrorKind::UnsupportedProtocol,
         RuntimeError::UnsupportedExecutionMode { .. } => ToolErrorKind::UnsupportedExecutionMode,
@@ -808,7 +943,12 @@ fn runtime_error_kind(error: &RuntimeError) -> ToolErrorKind {
         RuntimeError::IdempotencyInProgress { .. } => ToolErrorKind::IdempotencyInProgress,
         RuntimeError::IdempotencyConflict { .. } => ToolErrorKind::IdempotencyConflict,
         RuntimeError::IdempotencyOutcomeUnknown { .. } => ToolErrorKind::IdempotencyOutcomeUnknown,
+        RuntimeError::IdempotencyCompletionUnknown { .. } => {
+            ToolErrorKind::IdempotencyOutcomeUnknown
+        }
         RuntimeError::MissingAuthProfile { .. } => ToolErrorKind::MissingAuthProfile,
+        RuntimeError::InvalidAuthProfileConfig { .. } => ToolErrorKind::InvalidAuthSecret,
+        RuntimeError::AuthorizationStoreUnavailable => ToolErrorKind::IdempotencyStore,
         RuntimeError::MissingSecret { .. } => ToolErrorKind::MissingSecret,
         RuntimeError::MissingSecretVersion { .. } => ToolErrorKind::MissingSecretVersion,
         RuntimeError::InvalidAuthSecretValue { .. } => ToolErrorKind::InvalidAuthSecret,
@@ -820,7 +960,8 @@ fn idempotency_error_outcome(error: &RuntimeError) -> IdempotencyOutcome {
     match error {
         RuntimeError::IdempotencyConflict { .. } => IdempotencyOutcome::Conflict,
         RuntimeError::IdempotencyInProgress { .. } => IdempotencyOutcome::InProgress,
-        RuntimeError::IdempotencyOutcomeUnknown { .. } => IdempotencyOutcome::OutcomeUnknown,
+        RuntimeError::IdempotencyOutcomeUnknown { .. }
+        | RuntimeError::IdempotencyCompletionUnknown { .. } => IdempotencyOutcome::OutcomeUnknown,
         RuntimeError::IdempotencyStoreUnavailable { .. } => IdempotencyOutcome::StoreUnavailable,
         _ => IdempotencyOutcome::Error,
     }

crates/crank-runtime/src/idempotency.rs

@@ -1,4 +1,7 @@
-use std::time::{Duration, Instant};
+use std::{
+    collections::BTreeMap,
+    time::{Duration, Instant},
+};
 
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use crank_core::{
@@ -38,7 +41,7 @@ pub fn prepare_idempotency(
         return Ok(None);
     };
 
-    let key = key_from_policy(policy, input, prepared_request);
+    let key = key_from_policy(policy, input);
     let Some(key) = key else {
         if policy.mode == IdempotencyMode::Required {
             return Err(RuntimeError::InvalidPreparedRequest {
@@ -54,10 +57,13 @@ pub fn prepare_idempotency(
         .as_deref()
         .filter(|value| !value.is_empty())
     {
+        remove_header_case_insensitive(&mut prepared_request.headers, header_name);
         prepared_request
             .headers
-            .entry(header_name.to_owned())
-            .or_insert_with(|| key.clone());
+            .insert(header_name.to_owned(), key.clone());
+        prepared_request
+            .trusted_header_names
+            .insert(header_name.to_ascii_lowercase());
     }
 
     Ok(Some(key))
@@ -186,6 +192,19 @@ pub(crate) async fn mark_outcome_unknown(
     }
 }
 
+pub(crate) async fn release(
+    store: &dyn CoordinationStateStore,
+    operation: &RuntimeOperation,
+    reservation: &IdempotencyReservation,
+) -> Result<(), RuntimeError> {
+    store
+        .delete_value(CacheScope::Coordination, &reservation.key)
+        .await
+        .map_err(|_| RuntimeError::IdempotencyStoreUnavailable {
+            operation_id: operation.operation_id.as_str().to_owned(),
+        })
+}
+
 async fn resolve_existing(
     store: &dyn CoordinationStateStore,
     operation: &RuntimeOperation,
@@ -315,20 +334,7 @@ fn in_progress_value(fingerprint: &str) -> CoordinationStateValue {
     }
 }
 
-fn key_from_policy(
-    policy: &IdempotencyPolicy,
-    input: &Value,
-    prepared_request: &PreparedRequest,
-) -> Option<String> {
-    if let Some(header_name) = policy
-        .header_name
-        .as_deref()
-        .filter(|value| !value.is_empty())
-        && let Some(value) = prepared_request.headers.get(header_name)
-    {
-        return Some(value.clone());
-    }
-
+fn key_from_policy(policy: &IdempotencyPolicy, input: &Value) -> Option<String> {
     let field_name = policy.input_field.as_deref()?.trim();
     if field_name.is_empty() {
         return None;
@@ -340,3 +346,123 @@ fn key_from_policy(
         _ => None,
     })
 }
+
+pub(crate) fn verified_retry_key(
+    operation: &RuntimeOperation,
+    idempotency_key: Option<&str>,
+) -> bool {
+    let Some(policy) = policy(operation) else {
+        return false;
+    };
+    idempotency_key.is_some()
+        && policy
+            .input_field
+            .as_deref()
+            .is_some_and(|field| !field.trim().is_empty())
+}
+
+fn remove_header_case_insensitive(headers: &mut BTreeMap<String, String>, header_name: &str) {
+    let Some(existing) = headers
+        .keys()
+        .find(|candidate| candidate.eq_ignore_ascii_case(header_name))
+        .cloned()
+    else {
+        return;
+    };
+    headers.remove(&existing);
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeMap;
+
+    use crank_core::{
+        ExecutionConfig, HttpMethod, IdempotencyMode, IdempotencyPolicy, OperationId, Protocol,
+        RestTarget, Target, ToolDescription,
+    };
+    use crank_mapping::MappingSet;
+    use crank_schema::{Schema, SchemaKind};
+    use serde_json::json;
+
+    use crate::{PreparedRequest, RuntimeOperation};
+
+    #[test]
+    fn idempotency_header_is_derived_from_input_not_user_mapped_header() {
+        let operation = RuntimeOperation {
+            operation_id: OperationId::new("op_idempotent"),
+            operation_version: 1,
+            tool_name: "idempotent_write".to_owned(),
+            protocol: Protocol::Rest,
+            target: Target::Rest(RestTarget {
+                base_url: "https://api.example.invalid".to_owned(),
+                method: HttpMethod::Post,
+                path_template: "/orders".to_owned(),
+                static_headers: BTreeMap::new(),
+            }),
+            input_schema: Schema {
+                kind: SchemaKind::Object,
+                description: None,
+                required: true,
+                nullable: false,
+                default_value: None,
+                fields: BTreeMap::new(),
+                items: None,
+                enum_values: Vec::new(),
+                variants: Vec::new(),
+            },
+            output_schema: Schema {
+                kind: SchemaKind::Object,
+                description: None,
+                required: true,
+                nullable: false,
+                default_value: None,
+                fields: BTreeMap::new(),
+                items: None,
+                enum_values: Vec::new(),
+                variants: Vec::new(),
+            },
+            input_mapping: MappingSet { rules: Vec::new() },
+            output_mapping: MappingSet { rules: Vec::new() },
+            execution_config: ExecutionConfig {
+                timeout_ms: 1_000,
+                retry_policy: None,
+                response_cache: None,
+                idempotency: Some(IdempotencyPolicy {
+                    mode: IdempotencyMode::Required,
+                    ttl_ms: 60_000,
+                    input_field: Some("request_id".to_owned()),
+                    header_name: Some("Idempotency-Key".to_owned()),
+                }),
+                safety: None,
+                approval_policy: None,
+                auth_profile_ref: None,
+                headers: BTreeMap::new(),
+            },
+            tool_description: ToolDescription {
+                title: "Idempotent write".to_owned(),
+                description: "Test operation".to_owned(),
+                tags: Vec::new(),
+                examples: Vec::new(),
+            },
+        };
+        let mut prepared = PreparedRequest {
+            headers: BTreeMap::from([("idempotency-key".to_owned(), "attacker".to_owned())]),
+            ..PreparedRequest::default()
+        };
+
+        let key = super::prepare_idempotency(
+            &operation,
+            &json!({"request_id": "trusted-key"}),
+            &mut prepared,
+        )
+        .unwrap();
+
+        assert_eq!(key.as_deref(), Some("trusted-key"));
+        assert_eq!(
+            prepared.headers.get("Idempotency-Key").map(String::as_str),
+            Some("trusted-key")
+        );
+        assert!(!prepared.headers.contains_key("idempotency-key"));
+        assert!(prepared.trusted_header_names.contains("idempotency-key"));
+    }
+}

crates/crank-runtime/src/lib.rs

@@ -3,6 +3,8 @@ mod cache;
 mod cache_factory;
 mod confirmation;
 mod error;
+mod execution_failure;
+mod execution_request;
 mod executor;
 mod executor_builder;
 mod idempotency;
@@ -25,7 +27,11 @@ pub use cache_factory::{
 };
 pub use crank_adapter_rest::OutboundHttpPolicy;
 pub use error::RuntimeError;
-pub use executor::{RuntimeExecutionRequest, RuntimeExecutor};
+pub use execution_failure::{normalize_runtime_error, normalize_runtime_error_for_operation};
+pub use execution_request::{
+    ExecutionAuthorization, ExecutionRequestError, RuntimeExecutionRequest,
+};
+pub use executor::RuntimeExecutor;
 pub use executor_builder::{
     RuntimeExecutorBuilder, community_default, community_with_outbound_policy,
 };

crates/crank-runtime/src/model.rs

@@ -1,4 +1,4 @@
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 
 use crank_core::{ExecutionConfig, Operation, OperationId, Protocol, Target, ToolDescription};
 use crank_mapping::MappingSet;
@@ -47,6 +47,8 @@ pub struct PreparedRequest {
     pub query_params: BTreeMap<String, String>,
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub headers: BTreeMap<String, String>,
+    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
+    pub trusted_header_names: BTreeSet<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<serde_json::Value>,
     #[serde(default)]
@@ -68,6 +70,7 @@ impl From<PreparedRequest> for crank_core::PreparedRequest {
             path_params: value.path_params,
             query_params: value.query_params,
             headers: value.headers,
+            trusted_header_names: value.trusted_header_names,
             body: value.body,
             timeout_ms: value.timeout_ms,
         }
@@ -80,6 +83,7 @@ impl From<crank_core::PreparedRequest> for PreparedRequest {
             path_params: value.path_params,
             query_params: value.query_params,
             headers: value.headers,
+            trusted_header_names: value.trusted_header_names,
             body: value.body,
             timeout_ms: value.timeout_ms,
         }

crates/crank-runtime/src/request_context.rs

@@ -10,7 +10,7 @@ pub struct ResponseCacheScope {
     pub agent_key: String,
 }
 
-#[derive(Clone, Debug, PartialEq, Eq)]
+#[derive(Clone, PartialEq, Eq)]
 pub struct RuntimeRequestContext {
     pub request_id: RequestId,
     pub trace_context: TraceContext,
@@ -20,6 +20,23 @@ pub struct RuntimeRequestContext {
     pub approval_granted: bool,
 }
 
+impl std::fmt::Debug for RuntimeRequestContext {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("RuntimeRequestContext")
+            .field("request_id", &self.request_id)
+            .field("trace_context", &self.trace_context)
+            .field("response_cache_scope", &self.response_cache_scope)
+            .field("metering_context", &self.metering_context)
+            .field(
+                "confirmation_token",
+                &self.confirmation_token.as_ref().map(|_| "[REDACTED]"),
+            )
+            .field("approval_granted", &self.approval_granted)
+            .finish()
+    }
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MeteringContext {
     pub workspace_id: WorkspaceId,
@@ -142,12 +159,13 @@ impl From<&ResponseCacheScope> for crank_core::ResponseCacheScope {
 
 impl From<&RuntimeRequestContext> for crank_core::RuntimeRequestContext {
     fn from(value: &RuntimeRequestContext) -> Self {
-        Self {
-            request_id: value.request_id.clone(),
-            trace_context: value.trace_context.clone(),
-            response_cache_scope: value.response_cache_scope.as_ref().map(Into::into),
-            metering_context: value.metering_context.as_ref().map(Into::into),
-        }
+        let mut context = crank_core::RuntimeRequestContext::new(
+            value.request_id.clone(),
+            value.trace_context.clone(),
+        );
+        context.response_cache_scope = value.response_cache_scope.as_ref().map(Into::into);
+        context.metering_context = value.metering_context.as_ref().map(Into::into);
+        context
     }
 }
 
@@ -218,6 +236,7 @@ mod tests {
             RuntimeRequestContext::from_request_id("req_123").with_confirmation_token("ct_123");
 
         assert_eq!(context.confirmation_token(), Some("ct_123"));
+        assert!(!format!("{context:?}").contains("ct_123"));
     }
 
     #[test]

crates/crank-runtime/src/request_preparation.rs

@@ -19,6 +19,7 @@ impl PreparedRequest {
             path_params: read_string_map(request.get("path"), "request.path")?,
             query_params: read_string_map(request.get("query"), "request.query")?,
             headers: read_string_map(request.get("headers"), "request.headers")?,
+            trusted_header_names: Default::default(),
             body: request.get("body").and_then(non_empty_body).cloned(),
             timeout_ms: 0,
         })

crates/crank-runtime/src/secret_crypto.rs

@@ -13,22 +13,35 @@ use crate::RuntimeError;
 const LEGACY_KEY_VERSION: &str = "v1";
 const CURRENT_KEY_VERSION: &str = "v2";
 const SECRET_ENVELOPE_INFO: &[u8] = b"crank.secret-envelope.v2";
+const MASTER_KEY_FINGERPRINT_INFO: &[u8] = b"crank.master-key-identity.v1";
+const DEFAULT_MASTER_KEY_EPOCH: i64 = 1;
+const MIN_MASTER_KEY_BYTES: usize = 32;
 
 #[derive(Clone)]
 pub struct SecretCrypto {
     current_cipher: Aes256Gcm,
     legacy_cipher: Aes256Gcm,
     key_version: String,
+    master_key_fingerprint: String,
+    master_key_epoch: i64,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
 struct CipherEnvelope {
     nonce_b64: String,
     ciphertext_b64: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    cipher_version: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    epoch: Option<i64>,
 }
 
 impl SecretCrypto {
     pub fn new(master_key: &str) -> Result<Self, RuntimeError> {
+        Self::with_epoch(master_key, DEFAULT_MASTER_KEY_EPOCH)
+    }
+
+    pub fn with_epoch(master_key: &str, master_key_epoch: i64) -> Result<Self, RuntimeError> {
         let trimmed = master_key.trim();
         if trimmed.is_empty() {
             return Err(RuntimeError::SecretCrypto {
@@ -36,11 +49,25 @@ impl SecretCrypto {
                 details: "CRANK_MASTER_KEY must not be empty".to_owned(),
             });
         }
+        if trimmed.len() < MIN_MASTER_KEY_BYTES {
+            return Err(RuntimeError::SecretCrypto {
+                operation: "initialize secret crypto",
+                details: "CRANK_MASTER_KEY must be at least 32 bytes".to_owned(),
+            });
+        }
+        if master_key_epoch < 1 {
+            return Err(RuntimeError::SecretCrypto {
+                operation: "initialize secret crypto",
+                details: "master key epoch must be positive".to_owned(),
+            });
+        }
 
         Ok(Self {
             current_cipher: derive_hkdf_cipher(trimmed)?,
             legacy_cipher: derive_legacy_cipher(trimmed)?,
             key_version: CURRENT_KEY_VERSION.to_owned(),
+            master_key_fingerprint: master_key_fingerprint(trimmed),
+            master_key_epoch,
         })
     }
 
@@ -48,16 +75,77 @@ impl SecretCrypto {
         &self.key_version
     }
 
+    pub fn master_key_fingerprint(&self) -> &str {
+        &self.master_key_fingerprint
+    }
+
+    pub fn master_key_epoch(&self) -> i64 {
+        self.master_key_epoch
+    }
+
     pub fn encrypt(&self, value: &Value) -> Result<String, RuntimeError> {
-        encrypt_value_with_cipher(&self.current_cipher, value, "encrypt secret value")
+        encrypt_value_with_cipher(
+            &self.current_cipher,
+            value,
+            "encrypt secret value",
+            Some(self.key_version.as_str()),
+            Some(self.master_key_epoch),
+        )
     }
 
     pub fn decrypt(&self, key_version: &str, ciphertext: &str) -> Result<Value, RuntimeError> {
+        self.decrypt_envelope(key_version, None, ciphertext)
+    }
+
+    pub fn decrypt_for_epoch(
+        &self,
+        key_version: &str,
+        expected_epoch: i64,
+        ciphertext: &str,
+    ) -> Result<Value, RuntimeError> {
+        if expected_epoch < 1 {
+            return Err(RuntimeError::SecretCrypto {
+                operation: "validate secret epoch",
+                details: "secret epoch must be positive".to_owned(),
+            });
+        }
+        self.decrypt_envelope(key_version, Some(expected_epoch), ciphertext)
+    }
+
+    fn decrypt_envelope(
+        &self,
+        key_version: &str,
+        expected_epoch: Option<i64>,
+        ciphertext: &str,
+    ) -> Result<Value, RuntimeError> {
         let envelope: CipherEnvelope =
             serde_json::from_str(ciphertext).map_err(|error| RuntimeError::SecretCrypto {
                 operation: "decode secret envelope",
                 details: format!("failed to decode secret envelope: {error}"),
             })?;
+        if let Some(expected_epoch) = expected_epoch {
+            match envelope.epoch {
+                Some(actual_epoch) if actual_epoch == expected_epoch => {}
+                None if expected_epoch == DEFAULT_MASTER_KEY_EPOCH => {}
+                _ => {
+                    return Err(RuntimeError::SecretCrypto {
+                        operation: "validate secret epoch",
+                        details: "secret ciphertext epoch does not match active master key epoch"
+                            .to_owned(),
+                    });
+                }
+            }
+        }
+        let cipher = self.cipher_for_version(key_version)?;
+        if let Some(cipher_version) = &envelope.cipher_version
+            && cipher_version != key_version
+        {
+            return Err(RuntimeError::SecretCrypto {
+                operation: "validate secret cipher version",
+                details: "secret ciphertext cipher version does not match stored key version"
+                    .to_owned(),
+            });
+        }
         let nonce_bytes =
             STANDARD
                 .decode(envelope.nonce_b64)
@@ -71,7 +159,6 @@ impl SecretCrypto {
                 details: format!("failed to decode secret payload: {error}"),
             }
         })?;
-        let cipher = self.cipher_for_version(key_version)?;
         let plaintext = cipher
             .decrypt(Nonce::from_slice(&nonce_bytes), ciphertext_bytes.as_ref())
             .map_err(|error| RuntimeError::SecretCrypto {
@@ -97,6 +184,14 @@ impl SecretCrypto {
     }
 }
 
+fn master_key_fingerprint(master_key: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(MASTER_KEY_FINGERPRINT_INFO);
+    hasher.update([0]);
+    hasher.update(master_key.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
 fn derive_legacy_cipher(master_key: &str) -> Result<Aes256Gcm, RuntimeError> {
     let digest = Sha256::digest(master_key.as_bytes());
     Aes256Gcm::new_from_slice(digest.as_slice()).map_err(|error| RuntimeError::SecretCrypto {
@@ -123,6 +218,8 @@ fn encrypt_value_with_cipher(
     cipher: &Aes256Gcm,
     value: &Value,
     action: &str,
+    cipher_version: Option<&str>,
+    epoch: Option<i64>,
 ) -> Result<String, RuntimeError> {
     let plaintext = serde_json::to_vec(value).map_err(|error| RuntimeError::SecretCrypto {
         operation: "serialize secret value",
@@ -141,6 +238,8 @@ fn encrypt_value_with_cipher(
     let envelope = CipherEnvelope {
         nonce_b64: STANDARD.encode(nonce_bytes),
         ciphertext_b64: STANDARD.encode(ciphertext),
+        cipher_version: cipher_version.map(str::to_owned),
+        epoch,
     };
 
     serde_json::to_string(&envelope).map_err(|error| RuntimeError::SecretCrypto {
@@ -152,7 +251,13 @@ fn encrypt_value_with_cipher(
 #[cfg(test)]
 fn encrypt_with_legacy_scheme(master_key: &str, value: &Value) -> Result<String, RuntimeError> {
     let cipher = derive_legacy_cipher(master_key)?;
-    encrypt_value_with_cipher(&cipher, value, "encrypt secret value with legacy scheme")
+    encrypt_value_with_cipher(
+        &cipher,
+        value,
+        "encrypt secret value with legacy scheme",
+        None,
+        None,
+    )
 }
 
 #[cfg(test)]
@@ -185,9 +290,13 @@ mod tests {
         encrypt_with_legacy_scheme, legacy_key_bytes,
     };
 
+    const TEST_MASTER_KEY: &str = "test-master-key-00000000000000000000000000000000";
+    const TEST_MASTER_KEY_A: &str = "test-master-key-a-000000000000000000000000000000";
+    const TEST_MASTER_KEY_B: &str = "test-master-key-b-000000000000000000000000000000";
+
     #[test]
     fn roundtrips_secret_payload_with_current_scheme() {
-        let crypto = SecretCrypto::new("test-master-key").unwrap();
+        let crypto = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
         let plaintext = json!({
             "token": "top-secret",
             "username": "demo"
@@ -206,8 +315,8 @@ mod tests {
             "token": "top-secret",
             "username": "demo"
         });
-        let ciphertext = encrypt_with_legacy_scheme("test-master-key", &plaintext).unwrap();
-        let crypto = SecretCrypto::new("test-master-key").unwrap();
+        let ciphertext = encrypt_with_legacy_scheme(TEST_MASTER_KEY, &plaintext).unwrap();
+        let crypto = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
 
         let decrypted = crypto.decrypt(LEGACY_KEY_VERSION, &ciphertext).unwrap();
 
@@ -226,18 +335,30 @@ mod tests {
         }
     }
 
+    #[test]
+    fn rejects_weak_master_key() {
+        let error = SecretCrypto::new("short-master-key").err().unwrap();
+        match error {
+            RuntimeError::SecretCrypto { operation, details } => {
+                assert_eq!(operation, "initialize secret crypto");
+                assert_eq!(details, "CRANK_MASTER_KEY must be at least 32 bytes");
+            }
+            other => panic!("unexpected error: {other}"),
+        }
+    }
+
     #[test]
     fn same_master_key_derives_stable_hkdf_key() {
-        let lhs = current_key_bytes("test-master-key").unwrap();
-        let rhs = current_key_bytes("test-master-key").unwrap();
+        let lhs = current_key_bytes(TEST_MASTER_KEY).unwrap();
+        let rhs = current_key_bytes(TEST_MASTER_KEY).unwrap();
 
         assert_eq!(lhs, rhs);
     }
 
     #[test]
     fn current_scheme_key_differs_from_legacy_scheme() {
-        let current = current_key_bytes("test-master-key").unwrap();
-        let legacy = legacy_key_bytes("test-master-key");
+        let current = current_key_bytes(TEST_MASTER_KEY).unwrap();
+        let legacy = legacy_key_bytes(TEST_MASTER_KEY);
 
         assert_ne!(current, legacy);
     }
@@ -248,8 +369,8 @@ mod tests {
             "token": "top-secret",
             "username": "demo"
         });
-        let left = SecretCrypto::new("test-master-key-a").unwrap();
-        let right = SecretCrypto::new("test-master-key-b").unwrap();
+        let left = SecretCrypto::new(TEST_MASTER_KEY_A).unwrap();
+        let right = SecretCrypto::new(TEST_MASTER_KEY_B).unwrap();
 
         let left_ciphertext = left.encrypt(&plaintext).unwrap();
         let right_ciphertext = right.encrypt(&plaintext).unwrap();
@@ -259,7 +380,7 @@ mod tests {
 
     #[test]
     fn rejects_unknown_key_version() {
-        let crypto = SecretCrypto::new("test-master-key").unwrap();
+        let crypto = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
         let ciphertext = crypto.encrypt(&json!({"token": "top-secret"})).unwrap();
         let error = crypto.decrypt("v999", &ciphertext).unwrap_err();
 
@@ -271,4 +392,59 @@ mod tests {
             other => panic!("unexpected error: {other}"),
         }
     }
+
+    #[test]
+    fn exposes_stable_non_secret_master_key_identity() {
+        let left = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
+        let right = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
+        let different = SecretCrypto::new(TEST_MASTER_KEY_B).unwrap();
+
+        assert_eq!(left.master_key_epoch(), 1);
+        assert_eq!(
+            left.master_key_fingerprint(),
+            right.master_key_fingerprint()
+        );
+        assert_ne!(
+            left.master_key_fingerprint(),
+            different.master_key_fingerprint()
+        );
+        assert_eq!(left.master_key_fingerprint().len(), 64);
+        assert!(
+            left.master_key_fingerprint()
+                .bytes()
+                .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+        );
+        assert!(!left.master_key_fingerprint().contains("test-master-key"));
+    }
+
+    #[test]
+    fn current_ciphertext_carries_epoch_metadata() {
+        let crypto = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
+        let ciphertext = crypto.encrypt(&json!({"token": "top-secret"})).unwrap();
+        let envelope: serde_json::Value = serde_json::from_str(&ciphertext).unwrap();
+
+        assert_eq!(envelope["epoch"], json!(1));
+        assert_eq!(envelope["cipher_version"], json!(CURRENT_KEY_VERSION));
+        assert!(envelope.get("master_key_fingerprint").is_none());
+
+        let decrypted = crypto
+            .decrypt_for_epoch(CURRENT_KEY_VERSION, 1, &ciphertext)
+            .unwrap();
+        assert_eq!(decrypted, json!({"token": "top-secret"}));
+    }
+
+    #[test]
+    fn legacy_ciphertext_without_epoch_remains_readable() {
+        let plaintext = json!({"token": "top-secret"});
+        let ciphertext = encrypt_with_legacy_scheme(TEST_MASTER_KEY, &plaintext).unwrap();
+        let envelope: serde_json::Value = serde_json::from_str(&ciphertext).unwrap();
+        assert!(envelope.get("epoch").is_none());
+
+        let crypto = SecretCrypto::new(TEST_MASTER_KEY).unwrap();
+        let decrypted = crypto
+            .decrypt_for_epoch(LEGACY_KEY_VERSION, 1, &ciphertext)
+            .unwrap();
+
+        assert_eq!(decrypted, plaintext);
+    }
 }

crates/crank-runtime/tests/integration.rs

@@ -1,3 +1,5 @@
+mod support;
+
 mod integration {
     mod confirmation;
     mod idempotency;

crates/crank-runtime/tests/integration/confirmation.rs

@@ -7,14 +7,14 @@ use std::sync::{
 use async_trait::async_trait;
 use crank_core::{
     AdapterResponse, CacheScope, CacheStoreError, ConfirmationPolicy, CoordinationStateReservation,
-    CoordinationStateStore, CoordinationStateValue, ExecutionConfig, ExecutionMode, HttpMethod,
-    Operation, OperationId, OperationSafetyClass, OperationSafetyPolicy, OperationSecurityLevel,
-    OperationStatus, Protocol, ProtocolAdapter, ProtocolAdapterError, RestTarget, Target,
-    ToolDescription,
+    CoordinationStateStore, CoordinationStateValue, ExecutionConfig, ExecutionErrorCode,
+    ExecutionMode, HttpMethod, Operation, OperationId, OperationSafetyClass, OperationSafetyPolicy,
+    OperationSecurityLevel, OperationStatus, Protocol, ProtocolAdapter, ProtocolAdapterError,
+    RestTarget, Target, ToolDescription,
 };
 use crank_mapping::{MappingRule, MappingSet};
 use crank_runtime::{
-    InMemoryCoordinationStateStore, RuntimeError, RuntimeExecutorBuilder, RuntimeRequestContext,
+    InMemoryCoordinationStateStore, RuntimeExecutorBuilder, RuntimeRequestContext,
 };
 use crank_schema::{Schema, SchemaKind};
 use futures_util::future::join_all;
@@ -42,12 +42,12 @@ async fn destructive_operation_requires_single_use_confirmation() {
         )
         .await
         .expect_err("first destructive call must only stage confirmation");
-    let confirmation_token = match first {
-        RuntimeError::ConfirmationRequired {
-            confirmation_token, ..
-        } => confirmation_token,
-        error => panic!("expected confirmation required, got {error:?}"),
-    };
+    assert_eq!(first.error_code(), ExecutionErrorCode::ConfirmationRequired);
+    let confirmation_token = first
+        .confirmation()
+        .expect("expected confirmation challenge")
+        .token()
+        .to_owned();
     assert_eq!(call_count.load(Ordering::SeqCst), 0);
 
     let confirmed_context = context
@@ -72,10 +72,7 @@ async fn destructive_operation_requires_single_use_confirmation() {
         )
         .await
         .expect_err("confirmation token must be single-use");
-    assert!(matches!(
-        replay,
-        RuntimeError::InvalidConfirmationToken { .. }
-    ));
+    assert_eq!(replay.error_code(), ExecutionErrorCode::ConfirmationInvalid);
     assert_eq!(call_count.load(Ordering::SeqCst), 1);
 
     let approved_context = context.with_approval_granted();
@@ -111,12 +108,12 @@ async fn confirmation_token_allows_only_one_concurrent_execution() {
         )
         .await
         .unwrap_err();
-    let RuntimeError::ConfirmationRequired {
-        confirmation_token, ..
-    } = first
-    else {
-        panic!("expected confirmation token")
-    };
+    assert_eq!(first.error_code(), ExecutionErrorCode::ConfirmationRequired);
+    let confirmation_token = first
+        .confirmation()
+        .expect("expected confirmation token")
+        .token()
+        .to_owned();
 
     let attempts = (0..16).map(|_| {
         let executor = executor.clone();
@@ -143,7 +140,7 @@ async fn confirmation_token_allows_only_one_concurrent_execution() {
         results
             .iter()
             .filter_map(|result| result.as_ref().err())
-            .all(|error| matches!(error, RuntimeError::InvalidConfirmationToken { .. }))
+            .all(|error| error.error_code() == ExecutionErrorCode::ConfirmationInvalid)
     );
 }
 
@@ -167,11 +164,10 @@ async fn unavailable_confirmation_store_is_preserved_as_a_typed_error() {
         )
         .await
         .expect_err("unavailable store must prevent issuing a token");
-    assert!(matches!(
-        issue_error,
-        RuntimeError::ConfirmationStoreUnavailable { ref operation_id }
-            if operation_id == "op_delete_order"
-    ));
+    assert_eq!(
+        issue_error.error_code(),
+        ExecutionErrorCode::SafetyStoreUnavailable
+    );
 
     let consume_error = executor
         .execute_with_context(
@@ -181,11 +177,10 @@ async fn unavailable_confirmation_store_is_preserved_as_a_typed_error() {
         )
         .await
         .expect_err("unavailable store must not look like an invalid token");
-    assert!(matches!(
-        consume_error,
-        RuntimeError::ConfirmationStoreUnavailable { ref operation_id }
-            if operation_id == "op_delete_order"
-    ));
+    assert_eq!(
+        consume_error.error_code(),
+        ExecutionErrorCode::SafetyStoreUnavailable
+    );
 }
 
 struct UnavailableCoordinationStore;
@@ -396,3 +391,4 @@ fn bool_schema() -> Schema {
         variants: Vec::new(),
     }
 }
+use crate::support::RuntimeExecutorTestExt;

crates/crank-runtime/tests/integration/idempotency.rs

@@ -6,15 +6,14 @@ use std::sync::{
 
 use async_trait::async_trait;
 use crank_core::{
-    AdapterResponse, ExecutionConfig, ExecutionMode, HttpMethod, IdempotencyMode,
-    IdempotencyPolicy, Operation, OperationId, OperationSecurityLevel, OperationStatus, Protocol,
-    ProtocolAdapter, ProtocolAdapterError, RestTarget, RuntimeRequestContext, Target,
-    ToolDescription,
+    AdapterResponse, ExecutionConfig, ExecutionErrorCode, ExecutionMode, HttpMethod,
+    IdempotencyMode, IdempotencyPolicy, Operation, OperationId, OperationSecurityLevel,
+    OperationStatus, Protocol, ProtocolAdapter, ProtocolAdapterError, RestTarget,
+    RuntimeRequestContext, Target, ToolDescription,
 };
 use crank_mapping::{MappingRule, MappingSet};
 use crank_runtime::{
-    InMemoryCoordinationStateStore, InMemoryResponseCacheStore, RuntimeError,
-    RuntimeExecutorBuilder,
+    InMemoryCoordinationStateStore, InMemoryResponseCacheStore, RuntimeExecutorBuilder,
 };
 use crank_schema::{Schema, SchemaKind};
 use serde_json::json;
@@ -71,10 +70,10 @@ async fn required_idempotency_rejects_missing_key_before_adapter_call() {
         .await
         .expect_err("missing idempotency key must fail");
 
-    assert!(matches!(
-        error,
-        crank_runtime::RuntimeError::InvalidPreparedRequest { .. }
-    ));
+    assert_eq!(
+        error.error_code(),
+        ExecutionErrorCode::PreparedRequestInvalid
+    );
     assert_eq!(call_count.load(Ordering::SeqCst), 0);
 }
 
@@ -100,10 +99,10 @@ async fn required_idempotency_fails_closed_without_coordination_store() {
         .await
         .expect_err("required idempotency must not execute without an atomic store");
 
-    assert!(matches!(
-        error,
-        RuntimeError::IdempotencyStoreUnavailable { .. }
-    ));
+    assert_eq!(
+        error.error_code(),
+        ExecutionErrorCode::SafetyStoreUnavailable
+    );
     assert_eq!(call_count.load(Ordering::SeqCst), 0);
 }
 
@@ -186,7 +185,7 @@ async fn same_key_with_different_input_is_rejected() {
         .await
         .expect_err("same key must not accept a different request fingerprint");
 
-    assert!(matches!(error, RuntimeError::IdempotencyConflict { .. }));
+    assert_eq!(error.error_code(), ExecutionErrorCode::IdempotencyConflict);
     assert_eq!(call_count.load(Ordering::SeqCst), 1);
 }
 
@@ -208,16 +207,19 @@ async fn uncertain_adapter_failure_blocks_automatic_retry() {
         .execute_with_context(&operation, &input, Some(&context))
         .await
         .expect_err("adapter failure must be returned");
-    assert!(matches!(first, RuntimeError::ProtocolAdapter(_)));
+    assert_eq!(
+        first.error_code(),
+        ExecutionErrorCode::UpstreamTransportError
+    );
 
     let retry = executor
         .execute_with_context(&operation, &input, Some(&context))
         .await
         .expect_err("an uncertain external outcome must not be retried automatically");
-    assert!(matches!(
-        retry,
-        RuntimeError::IdempotencyOutcomeUnknown { .. }
-    ));
+    assert_eq!(
+        retry.error_code(),
+        ExecutionErrorCode::IdempotencyOutcomeUnknown
+    );
     assert_eq!(call_count.load(Ordering::SeqCst), 1);
 }
 
@@ -257,9 +259,9 @@ impl ProtocolAdapter for FailingAdapter {
         _context: &RuntimeRequestContext,
     ) -> Result<AdapterResponse, ProtocolAdapterError> {
         self.call_count.fetch_add(1, Ordering::SeqCst);
-        Err(ProtocolAdapterError::Message(
-            "upstream outcome is unknown".to_owned(),
-        ))
+        Err(ProtocolAdapterError::Transport {
+            dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+        })
     }
 }
 
@@ -381,3 +383,4 @@ fn string_schema() -> Schema {
         variants: Vec::new(),
     }
 }
+use crate::support::RuntimeExecutorTestExt;

crates/crank-runtime/tests/integration/no_input_get.rs

@@ -1,28 +1,60 @@
-use std::collections::BTreeMap;
+use std::{collections::BTreeMap, sync::Arc};
 
+use async_trait::async_trait;
 use crank_core::{
-    ExecutionConfig, HttpMethod, Operation, OperationId, OperationSecurityLevel, OperationStatus,
-    Protocol, RestTarget, Target, ToolDescription,
+    AdapterResponse, ExecutionConfig, ExecutionMode, HttpMethod, Operation, OperationId,
+    OperationSecurityLevel, OperationStatus, PreparedRequest, Protocol, ProtocolAdapter,
+    ProtocolAdapterError, RestTarget, RuntimeRequestContext as ProtocolRequestContext, Target,
+    ToolDescription,
 };
 use crank_mapping::MappingSet;
-use crank_runtime::RuntimeExecutor;
+use crank_runtime::RuntimeExecutorBuilder;
 use crank_schema::{Schema, SchemaKind};
 use serde_json::json;
 use time::OffsetDateTime;
 
-#[test]
-fn prepares_empty_request_for_no_input_get_with_empty_mapping() {
-    let executor = RuntimeExecutor::new();
-    let operation = no_input_get_operation();
+use crate::support::RuntimeExecutorTestExt;
 
-    let request = executor
-        .prepare_request(&operation.into(), &json!({}))
-        .unwrap();
+#[tokio::test]
+async fn prepares_empty_request_for_no_input_get_with_empty_mapping() {
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(EmptyRequestAdapter))
+        .build();
+    let operation = no_input_get_operation().into();
 
-    assert!(request.path_params.is_empty());
-    assert!(request.query_params.is_empty());
-    assert!(request.headers.is_empty());
-    assert!(request.body.is_none());
+    let response = executor.execute(&operation, &json!({})).await.unwrap();
+    assert_eq!(response, json!({}));
+}
+
+struct EmptyRequestAdapter;
+
+#[async_trait]
+impl ProtocolAdapter for EmptyRequestAdapter {
+    fn protocol(&self) -> Protocol {
+        Protocol::Rest
+    }
+
+    fn supports_mode(&self, mode: ExecutionMode) -> bool {
+        mode == ExecutionMode::Unary
+    }
+
+    async fn invoke_unary(
+        &self,
+        _target: &Target,
+        request: &PreparedRequest,
+        _context: &ProtocolRequestContext,
+    ) -> Result<AdapterResponse, ProtocolAdapterError> {
+        assert!(request.path_params.is_empty());
+        assert!(request.query_params.is_empty());
+        assert!(request.headers.is_empty());
+        assert!(request.body.is_none());
+        Ok(AdapterResponse {
+            status_code: 200,
+            headers: BTreeMap::new(),
+            body: json!({}),
+            data: json!({}),
+        })
+    }
 }
 
 fn no_input_get_operation() -> Operation<Schema, MappingSet> {

crates/crank-runtime/tests/product_metrics.rs

@@ -8,16 +8,16 @@ use std::{
 
 use async_trait::async_trait;
 use crank_core::{
-    AdapterResponse, ConfirmationPolicy, ExecutionConfig, ExecutionMode, HttpMethod,
-    IdempotencyMode, IdempotencyPolicy, Operation, OperationId, OperationSafetyClass,
+    AdapterResponse, ConfirmationPolicy, ExecutionConfig, ExecutionErrorCode, ExecutionMode,
+    HttpMethod, IdempotencyMode, IdempotencyPolicy, Operation, OperationId, OperationSafetyClass,
     OperationSafetyPolicy, OperationSecurityLevel, OperationStatus, Protocol, ProtocolAdapter,
     ProtocolAdapterError, ResponseCachePolicy, RestTarget,
     RuntimeRequestContext as ProtocolRequestContext, Target, ToolDescription,
 };
 use crank_mapping::{MappingRule, MappingSet};
 use crank_runtime::{
-    InMemoryCoordinationStateStore, InMemoryResponseCacheStore, RuntimeError,
-    RuntimeExecutorBuilder, RuntimeRequestContext,
+    InMemoryCoordinationStateStore, InMemoryResponseCacheStore, RuntimeExecutorBuilder,
+    RuntimeRequestContext,
 };
 use crank_schema::{Schema, SchemaKind};
 use metrics_util::debugging::DebuggingRecorder;
@@ -110,10 +110,10 @@ async fn exercise_cancelled_idempotency() {
         .execute_with_context(&operation, &input, Some(&context))
         .await
         .expect_err("cancelled external outcome must not be retried automatically");
-    assert!(matches!(
-        retry,
-        RuntimeError::IdempotencyOutcomeUnknown { .. }
-    ));
+    assert_eq!(
+        retry.error_code(),
+        ExecutionErrorCode::IdempotencyOutcomeUnknown
+    );
     assert_eq!(calls.load(Ordering::SeqCst), 1);
 }
 
@@ -180,7 +180,10 @@ async fn exercise_idempotency() {
         .await
         .expect_err("same idempotency key with a different input must conflict");
 
-    assert!(matches!(conflict, RuntimeError::IdempotencyConflict { .. }));
+    assert_eq!(
+        conflict.error_code(),
+        ExecutionErrorCode::IdempotencyConflict
+    );
     assert_eq!(calls.load(Ordering::SeqCst), 1);
 }
 
@@ -206,12 +209,15 @@ async fn exercise_confirmation() {
         .execute_with_context(&operation, &input, Some(&context))
         .await
         .expect_err("destructive operation must require confirmation");
-    let RuntimeError::ConfirmationRequired {
-        confirmation_token, ..
-    } = required
-    else {
-        panic!("expected confirmation token");
-    };
+    assert_eq!(
+        required.error_code(),
+        ExecutionErrorCode::ConfirmationRequired
+    );
+    let confirmation_token = required
+        .confirmation()
+        .expect("expected confirmation token")
+        .token()
+        .to_owned();
     let confirmed = context
         .clone()
         .with_confirmation_token(confirmation_token.clone());
@@ -224,10 +230,10 @@ async fn exercise_confirmation() {
         .await
         .expect_err("confirmation token must be single-use");
 
-    assert!(matches!(
-        invalid,
-        RuntimeError::InvalidConfirmationToken { .. }
-    ));
+    assert_eq!(
+        invalid.error_code(),
+        ExecutionErrorCode::ConfirmationInvalid
+    );
     assert_eq!(calls.load(Ordering::SeqCst), 1);
 }
 
@@ -261,9 +267,10 @@ impl ProtocolAdapter for BlockingAdapter {
         &self,
         _target: &Target,
         _prepared: &crank_core::PreparedRequest,
-        _context: &ProtocolRequestContext,
+        context: &ProtocolRequestContext,
     ) -> Result<AdapterResponse, ProtocolAdapterError> {
         self.calls.fetch_add(1, Ordering::SeqCst);
+        context.mark_dispatch_started();
         std::future::pending().await
     }
 }
@@ -412,3 +419,6 @@ async fn wait_for_calls(calls: &AtomicUsize, expected: usize) {
     }
     panic!("adapter did not receive {expected} call(s)");
 }
+mod support;
+
+use support::RuntimeExecutorTestExt;

crates/crank-runtime/tests/stages.rs

@@ -1,3 +1,7 @@
+mod support;
+
+use support::RuntimeExecutorTestExt;
+
 use std::{
     collections::BTreeMap,
     sync::{Arc, Mutex},
@@ -5,14 +9,17 @@ use std::{
 
 use async_trait::async_trait;
 use crank_core::{
-    AdapterResponse, ConfirmationPolicy, ExecutionConfig, ExecutionMode, HttpMethod,
-    IdempotencyMode, IdempotencyPolicy, Operation, OperationId, OperationSafetyClass,
-    OperationSafetyPolicy, OperationSecurityLevel, OperationStatus, Protocol, ProtocolAdapter,
-    ProtocolAdapterError, RestTarget, Target, ToolDescription,
+    AdapterResponse, ConfirmationPolicy, CorrelationContext, ExecutionConfig, ExecutionErrorCode,
+    ExecutionMode, ExecutionOrigin, HttpMethod, IdempotencyMode, IdempotencyPolicy,
+    InvocationSource, Operation, OperationId, OperationSafetyClass, OperationSafetyPolicy,
+    OperationSecurityLevel, OperationStatus, OutcomeCertainty, Protocol, ProtocolAdapter,
+    ProtocolAdapterError, RestTarget, RetryPolicy, Retryability, Target, ToolDescription,
+    WorkspaceId,
 };
 use crank_mapping::{MappingRule, MappingSet};
 use crank_runtime::{
-    InMemoryCoordinationStateStore, RuntimeError, RuntimeExecutorBuilder, RuntimeRequestContext,
+    ExecutionAuthorization, InMemoryCoordinationStateStore, RuntimeExecutionRequest,
+    RuntimeExecutorBuilder, RuntimeRequestContext,
 };
 use crank_schema::{Schema, SchemaKind};
 use crank_trace::{Stage, StageOutcome};
@@ -24,6 +31,161 @@ use uuid::Version;
 
 static TRACING_TEST_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
 
+#[tokio::test]
+async fn deadline_after_dispatch_is_normalized_as_unknown_outcome() {
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(DelayedAdapter))
+        .build();
+    let operation = operation().into();
+    let input = json!({"name": "deadline"});
+    let workspace = WorkspaceId::new("ws_deadline");
+    let correlation = CorrelationContext::generate();
+    let context = RuntimeRequestContext::from_correlation(&correlation).with_metering_context(
+        workspace.clone(),
+        None,
+        InvocationSource::AdminTestRun,
+    );
+    let request = RuntimeExecutionRequest::try_new(
+        &workspace,
+        ExecutionOrigin::AdminDraft,
+        None,
+        &operation,
+        &input,
+        ExecutionAuthorization::Authorized,
+        None,
+        &context,
+        std::time::Instant::now() + std::time::Duration::from_millis(5),
+    )
+    .unwrap();
+
+    let failure = executor.execute_outcome(request).await.unwrap_err();
+    assert_eq!(failure.retryability(), Retryability::ManualReconcile);
+    assert_eq!(
+        failure.outcome_certainty(),
+        OutcomeCertainty::OutcomeUnknown
+    );
+}
+
+#[tokio::test]
+async fn deadline_after_read_only_dispatch_remains_safe_to_retry() {
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(DelayedAdapter))
+        .build();
+    let mut operation: crank_runtime::RuntimeOperation = operation().into();
+    let Target::Rest(target) = &mut operation.target;
+    target.method = HttpMethod::Get;
+    let input = json!({"name": "deadline"});
+    let workspace = WorkspaceId::new("ws_read_deadline");
+    let correlation = CorrelationContext::generate();
+    let context = RuntimeRequestContext::from_correlation(&correlation).with_metering_context(
+        workspace.clone(),
+        None,
+        InvocationSource::AdminTestRun,
+    );
+    let request = RuntimeExecutionRequest::try_new(
+        &workspace,
+        ExecutionOrigin::AdminDraft,
+        None,
+        &operation,
+        &input,
+        ExecutionAuthorization::Authorized,
+        None,
+        &context,
+        std::time::Instant::now() + std::time::Duration::from_millis(5),
+    )
+    .unwrap();
+
+    let failure = executor.execute_outcome(request).await.unwrap_err();
+    assert_eq!(failure.retryability(), Retryability::AfterDelay);
+    assert_eq!(failure.outcome_certainty(), OutcomeCertainty::Certain);
+}
+
+#[tokio::test]
+async fn read_retry_revalidates_adapter_attempt_and_keeps_one_success_outcome() {
+    let call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(FlakyReadAdapter {
+            call_count: Arc::clone(&call_count),
+        }))
+        .build();
+    let mut operation: crank_runtime::RuntimeOperation = operation().into();
+    let Target::Rest(target) = &mut operation.target;
+    target.method = HttpMethod::Get;
+    operation.execution_config.retry_policy = Some(RetryPolicy { max_attempts: 2 });
+
+    let result = executor
+        .execute(&operation, &json!({"name": "retry-read"}))
+        .await
+        .expect("read retry should recover after a known pre-dispatch transport failure");
+
+    assert_eq!(result, json!({"accepted": true}));
+    assert_eq!(call_count.load(std::sync::atomic::Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn mutating_retry_requires_verified_idempotency_contract() {
+    let call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(FlakyMayDispatchAdapter {
+            call_count: Arc::clone(&call_count),
+            captured_keys: Arc::new(Mutex::new(Vec::new())),
+        }))
+        .build();
+    let mut operation: crank_runtime::RuntimeOperation = operation().into();
+    operation.execution_config.retry_policy = Some(RetryPolicy { max_attempts: 2 });
+
+    let failure = executor
+        .execute(&operation, &json!({"name": "write-no-idempotency"}))
+        .await
+        .expect_err("write without idempotency must not retry after dispatch uncertainty");
+
+    assert_eq!(failure.retryability(), Retryability::ManualReconcile);
+    assert_eq!(
+        failure.outcome_certainty(),
+        OutcomeCertainty::OutcomeUnknown
+    );
+    assert_eq!(call_count.load(std::sync::atomic::Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn mutating_retry_with_verified_idempotency_reuses_same_key() {
+    let call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+    let captured_keys = Arc::new(Mutex::new(Vec::new()));
+    let executor = RuntimeExecutorBuilder::new()
+        .register_adapter(Arc::new(FlakyMayDispatchAdapter {
+            call_count: Arc::clone(&call_count),
+            captured_keys: Arc::clone(&captured_keys),
+        }))
+        .with_coordination_store(Arc::new(InMemoryCoordinationStateStore::default()))
+        .build();
+    let mut operation: crank_runtime::RuntimeOperation = operation().into();
+    operation.execution_config.retry_policy = Some(RetryPolicy { max_attempts: 2 });
+    operation.execution_config.idempotency = Some(IdempotencyPolicy {
+        mode: IdempotencyMode::Required,
+        ttl_ms: 60_000,
+        input_field: Some("name".to_owned()),
+        header_name: Some("Idempotency-Key".to_owned()),
+    });
+    let context = RuntimeRequestContext::from_request_id("req_retry_write")
+        .with_response_cache_scope("workspace", "agent");
+
+    let result = executor
+        .execute_with_context(
+            &operation,
+            &json!({"name": "write-with-idempotency"}),
+            Some(&context),
+        )
+        .await
+        .expect("idempotent write may retry with the same upstream key");
+
+    assert_eq!(result, json!({"accepted": true}));
+    assert_eq!(call_count.load(std::sync::atomic::Ordering::SeqCst), 2);
+    let keys = captured_keys.lock().expect("captured keys lock").clone();
+    assert_eq!(keys.len(), 2);
+    assert_eq!(keys[0], "write-with-idempotency");
+    assert_eq!(keys[1], keys[0]);
+}
+
 #[tokio::test]
 async fn successful_execution_has_real_stages_and_omits_inapplicable_ones() {
     let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
@@ -116,7 +278,7 @@ async fn failed_mapping_records_closed_category_and_stops_later_stages() {
 }
 
 #[tokio::test]
-async fn execution_without_context_sends_generated_correlation_headers() {
+async fn explicit_test_fixture_sends_generated_correlation_headers() {
     let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
     let captured_headers = Arc::new(Mutex::new(None));
     let executor = RuntimeExecutorBuilder::new()
@@ -184,7 +346,7 @@ async fn approval_stage_is_present_only_when_confirmation_is_required() {
 
     assert!(matches!(
         result,
-        Err(RuntimeError::ConfirmationRequired { .. })
+        Err(failure) if failure.error_code() == ExecutionErrorCode::ConfirmationRequired
     ));
     let spans = capture.snapshot();
     assert_stage(&spans, "approval.check", "required");
@@ -254,6 +416,113 @@ fn assert_stage(spans: &[CapturedSpan], name: &str, outcome: &str) {
 
 struct SuccessAdapter;
 
+struct DelayedAdapter;
+
+struct FlakyReadAdapter {
+    call_count: Arc<std::sync::atomic::AtomicUsize>,
+}
+
+struct FlakyMayDispatchAdapter {
+    call_count: Arc<std::sync::atomic::AtomicUsize>,
+    captured_keys: Arc<Mutex<Vec<String>>>,
+}
+
+#[async_trait]
+impl ProtocolAdapter for DelayedAdapter {
+    fn protocol(&self) -> Protocol {
+        Protocol::Rest
+    }
+
+    fn supports_mode(&self, mode: ExecutionMode) -> bool {
+        mode == ExecutionMode::Unary
+    }
+
+    async fn invoke_unary(
+        &self,
+        _target: &Target,
+        _prepared: &crank_core::PreparedRequest,
+        context: &crank_core::RuntimeRequestContext,
+    ) -> Result<AdapterResponse, ProtocolAdapterError> {
+        context.mark_dispatch_started();
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        unreachable!("deadline must cancel the adapter future")
+    }
+}
+
+#[async_trait]
+impl ProtocolAdapter for FlakyReadAdapter {
+    fn protocol(&self) -> Protocol {
+        Protocol::Rest
+    }
+
+    fn supports_mode(&self, mode: ExecutionMode) -> bool {
+        mode == ExecutionMode::Unary
+    }
+
+    async fn invoke_unary(
+        &self,
+        _target: &Target,
+        _prepared: &crank_core::PreparedRequest,
+        _context: &crank_core::RuntimeRequestContext,
+    ) -> Result<AdapterResponse, ProtocolAdapterError> {
+        if self
+            .call_count
+            .fetch_add(1, std::sync::atomic::Ordering::SeqCst)
+            == 0
+        {
+            return Err(ProtocolAdapterError::Transport {
+                dispatch: crank_core::DispatchEvidence::NotDispatched,
+            });
+        }
+        Ok(AdapterResponse {
+            status_code: 200,
+            headers: BTreeMap::new(),
+            body: json!({"accepted": true}),
+            data: json!({"accepted": true}),
+        })
+    }
+}
+
+#[async_trait]
+impl ProtocolAdapter for FlakyMayDispatchAdapter {
+    fn protocol(&self) -> Protocol {
+        Protocol::Rest
+    }
+
+    fn supports_mode(&self, mode: ExecutionMode) -> bool {
+        mode == ExecutionMode::Unary
+    }
+
+    async fn invoke_unary(
+        &self,
+        _target: &Target,
+        prepared: &crank_core::PreparedRequest,
+        _context: &crank_core::RuntimeRequestContext,
+    ) -> Result<AdapterResponse, ProtocolAdapterError> {
+        if let Some(key) = prepared.headers.get("Idempotency-Key") {
+            self.captured_keys
+                .lock()
+                .expect("captured keys lock")
+                .push(key.clone());
+        }
+        if self
+            .call_count
+            .fetch_add(1, std::sync::atomic::Ordering::SeqCst)
+            == 0
+        {
+            return Err(ProtocolAdapterError::Transport {
+                dispatch: crank_core::DispatchEvidence::MayHaveDispatched,
+            });
+        }
+        Ok(AdapterResponse {
+            status_code: 200,
+            headers: BTreeMap::new(),
+            body: json!({"accepted": true}),
+            data: json!({"accepted": true}),
+        })
+    }
+}
+
 #[async_trait]
 impl ProtocolAdapter for SuccessAdapter {
     fn protocol(&self) -> Protocol {

crates/crank-runtime/tests/support/mod.rs

@@ -0,0 +1,101 @@
+use std::time::{Duration, Instant};
+
+use crank_core::{ExecutionFailure, ExecutionOrigin, InvocationSource, WorkspaceId};
+use crank_runtime::{
+    ExecutionAuthorization, ResolvedAuth, RuntimeExecutionRequest, RuntimeExecutor,
+    RuntimeOperation, RuntimeRequestContext,
+};
+use serde_json::Value;
+
+#[allow(dead_code)]
+pub trait RuntimeExecutorTestExt {
+    async fn execute(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+    ) -> Result<Value, ExecutionFailure>;
+
+    async fn execute_with_context(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+        context: Option<&RuntimeRequestContext>,
+    ) -> Result<Value, ExecutionFailure>;
+
+    async fn execute_with_auth_and_context(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+        resolved_auth: Option<&ResolvedAuth>,
+        context: Option<&RuntimeRequestContext>,
+    ) -> Result<Value, ExecutionFailure>;
+}
+
+impl RuntimeExecutorTestExt for RuntimeExecutor {
+    async fn execute(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+    ) -> Result<Value, ExecutionFailure> {
+        self.execute_with_auth_and_context(operation, input, None, None)
+            .await
+    }
+
+    async fn execute_with_context(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+        context: Option<&RuntimeRequestContext>,
+    ) -> Result<Value, ExecutionFailure> {
+        self.execute_with_auth_and_context(operation, input, None, context)
+            .await
+    }
+
+    async fn execute_with_auth_and_context(
+        &self,
+        operation: &RuntimeOperation,
+        input: &Value,
+        resolved_auth: Option<&ResolvedAuth>,
+        context: Option<&RuntimeRequestContext>,
+    ) -> Result<Value, ExecutionFailure> {
+        let mut context = context.cloned().unwrap_or_else(|| {
+            RuntimeRequestContext::from_correlation(&crank_core::CorrelationContext::generate())
+        });
+        if context.metering_context().is_none() {
+            context = context.with_metering_context(
+                WorkspaceId::new("ws_test"),
+                None,
+                InvocationSource::AdminTestRun,
+            );
+        }
+        let metering = context.metering_context().expect("test metering context");
+        let origin = if metering.agent_id.is_some() {
+            ExecutionOrigin::AgentSnapshot
+        } else {
+            ExecutionOrigin::AdminDraft
+        };
+        let request = RuntimeExecutionRequest::try_new(
+            &metering.workspace_id,
+            origin,
+            metering.agent_id.as_ref(),
+            operation,
+            input,
+            ExecutionAuthorization::Authorized,
+            resolved_auth,
+            &context,
+            Instant::now() + Duration::from_secs(30),
+        )
+        .map_err(|_| {
+            crank_core::ExecutionFailure::new(
+                crank_core::ExecutionErrorCode::RuntimeInternal,
+                crank_core::CorrelationContext::new(
+                    context.request_id.clone(),
+                    context.trace_context.clone(),
+                ),
+            )
+        })?;
+        self.execute_outcome(request)
+            .await
+            .map(|success| success.output)
+    }
+}