move idempotency patterns to patterns.md

references/core/patterns.md

@@ -259,6 +259,75 @@ This will enable the Activity to be retried exactly on the set interval.
 
 **Advantage:**  Individual Activity retries are not recorded in Workflow History, so this approach can poll for a very long time without affecting the history size.
 
+## Idempotency Patterns
+
+**Purpose**: Ensure activities can be safely retried and replayed without causing duplicate side effects.
+
+**Why It Matters**: Temporal may re-execute activities during retries (on failure) or replay (on worker restart). Without idempotency, this can cause duplicate charges, duplicate emails, duplicate database entries, etc.
+
+### Using Idempotency Keys
+
+Pass a unique identifier to external services so they can detect and deduplicate repeated requests:
+
+```
+Activity: charge_payment(order_id, amount)
+    │
+    └── Call payment API with:
+            amount: $100
+            idempotency_key: "order-{order_id}"
+        │
+        └── Payment provider deduplicates based on key
+            (second call with same key returns original result)
+```
+
+**Good idempotency key sources**:
+- Workflow ID (unique per workflow execution)
+- Business identifier (order ID, transaction ID)
+- Workflow ID + activity name + attempt number
+
+### Check-Before-Act Pattern
+
+Query the external system's state before making changes:
+
+```
+Activity: send_welcome_email(user_id)
+    │
+    ├── Check: Has welcome email been sent for user_id?
+    │   │
+    │   ├── YES: Return early (already done)
+    │   │
+    │   └── NO: Send email, mark as sent
+```
+
+### Designing Idempotent Activities
+
+1. **Use unique identifiers** as idempotency keys with external APIs
+2. **Check before acting**: Query current state before making changes
+3. **Make operations repeatable**: Ensure calling twice produces the same result
+4. **Record outcomes**: Store transaction IDs or results for verification
+5. **Leverage external system features**: Many APIs (Stripe, AWS, etc.) have built-in idempotency key support
+
+### Tracking State in Workflows
+
+For complex multi-step operations, track completion status in workflow state:
+
+```
+Workflow State:
+    payment_completed: false
+    shipment_created: false
+
+Run:
+    if not payment_completed:
+        charge_payment(...)
+        payment_completed = true
+
+    if not shipment_created:
+        create_shipment(...)
+        shipment_created = true
+```
+
+This ensures that on replay, already-completed steps are skipped.
+
 ## Choosing Between Patterns
 
 | Need | Pattern |
@@ -271,3 +340,4 @@ This will enable the Activity to be retried exactly on the set interval.
 | Rollback on failure | Saga |
 | Process items concurrently | Parallel Execution |
 | Long-lived stateful entity | Entity Workflow |
+| Safe retries/replays | Idempotency |

references/python/error-handling.md

@@ -119,57 +119,6 @@ class MyWorkflow:
 
 **Note:** Do not use `non_retryable=` with `ApplicationError` inside a worklow (as opposed to an activity).
 
-## Idempotency Patterns
-
-When Activities interact with external systems, making them idempotent ensures correctness during retries and replay.
-
-### Using Workflow IDs as Idempotency Keys
-
-```python
-from temporalio import activity
-
-@activity.defn
-async def charge_payment(order_id: str, amount: float) -> str:
-    # Use order_id as idempotency key with payment provider
-    result = await payment_api.charge(
-        amount=amount,
-        idempotency_key=f"order-{order_id}",  # Prevents duplicate charges
-    )
-    return result.transaction_id
-```
-
-### Tracking Operation Status in Workflow State
-
-```python
-from datetime import timedelta
-from temporalio import workflow
-
-@workflow.defn
-class OrderWorkflow:
-    def __init__(self):
-        self._payment_completed = False
-        self._transaction_id: str | None = None
-
-    @workflow.run
-    async def run(self, order: Order) -> str:
-        if not self._payment_completed:
-            self._transaction_id = await workflow.execute_activity(
-                charge_payment, order.id, order.total,
-                start_to_close_timeout=timedelta(minutes=5),
-            )
-            self._payment_completed = True
-
-        # Continue with order processing...
-        return self._transaction_id
-```
-
-### Designing Idempotent Activities
-
-1. **Use unique identifiers** as idempotency keys (workflow ID, activity ID, or business ID)
-2. **Check before acting**: Query external system state before making changes
-3. **Make operations repeatable**: Ensure calling twice produces the same result
-4. **Record outcomes**: Store transaction IDs or results for verification
-
 ## Best Practices
 
 1. Use specific error types for different failure modes