durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/defining-workflows/starting-workflows.md

@@ -75,6 +75,46 @@ Visibility labels are exact-match strings for operator filtering in Waterline, n
 
 `memo` is JSON-like metadata for selected-run detail and history export, not a list-filter or run-summary search field. Top-level and nested memo object keys must be non-empty strings up to 64 characters, and memo values may be scalars, `null`, arrays, or nested objects.
 
+### Search Attributes
+
+Search attributes are indexed scalar metadata for operator filtering and fleet visibility. Unlike memo, search attributes are surfaced in run list views and can be used for visibility filtering in Waterline:
+
+```php
+$workflow->start(
+    $orderId,
+    StartOptions::withVisibility(
+        businessKey: 'order-123',
+        labels: ['tenant' => 'acme'],
+    )->withSearchAttributes([
+        'priority' => 'high',
+        'status' => 'pending',
+        'amount' => '99.50',
+    ]),
+);
+```
+
+Search attribute keys follow the same rules as visibility label keys: letters, numbers, `.`, `_`, `-`, and `:`, up to 64 characters. Values must be scalars or `null`. Boolean values are cast to `"1"` or `"0"`, and `null` values are silently dropped. Empty string values after casting are also dropped.
+
+Search attributes can be upserted during workflow execution using `upsertSearchAttributes()`, which merges the new attributes into the existing set.
+
+### Execution and Run Timeouts
+
+`StartOptions` also supports execution-level and run-level timeouts:
+
+```php
+$workflow->start(
+    $orderId,
+    (new StartOptions())
+        ->withExecutionTimeout(86400)  // 24 hours across all runs
+        ->withRunTimeout(3600),        // 1 hour per individual run
+);
+```
+
+- **Execution timeout** spans the entire workflow instance lifecycle, including retries and continue-as-new runs. Once the execution deadline passes, the engine will not schedule further workflow tasks.
+- **Run timeout** applies to the current run only. It resets when a workflow continues as new.
+
+Both timeouts must be at least 1 second. Pass `null` (the default) to leave the timeout unlimited.
+
 ## Workflow Type
 
 The durable `workflow_type` for that instance comes from either:

docs/testing.md

@@ -230,6 +230,96 @@ WorkflowStub::assertUpdateSent(
 );
 ```
 
+### Testing Start Outcomes and Duplicate-Start Policy
+
+Use `attemptStart()` to verify duplicate-start behavior without throwing exceptions. The `StartResult` exposes typed outcome helpers:
+
+```php
+use Workflow\V2\StartOptions;
+use Workflow\V2\WorkflowStub;
+
+public function testRejectDuplicateStart(): void
+{
+    WorkflowStub::fake();
+    WorkflowStub::mock(MyActivity::class, 'result');
+
+    $workflow = WorkflowStub::make(MyWorkflow::class, 'order-123');
+
+    $first = $workflow->start('Taylor');
+    $this->assertTrue($first->startedNew());
+
+    $second = WorkflowStub::load('order-123');
+    $duplicate = $second->attemptStart('Taylor');
+
+    $this->assertTrue($duplicate->rejected());
+    $this->assertTrue($duplicate->rejectedDuplicate());
+    $this->assertSame('instance_already_started', $duplicate->rejectionReason());
+}
+```
+
+To test the return-existing-active policy, pass `StartOptions::returnExistingActive()`:
+
+```php
+public function testReturnExistingActiveStart(): void
+{
+    WorkflowStub::fake();
+
+    $workflow = WorkflowStub::make(MySignalWorkflow::class, 'order-123');
+    $workflow->start();
+
+    $this->assertSame('waiting', $workflow->refresh()->status());
+
+    $second = WorkflowStub::load('order-123');
+    $result = $second->attemptStart(StartOptions::returnExistingActive());
+
+    $this->assertTrue($result->accepted());
+    $this->assertTrue($result->returnedExistingActive());
+    $this->assertSame($workflow->runId(), $result->runId());
+}
+```
+
+Both policies record durable command and history events, so you can also assert on `WorkflowCommand` and `WorkflowHistoryEvent` rows for deeper verification.
+
+### Testing History Budget
+
+The `HistoryBudget` fields (`history_event_count`, `history_size_bytes`, `continue_as_new_recommended`) are surfaced on the run summary projection and are available through the `RunDetailView`. In your workflow code, the `Workflow` base class exposes these as `$this->historyEventCount()`, `$this->historySizeBytes()`, and `$this->continueAsNewRecommended()`:
+
+```php
+use Workflow\V2\Workflow;
+
+final class LongRunningWorkflow extends Workflow
+{
+    public function handle(): void
+    {
+        while (true) {
+            // ... process work ...
+
+            if ($this->continueAsNewRecommended()) {
+                $this->continueAsNew($this->carryForwardState());
+            }
+        }
+    }
+}
+```
+
+To test history budget thresholds, configure the thresholds low and verify the recommendation:
+
+```php
+public function testHistoryBudgetRecommendsContinueAsNew(): void
+{
+    config()->set('workflows.v2.history_budget.continue_as_new_event_threshold', 5);
+
+    WorkflowStub::fake();
+
+    // Run a workflow that produces enough history events to trip the threshold
+    $workflow = WorkflowStub::make(ManyActivitiesWorkflow::class, 'budget-test');
+    $workflow->start();
+
+    $summary = $workflow->summary();
+    $this->assertTrue($summary->continue_as_new_recommended);
+}
+```
+
 ## Legacy `Workflow\WorkflowStub`
 
 ### Workflows