Skip to content

docs(power): step-operations.md "Step Semantics" section has stale heading names and incorrect prose #181

@yaythomas

Description

@yaythomas

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions