Clarify Python retry and timeout scopes

Issue: zorporation/durable-workflow#490

Loop-ID: build-01

Author: durable-workflow-ops

README.md

@@ -54,6 +54,17 @@ For a fuller deployable example, see
 [`examples/order_processing`](examples/order_processing), which runs a
 multi-activity order workflow against a local server with Docker Compose.
 
+## Retry policy scopes
+
+Retry and timeout settings are scoped to the layer where you configure them:
+
+- `TransportRetryPolicy` on `Client(...)` retries SDK HTTP requests only. It handles transient connection failures, request timeouts, 5xx responses, and 429 rate limits. It does not retry workflow code, activity code, child workflows, or failed workflow runs.
+- `ActivityRetryPolicy` on `ctx.schedule_activity(...)` is recorded into durable history with that activity command. It controls server-side attempts for that one activity execution.
+- `ChildWorkflowRetryPolicy` on `ctx.start_child_workflow(...)` is recorded with that child-start command. It controls server-side attempts for that child workflow execution.
+- `non_retryable_error_types` belongs to durable activity/child retry policies. `non_retryable=True` on an activity failure bypasses the activity retry budget and surfaces the failure to the workflow.
+
+Timeout names are also layer-specific. `start_to_close_timeout` limits one activity attempt, `schedule_to_start_timeout` limits queue wait before an activity starts, `schedule_to_close_timeout` limits the whole activity execution including retries, and `heartbeat_timeout` limits the gap between activity heartbeats. For child workflows, `execution_timeout_seconds` covers the overall child workflow execution and `run_timeout_seconds` covers one run.
+
 ## Activity retries and timeouts
 
 Configure per-call activity retries and deadlines from workflow code:

docs/index.md

@@ -21,7 +21,7 @@ pip install 'durable-workflow[prometheus]'
 - **[Workflow](reference/workflow.md)** — workflow-side primitives: `ActivityRetryPolicy`, `ChildWorkflowRetryPolicy`, `ContinueAsNew`, `StartChildWorkflow`, signal/query/update decorators, and query-state replay helpers.
 - **[Activity](reference/activity.md)** — activity decorator and execution context.
 - **[Errors](reference/errors.md)** — typed exceptions raised by the client and worker.
-- **[Retry policy](reference/retry_policy.md)** — HTTP transport retry configuration for the client.
+- **[Retry policy](reference/retry_policy.md)** — HTTP transport retry configuration for the client. Durable activity and child workflow retry policies are workflow primitives, not transport settings.
 - **[Metrics](reference/metrics.md)** — pluggable recorders, including a Prometheus adapter.
 - **[Serializer](reference/serializer.md)** — payload encoding and decoding helpers.
 - **[Sync helpers](reference/sync.md)** — blocking wrappers around the async client for scripts and tests.

docs/reference/retry_policy.md

@@ -1,3 +1,17 @@
 # Retry policy
 
+`TransportRetryPolicy` is the client HTTP retry policy. It retries transient
+network/request failures while talking to the Durable Workflow server; it does
+not retry workflow runs, workflow tasks, activities, child workflows, or user
+code.
+
+Durable retry budgets live on workflow commands instead:
+
+- `ActivityRetryPolicy` with `ctx.schedule_activity(...)` controls attempts for
+  one activity execution.
+- `ChildWorkflowRetryPolicy` with `ctx.start_child_workflow(...)` controls
+  attempts for one child workflow execution.
+- Activity timeout fields and child workflow timeout fields are server-side
+  durable budgets, not SDK HTTP request timeouts.
+
 ::: durable_workflow.retry_policy

docs/reference/workflow.md

@@ -1,3 +1,8 @@
 # Workflow
 
+Workflow retry and timeout settings are durable command budgets. Use
+`ActivityRetryPolicy` on `ctx.schedule_activity(...)` for activity attempts and
+`ChildWorkflowRetryPolicy` on `ctx.start_child_workflow(...)` for child workflow
+attempts. Use `TransportRetryPolicy` only for client HTTP retries.
+
 ::: durable_workflow.workflow

src/durable_workflow/retry_policy.py

@@ -32,6 +32,13 @@ class TransportRetryPolicy:
     timeouts, 5xx server errors, 429 rate limit). Does not retry client
     errors (4xx except 429).
 
+    This policy runs inside :class:`~durable_workflow.Client` around HTTP
+    requests. It does not retry workflow runs, workflow tasks, activity
+    executions, child workflows, or any user code. Configure durable activity
+    retries with :class:`durable_workflow.workflow.ActivityRetryPolicy` and
+    child workflow retries with
+    :class:`durable_workflow.workflow.ChildWorkflowRetryPolicy`.
+
     Uses exponential backoff with jitter to avoid thundering herd.
     """
 

src/durable_workflow/workflow.py

@@ -169,7 +169,12 @@ class ActivityRetryPolicy:
 
     The policy is snapped onto the durable activity execution when the
     workflow task completes, so later code deploys do not change the retry
-    budget for an already-scheduled activity.
+    budget for an already-scheduled activity. It is a server-side durable
+    retry policy, not the SDK HTTP transport retry policy.
+
+    ``non_retryable_error_types`` names failure types that should bypass this
+    retry budget. An activity worker can also report ``non_retryable=True`` on
+    a failure to stop retrying that activity execution.
     """
 
     max_attempts: int = 3
@@ -249,15 +254,28 @@ def _payload_warning_context(
 
 @dataclass
 class ChildWorkflowRetryPolicy(ActivityRetryPolicy):
-    """Retry policy applied to one started child workflow call."""
+    """Retry policy applied to one started child workflow call.
+
+    This is recorded with the child workflow command and controls durable
+    server-side child attempts. It is separate from SDK HTTP transport retry
+    and from activity retry.
+    """
 
 
 ChildWorkflowRetryPolicyInput = ChildWorkflowRetryPolicy | ActivityRetryPolicy | Mapping[str, Any]
 
 
 @dataclass
 class ScheduleActivity:
-    """Command requesting an activity task."""
+    """Command requesting an activity task.
+
+    Timeout fields are activity budgets, not HTTP request timeouts:
+    ``start_to_close_timeout`` limits one activity attempt,
+    ``schedule_to_start_timeout`` limits queue wait before an attempt starts,
+    ``schedule_to_close_timeout`` limits the whole activity execution including
+    retries, and ``heartbeat_timeout`` limits the gap between activity
+    heartbeats.
+    """
 
     activity_type: str
     arguments: list[Any]
@@ -512,7 +530,12 @@ def to_server_command(
 
 @dataclass
 class StartChildWorkflow:
-    """Command requesting a child workflow run."""
+    """Command requesting a child workflow run.
+
+    ``execution_timeout_seconds`` limits the overall child workflow execution.
+    ``run_timeout_seconds`` limits one child run. These budgets are durable
+    server-side workflow budgets and are separate from client HTTP timeouts.
+    """
 
     workflow_type: str
     arguments: list[Any] = field(default_factory=list)