Expand documentation on side effects and signals

Author: rmcdaniel

docs/features/side-effects.md

@@ -24,3 +24,39 @@ 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.
+
+## Signals and Control Flow
+
+Signals are applied before the workflow continues execution. That means a signal-mutated variable can break replays unless the control flow decision is recorded deterministically.
+
+Use `sideEffect` to snapshot any signal-driven branch decision:
+
+```php
+use function Workflow\{activity, sideEffect};
+use Exception;
+use Workflow\SignalMethod;
+use Workflow\Workflow;
+
+class MyWorkflow extends Workflow
+{
+    private bool $cancelled = false;
+
+    #[SignalMethod]
+    public function cancel()
+    {
+        $this->cancelled = true;
+    }
+
+    public function execute()
+    {
+        while (true) {
+            yield activity(MyActivity::class);
+
+            if (yield sideEffect(fn () => $this->cancelled)) {
+                throw new Exception('Workflow cancelled by signal.');
+            }
+        }
+    }
+```
+
+This keeps control flow replay-safe and avoids non-deterministic branching during signal handling.