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

BlockExecutionForAdmissionArgs

Inputs to crate::engine_backend::EngineBackend::block_execution_for_admission (FF #511 Phase 2b). Generalises block_route (capability-mismatch only) to cover every admission-time block target: budget denial, quota denial, capability mismatch, operator pause, lane pause.

BlockRouteArgs

Inputs to crate::engine_backend::EngineBackend::block_route.

BudgetStatus

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

BudgetUsageAndLimits

Typed snapshot of one budget’s usage + limits map. Returned by crate::engine_backend::EngineBackend::read_budget_usage_and_limits so the scheduler’s BudgetChecker can evaluate hard-limit breaches without reaching at Valkey-shaped HGETs.

BufferSignalArgs

CancelExecutionArgs

CancelFlowArgs

CascadeOutcome

Typed outcome of crate::engine_backend::EngineBackend::cascade_completion.

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.

ClaimGrantOutcome

Outcome of crate::engine_backend::EngineBackend::issue_grant_and_claim.

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

DeliverApprovalSignalArgs

Args for crate::engine_backend::EngineBackend::deliver_approval_signal.

DeliverSignalArgs

EdgeGroupSnapshot

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

EdgeSnapshot

Engine-decoupled read-model for one dependency edge.

EvaluateFlowEligibilityArgs

ExecutionContext

Point-read bundle of the three execution-scoped fields the SDK worker needs to construct a ClaimedTask (see ff_sdk::ClaimedTask): input_payload, execution_kind, and tags.

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

ExpiredLeaseInfo

ExpiredLeasesCursor

Cursor for crate::engine_backend::EngineBackend::list_expired_leases (RFC-025 §9-locked). Tuple (not bare ExecutionId) so pagination is stable under equal-expiry: ZRANGEBYSCORE with LIMIT keyed on score alone duplicates or skips when two leases share a millisecond.

FailExecutionArgs

FlowSnapshot

Engine-decoupled read-model for one flow.

FlowSummary

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

HeartbeatWorkerArgs

Inputs to crate::engine_backend::EngineBackend::heartbeat_worker (RFC-025). Feature gate: core.

IdempotencyKey

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

IssueClaimGrantArgs

Inputs to crate::engine_backend::EngineBackend::issue_claim_grant — the trait-level entry point v0.12 PR-5 lifted out of the SDK-side FlowFabricWorker::claim_next inline helper.

IssueGrantAndClaimArgs

Args for crate::engine_backend::EngineBackend::issue_grant_and_claim.

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.

ListExpiredLeasesArgs

Inputs to crate::engine_backend::EngineBackend::list_expired_leases (RFC-025). Feature gate: suspension.

ListExpiredLeasesResult

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

ListWorkersArgs

Inputs to crate::engine_backend::EngineBackend::list_workers (RFC-025 Phase 6, §9.4).

ListWorkersResult

MarkLeaseExpiredArgs

MarkWorkerDeadArgs

Inputs to crate::engine_backend::EngineBackend::mark_worker_dead (RFC-025). Feature gate: core.

MoveToWaitingChildrenArgs

PendingWaitpointInfo

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

PromoteBlockedToEligibleArgs

QuotaPolicyLimits

Typed snapshot of the admission-relevant fields on a quota policy. Returned by crate::engine_backend::EngineBackend::read_quota_policy_limits so the scheduler can make admission decisions without reaching directly at Valkey-shaped HGETs on ff:quota:{K}:def.

ReadFramesArgs

Inputs to ff_read_attempt_stream (XRANGE wrapper).

ReclaimExecutionArgs

ReclaimGrant

A lease-reclaim grant issued for an execution in lease_expired_reclaimable or lease_revoked state (RFC-024 §3.1).

RecordSpendArgs

Args for crate::engine_backend::EngineBackend::record_spend.

RegisterWorkerArgs

Inputs to crate::engine_backend::EngineBackend::register_worker (RFC-025). Feature gate: core.

ReleaseAdmissionArgs

Args for crate::engine_backend::EngineBackend::release_admission.

ReleaseBudgetArgs

Args for crate::engine_backend::EngineBackend::release_budget.

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

Inputs to crate::engine_backend::EngineBackend::resolve_dependency — the trait-level entry point PR-7b Step 0 lifted out of the two inline FCALL call sites (ff-engine::partition_router:: dispatch_dependency_resolution and ff-engine::scanner::dependency_reconciler::resolve_eligible_edges).

ResumeExecutionArgs

ResumeGrant

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

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

ScanEligibleArgs

Inputs to crate::engine_backend::EngineBackend::scan_eligible_executions.

SeedWaitpointHmacSecretArgs

Args for [EngineBackend::seed_waitpoint_hmac_secret].

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.

WorkerInfo

Enums

AddExecutionToFlowResult

AppendFrameResult

ApplyDependencyToChildResult

BlockExecutionForAdmissionOutcome

Typed outcome of crate::engine_backend::EngineBackend::block_execution_for_admission.

BlockExecutionResult

BlockRouteOutcome

Typed outcome of crate::engine_backend::EngineBackend::block_route.

BlockingReason

Admission-time block reasons supported by block_execution_for_admission. Mirrors the Lua REASON_TO_ELIGIBILITY map.

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

Typed outcome of crate::engine_backend::EngineBackend::claim_execution.

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.

HeartbeatWorkerOutcome

IssueClaimGrantOutcome

Typed outcome of crate::engine_backend::EngineBackend::issue_claim_grant.

IssueClaimGrantResult

Legacy name for IssueClaimGrantOutcome — retained for ff-script’s FromFcallResult plumbing. Prefer IssueClaimGrantOutcome in trait-level code.

IssueReclaimGrantOutcome

Typed outcome of crate::engine_backend::EngineBackend::issue_reclaim_grant (RFC-024 §3.2).

IssueReclaimGrantResult

MarkLeaseExpiredResult

MarkWorkerDeadOutcome

MoveToWaitingChildrenResult

OnSatisfied

Policy for unfinished sibling upstreams once the quorum is met.

PromoteBlockedToEligibleResult

ReadFramesResult

ReclaimExecutionOutcome

Typed outcome of crate::engine_backend::EngineBackend::reclaim_execution (RFC-024 §3.2).

ReclaimExecutionResult

RegisterWorkerOutcome

ReleaseAdmissionResult

RenewLeaseResult

ReplayExecutionResult

ReportUsageResult

ResetBudgetResult

ResolveDependencyOutcome

Typed outcome of crate::engine_backend::EngineBackend::resolve_dependency.

ResolveDependencyResult

Legacy name retained for ff-script’s FromFcallResult plumbing. Prefer ResolveDependencyOutcome in trait-level code.

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.

SeedOutcome

Result of [EngineBackend::seed_waitpoint_hmac_secret].

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

LIST_EXPIRED_LEASES_DEFAULT_LIMIT

Default page size when limit is None.

LIST_EXPIRED_LEASES_DEFAULT_MAX_PARTITIONS

Default fan-out for list_expired_leases when max_partitions_per_call is None (RFC-025 §9.2).

LIST_EXPIRED_LEASES_MAX_LIMIT

Backend cap for limit.

MARK_WORKER_DEAD_REASON_MAX_BYTES

Max bytes for MarkWorkerDeadArgs.reason. Mirrors FailExecutionArgs::failure_reason ceiling.

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.