feat: simplify operation id

Author: maschnetwork

docs/design-run-in-child-context.md

@@ -31,19 +31,21 @@ This aligns the Java SDK with the TypeScript and Python reference implementation
 A child context is a `CONTEXT` operation in the checkpoint log. Its lifecycle:
 
 1. **START** (fire-and-forget) — marks the child context as in-progress
-2. Inner operations checkpoint with `parentId` set to the child context's ID
+2. Inner operations checkpoint with `parentId` set to the child context's operation ID
 3. **SUCCEED** or **FAIL** (blocking) — finalizes the child context
 
 ```
 Op ID | Parent ID | Type    | Action  | Payload
 ------|-----------|---------|---------|--------
 3     | null      | CONTEXT | START   | —
-1     | 3         | STEP    | START   | —
-1     | 3         | STEP    | SUCCEED | "result"
+3-1   | 3         | STEP    | START   | —
+3-1   | 3         | STEP    | SUCCEED | "result"
 3     | null      | CONTEXT | SUCCEED | "final result"
 ```
 
-For nested child contexts, the `parentId` uses the qualified context path (e.g., `"3:2"` for a child context created as operation `"2"` inside parent context `"3"`).
+Inner operation IDs are prefixed with the parent context's operation ID using `-` as separator (e.g., `"3-1"`, `"3-2"`). This matches the JavaScript SDK's `stepPrefix` convention and ensures operation IDs are globally unique — the backend validates type consistency by operation ID, so bare sequential IDs inside child contexts would collide with root-level operations.
+
+For nested child contexts, the prefix chains naturally (e.g., `"3-2-1"` for the first operation inside a nested child context that is operation `"2"` inside parent context `"3"`).
 
 ### Replay behavior
 
