docs(operations): use typed 2.x errors and add StepContext.attempt for Python

docs/sdk-reference/languages/python/index.md

@@ -37,3 +37,22 @@ The SDK provides decorators to mark functions as durable:
     `callback_id` and `WaitForCallbackContext`.
 
 The Python SDK uses synchronous methods and does not support `await`.
+
+## 2.x Upgrade
+
+When upgrading from `1.x` to `2.x`, review the Python SDK migration guide in the
+[SDK repository](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/docs/migration-1.x-to-2.x.md).
+The main changes are:
+
+- Catch the typed, per-operation errors `StepError`, `InvokeError`,
+    `ChildContextError`, and `WaitForConditionError` (or the base
+    `DurableOperationError`) instead of the removed `CallableRuntimeError`.
+- Replace `except CallableRuntimeError` after `BatchResult.throw_if_error()` with
+    `ChildContextError`, `SerDesError`, and `BatchCompletionError`.
+- Catch serialization failures as `SerDesError` (a direct child of
+    `DurableExecutionsError`) instead of `ExecutionError`.
+- Expect the first-run serialize/deserialize round trip for `step`, child contexts,
+    `map`/`parallel`, and `wait_for_condition`, and ensure `wait_for_condition`
+    `initial_state` is serializable by the configured serdes.
+- Read the new `attempt` field on `StepContext` and `WaitForConditionCheckContext`, and
+    pass `attempt` when constructing those contexts directly in tests.

docs/sdk-reference/operations/child-context.md

@@ -78,8 +78,8 @@ multiple child contexts concurrently.
 
     **Returns:** `T`, the return value of `func`.
 
-    **Raises:** `CallableRuntimeError` wrapping the original exception if the child context
-    function raises.
+    **Raises:** `ChildContextError` (a `DurableOperationError` subclass) wrapping the
+    original exception if the child context function raises.
 
 === "Java"
 
@@ -154,12 +154,13 @@ multiple child contexts concurrently.
 
     - `serdes` (optional) Custom `SerDes` for the child context result. See
         [Serialization](../state/serialization.md).
-    - `item_serdes` (optional) Custom `SerDes` for individual items within the child
-        context.
     - `sub_type` (optional) An internal subtype identifier. Used by `map` and `parallel`
         internally; not needed for direct use.
     - `summary_generator` (optional) A function that generates a compact summary when the
         result exceeds the checkpoint size limit. Used internally by `map` and `parallel`.
+    - `is_virtual` (optional) When `True`, skips checkpointing for the child context and
+        propagates the parent's ID to its operations. Used internally by `map` and
+        `parallel` for flat nesting; not needed for direct use.
 
 === "Java"
 

docs/sdk-reference/operations/invoke.md

@@ -127,7 +127,8 @@ When this function runs:
 
     **Returns:** `R`, the return value of the invoked function.
 
-    **Raises:** `CallableRuntimeError` if the invoked function fails or times out.
+    **Raises:** `InvokeError` (a `DurableOperationError` subclass) if the invoked function
+    fails, times out, or is stopped.
 
 === "Java"
 

docs/sdk-reference/operations/step.md

@@ -81,8 +81,10 @@ The step will checkpoint the last error after exhausting all retry attempts.
 
     **Returns:** `T`, the return value of `func`.
 
-    **Raises:** `CallableRuntimeError` wrapping the original exception after retries are
-    exhausted. `StepInterruptedError` if an at-most-once step was interrupted.
+    **Raises:** `StepError` (a `DurableOperationError` subclass) wrapping the original
+    exception after retries are exhausted. An at-most-once step interrupted before it
+    checkpointed also surfaces as `StepError`, with `error_type` recording
+    `StepInterruptedError`. A permanent serializer failure raises `SerDesError`.
 
 === "Java"
 
@@ -229,10 +231,12 @@ The step will checkpoint the last error after exhausting all retry attempts.
     @dataclass(frozen=True)
     class StepContext:
         logger: LoggerInterface
+        attempt: int          # current attempt, 1-based
     ```
 
     - `logger` A logger enriched with execution context metadata. See
         [Logging](../observability/logging.md).
+    - `attempt` The current attempt number, starting at 1 for the first execution.
 
 === "Java"
 

examples/python/operations/child-contexts/child-config-signature.py

@@ -1,6 +1,6 @@
 @dataclass(frozen=True)
 class ChildConfig(Generic[T]):
     serdes: SerDes | None = None
-    item_serdes: SerDes | None = None
     sub_type: OperationSubType | None = None
     summary_generator: SummaryGenerator | None = None
+    is_virtual: bool = False

examples/python/operations/invoke/handle-invocation-error.py

@@ -1,5 +1,4 @@
-from aws_durable_execution_sdk_python import DurableContext, durable_execution
-from aws_durable_execution_sdk_python.exceptions import CallableRuntimeError
+from aws_durable_execution_sdk_python import DurableContext, InvokeError, durable_execution
 
 
 @durable_execution
@@ -11,5 +10,5 @@ def handler(event: dict, context: DurableContext) -> dict:
             name="process-payment",
         )
         return {"status": "success", "result": result}
-    except CallableRuntimeError as e:
+    except InvokeError as e:
         return {"status": "failed", "reason": str(e)}