Saga to Workflow Upgrade

Both versions use the same ChecksService to start independent credit and stock checks. The service methods enqueue work and return without waiting for its result; both checks can be in progress together. Both versions accept the first result for each check in either order and ignore duplicate results. The saga publishes ChecksCompleted; the workflow completes naturally when both checks accept, or fails on rejection or timeout. The workflow does not publish a custom completion event. Consumers of ChecksCompleted therefore require a separate compatibility decision; the event contracts are not identical. Each check has one day to respond; a missing result counts as rejected. The saga joins both responses or expiries. The workflow can reject as soon as one wait times out, without waiting for the other deadline. The decision is accepted only when both results are accepted.

The saga stores result flags and deadline identifiers, cancels deadlines for received results, and joins results in separate handlers. The workflow registers the event waits, starts two durable service steps with ctx.execute, and joins the requests and results with ctx.allMatch. The step calls can execute concurrently; using awaitExecute for the first call would serialize the requests.

CreditChecked and StockChecked carry the business outcomes in both versions, including rejected checks (accepted = false). Both joins use WorkflowStepResult::success directly. The result join succeeds after both results arrive; a timeout makes it return false. The business decision also requires both result payloads to contain accepted = true. Request methods must be idempotent using orderId, and each check must produce one authoritative result.

A rejected business result is still a successful event-wait step, so the result join waits for the other result. A failed or timed-out step short-circuits the join; it does not undo another branch’s external work. These examples perform read-only checks; reservation or payment branches need explicit handling for cancellation, compensation, and late success. See parallel steps and short-circuit behavior.

Both versions request approval and produce an approved result when confirmation arrives, or an expired result after one hour. The saga stores and cancels a deadline identifier. The workflow’s event wait carries the timeout and exposes its outcome directly. Both call ApprovalService.requestApproval, which enqueues the request and returns without waiting for approval. The workflow registers the wait before making this call inside a step, so a fast confirmation can be received.

The workflow does not need a separate cancellation command for a wait that already completed. A timeout is a normal business outcome in this example, so the workflow publishes a negative result and completes. An unhandled StepFailedException fails the workflow; a failed event wait calls ctx.fail(…​).

Timing boundary: the hour begins when the saga schedules its deadline or the workflow registers its wait, not when an external user receives the request. Specify and test the policy for an approval racing with expiry and for an approval arriving after completion. A step timeout does not undo the external request. See event waits and workflow completion and failure.

The saga stores an attempt counter and schedules a deadline three seconds after a failed service call. The workflow puts the delivery call in one durable step with a retry policy. Both allow three total attempts: the initial attempt plus two retries. Both call the same DeliveryClient and use the order identifier as its idempotency key. Both save delivered = true after success, or false after three failed calls. This example retries any exception from the delivery service, with the same limit in both versions. Both rely on the delivery client’s transport timeout; the client reports that timeout as an exception. Workflow service steps also have a five-second default timeout; configure it above the client’s transport timeout. A step timeout or cancellation leaves the delivery outcome unknown and requires reconciliation. The workflow performs that write in a separate durable step; it does not publish an extra delivery-completed event.

RetryPolicy.maxRetries(2) means two retries in addition to the initial attempt. The saga maintains an attempt counter and schedules retry deadlines; the workflow step applies the same retry limit and backoff. The database write follows the delivery outcome in both versions and is not part of the delivery retry loop.

Step retries rerun an action after a technical failure. A business retry driven by an event such as PaymentDeclined needs an explicit event wait and loop; a successful dispatch step does not fail merely because a later business event reports rejection. Preserve the original event contracts, backoff, attempt correlation, and cancellation behavior when modeling that loop. See retry policies and backoff.

Record events, commands, deadlines, late events, and intentional behavior changes before writing code. Use that model to implement the workflow and port the saga’s behavioral tests. The skill README documents the orchestration, tools, inputs, outputs, scoring, and available assets.

Independent checks compare the implementation with the recorded behavior; failures return to the build loop. Agent judgment cannot override a failed machine check, and unsupported cases remain explicit. A passing result is ready for review, not proof of production durability. Complete the persistent coexistence and restart checks before retiring legacy sagas.

Find the upgraded saga’s start handlers:

Remove only its @StartSaga annotations (including their imports):

Keep its handlers, command/event contracts, type identities, serialized fields, associations, stores, and processor identities unchanged. Associated instances still receive events; unmatched events no longer create sagas. Register the tested workflow using the workflow configuration guide. Deploy both changes together.

The saved position, called a token, is a bookmark in the event stream. A new workflow processor starts at the current end, leaving old start events with the sagas. Keep new requests paused until this bookmark is saved so they are not skipped. On later restarts, preserve the token and processor identity; resetting the position can duplicate or skip work. See initial tracking tokens.

Test with persistent event, token, saga, and scheduler stores so state survives a restart:

Also test timeouts, retries, compensation, and duplicate or late events against the expected behavior. Keep the existing saga tests, but do not treat unit tests as proof that persistent recovery works. Fix any restart or persistence failures before proceeding.

Count the remaining sagas with a read-only query. Use your application’s table/column names and stored saga type; run separately for each tenant or add a tenant filter:

Wait for the count to reach zero and for commands, scheduled work, and failed/dead-lettered messages that need the saga to finish or be resolved. Track how long the oldest saga has been running; choose an observation period based on the process lifetime. Then follow Retire the drained legacy implementation.

If you roll back: keep the workflow definition and runtime available until existing workflows finish. Do not let sagas and workflows both start the same process. Test how new requests will be assigned during rollback, or fix the new deployment instead.