aws / aws/aws-durable-execution-docs
Expand StepSemantics docs to explain checkpoint ordering for at-most-once vs at-least-once
- Dominant language
- Python
- Stars
- 13
- Forks
- 13
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 25
Description
## Problem
The current [Step reference docs](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/) describe `StepSemantics.AT_MOST_ONCE_PER_RETRY` as: "Executes the step at most once per retry attempt. If the function replays before the result is checkpointed, the SDK skips the step and raises StepInterruptedError."
This is correct but doesn't explain *how* the guarantee is achieved. Users reading the [fraud detection best practices blog post](https://aws.amazon.com/blogs/compute/best-practices-for-lambda-durable-functions-using-a-fraud-detection-example/) are asking questions like:
- "Is there a failure window where the side effect has already happened, but the success checkpoint has not yet been persisted?"
- "If checkpoints are batched, could the step be retried even though the external side effect already occurred?"
## Proposed solution
Expand the `StepSemantics` section in the Step reference with a "How it works" subsection covering:
1. **Checkpoint ordering:** START and SUCCEED checkpoints for the same step are never in the same batch
2. **At-most-once behavior:** The START checkpoint must complete (synchronous) before the step body runs. Both START and SUCCEED are synchronous checkpoints.
3. **At-least-once behavior:** The step body may start running before the START checkpoint completes (asynchronous).
4. A diagram showing the checkpoint flow for each mode would help clarify the difference.
Contributor guide
Assessment
This issue has not been assessed yet.