durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/features/sagas.md

@@ -12,28 +12,91 @@ Sagas are an established design pattern for managing complex, long-running opera
 - The saga pattern assures that all operations are either completed successfully or the corresponding compensation activities are run to undo any completed work.
 
 ```php
-use function Workflow\activity;
-use Workflow\Workflow;
+use function Workflow\V2\activity;
+use Workflow\V2\Attributes\Type;
+use Workflow\V2\Workflow;
 
+#[Type('booking-saga')]
 class BookingSagaWorkflow extends Workflow
 {
-    public function execute()
+    public function handle(): array
     {
         try {
-            $flightId = yield activity(BookFlightActivity::class);
+            $flightId = activity(BookFlightActivity::class);
             $this->addCompensation(fn () => activity(CancelFlightActivity::class, $flightId));
 
-            $hotelId = yield activity(BookHotelActivity::class);
+            $hotelId = activity(BookHotelActivity::class);
             $this->addCompensation(fn () => activity(CancelHotelActivity::class, $hotelId));
 
-            $carId = yield activity(BookRentalCarActivity::class);
+            $carId = activity(BookRentalCarActivity::class);
             $this->addCompensation(fn () => activity(CancelRentalCarActivity::class, $carId));
-        } catch (Throwable $th) {
-            yield from $this->compensate();
-            throw $th;
+
+            return compact('flightId', 'hotelId', 'carId');
+        } catch (\Throwable $e) {
+            $this->compensate();
+
+            throw $e;
         }
     }
 }
 ```
 
-By default, compensations execute sequentially in the reverse order they were added. To run them in parallel, use `$this->setParallelCompensation(true)`. To ignore exceptions that occur inside compensation activities while still running them sequentially, use `$this->setContinueWithError(true)` instead.
+When the workflow catches an exception, `$this->compensate()` runs every registered compensation in **reverse order**. In the example above, if `BookRentalCarActivity` fails, the engine cancels the hotel first and then the flight — unwinding the saga from the most recent step backward.
+
+## Compensation ordering
+
+By default, compensations execute **sequentially in reverse registration order**. This is the safest default because later steps may depend on earlier ones.
+
+## Parallel compensation
+
+To run compensations in parallel, use `setParallelCompensation(true)`. When parallel compensation is enabled, each compensation closure should return a started (but not awaited) activity call so the engine can execute them concurrently:
+
+```php
+use function Workflow\V2\activity;
+use function Workflow\V2\startActivity;
+use Workflow\V2\Attributes\Type;
+use Workflow\V2\Workflow;
+
+#[Type('parallel-saga')]
+class ParallelSagaWorkflow extends Workflow
+{
+    public function handle(): void
+    {
+        $this->setParallelCompensation(true);
+
+        try {
+            $flightId = activity(BookFlightActivity::class);
+            $this->addCompensation(fn () => startActivity(CancelFlightActivity::class, $flightId));
+
+            $hotelId = activity(BookHotelActivity::class);
+            $this->addCompensation(fn () => startActivity(CancelHotelActivity::class, $hotelId));
+
+            activity(ChargePaymentActivity::class);
+        } catch (\Throwable $e) {
+            $this->compensate();
+
+            throw $e;
+        }
+    }
+}
+```
+
+Use `startActivity()` (not `activity()`) inside parallel compensation closures. `startActivity()` returns a pending call that the engine collects and runs through `all()`, while `activity()` would block inline and defeat the purpose of parallelism.
+
+## Continue with error
+
+By default, if a compensation activity throws an exception, the remaining compensations are skipped and the error propagates. To run all compensations regardless of individual failures, use `setContinueWithError(true)`:
+
+```php
+$this->setContinueWithError(true);
+```
+
+When enabled, the engine catches and discards exceptions from each compensation closure and continues to the next one. This is useful when compensations are independent and you want a best-effort cleanup even if some steps fail.
+
+## How it works
+
+- `addCompensation()` registers a callable that will be invoked during `compensate()`
+- `compensate()` iterates the registered compensations in reverse order
+- each compensation closure is a normal V2 workflow step — the activities it calls produce durable history events just like any other activity
+- compensation activities are visible in Waterline's timeline and history export
+- if the workflow succeeds, compensation closures are never invoked and produce no history

docs/features/side-effects.md

@@ -27,11 +27,72 @@ class MyWorkflow extends Workflow
 
 The workflow will only call `random_int()` once and save the result, even if the workflow later fails and is retried.
 
-**Important:** The code inside a side effect should never fail because it will not be retried. Code that can possibly fail and therefore need to be retried should be moved to an activity instead.
+## When to use side effects
 
-## How It Works
+Use `sideEffect()` when you need a non-deterministic value that:
+
+- is computed locally without external I/O (random numbers, UUIDs, timestamps)
+- should never change once recorded, even across replays
+- does not need retry semantics — the closure runs exactly once
+
+```php
+// Generate a correlation token for downstream systems.
+$correlationId = sideEffect(fn () => (string) Str::uuid());
+
+// Snapshot the current time for a business rule.
+$decidedAt = sideEffect(fn () => now()->toIso8601String());
+```
+
+## When to use an activity instead
+
+If the code can fail, talks to an external service, or needs retry/timeout semantics, use an [activity](../defining-workflows/activities.md) instead of a side effect:
+
+| Scenario | Use |
+|---|---|
+| Generate a random token | `sideEffect()` |
+| Read a config value at decision time | `sideEffect()` |
+| Call an external API | `activity()` |
+| Write to a database | `activity()` |
+| Send an email or notification | `activity()` |
+| Compute an expensive value that can throw | `activity()` |
+
+The rule of thumb: if the closure can throw an exception that you would want to retry, it belongs in an activity.
+
+## How it works
 
 - each `sideEffect()` call appends a typed `SideEffectRecorded` history event with the workflow step sequence
 - workflow replay and query replay both reuse that committed value instead of re-running the closure
 - Waterline surfaces the side-effect snapshot as a typed history entry in the selected run timeline
 - side effects are still for replay-safe snapshots only, not for work that can fail or that needs retry semantics
+
+## Anti-patterns
+
+**Do not call external services inside a side effect.** If the service call fails, the side effect will not be retried and the workflow will fail permanently:
+
+```php
+// BAD: HTTP calls can fail and side effects do not retry.
+$price = sideEffect(fn () => Http::get('/api/price')->json('amount'));
+
+// GOOD: Use an activity for external calls.
+$price = activity(FetchPriceActivity::class);
+```
+
+**Do not put slow or blocking operations inside a side effect.** The closure runs on the workflow task thread. Long-running work delays the entire workflow task:
+
+```php
+// BAD: Expensive computation blocks the workflow task.
+$hash = sideEffect(fn () => bcrypt($largePayload));
+
+// GOOD: Offload heavy work to an activity.
+$hash = activity(ComputeHashActivity::class, $largePayload);
+```
+
+**Do not rely on mutable external state.** The closure is executed exactly once. If you read a value that changes over time, the snapshot is frozen at the moment of first execution — not at replay time:
+
+```php
+// The cached value is whatever it was during the first execution.
+// If the cache changes later, this workflow still sees the old value.
+$setting = sideEffect(fn () => cache('feature.flag'));
+```
+
+This is by design — the snapshot is intentionally frozen for determinism. If you need a value that updates over the lifetime of the workflow, use a signal or an activity.