Document await signal waits

Author: durable-workflow-ops

docs/features/concurrency.md

@@ -6,7 +6,7 @@ import ConcurrencySimulator from '@site/src/components/ConcurrencySimulator';
 
 # Concurrency
 
-In `Workflow\V2`, named workflows use straight-line helpers inside an ordinary `handle()` method: `activity()`, `signal()`, `timer()`, `sideEffect()`, `getVersion()`, and the other single-step helpers suspend directly under the hood instead of forcing `yield` into every workflow body. Named v2 workflows are straight-line only, so do not `yield` from the workflow body.
+In `Workflow\V2`, named workflows use straight-line helpers inside an ordinary `handle()` method: `activity()`, `await()`, `timer()`, `sideEffect()`, `getVersion()`, and the other single-step helpers suspend directly under the hood instead of forcing `yield` into every workflow body. Use `await('signal-name')` for one named signal value. Named v2 workflows are straight-line only, so do not `yield` from the workflow body.
 
 Parallel barriers still suspend as one durable workflow step through `all([...])`. In straight-line workflows, build those barriers with closures such as `fn () => activity(...)` and `fn () => child(...)` so the runtime can see the full barrier tree before the workflow suspends. Results still come back in the original nested array shape, while Waterline keeps each durable leaf wait visible and uses `parallel_group_path` to show which outer and inner barriers that leaf belongs to.
 
@@ -101,7 +101,7 @@ In that example, Waterline exposes three open leaf waits, not one synthetic "nes
 
 ## Async Callback
 
-`async(...)` runs a serializable callback as a durable child workflow with the system type `durable-workflow.async`. Async callbacks use the same straight-line-only helper contract as named v2 workflows, so `activity()`, `signal()`, `timer()`, `sideEffect()`, and the other single-step helpers suspend directly inside the callback body without forcing `yield`.
+`async(...)` runs a serializable callback as a durable child workflow with the system type `durable-workflow.async`. Async callbacks use the same straight-line-only helper contract as named v2 workflows, so `activity()`, `await()`, `timer()`, `sideEffect()`, and the other single-step helpers suspend directly inside the callback body without forcing `yield`.
 
 ```php
 use function Workflow\V2\{activity, async};
@@ -125,7 +125,7 @@ final class CustomerWorkflow extends Workflow
 }
 ```
 
-The parent run sees the callback as a child wait, so command history, lineage, and Waterline detail use the same `child_call_id`, child run id, and child outcome history as an explicit `child(...)` call. The callback is serialized with Laravel's serializable-closure support, so keep it app-local and deployment-local. Use a named `child(SomeWorkflow::class, ...)` call when the work needs a stable public workflow type for cross-service routing or long-lived code evolution. `async(...)` callbacks are now straight-line only in v2, so call helpers like `activity()`, `child()`, `signal()`, `timer()`, and `all([...])` directly without `yield`.
+The parent run sees the callback as a child wait, so command history, lineage, and Waterline detail use the same `child_call_id`, child run id, and child outcome history as an explicit `child(...)` call. The callback is serialized with Laravel's serializable-closure support, so keep it app-local and deployment-local. Use a named `child(SomeWorkflow::class, ...)` call when the work needs a stable public workflow type for cross-service routing or long-lived code evolution. `async(...)` callbacks are now straight-line only in v2, so call helpers like `activity()`, `child()`, `await()`, `timer()`, and `all([...])` directly without `yield`.
 
 ## Mixed Activity + Child Barriers
 

docs/features/queries.md

@@ -15,7 +15,7 @@ Queries replay committed history for the current selected run and then invoke th
 ```php
 use Workflow\QueryMethod;
 use Workflow\V2\Workflow;
-use function Workflow\V2\signal;
+use function Workflow\V2\await;
 
 final class ApprovalWorkflow extends Workflow
 {
@@ -25,7 +25,7 @@ final class ApprovalWorkflow extends Workflow
     {
         $this->stage = 'waiting-for-approval';
 
-        signal('approved-by');
+        await('approved-by');
 
         $this->stage = 'approved';
     }

docs/features/side-effects.md

@@ -7,7 +7,7 @@ sidebar_position: 5
 A side effect is a closure containing non-deterministic code. The closure is only executed once and the result is saved. It will not execute again if the workflow is retried. Instead, it will return the saved result. This makes the workflow deterministic because replaying the workflow will always return the same stored value rather than re-running the non-deterministic code.
 
 ```php
-use function Workflow\V2\signal;
+use function Workflow\V2\await;
 use function Workflow\V2\sideEffect;
 use Workflow\V2\Attributes\Signal;
 use Workflow\V2\Workflow;
@@ -18,7 +18,7 @@ class MyWorkflow extends Workflow
     public function handle(): array
     {
         $token = sideEffect(fn () => random_int(1000, 9999));
-        $finish = signal('finish');
+        $finish = await('finish');
 
         return compact('token', 'finish');
     }

docs/features/signal+timer.md

@@ -4,7 +4,7 @@ sidebar_position: 4
 
 # Signal + Timer
 
-`Workflow\V2` supports `await($condition, timeout: $seconds, conditionKey: $key)` for timeout-backed condition waits.
+`Workflow\V2` supports both `await($condition, timeout: $seconds, conditionKey: $key)` for timeout-backed condition waits and `await('signal-name', timeout: $seconds)` for timeout-backed named signal waits.
 
 Use it when the workflow should continue as soon as some durable replayed state becomes true, but should also unblock after a deadline if that state never changes.
 
