aws / aws/aws-durable-execution-docs

Clarify attempt counter behavior in DurableLogData under different step semantics

Open
#149 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.