Struct EffectBuilder 

pub struct EffectBuilder<S, V = NoVerification> { /* private fields */ }

Builds and runs one effect. Created by Runtime::effect.

Invalid names, keys or inputs are reported when the effect is run, so the whole chain needs a single ?.

Implementations

impl<S: EffectStore> EffectBuilder<S>

pub fn verify<T, F, Fut>(self, check: F) -> EffectBuilder<S, VerifyWith<F>>

where F: Fn(EffectContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Verification<T>, EffectFailure>> + Send + 'static,

Verifies the effect against a remote system that reads its own writes: Verification::NotApplied is trusted at once.

The check runs after every successful attempt (a postcondition) and to reconcile an attempt whose outcome is unknown. It makes re-running safe even for irreversible effects, because the runtime only re-runs an effect the remote system says did not apply.

pub fn verify_eventually<T, F, Fut>( self, settle: Duration, check: F, ) -> EffectBuilder<S, VerifyWith<F>>

where F: Fn(EffectContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Verification<T>, EffectFailure>> + Send + 'static,

Like Self::verify, for a remote lookup that lags behind its writes by up to settle. Verification::NotApplied is trusted only once settle has passed since the attempt ended; until then the runtime waits and checks again.

impl<S: EffectStore, V> EffectBuilder<S, V>

pub fn kind(self, kind: EffectKind) -> Self

The effect’s kind. Defaults to EffectKind::IrreversibleWrite, the most cautious choice.

pub fn remote_idempotency(self, supported: bool) -> Self

Declares that the remote system deduplicates on EffectContext::idempotency_key, which the action must send. This makes re-running after an unknown outcome safe.

pub fn input<I: Serialize + ?Sized>(self, input: &I) -> Self

The input the action acts on. It is stored for audit and fingerprinted: reusing the key with a different input fails with RuntimeError::InputMismatch.

The input is persisted as-is. Keep credentials in the action’s captured state, not in the input.

pub fn actor(self, actor: impl Into<String>) -> Self

Who is asking for the effect, e.g. agent:refund-agent. Recorded on the effect and its audit events.

pub fn retry(self, policy: RetryPolicy) -> Self

The retry policy. Defaults to the runtime’s (RuntimeBuilder::retry_policy).

max_attempts bounds the attempts over the effect’s whole life, across calls and restarts. It also bounds verification and precondition checks per call.

pub fn attempt_timeout(self, timeout: Duration) -> Self

Gives up waiting for an attempt after timeout. The request may have been sent, so a timeout is an ambiguous failure.

pub fn precondition<F, Fut>(self, check: F) -> Self

where F: Fn(EffectContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Precondition> + Send + 'static,

A check that must pass before the effect’s first attempt, so a stale decision is not carried out, e.g. “refund only if the order is still unrefunded”.

It runs only before the first attempt. Once an attempt may have applied, the effect’s own success could falsify the check: a refund that went through makes “not yet refunded” false.

pub fn risk(self, risk: RiskLevel) -> Self

How much damage the effect could do; the runtime’s RiskPolicy adds requirements by risk. Defaults to RiskLevel::Low.

pub fn require_approval(self) -> Self

Requires a human decision before the first attempt; see approval. The effect waits in AwaitingApproval, durably, until the runtime’s approval provider or an operator decides.

pub async fn run<T, F, Fut>( self, action: F, ) -> Result<EffectOutcome<T>, RuntimeError>

where T: Serialize + DeserializeOwned + Send + 'static, F: Fn(EffectContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<T, EffectFailure>> + Send + 'static, V: Verifier<T>,

Runs the effect, or attaches to an earlier run with the same key.

The action may be called more than once over the effect’s life (for example to re-run an idempotent effect whose outcome was unknown), so it is an Fn. It runs on a spawned task: dropping the returned future does not abort an attempt that has started, and its result is still recorded.

Errors

Infrastructure failures only; see RuntimeError. Every effect result, including an unknown one, is an EffectOutcome.