Module engine_backend 

The EngineBackend trait — abstracting FlowFabric’s write surface.

RFC-012 Stage 1a: this is the trait landing. The Valkey-backed impl lives in ff-backend-valkey; future backends (Postgres) add a sibling crate with their own impl. ff-sdk’s FlowFabricWorker gains connect_with(backend) / backend(&self) accessors so consumers that want to bring their own backend (tests, future non-Valkey deployments) can hand one in. The hot-path migration of ClaimedTask / FlowFabricWorker to forward through the trait lands across Stages 1b-1d.

Object safety

EngineBackend is object-safe: all methods are async fn behind #[async_trait] and take &self. Consumers can hold Arc<dyn EngineBackend> for heterogenous-backend deployments. The trait is Send + Sync + 'static per RFC-012 §4.1; every impl must honour that bound.

Error surface

Every method returns Result<_, EngineError>. EngineError’s Transport variant carries a boxed dyn Error + Send + Sync; Valkey-backed transport faults box a ff_script::error::ScriptError (downcast via ff_script::engine_error_ext::transport_script_ref). Other backends box their native error type and set the backend tag accordingly.

Atomicity contract

Per-op state transitions MUST be atomic (RFC-012 §3.4). On Valkey this is the single-FCALL-per-op property; on Postgres it is the per-transaction property. A backend that cannot honour atomicity for a given op either MUST NOT implement EngineBackend or MUST return EngineError::Unavailable { op } for the affected method.

Replay semantics

complete, fail, cancel, suspend, delay, wait_children are idempotent under replay — calling twice with the same handle and args returns the same outcome (success on first call, typed State / Contention on subsequent calls where the fence triple no longer matches a live lease).

Traits

EngineBackend

The engine write surface — a single trait a backend implementation honours to serve a FlowFabricWorker.

Functions

cancel_flow_wait_deadline

Convert a CancelFlowWait into the deadline passed to wait_for_flow_cancellation. NoWait returns None — the caller must skip the wait entirely.

wait_for_flow_cancellation

Poll backend.describe_flow(flow_id) until public_flow_state is "cancelled" or deadline elapses.