add stepCtx to all step examples and docs (#164)

Author: zhongkechen

AGENTS.md

@@ -142,7 +142,7 @@ examples/src/test/               # Customer-facing examples + cloud tests
 @Test
 void stepReturnsResultOnReplay() {
     var context = createTestContext(completedOperations);
-    var result = context.step("test", String.class, () -> "new");
+    var result = context.step("test", String.class, stepCtx -> "new");
     assertEquals("cached", result);  // Returns cached, doesn't re-execute
 }
 ```

README.md

@@ -50,18 +50,18 @@ public class OrderProcessor extends DurableHandler<Order, OrderResult> {
     protected OrderResult handleRequest(Order order, DurableContext ctx) {
         // Step 1: Validate and reserve inventory
         var reservation = ctx.step("reserve-inventory", Reservation.class, 
-            () -> inventoryService.reserve(order.getItems()));
+            stepCtx -> inventoryService.reserve(order.getItems()));
 
         // Step 2: Process payment
         var payment = ctx.step("process-payment", Payment.class,
-            () -> paymentService.charge(order.getPaymentMethod(), order.getTotal()));
+            stepCtx -> paymentService.charge(order.getPaymentMethod(), order.getTotal()));
 
         // Wait for warehouse processing (no compute charges)
         ctx.wait(null, Duration.ofHours(2));
 
         // Step 3: Confirm shipment
         var shipment = ctx.step("confirm-shipment", Shipment.class,
-            () -> shippingService.ship(reservation, order.getAddress()));
+            stepCtx -> shippingService.ship(reservation, order.getAddress()));
 
         return new OrderResult(order.getId(), shipment.getTrackingNumber());
     }

docs/adr/001-threaded-handler-execution.md

@@ -9,9 +9,9 @@ Durable functions need to suspend execution immediately at suspension points (wa
 
 ```java
 public String handleRequest(MyInput input, DurableContext context) {
-    var result1 = context.step("step1", () -> "first");
+    var result1 = context.step("step1", stepCtx -> "first");
     context.wait(null, Duration.ofHours(1)); // Should suspend HERE
-    var result2 = context.step("step2", () -> "second"); // Don't wait for this
+    var result2 = context.step("step2", stepCtx -> "second"); // Don't wait for this
     return result1 + result2;
 }
 ```
@@ -21,7 +21,7 @@ public String handleRequest(MyInput input, DurableContext context) {
 Run the handler in a background thread and race two futures:
 
 ```java
-var handlerFuture = CompletableFuture.supplyAsync(() -> handler.apply(input, context), executor);
+var handlerFuture = CompletableFuture.supplyAsync(stepCtx -> handler.apply(input, context), executor);
 var suspendFuture = executionManager.getSuspendExecutionFuture();
 
 CompletableFuture.anyOf(handlerFuture, suspendFuture).join();

docs/adr/002-phaser-based-coordination.md

@@ -15,8 +15,8 @@ context.wait(null, Duration.ofMinutes(5)); // Root deregisters → immediate sus
 
 ### Complex Case: Blocking on Retrying Operations
 ```java
-var future1 = context.stepAsync("step1", () -> failsAndRetries());
-var result = context.step("step2", () -> future1.get() + "-processed");
+var future1 = context.stepAsync("step1", stepCtx -> failsAndRetries());
+var result = context.step("step2", stepCtx -> future1.get() + "-processed");
 ```
 
 **Problem:** Simple thread counting fails because step2's thread would stay registered while blocked on `future1.get()`, preventing suspension during step1's retry delay.

docs/adr/004-child-context-execution.md

@@ -9,9 +9,9 @@ The TypeScript and Python durable execution SDKs support child contexts via `Ope
 
 ```java
 var futureA = ctx.runInChildContextAsync("branch-a", String.class, child -> {
-    child.step("validate", Void.class, () -> validate(order));
+    child.step("validate", Void.class, stepCtx -> validate(order));
     child.wait(null, Duration.ofMinutes(5));
-    return child.step("charge", String.class, () -> charge(order));
+    return child.step("charge", String.class, stepCtx -> charge(order));
 });
 var futureB = ctx.runInChildContextAsync("branch-b", String.class, child -> { ... });
 var results = DurableFuture.allOf(futureA, futureB);

docs/advanced/error-handling.md

@@ -23,7 +23,7 @@ DurableExecutionException              - General durable exception
 ```java
 try {
     var result = ctx.step("charge-payment", Payment.class,
-        () -> paymentService.charge(amount),
+        stepCtx -> paymentService.charge(amount),
         StepConfig.builder()
             .semantics(StepSemantics.AT_MOST_ONCE_PER_RETRY)
             .build());

docs/advanced/testing.md

@@ -32,7 +32,7 @@ You can also pass a lambda directly instead of a handler instance:
 
 ```java
 var runner = LocalDurableTestRunner.create(Order.class, (order, ctx) -> {
-    var result = ctx.step("process", String.class, () -> "done");
+    var result = ctx.step("process", String.class, stepCtx -> "done");
     return new OrderResult(order.getId(), result);
 });
 ```

docs/core/child-contexts.md

@@ -5,17 +5,17 @@ Child contexts run an isolated stream of work with their own operation counter a
 ```java
 // Sync: blocks until the child context completes
 var result = ctx.runInChildContext("validate-order", String.class, child -> {
-    var data = child.step("fetch", String.class, () -> fetchData());
+    var data = child.step("fetch", String.class, stepCtx -> fetchData());
     child.wait(null, Duration.ofMinutes(5));
-    return child.step("validate", String.class, () -> validate(data));
+    return child.step("validate", String.class, stepCtx -> validate(data));
 });
 
 // Async: returns a DurableFuture for concurrent execution
 var futureA = ctx.runInChildContextAsync("branch-a", String.class, child -> {
-    return child.step("work-a", String.class, () -> doWorkA());
+    return child.step("work-a", String.class, stepCtx -> doWorkA());
 });
 var futureB = ctx.runInChildContextAsync("branch-b", String.class, child -> {
-    return child.step("work-b", String.class, () -> doWorkB());
+    return child.step("work-b", String.class, stepCtx -> doWorkB());
 });
 
 // Wait for all child contexts to complete

docs/core/steps.md

@@ -4,11 +4,11 @@ Steps execute your code and checkpoint the result. On replay, results from compl
 
 ```java
 // Basic step (blocks until complete)
-var result = ctx.step("fetch-user", User.class, () -> userService.getUser(userId));
+var result = ctx.step("fetch-user", User.class, stepCtx -> userService.getUser(userId));
 
 // Step with custom configuration (retries, semantics, serialization)
 var result = ctx.step("call-api", Response.class, 
-	() -> externalApi.call(request),
+	stepCtx -> externalApi.call(request),
 	StepConfig.builder()
 		.retryStrategy(...)
 		.semantics(...)
@@ -24,9 +24,9 @@ See [Step Configuration](#step-configuration) for retry strategies, delivery sem
 ```java
 // Start multiple operations concurrently
 DurableFuture<User> userFuture = ctx.stepAsync("fetch-user", User.class, 
-	() -> userService.getUser(userId));
+	stepCtx -> userService.getUser(userId));
 DurableFuture<List<Order>> ordersFuture = ctx.stepAsync("fetch-orders", 
-	new TypeToken<List<Order>>() {}, () -> orderService.getOrders(userId));
+	new TypeToken<List<Order>>() {}, stepCtx -> orderService.getOrders(userId));
 
 // Both operations run concurrently
 // Block and get results when needed
