Trait EffectHandler 

pub trait EffectHandler: Send + Sync {
    // Required methods
    fn handle_send(
        &self,
        role: &str,
        partner: &str,
        label: &str,
        state: &[Value],
    ) -> EffectResult<Value>;
    fn handle_recv(
        &self,
        role: &str,
        partner: &str,
        label: &str,
        state: &mut Vec<Value>,
        payload: &Value,
    ) -> EffectResult<()>;
    fn handle_choose(
        &self,
        role: &str,
        partner: &str,
        labels: &[String],
        state: &[Value],
    ) -> EffectResult<String>;
    fn step(&self, role: &str, state: &mut Vec<Value>) -> EffectResult<()>;

    // Provided methods
    fn handler_identity(&self) -> String { ... }
    fn handle_effect(&self, request: EffectRequest) -> EffectOutcome { ... }
    fn send_decision(
        &self,
        input: SendDecisionInput<'_>,
    ) -> EffectResult<SendDecision> { ... }
    fn handle_acquire(
        &self,
        _sid: SessionId,
        _role: &str,
        _layer: &str,
        _state: &[Value],
    ) -> EffectResult<Value> { ... }
    fn handle_release(
        &self,
        _sid: SessionId,
        _role: &str,
        _layer: &str,
        _evidence: &Value,
        _state: &[Value],
    ) -> EffectResult<()> { ... }
    fn supports_wal_sync(&self) -> bool { ... }
    fn wal_sync(&self, _sync: &WalSyncRequest) -> EffectResult<()> { ... }
    fn topology_events(
        &self,
        _tick: u64,
    ) -> EffectResult<Vec<TopologyPerturbation>> { ... }
    fn output_condition_hint(
        &self,
        _sid: SessionId,
        _role: &str,
        _state: &[Value],
    ) -> Option<OutputConditionHint> { ... }
}

ProtocolMachine-level effect handler.

This is the interface between a guest runtime and the surrounding host runtime. Each choreography can bind a different handler at session open time.

Host-contract rules:

• Methods on this trait are synchronous. Async I/O, transport polling, storage flushes, and background retries must happen outside handler execution and feed their results back through canonical ingress.
• Implementations must treat the provided state as session-local scratch for the current request only. They must not rely on unrelated session state or mutate ProtocolMachine session metadata through side channels.
• Host-managed session-local mutation should flow through an explicit ownership capability such as OwnedSession, not through ad hoc access to the session store while handlers are executing.

Required Methods

fn handle_send( &self, role: &str, partner: &str, label: &str, state: &[Value], ) -> EffectResult<Value>

Compute the payload for a send instruction.

Helper hook used by the default send_decision implementation and by custom runners that want direct payload computation.

Arguments

• role - The sending role
• partner - The receiving role
• label - The message label
• state - The coroutine’s register file (for reading state)

Returns a typed outcome for the request.

fn handle_recv( &self, role: &str, partner: &str, label: &str, state: &mut Vec<Value>, payload: &Value, ) -> EffectResult<()>

Process a received value.

Arguments

• role - The receiving role
• partner - The sending role
• label - The message label
• state - The coroutine’s register file (mutable for state updates)
• payload - The received value

Returns a typed outcome for the request.

fn handle_choose( &self, role: &str, partner: &str, labels: &[String], state: &[Value], ) -> EffectResult<String>

Choose which branch to take for internal choice (select).

Branch-selection helper for custom runners.

The canonical ProtocolMachine resolves branch labels from received payloads and does not call this method in default dispatch paths.

Arguments

• role - The choosing role
• partner - The partner role
• labels - The available branch labels
• state - The coroutine’s register file (for reading state)

Returns a typed outcome for the request.

fn step(&self, role: &str, state: &mut Vec<Value>) -> EffectResult<()>

Perform an integration step after a protocol round.

Called after all sends/receives for a tick are complete.

Returns a typed outcome for the request.

Provided Methods

fn handler_identity(&self) -> String

Stable identifier for effect-trace attribution.

