Struct StepDescriptor 

pub struct StepDescriptor { /* private fields */ }

The description of a step: its identity, effect contract, and ambiguity policy.

A descriptor is what a step is, independent of when it runs. The durable layer derives the step’s IdempotencyKey and replay-divergence fingerprint from the descriptor, so the same program point must build an equal descriptor on every run — a structurally different descriptor at a given StepId is a DurableError::ReplayDivergence.

Build a descriptor through the effect-specific constructors; the exactly_once_guarded constructor enforces the construction-time ambiguity rule (FR-DE-09).

Examples

use zeph_durable::{EffectIntentSubClass, OnAmbiguous, StepDescriptor};

// A read-only step is idempotent and needs no ambiguity policy.
let read = StepDescriptor::idempotent("read_file", b"tool:read_file:/etc/hosts".to_vec());

// A destructive guarded step MUST declare its ambiguity policy or construction fails.
let delete = StepDescriptor::exactly_once_guarded(
    "delete_file",
    EffectIntentSubClass::Destructive,
    Some(OnAmbiguous::Fail),
    b"tool:delete_file:/tmp/x".to_vec(),
);
assert!(delete.is_ok());

let unsafe_delete = StepDescriptor::exactly_once_guarded(
    "delete_file",
    EffectIntentSubClass::Destructive,
    None,
    b"tool:delete_file:/tmp/x".to_vec(),
);
assert!(unsafe_delete.is_err(), "a destructive guarded step needs an explicit policy");

Implementations

impl StepDescriptor

pub fn idempotent(name: &'static str, op_fingerprint: impl Into<Bytes>) -> Self

Describe an EffectClass::Idempotent step (pure or naturally repeatable).

A replayed idempotent step returns its journaled result and never re-invokes the closure (INV-10). No ambiguity policy applies.

pub fn at_least_once( name: &'static str, op_fingerprint: impl Into<Bytes>, ) -> Self

Describe an EffectClass::AtLeastOnce step (safe to repeat under an ambiguous replay).

pub fn exactly_once_guarded( name: &'static str, sub_class: EffectIntentSubClass, on_ambiguous: Option<OnAmbiguous>, op_fingerprint: impl Into<Bytes>, ) -> Result<Self, DurableError>

Describe an EffectClass::ExactlyOnceGuarded step, enforcing the ambiguity-policy rule.

The sub_class refines what the effect does; the resulting OnAmbiguous policy decides what happens if a crash leaves the step in the ambiguous window. Only EffectIntentSubClass::CostBearingOrBoundaryIdempotent has a safe default (OnAmbiguous::Skip); every other sub-class requires an explicit policy.

Errors

Returns DurableError::AmbiguityPolicyRequired when sub_class requires an explicit policy (EffectIntentSubClass::requires_explicit_policy) but on_ambiguous is None.

pub fn name(&self) -> &'static str

The step’s stable name (used in spans, audit records, and error messages).

pub fn effect(&self) -> EffectClass

The step’s effect class.

pub fn on_ambiguous(&self) -> Option<OnAmbiguous>

The resolved ambiguity policy, Some only for a guarded step.

pub fn op_fingerprint(&self) -> &Bytes

The opaque, non-secret operation fingerprint (INV-6).

Trait Implementations

impl Clone for StepDescriptor

fn clone(&self) -> StepDescriptor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StepDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.