aws / aws/aws-durable-execution-docs
Clarify attempt counter behavior in DurableLogData under different step semantics
- Dominant language
- Python
- Stars
- 13
- Forks
- 13
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 25
Description
### Problem
The `attempt` field in `DurableLogData` does not increment after Lambda sandbox errors when using **at-least-once** step semantics. This is because uncheckpointed failures are invisible to the attempt counter under at-least-once mode — the failure was not persisted, so from the SDK perspective it never happened.
Under **at-most-once** semantics, the attempt counter behaves as expected because failures are checkpointed.
This causes confusion when users rely on `attempt` for observability or retry logic and don't realize the behavior differs between semantic modes.
Related: https://github.com/aws/aws-durable-execution-sdk-js/issues/497
### Current state
The [step operation docs](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/) describe at-least-once vs at-most-once semantics, and the [idempotency docs](https://docs.aws.amazon.com/lambda/latest/dg/durable-execution-idempotency.html) cover replay behavior. However, the docs do not explain how the `attempt` counter behaves differently under each semantic mode, nor document the specific case of sandbox errors and uncheckpointed failures.
### Suggested improvement
- Add a note to the step operation docs explaining `attempt` counter behavior under each mode
- Document that uncheckpointed failures (e.g., sandbox errors) are invisible to the attempt counter under at-least-once
- Cross-reference from the logging/observability docs
Contributor guide
Assessment
This issue has not been assessed yet.