fn handle_effect(&self, request: EffectRequest) -> EffectOutcome

Canonical typed effect boundary for guest-runtime execution.

Runtime code must route host-facing effect work through this method so the request/outcome contract remains explicit and replay-visible.

The default implementation preserves compatibility for existing helper-method-based handlers by translating each typed request into the corresponding helper method. New code should prefer overriding handle_effect directly.

fn send_decision( &self, input: SendDecisionInput<'_>, ) -> EffectResult<SendDecision>

Decide how to handle a send, optionally with a precomputed payload.

Middleware can override this to model loss/delay/corruption. The default behavior computes a payload via handle_send unless one is provided.

Returns a typed outcome for the request.

fn handle_acquire( &self, _sid: SessionId, _role: &str, _layer: &str, _state: &[Value], ) -> EffectResult<Value>

Attempt to acquire a guard layer.

Returning EffectResult::Blocked causes the coroutine to block. Success(evidence) grants the acquire and binds the evidence value.

fn handle_release( &self, _sid: SessionId, _role: &str, _layer: &str, _evidence: &Value, _state: &[Value], ) -> EffectResult<()>

Release a guard layer using previously acquired evidence.

fn supports_wal_sync(&self) -> bool

Whether this handler can service the internal wal_sync effect.

fn wal_sync(&self, _sync: &WalSyncRequest) -> EffectResult<()>

Confirm that the agreement WAL has been durably synchronized.

fn topology_events(&self, _tick: u64) -> EffectResult<Vec<TopologyPerturbation>>

Topology perturbations injected by the environment for this scheduler tick.

The ProtocolMachine ingests these before selecting coroutines for the round. This is a canonical ingress surface for external events; implementations should stage async discoveries before this method is called rather than doing async work from inside request handling.

Returns a typed outcome for the request.

fn output_condition_hint( &self, _sid: SessionId, _role: &str, _state: &[Value], ) -> Option<OutputConditionHint>

Optional output-condition metadata for commit gating.

The ProtocolMachine calls this only when a step emits observable events. Returning None delegates to ProtocolMachine-default metadata.

Implementations on Foreign Types

impl<T: EffectHandler + ?Sized> EffectHandler for &T

fn handler_identity(&self) -> String

fn handle_effect(&self, request: EffectRequest) -> EffectOutcome

fn handle_send( &self, role: &str, partner: &str, label: &str, state: &[Value], ) -> EffectResult<Value>

fn send_decision( &self, input: SendDecisionInput<'_>, ) -> EffectResult<SendDecision>

fn handle_recv( &self, role: &str, partner: &str, label: &str, state: &mut Vec<Value>, payload: &Value, ) -> EffectResult<()>

fn handle_choose( &self, role: &str, partner: &str, labels: &[String], state: &[Value], ) -> EffectResult<String>

fn step(&self, role: &str, state: &mut Vec<Value>) -> EffectResult<()>

fn handle_acquire( &self, sid: SessionId, role: &str, layer: &str, state: &[Value], ) -> EffectResult<Value>

fn handle_release( &self, sid: SessionId, role: &str, layer: &str, evidence: &Value, state: &[Value], ) -> EffectResult<()>

fn topology_events(&self, tick: u64) -> EffectResult<Vec<TopologyPerturbation>>

fn output_condition_hint( &self, sid: SessionId, role: &str, state: &[Value], ) -> Option<OutputConditionHint>

fn supports_wal_sync(&self) -> bool

fn wal_sync(&self, sync: &WalSyncRequest) -> EffectResult<()>

Implementors

impl EffectHandler for NestedProtocolMachineHandler

impl EffectHandler for RecordingEffectHandler<'_>

impl EffectHandler for ReplayEffectHandler<'_>

impl<C, R> EffectHandler for EvidencePersistenceHandler<'_, C, R>

where C: EvidenceOutcomeCache + Send, R: EvidenceIdResolver,

impl<W> EffectHandler for AgreementWalHandler<'_, W>

where W: AgreementWal + Send,