The Step Semantics section in aws-lambda-durable-functions-power/steering/step-operations.md has two pre-existing bugs surfaced during review of #176.
1. Headings use pre-enum string names
### AT_LEAST_ONCE (Default)
### AT_MOST_ONCE
The actual SDK enum members are AtLeastOncePerRetry and AtMostOncePerRetry, declared at step.ts:65. #176 updated the code bodies to use the enum values, which leaves the headings out of sync with the code immediately below them.
Proposed:
### AtLeastOncePerRetry (default)
### AtMostOncePerRetry
2. Prose under AT_MOST_ONCE is incorrect
Current (L199):
Step executes at most once, never retries. Use for non-idempotent operations.
AtMostOncePerRetry does not disable retries. Its guarantee is per retry attempt: if a crash happens between the pre-step checkpoint and step completion, the step is skipped on replay rather than re-executed. Across multiple retry attempts the step can still run more than once.
The SDK docstring at step.ts:34–38 is explicit:
Note: This is "at-most-once per retry". With multiple retry attempts, the step could still execute multiple times across different retries. To guarantee the step executes at most once, disable retries by returning { shouldRetry: false } from your retry strategy.
Proposed replacement prose:
Step executes at most once per retry attempt. If a crash happens between the pre-step checkpoint and step completion, the step is skipped on replay rather than re-executed. The step can still run across multiple retry attempts — to guarantee at-most-once overall, pair with retryStrategy: () => ({ shouldRetry: false }).
3. While there, also tighten AT_LEAST_ONCE prose
Current (L183):
Step executes at least once, may execute multiple times on failure/retry.
Could similarly note the per-retry distinction and the checkpoint-succeeded-body-failed case the SDK docstring describes at step.ts:47.
Context
Surfaced during review of #176, which landed the narrower string → enum fix.
The
Step Semanticssection inaws-lambda-durable-functions-power/steering/step-operations.mdhas two pre-existing bugs surfaced during review of #176.1. Headings use pre-enum string names
The actual SDK enum members are
AtLeastOncePerRetryandAtMostOncePerRetry, declared atstep.ts:65. #176 updated the code bodies to use the enum values, which leaves the headings out of sync with the code immediately below them.Proposed:
2. Prose under
AT_MOST_ONCEis incorrectCurrent (L199):
AtMostOncePerRetrydoes not disable retries. Its guarantee is per retry attempt: if a crash happens between the pre-step checkpoint and step completion, the step is skipped on replay rather than re-executed. Across multiple retry attempts the step can still run more than once.The SDK docstring at
step.ts:34–38is explicit:Proposed replacement prose:
3. While there, also tighten
AT_LEAST_ONCEproseCurrent (L183):
Could similarly note the per-retry distinction and the checkpoint-succeeded-body-failed case the SDK docstring describes at
step.ts:47.Context
Surfaced during review of #176, which landed the narrower string → enum fix.