@@ -39,7 +39,7 @@ List<Order> orders = ordersFuture.get();
 Configure step behavior with `StepConfig`:
 
 ```java
-ctx.step("my-step", Result.class, () -> doWork(),
+ctx.step("my-step", Result.class, stepCtx -> doWork(),
 	StepConfig.builder()
 		.retryStrategy(...)    // How to handle failures
 		.semantics(...)        // At-least-once vs at-most-once
@@ -78,11 +78,11 @@ Control how steps behave when interrupted mid-execution:
 ```java
 // Default: at-least-once per retry (step may re-run if interrupted)
 var result = ctx.step("idempotent-update", Result.class, 
-	() -> database.upsert(record));
+	stepCtx -> database.upsert(record));
 
 // At-most-once per retry
 var result = ctx.step("send-email", Result.class,
-	() -> emailService.send(notification),
+	stepCtx -> emailService.send(notification),
 	StepConfig.builder()
 		.semantics(StepSemantics.AT_MOST_ONCE_PER_RETRY)
 		.build());
@@ -98,7 +98,7 @@ To achieve step-level at-most-once semantics, combine with a no-retry strategy:
 ```java
 // True at-most-once: step executes at most once, ever
 var result = ctx.step("charge-payment", Result.class,
-	() -> paymentService.charge(amount),
+	stepCtx -> paymentService.charge(amount),
 	StepConfig.builder()
 		.semantics(StepSemantics.AT_MOST_ONCE_PER_RETRY)
 		.retryStrategy(RetryStrategies.Presets.NO_RETRY)
@@ -113,10 +113,10 @@ When a step returns a parameterized type like `List<User>`, use `TypeToken` to p
 
 ```java
 var users = ctx.step("fetch-users", new TypeToken<List<User>>() {}, 
-	() -> userService.getAllUsers());
+	stepCtx -> userService.getAllUsers());
 
 var orderMap = ctx.step("fetch-orders", new TypeToken<Map<String, Order>>() {},
-	() -> orderService.getOrdersByCustomer());
+	stepCtx -> orderService.getOrdersByCustomer());
 ```
 
 This is needed for the SDK to deserialize a checkpointed result and get the exact type to reconstruct. See [TypeToken and Type Erasure](docs/internal-design.md#typetoken-and-type-erasure) for technical details. 

docs/core/wait.md

@@ -19,7 +19,7 @@ ctx.wait("cooling-off-period", Duration.ofDays(7));
 DurableFuture<Void> timer = ctx.waitAsync("min-delay", Duration.ofSeconds(5));
 
 // Do work while the timer runs
-var result = ctx.step("process", String.class, () -> doWork());
+var result = ctx.step("process", String.class, stepCtx -> doWork());
 
 // Block until the wait elapses
 timer.get();