durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/features/child-workflows.md

@@ -197,7 +197,7 @@ $results = all([
 - The policy is recorded on the `workflow_links` row (`parent_close_policy`) and in the `ChildWorkflowScheduled` history event payload.
 - When the parent run closes for any reason, the engine queries open child links with a non-abandon policy and sends the appropriate command (cancel or terminate) to each open child.
 - If the child has already closed by the time the policy is enforced, no action is taken — the command is silently skipped.
-- Policy enforcement is best-effort: if a child command is rejected (e.g. the child is already terminal), the parent's closure is not affected.
+- Policy enforcement is best-effort: if a child command is rejected (e.g. the child is already terminal), the parent's closure is not affected. When enforcement succeeds, a `ParentClosePolicyApplied` history event is recorded on the parent run. When enforcement fails, a `ParentClosePolicyFailed` history event is recorded instead, so operators can distinguish successful enforcement from silent failures.
 - Continue-as-new does **not** trigger parent-close policy, because the workflow instance remains active under a new run.
 
 ### When to use each policy

docs/features/timeouts.md

@@ -104,6 +104,25 @@ When a workflow continues as new:
 
 This means the execution timeout always measures from the original start, while each new run gets its own fresh run-timeout window.
 
+## Enforcement
+
+Workflow-level timeouts are enforced at two points:
+
+1. **At workflow task start** — every workflow task checks `deadlineExpired()` before executing the workflow. If the deadline has passed, the run is immediately timed out.
+2. **By the TaskWatchdog** — the watchdog scans for non-terminal runs whose execution or run deadline has passed but that have no open workflow task. When found, it creates a deadline-expired workflow task and dispatches it, which triggers the timeout on the next task execution.
+
+When a timeout fires, the engine:
+
+- Cancels all open tasks (activity, timer, workflow) except the current one
+- Cancels all open activity executions with `ActivityCancelled` history events
+- Cancels all pending timers with `TimerCancelled` history events
+- Records a `WorkflowFailure` with `failure_category = timeout` and a `WorkflowTimeoutException`
+- Records a terminal `WorkflowTimedOut` history event with `timeout_kind` set to `execution_timeout` or `run_timeout`
+- Applies parent-close policy to any open child workflows
+- Notifies parent workflows if this was a child run
+
+The failure row stores `Workflow\V2\Exceptions\WorkflowTimeoutException` as the exception class, carrying the `timeout_kind` and the deadline timestamp for programmatic inspection.
+
 ## Activity timeouts
 
 Activity timeouts let you bound how long individual activity executions are allowed to take. There are four activity timeout scopes:

docs/features/timers.md

@@ -36,4 +36,14 @@ Timer behavior:
 - Waterline surfaces timer waits in run detail and dashboard payloads
 - engine-level `cancel()` and `terminate()` commands supersede open timer waits durably, and late timer jobs no-op instead of reopening the run
 
+### Transport chunking
+
+Some queue drivers impose a maximum delay on initial message delivery. For example, Amazon SQS caps `DelaySeconds` at 900 seconds (15 minutes). When a timer's duration exceeds the queue driver's limit, the engine automatically chunks the delay:
+
+1. The timer task is dispatched with the driver's maximum delay instead of the full duration.
+2. When the task arrives early (before `fire_at`), it re-releases itself with the remaining delay.
+3. This relay continues until the timer's actual fire time is reached.
+
+This is transparent to the workflow — the timer row still records the full duration and the correct `fire_at` timestamp. The chunking happens purely at the transport layer. For SQS, subsequent relay hops can use up to 43,200 seconds (12 hours) via `ChangeMessageVisibility`, so most timers complete in one or two hops.
+
 `sideEffect()` is available for replay-safe snapshots such as randomness or one-time branch inputs. A dedicated `Workflow\V2\now()` and unit-helper API is still evolving, so `timer()` remains the only time suspension helper today.