Docs/migration 1x to 2x

[ayushiahjolia]

Issue #, if available: N/A

Description of changes:
Migration guide for python v2

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Claude AI review

Documentation-only PR: a new docs/migration-1.x-to-2.x.md migration guide and an expanded WaitForConditionConfig docstring in packages/aws-durable-execution-sdk-python/src/aws_durable_execution_sdk_python/waits.py.

I verified the guide's technical claims against the source rather than reviewing runtime behavior, since inaccurate migration docs would misdirect users:

• Error hierarchy / exports — DurableOperationError base, StepError/InvokeError/ChildContextError/WaitForConditionError, graded CallbackError subtypes, SerDesError (child of DurableExecutionsError), RetryableSerDesError (retryable InvocationError); all root exports match __init__.py __all__.
• __cause__ — raise_as_operation_error reconstructs a DurableOperationError stand-in (registry fallback to base for non-SDK types) on both first run and replay; the guide's claim is accurate.
• First-run round trip — confirmed in step.py, child.py, wait_for_condition.py; invoke.py does not round-trip, matching "invoke unaffected."
• wait_for_condition — initial_state round-tripped before first check; empty-string payload treated as no stored state, restarting from initial_state.
• wait_for_callback serdes — enclosing child context uses default extended-type serdes, distinct from WaitForCallbackConfig.serdes.
• Completion predicate / BatchResult — should_complete, complete_batch/continue_batch, BatchCompletionError (only CUSTOM_COMPLETION_FAILED), throw_if_error typed raises, and fail-fast map/parallel defaults all match.
• attempt field — required no-default field on StepContext and WaitForConditionCheckContext.
• Removed names — CallableRuntimeError, WaitDecision, ItemBatcher, WaitStrategyConfig.timeout*, etc. confirmed absent.

No inaccurate statements or broken examples found. No actionable findings.

Residual test risk: the guide's code snippets and rg helpers are not covered by doctests/CI, so future API drift wouldn't be caught automatically — acceptable for a docs-only change. Separately (out of scope, not in this diff): the pre-existing DurableOperationError docstring at packages/aws-durable-execution-sdk-python/src/aws_durable_execution_sdk_python/exceptions.py:268-269 states the escaping error "is preserved as __cause__ on the first run," which contradicts the actual reconstruction behavior the new guide correctly documents.

Reviewed commit 6c1c23fe6206a4982795f437c0e251941292116b. Workflow run

[yaythomas]

"what you must do" reads demanding. Suggest "what to do", matching the tone of the section headings.

[yaythomas]

The ChainedInvoke* enums (added per #655 (comment)) are not batching names, so this heading mislabels them. "Removed 1.x-only names" would cover everything in the section.

[github-actions]

Codex AI review · Finding arf_v1_6jzq2y7mwo2cthuq7sg6t3i467

P1 — Document that RetryableSerDesError replays the whole invocation. This does not retry only serialization: executors re-raise it before a success checkpoint, so backend re-invocation can re-run an AT_LEAST_ONCE_PER_RETRY step and repeat its side effects; an at-most-once step instead follows interrupted-step retry handling. Saying only “(retries)” can introduce duplicate writes during migration. Explain the invocation-level replay and its idempotency/step-semantics implications.

[github-actions]

Codex AI review · Finding arf_v1_y7lkshfplubrflac5c4etrgbk3

P2 — Scope exhaustion behavior to the built-in strategy. WaitForConditionConfig has no max_attempts; only a strategy produced by create_wait_strategy(WaitStrategyConfig(...)) raises on exhaustion. A custom strategy can continue indefinitely unless it enforces its own limit, so the current wording may leave migrated workflows polling forever.

Suggested change

	### `wait_for_condition` raises on exhaustion
	It raises `WaitForConditionError` when it exhausts `max_attempts`.
	Catch `WaitForConditionError` instead of inspecting the returned state.
	### `create_wait_strategy` raises on exhaustion
	A strategy created by `create_wait_strategy(WaitStrategyConfig(...))` raises
	`WaitForConditionError` when it exhausts `max_attempts`; custom wait strategies
	must enforce their own limit.
	Catch `WaitForConditionError` instead of inspecting the returned state.

[github-actions]

Codex AI review · Finding arf_v1_o4c23apyh45544dfpujfjo2fi7

P2 — Preserve the documented manual callback API. context.create_callback() still returns a public Callback whose .result() waits for completion. The absolute statement that there is no callback.result() can cause users of manual callback flows to remove the required wait; restrict this statement to the value returned by wait_for_callback().

Suggested change

	`context.wait_for_callback(...)` returns the payload directly and raises the
	callback error from the call itself (there is no `callback.result()`):
	`context.wait_for_callback(...)` returns the payload directly, so do not call
	`.result()` on that return value. The separate `context.create_callback()` API still
	returns a callback whose `.result()` waits for completion:

[github-actions]

Codex AI review

Found three migration-guide issues: one replay-safety omission and two misleading API descriptions.

Reviewed commit ea3ae4884dcd84d9c1d47eb03121c61c437f7f6e. Workflow run

[zhongkechen]

max_concurrency behavior changed. Seems we didn't mention it