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.

Re-exports

pub use crate::types::Namespace;

pub use crate::contracts::CompositeBody;

pub use crate::contracts::IdempotencyKey;

pub use crate::contracts::ResumeCondition;

pub use crate::contracts::ResumePolicy;

pub use crate::contracts::ResumeTarget;

pub use crate::contracts::SignalMatcher;

pub use crate::contracts::SuspendArgs;

pub use crate::contracts::SuspendOutcome;

pub use crate::contracts::SuspendOutcomeDetails;

pub use crate::contracts::SuspensionReasonCode;

pub use crate::contracts::SuspensionRequester;

pub use crate::contracts::TimeoutBehavior;

pub use crate::contracts::WaitpointBinding;

Structs

AppendFrameOutcome

Outcome of an append_frame() call.

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.

BackendTimeouts

Pool timing shared across backend connections.

BestEffortLiveConfig

Configuration knobs for StreamMode::BestEffortLive — RFC-015 §4.2 dynamic MAXLEN sizing.

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. Carries the worker identity the backend needs to invoke ff_claim_execution (v0.7 Wave 2) plus the blocking-wait bound.

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.

PendingWaitpoint

Handle returned by create_waitpoint — the id of the newly-minted pending waitpoint plus its HMAC token. Signals targeted at the waitpoint must present the token; a later suspend call transitions the waitpoint from pending to active (RFC-012 §R7.2.2).

PostgresConnection

Postgres-specific connection parameters (RFC-v0.7 Wave 0).

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).

SummaryDocument

Materialised rolling summary document returned by a summary-read call (RFC-015 §6.3).

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

BackendConnection

Discriminated union over per-backend connection shapes. Stage 1a shipped the Valkey arm; RFC-v0.7 Wave 0 adds the Postgres arm 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.

PatchKind

Patch format used by StreamMode::DurableSummary to apply each frame’s payload against the server-side rolling summary document.

StreamMode

Per-call durability mode for [EngineBackend::append_frame].

TailVisibility

Tail-stream visibility filter (RFC-015 §6).

WaitpointKind

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

Constants

SUMMARY_NULL_SENTINEL

Byte-exact null-sentinel used by StreamMode::DurableSummary + PatchKind::JsonMergePatch to set a field to JSON null (RFC-015 §3.2).