docs: update sdk readme with step semantics (#407)

Closes: #406

*Issue #, if available:*

*Description of changes:*


By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

---------

Signed-off-by: Michael Gasch <15986659+embano1@users.noreply.github.com>
Co-authored-by: anthonyting <49772744+anthonyting@users.noreply.github.com>

Author: embano1

packages/aws-durable-execution-sdk-js/README.md

@@ -285,17 +285,37 @@ Control execution guarantees:
 ```typescript
 import { StepSemantics } from "@aws/durable-execution-sdk-js";
 
-// At-most-once per retry (default)
+// At-least-once per retry (default)
+await context.step("retriable-operation", async () => sendNotification(), {
+  semantics: StepSemantics.AtLeastOncePerRetry,
+});
+
+// At-most-once per retry
 await context.step("idempotent-operation", async () => updateDatabase(), {
   semantics: StepSemantics.AtMostOncePerRetry,
 });
+```
 
-// At-least-once per retry
-await context.step("retriable-operation", async () => sendNotification(), {
-  semantics: StepSemantics.AtLeastOncePerRetry,
-});
+**Important**: These semantics apply _per retry_, not per overall execution:
+
+- **AtLeastOncePerRetry**: The step will execute at least once on each retry attempt. If the step succeeds but the checkpoint fails (e.g., sandbox crash), the step will re-execute on replay.
+- **AtMostOncePerRetry**: The step will execute at most once per retry attempt. A checkpoint is created before execution, so if a failure occurs after the checkpoint but before step completion, the previous step retry attempt is skipped on replay.
+
+**To achieve at-most-once semantics on a step-level**, use a custom retry strategy:
+
+```typescript
+await context.step(
+  "truly-once-only",
+  async () => callThatCannotTolerateDuplicates(),
+  {
+    semantics: StepSemantics.AtMostOncePerRetry,
+    retryStrategy: () => ({ shouldRetry: false }), // No retries
+  },
+);
 ```
 
+Without this, a step using `AtMostOncePerRetry` with retries enabled could still execute multiple times across different retry attempts.
+
 ### Jitter Strategies
 
 Prevent thundering herd:

packages/aws-durable-execution-sdk-js/src/documents/CONCEPTS.md

@@ -316,6 +316,22 @@ await context.step("api-call", async () => callExternalAPI(), {
 });
 ```
 
+### Step Semantics
+
+Step semantics control execution guarantees _per retry attempt_:
+
+- **AtLeastOncePerRetry** (default): The step executes at least once per retry. If the step succeeds but checkpointing fails, it re-executes on replay.
+- **AtMostOncePerRetry**: A checkpoint is created before execution. If failure occurs after checkpoint but before completion, the previous step retry attempt is skipped on replay.
+
+**Important**: These guarantees are per retry, not per workflow execution. With retries enabled, `AtMostOncePerRetry` could still result in multiple executions across retry attempts. For step-level at-most-once semantics, use a custom retry policy:
+
+```typescript
+await context.step("critical-operation", async () => attemptOnlyOnce(), {
+  semantics: StepSemantics.AtMostOncePerRetry,
+  retryStrategy: () => ({ shouldRetry: false }), // Disable retries
+});
+```
+
 ## Limitations and Considerations
 
 - Code outside steps must be deterministic

packages/aws-durable-execution-sdk-js/src/types/step.ts

@@ -36,10 +36,56 @@ export interface RetryDecision {
 }
 
 /**
+ * Execution semantics for step operations.
+ *
+ * @remarks
+ * These semantics control how step execution is checkpointed and replayed. **Important**: The guarantees apply *per
+ * retry attempt*, not per overall workflow execution.
+ *
+ * With retries enabled (the default), a step could execute multiple times across different retry attempts even when
+ * using `AtMostOncePerRetry`. To achieve step-level at-most-once execution, combine `AtMostOncePerRetry` with a retry
+ * strategy that disables retries (`shouldRetry: false`).
+ *
+ * @example
+ * ```typescript
+ * // At-least-once per retry (default) - safe for idempotent operations
+ * await context.step("send-notification", async () => sendEmail(), {
+ *   semantics: StepSemantics.AtLeastOncePerRetry,
+ * });
+ *
+ * // At-most-once per retry - for non-idempotent operations
+ * await context.step("charge-payment", async () => processPayment(), {
+ *   semantics: StepSemantics.AtMostOncePerRetry,
+ *   retryStrategy: () => ({ shouldRetry: false }),
+ * });
+ * ```
+ *
  * @public
  */
 export enum StepSemantics {
+  /**
+   * At-most-once execution per retry attempt.
+   *
+   * @remarks
+   * A checkpoint is created before step execution. If a failure occurs after the checkpoint
+   * but before step completion, the previous step retry attempt is skipped on replay.
+   *
+   * **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.
+   */
   AtMostOncePerRetry = "AT_MOST_ONCE_PER_RETRY",
+
+  /**
+   * At-least-once execution per retry attempt (default).
+   *
+   * @remarks
+   * The step will execute at least once on each retry attempt. If the step succeeds
+   * but the checkpoint fails (e.g., due to a sandbox crash), the step will re-execute
+   * on replay. This is the safer default for operations that are idempotent or can
+   * tolerate duplicate execution.
+   */
   AtLeastOncePerRetry = "AT_LEAST_ONCE_PER_RETRY",
 }