Module contracts 

Phase 1 function contracts — Args + Result types for each FCALL.

Each Args struct defines the typed inputs to a Valkey Function. Each Result enum defines the possible outcomes (success variants + error codes).

Modules

decode

Canonical decoders for engine-owned hash shapes.

Structs

AddExecutionToFlowArgs

AdditionalWaitpointBinding

RFC-014 Pattern 3 — per-binding identity + HMAC token for waitpoints beyond the primary. Structure mirrors the top-level fields on SuspendOutcomeDetails.

AppendFrameArgs

ApplyDependencyToChildArgs

AttemptSummary

Currently-active attempt summary inside an ExecutionSnapshot.

BlockExecutionArgs

BudgetStatus

Operator-facing budget status snapshot (not an FCALL — direct HGETALL reads).

BufferSignalArgs

CancelExecutionArgs

CancelFlowArgs

ChangePriorityArgs

CheckAdmissionArgs

ClaimExecutionArgs

ClaimForWorkerArgs

Inputs to EngineBackend::claim_for_worker (RFC-017 §5, §7). The Valkey impl forwards to ff_scheduler::Scheduler::claim_for_worker; the Postgres impl forwards to its own scheduler module. The trait method hides the backend-specific dispatch behind one shape.

ClaimGrant

A claim grant issued by the scheduler for a specific execution.

ClaimResumedExecutionArgs

ClaimedExecution

ClaimedResumedExecution

CloseWaitpointArgs

CompleteExecutionArgs

CompositeValidationError

RFC-014 §5.1 validation error shape. Emitted by ResumeCondition::validate_composite when a composite fails a structural / cardinality invariant at suspend-time, before any Valkey call. Carries a human-readable detail per §5.1.1.

CreateBudgetArgs

CreateExecutionArgs

CreateFlowArgs

CreatePendingWaitpointArgs

CreateQuotaPolicyArgs

DelayExecutionArgs

DeliverSignalArgs

EdgeGroupSnapshot

Snapshot of one inbound edge group (per downstream execution).

EdgeSnapshot

Engine-decoupled read-model for one dependency edge.

EvaluateFlowEligibilityArgs

ExecutionInfo

Full execution info returned by Server::get_execution.

ExecutionSnapshot

Engine-decoupled read-model for one execution.

ExecutionSummary

Summary of an execution for list views.

ExpireExecutionArgs

ExpireSuspensionArgs

FailExecutionArgs

FlowSnapshot

Engine-decoupled read-model for one flow.

FlowSummary

Lightweight per-flow projection returned by crate::engine_backend::EngineBackend::list_flows.

IdempotencyKey

Partition-scoped idempotency key for retry-safe EngineBackend::suspend.

IssueClaimGrantArgs

IssueReclaimGrantArgs

LeaseSummary

Currently-held lease summary inside an ExecutionSnapshot.

ListExecutionsPage

One page of partition-scoped execution ids returned by EngineBackend::list_executions.

ListExecutionsResult

Result of a list_executions query.

ListFlowsPage

One page of FlowSummary rows returned by crate::engine_backend::EngineBackend::list_flows.

ListLanesPage

One page of lane ids returned by crate::engine_backend::EngineBackend::list_lanes.

ListPendingWaitpointsArgs

Inputs to EngineBackend::list_pending_waitpoints (RFC-017 §5, §8). Pagination is part of the signature so a flow with 10k pending waitpoints cannot force a single-round-trip read regardless of backend.

ListPendingWaitpointsResult

Page of pending-waitpoint entries. Stage A preserves the existing PendingWaitpointInfo shape; the §8 schema rewrite (HMAC sanitisation + (token_kid, token_fingerprint) additive fields) ships in Stage D alongside the HTTP wire-format deprecation.

ListSuspendedPage

One cursor-paginated page of suspended executions.

ListWaitpointHmacKidsArgs

MarkLeaseExpiredArgs

MoveToWaitingChildrenArgs

PendingWaitpointInfo

One entry in the read-only view of an execution’s active waitpoints.

PromoteBlockedToEligibleArgs

ReadFramesArgs

Inputs to ff_read_attempt_stream (XRANGE wrapper).

ReclaimExecutionArgs

ReclaimGrant

A reclaim grant issued for a resumed (attempt_interrupted) execution.

ReleaseAdmissionArgs

RenewLeaseArgs

ReplayExecutionArgs

ReportUsageAdminArgs

Inputs to EngineBackend::report_usage_admin (RFC-017 §5 budget+ quota admin §5, round-1 F4). Admin-path peer of report_usage — both wrap ff_report_usage_and_check on the Valkey side but the admin call is worker-less, so it cannot reuse the lease-bound report_usage(&Handle, ...) signature. ReportUsageAdminArgs carries the same fields as ReportUsageArgs without a worker handle — kept as a distinct type so future admin-only fields (e.g. actor_identity, audit_reason) don’t pollute the worker path.

ReportUsageArgs

ResetBudgetArgs

ResolveDependencyArgs

ResumeExecutionArgs

ResumePolicy

Resume-side policy carried alongside ResumeCondition.

RevokeLeaseArgs

RotateWaitpointHmacSecretAllArgs

Args for [EngineBackend::rotate_waitpoint_hmac_secret_all] — the cluster-wide / backend-native rotation of the waitpoint HMAC signing kid.

RotateWaitpointHmacSecretAllEntry

Per-partition entry of RotateWaitpointHmacSecretAllResult. Mirrors [ff_sdk::admin::PartitionRotationOutcome] but typed at the ff-core layer so both Valkey and Postgres backends return the same shape without a Postgres→ferriskey dep.

RotateWaitpointHmacSecretAllResult

Result of [EngineBackend::rotate_waitpoint_hmac_secret_all].

RotateWaitpointHmacSecretArgs

Args for ff_rotate_waitpoint_hmac_secret. Rotates the HMAC signing kid on ONE partition. Callers fan out across every partition themselves (ff-server does the parallel fan-out in rotate_waitpoint_secret; direct-Valkey consumers mirror the pattern).

SetEdgeGroupPolicyArgs

SetExecutionTagsArgs

Args for ff_set_execution_tags. Tag keys MUST match ^[a-z][a-z0-9_]*\. — the caller-namespace rule — or the FCALL returns invalid_tag_key. Values are arbitrary strings. The map is ordered (BTreeMap) so two callers submitting the same logical set of tags produce identical ARGV.

SetFlowTagsArgs

Args for ff_set_flow_tags. Same namespace rule as SetExecutionTagsArgs. The Lua function also lazy-migrates any pre-58.4 reserved-namespace fields stashed inline on flow_core into the new tags key.

StageDependencyEdgeArgs

StateSummary

Summary of state after a mutation, returned by many functions.

StreamFrame

A single frame read from an attempt-scoped stream.

StreamFrames

Result of reading frames from an attempt stream — frames plus terminal signal so consumers can stop polling without a timeout fallback.

SuspendArgs

Trait-surface input to [EngineBackend::suspend] (RFC-013 §2.2 + RFC-014 Pattern 3 widening).

SuspendExecutionArgs

SuspendOutcomeDetails

Shared “what happened on the waitpoint” payload carried in both SuspendOutcome variants.

SuspendedExecutionEntry

One entry in a ListSuspendedPage — a suspended execution and the reason it is blocked, answering an operator’s “what’s this waiting on?” without a follow-up round-trip.

UnblockExecutionArgs

UpdateProgressArgs

VerifyingKid

WaitpointHmacKids

Snapshot of the waitpoint HMAC keystore on ONE partition.

Enums

AddExecutionToFlowResult

AppendFrameResult

ApplyDependencyToChildResult

BlockExecutionResult

BufferSignalResult

CancelExecutionResult

CancelFlowHeader

RFC-017 Stage E2: result of the “header” portion of a cancel_flow operation — the atomic flow-state flip + member enumeration.

CancelFlowResult

ChangePriorityResult

CheckAdmissionResult

ClaimExecutionResult

ClaimForWorkerOutcome

Outcome of EngineBackend::claim_for_worker. None-like shape modelled as an enum so additive variants (e.g. BackPressured { retry_after_ms }) do not force a wire break.

ClaimResumedExecutionResult

CloseWaitpointResult

CompleteExecutionResult

CompositeBody

RFC-013 reserves this enum slot; RFC-014 populates it with the concrete composition vocabulary (AllOf + Count). The enum is #[non_exhaustive] so RFC-016 or later RFCs may add variants (AnyOf has been explicitly rejected per RFC-014 §2.3 in favour of Count { n: 1, .. }; the guard exists for orthogonal future work).

CountKind

How Count nodes distinguish satisfiers. RFC-014 §2.1 + §3.2.

CreateBudgetResult

CreateExecutionResult

CreateFlowResult

CreatePendingWaitpointResult

CreateQuotaPolicyResult

DelayExecutionResult

DeliverSignalResult

EdgeDependencyPolicy

Policy controlling how an inbound edge group’s satisfaction is decided.

EdgeDirection

Direction marker for crate::engine_backend::EngineBackend::list_edges.

EdgeGroupState

Edge-group lifecycle state (Stage A exposes only pending + satisfied + impossible; cancelled reserved for Stage C).

EvaluateFlowEligibilityResult

ExpireExecutionResult

ExpireSuspensionResult

FailExecutionResult

Outcome of a fail_execution call.

FlowStatus

Typed flow-lifecycle status surfaced on FlowSummary.

IssueClaimGrantResult

IssueReclaimGrantResult

MarkLeaseExpiredResult

MoveToWaitingChildrenResult

OnSatisfied

Policy for unfinished sibling upstreams once the quorum is met.

PromoteBlockedToEligibleResult

ReadFramesResult

ReclaimExecutionResult

ReleaseAdmissionResult

RenewLeaseResult

ReplayExecutionResult

ReportUsageResult

ResetBudgetResult

ResolveDependencyResult

ResumeCondition

Declarative resume condition for SuspendArgs::resume_condition.

ResumeExecutionResult

ResumeTarget

Where a satisfied suspension routes back to.

RevokeLeaseResult

RotateWaitpointHmacSecretOutcome

Outcome of a single-partition rotation.

SetEdgeGroupPolicyResult

SetExecutionTagsResult

Result of ff_set_execution_tags.

SetFlowTagsResult

Result of ff_set_flow_tags.

SignalMatcher

v1 signal-match predicate inside ResumeCondition::Single.

StageDependencyEdgeResult

StreamCursor

Opaque cursor for attempt-stream reads/tails.

StreamCursorParseError

Error produced when parsing a StreamCursor from a string.

SuspendExecutionResult

SuspendOutcome

Trait-surface output from [EngineBackend::suspend] (RFC-013 §2.3).

SuspensionReasonCode

Reason category for a suspension (RFC-004 §Suspension Reason Categories).

SuspensionRequester

Who requested the suspension.

TimeoutBehavior

Timeout behavior at the suspension deadline (RFC-004 §Timeout Behavior).

UnblockExecutionResult

UpdateProgressResult

WaitpointBinding

How the waitpoint resource backing a SuspendArgs is obtained.

Constants

MAX_COMPOSITE_DEPTH

Hard cap on composite-condition nesting depth (RFC-014 §5.4 invariant 4; §5.5 cap rationale). Soft-cap: bumping requires only this constant + the cap-rationale paragraph in RFC-014 §5.5 — no wire-format change. Keep in sync.

STREAM_READ_HARD_CAP

Hard cap on the number of frames returned by a single read/tail call.