@@ -68,4 +68,4 @@ $workflow->markReady();
 
 The return value is `true` when the condition becomes true before the timeout task fires and `false` when the timeout wins.
 
-If you want to wait for one named signal value directly instead of waiting for a local predicate, keep using `signal('name')`. `Workflow\V2` does not use legacy `#[SignalMethod]` mutator methods to flip workflow state.
+For named signals, `await('name', timeout: minutes(5))` returns the signal payload when the signal arrives and `null` when the timeout wins. `null` is reserved for timeout: no-argument signals resolve to `true`, one argument resolves to that value, and multiple arguments resolve to an array. `Workflow\V2` does not use legacy `#[SignalMethod]` mutator methods to flip workflow state.

docs/features/signals.md

@@ -10,13 +10,13 @@ Signals allow you to trigger events in a workflow from outside the workflow. Thi
 
 ## Named Signal Waits
 
-A workflow calls `signal('signal-name')` directly. The next accepted signal command with that name resumes the run and returns a deterministic value to the suspended workflow.
+A workflow calls `await('signal-name')` directly. The next accepted signal command with that name resumes the run and returns a deterministic value to the suspended workflow.
 
 ```php
 use Workflow\V2\Attributes\Signal;
 use Workflow\V2\Attributes\Type;
 use Workflow\V2\Workflow;
-use function Workflow\V2\signal;
+use function Workflow\V2\await;
 
 #[Type('order-approval')]
 #[Signal('approved-by', [
@@ -26,7 +26,7 @@ final class OrderApprovalWorkflow extends Workflow
 {
     public function handle(): array
     {
-        $approvedBy = signal('approved-by');
+        $approvedBy = await('approved-by');
 
         return [
             'approved_by' => $approvedBy,
@@ -65,7 +65,7 @@ Signal behavior:
 - each named wait gets its own durable `signal_wait_id`, and buffered same-name signals keep that same id across `SignalReceived`, `SignalWaitOpened`, and `SignalApplied`
 - selected-run detail exposes those lifecycle rows as `signals[*]`, with `id`, `command_id`, `command_sequence`, `workflow_sequence`, `signal_wait_id`, status, outcome, validation errors, and stored arguments
 - when a declared signal contract exists, PHP, webhook, and Waterline signal intake all accept either positional arguments or a JSON or associative object of named arguments, and invalid requests reject as `rejected_invalid_arguments` with machine-readable `validation_errors` for missing arguments, unknown arguments, declared type mismatches, or nullability violations
-- when a signal has no declared parameter contract, `signal('approved-by')` still receives `true` when no arguments were sent, the single argument when one value was sent, or the full argument array when multiple values were sent; `attemptSignalWithArguments('name', ['key' => 'value'])` keeps treating that associative array as one payload value instead of guessing named arguments
+- when a signal has no declared parameter contract, `await('approved-by')` receives `true` when no arguments were sent, the single argument when one value was sent, or the full argument array when multiple values were sent; `attemptSignalWithArguments('name', ['key' => 'value'])` keeps treating that associative array as one payload value instead of guessing named arguments
 - before a signal is accepted, Waterline projects the run as `wait_kind = signal` and `liveness_state = waiting_for_signal`, which means it is waiting healthily for external input rather than needing repair
 - once a signal command is durably accepted, that external signal wait is resolved; Waterline should then show either the backing workflow task with `workflow_wait_kind = signal`, `workflow_signal_id`, `workflow_command_id`, the open wait id, and the `workflow_signal` resume source, or, if that task disappeared before `SignalApplied`, `repair_needed` with `wait_kind = signal`, `open_wait_id = signal-application:{signal_id}` when the lifecycle row exists, and the same metadata on the repaired task
 - repeated waits with the same signal name stay distinguishable in Waterline and the typed timeline through both the workflow step `sequence` and the durable `signal_wait_id`
@@ -90,7 +90,7 @@ The cursor is automatically managed by the engine during signal application and
 
 ## Condition Waits
 
-`await($condition, $conditionKey = null)` provides replay-safe condition waits. Use it when the predicate depends only on workflow state that was already derived from durable inputs such as updates, activity results, or child results. If you want one named external signal value directly, prefer `signal('name')`.
+`await($condition, $conditionKey = null)` provides replay-safe condition waits. Use it when the predicate depends only on workflow state that was already derived from durable inputs such as updates, activity results, or child results. If you want one named external signal value directly, call `await('name')`.
 
 Condition waits are driven by an update method instead of signal mutators:
 

docs/features/webhooks.md

@@ -606,7 +606,7 @@ POST /webhooks/instances/{workflowId}/runs/{runId}/signals/{signal}
 }
 ```
 
-The `arguments` field must be an array. When it is omitted, the signal resumes `signal(...)` with `true`.
+The `arguments` field must be an array. When it is omitted, a workflow waiting with `await('signal-name')` resumes with `true`.
 The targeted workflow class must also declare the signal name with `#[Workflow\V2\Attributes\Signal('...')]`; undeclared names are rejected durably instead of being buffered blindly.
 
 Signal example: