Idempotency in a workflow step

The contract binds every step handler to idempotence on the step's stable identity. The engine stamps that identity on each command it publishes, and it holds the identity stable across a re-publish. The handler keeps the other half, because only the handler performs the effect: a second execution of one step identity must leave the system as the first left it.

Two routine events re-publish a step command, so a handler must expect the repeat. Recovery re-dispatches every unfinished step of every unfinished instance, and it runs once at service start. Recovery writes no new step, so the command carries the identity the handler has already seen. A caller's retry after a lost reply re-sends that same command.

The completion guard deduplicates the engine's bookkeeping and nothing more. The engine discards a completion for a step that is no longer running, so a duplicate completion cannot overwrite a terminal state or advance the instance twice. The handler has already run by then; see the instance and step states for the state machine the guard reads.

A handler can ask the engine to replay the outcome the step already produced. The handler sends the step's identity and its tenant with the request, and a hit returns the cached outcome — result, error and log — which the handler publishes as its own completion, reproducing the answer without the work. The request is bounded by a short timeout.

The guard fails open: a timeout or a transport error returns no cached result, and the handler proceeds with normal execution. The guard therefore optimises a repeat rather than preventing one, and the underlying work must stay safe to repeat.

The engine serves the request from a tenant-scoped read, and it reports the step as absent unless the cached outcome belongs to the requesting tenant.

The converging write makes the handler's own effect repeat-safe and needs no conversation with the engine. The publish steps of the bundle workflow give the reason they carry no compensation action: each of them writes so that a repeat converges. A repeat meets its own earlier effect and is absorbed, and the same end state stands.

A new operation must satisfy the step-identity contract before it ships, because neither engine mechanism covers it: the completion guard acts after the work, and the replay guard fails open. It therefore either asks the engine to replay a recorded outcome before it acts, or writes so that a repeat converges on stable business data.