Struct ClaimedTask 

pub struct ClaimedTask { /* private fields */ }

A claimed execution with an active lease. The worker processes this task and must call one of complete(), fail(), or cancel() when done.

The lease is automatically renewed in the background at lease_ttl / 3 intervals. Renewal stops when the task is consumed or dropped.

complete, fail, and cancel consume self — this prevents double-complete bugs at the type level.

Implementations

impl ClaimedTask

pub fn execution_id(&self) -> &ExecutionId

pub fn attempt_index(&self) -> AttemptIndex

pub fn attempt_id(&self) -> &AttemptId

pub fn lease_id(&self) -> &LeaseId

pub fn lease_epoch(&self) -> LeaseEpoch

pub fn input_payload(&self) -> &[u8]

pub fn execution_kind(&self) -> &str

pub fn tags(&self) -> &HashMap<String, String>

pub fn lane_id(&self) -> &LaneId

pub fn is_lease_healthy(&self) -> bool

Check if the lease is likely still valid based on renewal success.

Returns false if 3 or more consecutive renewal attempts have failed. Workers should check this before committing expensive or irreversible side effects. A false return means Valkey may have already expired the lease and another worker could be processing this execution.

pub fn consecutive_renewal_failures(&self) -> u32

Number of consecutive lease renewal failures since the last success.

Returns 0 when renewals are working normally. Useful for observability and custom health policies beyond the default threshold of 3.

pub async fn delay_execution( self, delay_until: TimestampMs, ) -> Result<(), SdkError>

Delay the execution until delay_until.

Releases the lease. The execution moves to delayed state. Consumes self — the task cannot be used after delay.

pub async fn move_to_waiting_children(self) -> Result<(), SdkError>

Move execution to waiting_children state.

Releases the lease. The execution waits for child dependencies to complete. Consumes self.

pub async fn complete( self, result_payload: Option<Vec<u8>>, ) -> Result<(), SdkError>

Complete the execution successfully.

Calls ff_complete_execution via FCALL, then stops lease renewal. Renewal continues during the FCALL to prevent lease expiry under network latency — the Lua fences on lease_id+epoch atomically. Consumes self — the task cannot be used after completion.

Connection errors and replay

If the Valkey connection drops after the Lua commit but before the client reads the response, retrying complete() with the same ClaimedTask (same lease_epoch + attempt_id) is safe: the SDK reconciles the “already terminal with matching outcome” response into Ok(()). A retry after a different terminal op has raced in (e.g. operator cancel) surfaces as ExecutionNotActive with the populated terminal_outcome so the caller can see what actually happened.

pub async fn fail( self, reason: &str, error_category: &str, ) -> Result<FailOutcome, SdkError>

Fail the execution with a reason and error category.

If the execution policy allows retries, the engine schedules a retry (delayed backoff). Otherwise, the execution becomes terminal failed. Returns FailOutcome so the caller knows what happened.

Connection errors and replay

fail() is replay-safe under the same conditions as complete(): a retry by the same caller matching lease_epoch + attempt_id is reconciled into the outcome the server actually committed (TerminalFailed if no retries left; RetryScheduled with delay_until = 0 if a retry was scheduled — the exact delay is not recovered on the replay path).

pub async fn cancel(self, reason: &str) -> Result<(), SdkError>

Cancel the execution.

Stops lease renewal, then calls ff_cancel_execution via FCALL. Consumes self.

Connection errors and replay

cancel() is replay-safe under the same conditions as complete(): a retry by the same caller matching lease_epoch + attempt_id returns Ok(()) if the server’s stored terminal_outcome is cancelled. A retry that finds a different outcome (because a concurrent complete() or fail() won the race) surfaces as ExecutionNotActive with the populated terminal_outcome so the caller can see that the cancel intent was NOT honored.

pub async fn renew_lease(&self) -> Result<(), SdkError>

Manually renew the lease.

RFC-012 Stage 1b. Forwards through the EngineBackend trait. The background renewal task calls backend.renew(&handle) directly (see spawn_renewal_task); this method is the public entry point for workers that want to force a renew out-of-band.

pub async fn update_progress( &self, pct: u8, message: &str, ) -> Result<(), SdkError>

Update progress (pct 0-100 and optional message).

RFC-012 Stage 1b. Forwards through the EngineBackend trait (backend.progress(&handle, Some(pct), Some(msg))).

pub async fn report_usage( &self, budget_id: &BudgetId, dimensions: &[(&str, u64)], dedup_key: Option<&str>, ) -> Result<ReportUsageResult, SdkError>

Report usage against a budget and check limits.

Non-consuming — the worker can report usage multiple times. dimensions is a slice of (dimension_name, delta) pairs. dedup_key prevents double-counting on retries (auto-prefixed with budget hash tag).

pub async fn create_pending_waitpoint( &self, waitpoint_key: &str, expires_in_ms: u64, ) -> Result<(WaitpointId, WaitpointToken), SdkError>

Create a pending waitpoint for future signal delivery.

Non-consuming — the worker keeps the lease. Signals delivered to the waitpoint are buffered. When the worker later calls suspend() with use_pending_waitpoint, buffered signals may immediately satisfy the resume condition.

Returns both the waitpoint_id AND the HMAC token required by external callers to buffer signals against this pending waitpoint (RFC-004 §Waitpoint Security).

pub async fn append_frame( &self, frame_type: &str, payload: &[u8], metadata: Option<&str>, ) -> Result<AppendFrameOutcome, SdkError>

Append a frame to the current attempt’s output stream.

Non-consuming — the worker can append many frames during execution. The stream is created lazily on the first append.

pub async fn suspend( self, reason_code: &str, condition_matchers: &[ConditionMatcher], timeout_ms: Option<u64>, timeout_behavior: TimeoutBehavior, ) -> Result<SuspendOutcome, SdkError>

Suspend the execution, releasing the lease and creating a waitpoint.

The execution transitions to suspended and the worker loses ownership. An external signal matching the condition will resume the execution.

If condition_matchers is empty, a wildcard matcher is created that matches ANY signal name. To require an explicit operator resume with no signal match, pass a sentinel name that no real signal will use.

If buffered signals on a pending waitpoint already satisfy the condition, returns AlreadySatisfied and the lease is NOT released.

Consumes self — the task cannot be used after suspension.

pub async fn resume_signals(&self) -> Result<Vec<ResumeSignal>, SdkError>

Read the signals that satisfied the waitpoint and triggered this resume.

Non-consuming. Intended to be called immediately after re-claim via crate::FlowFabricWorker::claim_from_reclaim_grant, before any subsequent suspend() (which replaces suspension:current).

Returns Ok(vec![]) when this claim is NOT a signal-resume:

• No prior suspension on this execution.
• The prior suspension belonged to an earlier attempt (e.g. the attempt was cancelled/failed and a retry is now claiming).
• The prior suspension was closed by timeout / cancel / operator override rather than by a matched signal.

Reads suspension:current once, filters by attempt_index to guard against stale prior-attempt records, then fetches the matched signal_id set from waitpoint_condition’s matcher:N:signal_id fields and reads each signal’s metadata + payload directly.

Trait Implementations

impl Drop for ClaimedTask

fn drop(&mut self)

Executes the destructor for this type.