@@ -54,28 +56,24 @@ For nested child contexts, the `parentId` uses the qualified context path (e.g.,
 | FAILED | Re-throw cached error |
 | STARTED | Re-execute (was interrupted mid-flight) |
 
-### Operation scoping
-
-Child contexts restart their operation counter at 1. To avoid ID collisions, `ExecutionManager` uses a composite key:
-
-```java
-record OperationKey(String parentId, String operationId) { ... }
-```
-
-This applies to the `operations` map, `openPhasers` map, and all checkpoint completion handlers. The backend's `ParentId` field on each `Operation` is the source of truth for scoping.
+### Operation ID prefixing
 
-### Nested context ID qualification
+To ensure global uniqueness, `DurableContext.nextOperationId()` prefixes operation IDs with the context's `parentId` when inside a child context:
 
-To prevent `OperationKey` collisions when sibling contexts at different nesting levels share the same local operation ID, child contexts build a globally unique `contextId` by qualifying with the parent's context path:
-
-- Root-level child contexts use just their operation ID (e.g., `"3"`)
-- Nested child contexts include the parent path (e.g., `"3:2"` for operation `"2"` inside parent context `"3"`)
+- Root context: IDs are `"1"`, `"2"`, `"3"` (no prefix)
+- Child context `"1"`: IDs are `"1-1"`, `"1-2"`, `"1-3"`
+- Nested child context `"1-2"`: IDs are `"1-2-1"`, `"1-2-2"`
 
 ```java
-var contextId = getParentId() != null ? getParentId() + ":" + getOperationId() : getOperationId();
+private String nextOperationId() {
+    var counter = String.valueOf(operationCounter.incrementAndGet());
+    return parentId != null ? parentId + "-" + counter : counter;
+}
 ```
 
-This qualified `contextId` is used as the `parentId` for all operations within the child context.
+This matches the JavaScript SDK's `_stepPrefix` mechanism. The backend validates type consistency by operation ID alone, so without prefixing, a CONTEXT operation with ID `"1"` and an inner STEP with ID `"1"` (different `parentId`) would trigger an `InvalidParameterValueException`.
+
+`ExecutionManager` still uses plain `String` keys (the globally unique operation ID) for its internal maps, since prefixed IDs are inherently unique across all contexts.
 
 ### Thread model
 
@@ -95,13 +93,14 @@ The `DurableContext` stores its context identity in a `parentId` field — `null
 
 | File | Change |
 |------|--------|
-| `ChildContextOperation` (new) | Extends `BaseDurableOperation<T>`. Manages child context lifecycle, thread coordination, large result handling. Builds qualified `contextId` for nested contexts (e.g., `"3:2"`). |
+| `ChildContextOperation` (new) | Extends `BaseDurableOperation<T>`. Manages child context lifecycle, thread coordination, large result handling. Uses `getOperationId()` directly as `contextId` (already globally unique via prefixed IDs). |
 | `ChildContextFailedException` (new) | Extends `DurableOperationException`. Wraps the `Operation` object; extracts error from `contextDetails()`. |
-| `DurableContext` | New `runInChildContext`/`runInChildContextAsync` methods. New `createChildContext` factory (skips thread registration). Stores `parentId` field (null for root, contextId for child). Per-context replay tracking via `isReplaying` field. |
+| `DurableContext` | New `runInChildContext`/`runInChildContextAsync` methods. New `createChildContext` factory (skips thread registration). Stores `parentId` field (null for root, contextId for child). Per-context replay tracking via `isReplaying` field. `nextOperationId()` prefixes with `parentId` for child contexts (e.g., `"1-1"`). |
 | `BaseDurableOperation` | New `parentId` constructor parameter. `sendOperationUpdateAsync` uses it instead of hardcoded `null`. Protected `getParentId()` getter. |
-| `ExecutionManager` | `OperationKey` record for composite keys. All maps (`operations`, `openPhasers`) use composite keys. `getOperationAndUpdateReplayState` accepts `parentId`. `startPhaser` takes `parentId` + `operationId`. New `hasOperationsForContext(parentId)` method for per-context replay initialization. |
-| `StepOperation` | Thread ID includes parent context: `(parentId != null ? parentId + ":" : "") + operationId + "-step"` |
+| `ExecutionManager` | All maps (`operations`, `openPhasers`) use plain `String` keys (globally unique operation IDs). `getOperationAndUpdateReplayState` and `startPhaser` take a single `operationId` argument. New `hasOperationsForContext(parentId)` method for per-context replay initialization. |
+| `StepOperation` | Thread ID uses `getOperationId() + "-step"` (operation IDs are globally unique via prefixing). |
 | `LocalMemoryExecutionClient` | Handles `CONTEXT` operations (was `throw UnsupportedOperationException`). Propagates `parentId` for all operation types. |
+| `HistoryEventProcessor` | Handles `CONTEXT_STARTED`, `CONTEXT_SUCCEEDED`, `CONTEXT_FAILED` events (was `throw UnsupportedOperationException`). Builds `ContextDetails` with result/error extraction. |
 
 ## Large result handling
 

examples/template-child-context.yaml

@@ -0,0 +1,62 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: AWS Lambda Durable Execution SDK - ChildContext Example
+
+Parameters:
+  Architecture:
+    Type: String
+    Default: arm64
+    Description: Lambda Function Architecture
+    AllowedValues:
+      - x86_64
+      - arm64
+  DockerFile:
+    Type: String
+    Default: examples/Dockerfile
+    Description: path to Dockerfile
+  FunctionNameSuffix:
+    Type: String
+    Default: ''
+    Description: Suffix to append to all function names
+
+Globals:
+  Function:
+    Timeout: 900
+    MemorySize: 512
+    Architectures:
+      - !Ref Architecture
+
+Resources:
+  ChildContextExampleFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      PackageType: Image
+      FunctionName: !Join
+        - ''
+        - - 'child-context-example'
+          - !Ref FunctionNameSuffix
+      ImageConfig:
+        Command: ["com.amazonaws.lambda.durable.examples.ChildContextExample::handleRequest"]
+      DurableConfig:
+        ExecutionTimeout: 300
+        RetentionPeriodInDays: 7
+      Policies:
+        - Statement:
+            - Effect: Allow
+              Action:
+                - lambda:CheckpointDurableExecutions
+                - lambda:GetDurableExecutionState
+              Resource: !Sub "arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:child-context-example${FunctionNameSuffix}"
+    Metadata:
+      Dockerfile: !Ref DockerFile
+      DockerContext: ../
+      DockerTag: durable-examples
+
+Outputs:
+  ChildContextExampleFunction:
+    Description: Child Context Example Function ARN
+    Value: !GetAtt ChildContextExampleFunction.Arn
+
+  ChildContextExampleFunctionName:
+    Description: Child Context Example Function Name
+    Value: !Ref ChildContextExampleFunction

sdk-testing/src/main/java/com/amazonaws/lambda/durable/testing/HistoryEventProcessor.java

@@ -9,6 +9,7 @@
 import java.util.List;
 import software.amazon.awssdk.services.lambda.model.CallbackDetails;
 import software.amazon.awssdk.services.lambda.model.ChainedInvokeDetails;
+import software.amazon.awssdk.services.lambda.model.ContextDetails;
 import software.amazon.awssdk.services.lambda.model.ErrorObject;
 import software.amazon.awssdk.services.lambda.model.Event;
 import software.amazon.awssdk.services.lambda.model.Operation;
@@ -142,8 +143,26 @@ public <O> TestResult<O> processEvents(List<Event> events, Class<O> outputType)
                     // Unknown event type - log and ignore gracefully
                 }
 
-                case CONTEXT_STARTED, CONTEXT_SUCCEEDED, CONTEXT_FAILED -> {
-                    throw new UnsupportedOperationException("Context operations currently not supported");
+                case CONTEXT_STARTED -> {
+                    if (operationId != null) {
+                        operations.putIfAbsent(
+                                operationId,
+                                createContextOperation(operationId, event.name(), OperationStatus.STARTED, event));
+                    }
+                }
+                case CONTEXT_SUCCEEDED -> {
+                    if (operationId != null) {
+                        operations.put(
+                                operationId,
+                                createContextOperation(operationId, event.name(), OperationStatus.SUCCEEDED, event));
+                    }
+                }
+                case CONTEXT_FAILED -> {
+                    if (operationId != null) {
+                        operations.put(
+                                operationId,
+                                createContextOperation(operationId, event.name(), OperationStatus.FAILED, event));
+                    }
                 }
 
                 case CHAINED_INVOKE_STARTED,
@@ -292,4 +311,28 @@ private Operation createInvokeOperation(String id, Event event) {
                 .chainedInvokeDetails(builder.build())
                 .build();
     }
+
+    private Operation createContextOperation(String id, String name, OperationStatus status, Event event) {
+        var builder = ContextDetails.builder();
+
+        if (event.contextSucceededDetails() != null) {
+            var details = event.contextSucceededDetails();
+            if (details.result() != null && details.result().payload() != null) {
+                builder.result(details.result().payload());
+            }
+        } else if (event.contextFailedDetails() != null) {
+            var details = event.contextFailedDetails();
+            if (details.error() != null && details.error().payload() != null) {
+                builder.error(details.error().payload());
+            }
+        }
+
+        return Operation.builder()
+                .id(id)
+                .name(name)
+                .status(status)
+                .type(OperationType.CONTEXT)
+                .contextDetails(builder.build())
+                .build();
+    }
 }

sdk/src/main/java/com/amazonaws/lambda/durable/DurableContext.java

@@ -319,8 +319,13 @@ void setExecutionMode() {
         this.isReplaying = false;
     }
 
-    /** Get the next operationId (latest operationId + 1) */
+    /**
+     * Get the next operationId. For root contexts, returns sequential IDs like "1", "2", "3". For child contexts,
+     * prefixes with the parentId to ensure global uniqueness, e.g. "1-1", "1-2" for operations inside child context
+     * "1". This matches the JavaScript SDK's stepPrefix convention and prevents ID collisions in checkpoint batches.
+     */
     private String nextOperationId() {
-        return String.valueOf(operationCounter.incrementAndGet());
+        var counter = String.valueOf(operationCounter.incrementAndGet());
+        return parentId != null ? parentId + "-" + counter : counter;
     }
 }

sdk/src/main/java/com/amazonaws/lambda/durable/execution/ExecutionManager.java

@@ -37,22 +37,25 @@
  * <p>This is the single entry point for all execution coordination. Internal coordination (polling, checkpointing) uses
  * a dedicated SDK thread pool, while user-defined operations run on a customer-configured executor.
  *
+ * <p>Operations are keyed by their globally unique operation ID. Child context operations use prefixed IDs (e.g.,
+ * "1-1", "1-2") to avoid collisions with root-level operations.
+ *
  * @see InternalExecutor
  */
 public class ExecutionManager {
 
     private static final Logger logger = LoggerFactory.getLogger(ExecutionManager.class);
 
     // ===== Execution State =====
-    private final Map<OperationKey, Operation> operations;
+    private final Map<String, Operation> operations;
     private final String executionOperationId;
     private final String durableExecutionArn;
     private final AtomicReference<ExecutionMode> executionMode;
 
     // ===== Thread Coordination =====
     private final Map<String, ThreadType> activeThreads = Collections.synchronizedMap(new HashMap<>());
     private static final ThreadLocal<OperationContext> currentContext = new ThreadLocal<>();
-    private final Map<OperationKey, Phaser> openPhasers = Collections.synchronizedMap(new HashMap<>());
+    private final Map<String, Phaser> openPhasers = Collections.synchronizedMap(new HashMap<>());
     private final CompletableFuture<Void> executionExceptionFuture = new CompletableFuture<>();
 
     // ===== Checkpoint Batching =====
@@ -71,7 +74,7 @@ public ExecutionManager(
                 new CheckpointBatcher(config, durableExecutionArn, checkpointToken, this::onCheckpointComplete);
 
         this.operations = checkpointBatcher.fetchAllPages(initialExecutionState).stream()
-                .collect(Collectors.toConcurrentMap(OperationKey::fromOperation, op -> op));
+                .collect(Collectors.toConcurrentMap(Operation::id, op -> op));
 
         // Start in REPLAY mode if we have more than just the initial EXECUTION operation
         this.executionMode =
@@ -92,13 +95,13 @@ public boolean isReplaying() {
     /** Called by CheckpointManager when a checkpoint completes. Updates state and advances phasers. */
     private void onCheckpointComplete(List<Operation> newOperations) {
         // Update operation storage
-        newOperations.forEach(op -> operations.put(OperationKey.fromOperation(op), op));
+        newOperations.forEach(op -> operations.put(op.id(), op));
 
         // Advance phasers for completed operations
         for (Operation operation : newOperations) {
-            var key = OperationKey.fromOperation(operation);
-            if (openPhasers.containsKey(key) && isTerminalStatus(operation.status())) {
-                var phaser = openPhasers.get(key);
+            var id = operation.id();
+            if (openPhasers.containsKey(id) && isTerminalStatus(operation.status())) {
+                var phaser = openPhasers.get(id);
 
                 // Two-phase completion
                 logger.trace("Advancing phaser 0 -> 1: {}", phaser);
@@ -110,28 +113,24 @@ private void onCheckpointComplete(List<Operation> newOperations) {
     }
 
     /**
-     * Gets an operation by parentId and operationId, and updates replay state. Transitions from REPLAY to EXECUTION
-     * mode if the operation is not found or is not in a terminal state (still in progress).
+     * Gets an operation by its globally unique operationId, and updates replay state. Transitions from REPLAY to
+     * EXECUTION mode if the operation is not found or is not in a terminal state (still in progress).
      *
-     * @param parentId the parent context ID (null for root context operations)
-     * @param operationId the operation ID to get
+     * @param operationId the globally unique operation ID (e.g., "1" for root, "1-1" for child context)
      * @return the existing operation, or null if not found (first execution)
      */
-    public Operation getOperationAndUpdateReplayState(String parentId, String operationId) {
-        var key = OperationKey.of(parentId, operationId);
-        var existing = operations.get(key);
-        if (executionMode.get() == ExecutionMode.REPLAY) {
-            if (existing == null || !isTerminalStatus(existing.status())) {
-                if (executionMode.compareAndSet(ExecutionMode.REPLAY, ExecutionMode.EXECUTION)) {
-                    logger.debug("Transitioned to EXECUTION mode at operation '{}'", operationId);
-                }
+    public Operation getOperationAndUpdateReplayState(String operationId) {
+        var existing = operations.get(operationId);
+        if (executionMode.get() == ExecutionMode.REPLAY && (existing == null || !isTerminalStatus(existing.status()))) {
+            if (executionMode.compareAndSet(ExecutionMode.REPLAY, ExecutionMode.EXECUTION)) {
+                logger.debug("Transitioned to EXECUTION mode at operation '{}'", operationId);
             }
         }
         return existing;
     }
 
     public Operation getExecutionOperation() {
-        return operations.get(OperationKey.of(null, executionOperationId));
+        return operations.get(executionOperationId);
     }
 
     /**
@@ -142,7 +141,7 @@ public Operation getExecutionOperation() {
      * @return true if at least one operation exists with the given parentId
      */
     public boolean hasOperationsForContext(String parentId) {
-        return operations.keySet().stream().anyMatch(key -> Objects.equals(key.parentId(), parentId));
+        return operations.values().stream().anyMatch(op -> Objects.equals(op.parentId(), parentId));
     }
 
     // ===== Thread Coordination =====
@@ -202,11 +201,10 @@ public void deregisterActiveThreadAndUnsetCurrentContext(String threadId) {
 
     // ===== Phaser Management =====
 
-    public Phaser startPhaser(String parentId, String operationId) {
-        var key = OperationKey.of(parentId, operationId);
+    public Phaser startPhaser(String operationId) {
         var phaser = new Phaser(1);
-        openPhasers.put(key, phaser);
-        logger.trace("Started phaser for operation '{}' (parentId='{}')", operationId, parentId);
+        openPhasers.put(operationId, phaser);
+        logger.trace("Started phaser for operation '{}'", operationId);
         return phaser;
     }