FlowFabric Worker SDK — public API for worker authors.

This crate depends on ff-script for the Lua-function types, Lua error kinds (ScriptError), and retry helpers (is_retryable_kind, kind_to_stable_str). Consumers using ff-sdk do not need to import ff-script directly for normal worker operations, but can if they need the ScriptError or retry types.

Quick start

The production claim path is FlowFabricWorker::claim_from_grant: obtain a ClaimGrant from ff_scheduler::Scheduler::claim_for_worker (the scheduler enforces budget, quota, and capability checks), then hand it to the SDK. claim_next is gated behind the default-off direct-valkey-claim feature and bypasses admission control — fine for benchmarks, not production.

use ff_sdk::{FlowFabricWorker, WorkerConfig};
use ff_core::backend::BackendConfig;
use ff_core::types::{LaneId, Namespace, WorkerId, WorkerInstanceId};

#[tokio::main]
async fn main() -> Result<(), ff_sdk::SdkError> {
    let config = WorkerConfig {
        backend: Some(BackendConfig::valkey("localhost", 6379)),
        worker_id: WorkerId::new("my-worker"),
        worker_instance_id: WorkerInstanceId::new("my-worker-instance-1"),
        namespace: Namespace::new("default"),
        lanes: vec![LaneId::new("main")],
        capabilities: Vec::new(),
        lease_ttl_ms: 30_000,
        claim_poll_interval_ms: 1_000,
        max_concurrent_tasks: 1,
        partition_config: None,
    };

    let worker = FlowFabricWorker::connect(config).await?;
    let lane = LaneId::new("main");

    // In a real deployment `grant` is obtained from the
    // scheduler's `claim_for_worker` RPC/helper; it carries the
    // execution id, capability match, and admission result.
    # let grant: ff_sdk::ClaimGrant = unimplemented!();
    let task = worker.claim_from_grant(lane, grant).await?;
    println!("claimed: {}", task.execution_id());
    // Process task...
    task.complete(Some(b"done".to_vec())).await?;
    Ok(())
}

Migration: direct-valkey-claim → scheduler-issued grants

The direct-valkey-claim cargo feature — which gates FlowFabricWorker::claim_next — is deprecated in favour of the pair of scheduler-issued grant entry points:

• FlowFabricWorker::claim_from_grant — fresh claims. Use ff_scheduler::Scheduler::claim_for_worker to obtain the ClaimGrant, then hand it to the SDK.
• FlowFabricWorker::claim_from_resume_grant — resumed claims for an attempt_interrupted execution. Wraps a ResumeGrant.

claim_next bypasses budget and quota admission control; the grant-based path does not. See each method's rustdoc for the exact migration recipe.

ClaimGrant / ResumeGrant / ReclaimGrant (and the ClaimPolicy / ResumeToken wire types on the scheduler-owner side) are re-exported from ff-sdk (#283) so consumers do not need a direct ff-scheduler dep just to type these signatures.