Incremental Runs

Reuse a workflow step's result across runs — cache hits skip re-execution within a TTL.

Mark a step cacheable with .cache(Duration) and re-running the same workflow within the TTL skips the expensive work: the step becomes a cache hit and its successors advance as if it had completed.

java

Workflow report = Workflow.named("report")
        .step("seed", seedTask, 0)
        .step(Step.of("crunch", crunchTask, 7)
                .cache(Duration.ofMinutes(5))
                .after("seed")
                .build())
        .step("render", renderTask, 1, "crunch");

These snippets assume a worker is already running with .trackWorkflows() and handlers for seedTask, crunchTask, and renderTask — e.g. queue.worker().handle(seedTask, ...).handle(crunchTask, ...).handle(renderTask, ...).trackWorkflows().start(). submitWorkflow only creates the run; a tracking worker is what advances it and applies the cache.

On the first run crunch executes normally; on a second run within five minutes its node status is CACHE_HIT and the task is not re-executed — render still runs.

java

WorkflowStatus second = queue.submitWorkflow(report).await(Duration.ofSeconds(30));
second.node("crunch").orElseThrow().status; // CACHE_HIT
second.node("render").orElseThrow().status; // COMPLETED

The cache key

A cached step is keyed by its workflow name, its step name, and a SHA-256 hash of its payload. Changing any of them (or letting the TTL lapse) misses the cache and re-runs the step.

The cache lives in the tracking worker's process memory — it survives across runs handled by the same worker, but not across worker restarts, and it is not shared between workers.

TTL

The TTL is required and must be positive; .cache(...) rejects zero or negative durations. Expired entries are swept when new results are cached and dropped lazily on lookup.

Constraints

A cacheable step must have a predecessor. A cacheable step is a deferred node, and a deferred root is never promoted — Step.build() rejects a cacheable step with an empty after, since it would wedge the run in PENDING.
A cached step cannot feed a fan-out. A cache hit skips the task, so it produces no fresh result list to expand — a fan-out whose producer is cacheable is rejected at submit.
A cache hit has no forward result downstream. A callable condition on a successor won't see the cached step's result, and a cache hit is never compensated by a saga (its side effects were not performed in this run).

Workflow report = Workflow.named("report") .step("seed", seedTask, 0) .step(Step.of("crunch", crunchTask, 7) .cache(Duration.ofMinutes(5)) .after("seed") .build()) .step("render", renderTask, 1, "crunch");

The cache key

A cached step is keyed by its workflow name, its step name, and a SHA-256 hash of its payload. Changing any of them (or letting the TTL lapse) misses the cache and re-runs the step.

The cache lives in the tracking worker's process memory — it survives across runs handled by the same worker, but not across worker restarts, and it is not shared between workers.

Constraints

A cacheable step must have a predecessor. A cacheable step is a deferred node, and a deferred root is never promoted — Step.build() rejects a cacheable step with an empty after, since it would wedge the run in PENDING.

A cached step cannot feed a fan-out. A cache hit skips the task, so it produces no fresh result list to expand — a fan-out whose producer is cacheable is rejected at submit.

A cache hit has no forward result downstream. A callable condition on a successor won't see the cached step's result, and a cache hit is never compensated by a saga (its side effects were not performed in this run).