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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions