Module backend 

Backend-trait supporting types (RFC-012 Stage 0).

This module carries the public types referenced by the EngineBackend trait signatures in RFC-012 §3.3. The trait itself lands in Stage 1 (issue #89 follow-up); Stage 0 is strictly type-plumbing and the ResumeSignal crate move.

Public structs/enums whose fields or variants are expected to grow are marked #[non_exhaustive] per project convention — consumers must write _-terminated matches and use the provided constructors rather than struct literals. Exceptions:

• Opaque single-field wrapper newtypes (HandleOpaque, WaitpointHmac) hide their inner field and need no non-exhaustive annotation — the wrapped value is unreachable from outside.
• ResumeSignal is intentionally NOT #[non_exhaustive] so the ff-sdk crate-move (Stage 0) preserves struct-literal compatibility at its existing call site.

See rfcs/RFC-012-engine-backend-trait.md §3.3.0 for the authoritative type inventory and §4.1-§4.2 for the Handle / EngineError shapes.

Structs

BackendConfig

Configuration passed to ValkeyBackend::connect (and, later, to other backend connect constructors). Carries the connection details + shared timing/retry policy. Replaces the Valkey-specific fields today on WorkerConfig (RFC-012 §5.1 migration plan).

BackendRetry

Retry policy shared across backend connections. Additive; Stage 1a ships the minimal shape so the trait signatures can reference it.

BackendTimeouts

Pool + keepalive timing shared across backend connections.

CapabilitySet

Worker capability set — the tokens the worker advertises to the scheduler and to claim. Today stored as Vec<String> on WorkerConfig; promoted to a named newtype so the trait signatures can talk about capabilities without committing to a concrete container shape.

ClaimPolicy

Policy hints for claim. Minimal at Stage 0 per RFC-012 §3.3.0 (“Bikeshed-prone; keep minimal at Stage 0”). Future fields (retry count, fairness hints) land additively.

CompletionPayload

One completion event delivered through the CompletionStream (RFC-012 §4.3). Also the payload type for issue #90’s subscription API. Stage 0 authorises the type; issue #90 fixes the wire shape.

FailureReason

Human-readable failure description + optional structured detail. Replaces today’s ad-hoc string arg to fail.

Frame

Single stream frame appended via append_frame (RFC-012 §3.3.0). Today’s FCALL takes the byte payload + frame_type + optional seq as discrete ARGV; Stage 0 collects them into a named type for trait signatures.

Handle

Opaque attempt cookie held by the worker for the duration of an attempt. Produced by claim / claim_from_reclaim / suspend; borrowed by every op (renew, progress, append_frame, complete, fail, cancel, suspend, delay, wait_children, observe_signals, report_usage).

HandleOpaque

Backend-private opaque payload carried inside a Handle.

LeaseRenewal

Result of a successful renew call.

ReclaimToken

Opaque cookie returned by the reclaim scanner; consumed by claim_from_reclaim to mint a resumed Handle.

ResumeSignal

Signal that satisfied a waitpoint matcher and is therefore part of the reason an execution resumed. Returned by observe_signals (RFC-012 §3.1.2) and by ClaimedTask::resume_signals in ff-sdk.

ScannerFilter

Per-consumer filter applied by FlowFabric’s background scanners and completion subscribers so multiple FlowFabric instances sharing a single Valkey keyspace can operate on disjoint subsets of executions without mutual interference (issue #122).

UsageDimensions

Usage report for report_usage. Mirrors today’s ff_report_usage_and_check ARGV: token-counts, wall-time, custom dimensions.

ValkeyConnection

Valkey-specific connection parameters.

WaitpointHmac

HMAC token that binds a waitpoint to its mint-time identity. Wire shape kid:40hex.

WaitpointSpec

One waitpoint inside a suspend request. suspend takes a Vec<WaitpointSpec>; the resume condition (any / all) lives on the enclosing suspend args in the Phase-1 contract.

Enums

AdmissionDecision

Admission outcome returned by report_usage.

BackendConnection

Discriminated union over per-backend connection shapes. Stage 1a ships the Valkey arm; future backends (Postgres) land additively under the #[non_exhaustive] guard.

BackendTag

Backend-tag discriminator embedded in every Handle so ops can dispatch to the correct backend implementation at runtime.

CancelFlowPolicy

Cancel-flow policy — what to do with the flow’s members. Today encoded as a String on CancelFlowArgs; Stage 0 extracts the policy shape as a typed enum (RFC-012 §3.3.0).

CancelFlowWait

Caller wait posture for cancel_flow.

FailOutcome

Outcome of a fail() call.

FailureClass

Failure classification — determines retry disposition on the Lua side. Mirrors the Lua-side classification codes.

FrameKind

Frame classification for append_frame. Mirrors the Lua-side ff_append_frame frame_type ARGV.

HandleKind

Lifecycle kind carried inside a Handle. Backends validate kind on entry to each op and return EngineError::State on mismatch.

WaitpointKind

Waitpoint matcher mode (mirrors today’s suspend/close matcher kinds — signal name, correlation id, etc.).