durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/constraints/structural-limits.md

@@ -19,6 +19,7 @@ Structural limits cap the resource consumption of a single workflow run. When an
 | `payload_size_bytes` | 2 MiB | Serialized size of a single argument payload |
 | `memo_size_bytes` | 256 KiB | Serialized size of non-indexed memo metadata |
 | `search_attribute_size_bytes` | 40 KiB | Serialized size of indexed search-attribute metadata |
+| `history_transaction_size` | 5,000 | History events produced by a single workflow task execution |
 
 All limits are enforced at the point of scheduling or recording. A value of `0` disables the check for that limit kind.
 
@@ -39,6 +40,7 @@ Override any limit through `workflows.v2.structural_limits` in your config or vi
         'payload_size_bytes' => (int) env('WORKFLOW_V2_LIMIT_PAYLOAD_SIZE_BYTES', 2097152),
         'memo_size_bytes' => (int) env('WORKFLOW_V2_LIMIT_MEMO_SIZE_BYTES', 262144),
         'search_attribute_size_bytes' => (int) env('WORKFLOW_V2_LIMIT_SEARCH_ATTRIBUTE_SIZE_BYTES', 40960),
+        'history_transaction_size' => (int) env('WORKFLOW_V2_LIMIT_HISTORY_TRANSACTION_SIZE', 5000),
     ],
 ],
 ```
@@ -101,6 +103,27 @@ activity(ProcessDocumentActivity::class, $ref);
 
 When a workflow upserts memo entries via `upsertMemo()`, the executor merges the new entries into the existing memo map, then JSON-encodes the merged result and checks the byte length against `memo_size_bytes`. If the merged memo exceeds the limit, the run fails before the memo is persisted.
 
+### History transaction size
+
+Each workflow task execution (a single "turn" of replay and forward progress) may produce new history events — activity scheduling, timer creation, side-effect recording, search-attribute upserts, and so on. The `history_transaction_size` limit caps the total number of new events a single task can produce.
+
+This catches runaway loops that create unbounded events in a single task without yielding control:
+
+```php
+// If a workflow schedules thousands of operations in one task,
+// the history transaction limit prevents the task from growing
+// without bound. Process large batches in bounded chunks instead.
+foreach (array_chunk($items, 500) as $chunk) {
+    $calls = [];
+    foreach ($chunk as $item) {
+        $calls[] = startActivity(ProcessItemActivity::class, $item);
+    }
+    all($calls);  // Each chunk is a separate task execution
+}
+```
+
+The check runs at the top of each iteration of the executor's main loop. Events created during replay (reading existing history) do not count toward the limit — only new events written during the current task contribute.
+
 ### Search attribute size
 
 When a workflow upserts search attributes via `upsertSearchAttributes()`, the executor merges the new attributes into the existing set, then JSON-encodes the merged result and checks the byte length against `search_attribute_size_bytes`. If the merged attributes exceed the limit, the run fails before the attributes are persisted.
@@ -133,7 +156,8 @@ The current structural limits configuration is included in the v2 health check s
     "command_batch_size": 1000,
     "payload_size_bytes": 2097152,
     "memo_size_bytes": 262144,
-    "search_attribute_size_bytes": 40960
+    "search_attribute_size_bytes": 40960,
+    "history_transaction_size": 5000
   }
 }
 ```

docs/failures-and-recovery.md

@@ -85,7 +85,7 @@ Every failure recorded by the engine carries a `failure_category` that classifie
 | Timeout | `timeout` | Failure caused by a timeout expiration — enforced by the engine when a workflow execution or run deadline passes. |
 | Task Failure | `task_failure` | Workflow-task execution failure such as replay errors, determinism violations, or invalid command shapes. |
 | Internal | `internal` | Server or infrastructure failure (database, queue, worker crash). |
-| Structural Limit | `structural_limit` | Failure caused by exceeding a structural limit (payload size, pending fan-out count, command batch size, metadata size). See [Structural Limits](./constraints/structural-limits.md). |
+| Structural Limit | `structural_limit` | Failure caused by exceeding a structural limit (payload size, pending fan-out count, command batch size, metadata size, history transaction size). See [Structural Limits](./constraints/structural-limits.md). |
 
 The category is determined automatically when the failure is recorded:
 
@@ -146,6 +146,44 @@ The retry task records `retry_of_task_id`, `retry_after_attempt_id`, `retry_afte
 
 `Workflow\Exceptions\NonRetryableExceptionContract` still short-circuits the retry policy: throwing a non-retryable exception fails the activity execution immediately and resumes the workflow with the exception.
 
+## Workflow-Level Retry
+
+Durable Workflow v2 does **not** support automatic workflow-level retry. When a workflow run fails — whether from an unhandled exception, a structural limit, or a timeout — the run is terminal. The engine does not automatically start a new run of the same workflow instance.
+
+This is an intentional design choice:
+
+- **Activities already have retry.** Activity retry policies with configurable `$tries`, `backoff()`, and non-retryable exceptions handle transient failures at the right granularity.
+- **Workflow replay is the recovery primitive.** If a workflow task encounters a transient infrastructure failure (database error, worker crash), the durable task system re-dispatches the task, and replay resumes from committed history — no new run needed.
+- **Continue-as-new handles long-lived workflows.** Workflows that need fresh state or history compaction use `continueAsNew()` as an explicit workflow-level restart.
+- **Repair handles stuck runs.** The `repair()` command and automatic worker-loop repair recover runs where durable task transport was lost.
+
+If your application needs workflow-level retry semantics, model them explicitly:
+
+```php
+class RetryableWorkflow extends Workflow
+{
+    public function handle(string $orderId): void
+    {
+        try {
+            activity(ProcessOrderActivity::class, $orderId);
+        } catch (Throwable $e) {
+            // Record the failure, then start a new workflow
+            // for retry-at-workflow-level scenarios.
+            activity(NotifyFailureActivity::class, $orderId, $e->getMessage());
+        }
+    }
+}
+```
+
+## Reset (Reserved)
+
+The `reset` operation is reserved for a future release. Reset is distinct from `repair`:
+
+- **Repair** recreates missing durable transport (task rows, execution rows) so a stuck run can resume from its committed history. It does not discard any recorded progress.
+- **Reset** would discard committed progress beyond a chosen history point and re-execute the workflow from that earlier state. This requires careful handling of already-started activities, child workflows, and timers.
+
+Until reset ships, the supported recovery path for a workflow that has made incorrect progress is: fix the underlying issue, deploy the corrected code, and let replay or repair resume the run. For terminal runs, start a new workflow instance with the corrected logic.
+
 ## Task Recovery
 
 The engine separates workflow truth from queue delivery. Durable task rows stay authoritative even if a queue publish is missed or a worker dies after leasing a task.