[andystaples]

Warning

Neither this PR nor any other PR in this stack should be merged on its own. The whole stack will be squash-merged once every PR in it is approved.

This is the contract-documentation layer (0/6) of a review-only stack that splits the closed #293. The APIs documented here are implemented in later layers; this PR changes documentation only. Later layers extend docs/async-orchestrators.md as they implement each area, and the final version of the contract is in #364.

• Explain the motivation (Support async/await orchestrators across the Python SDK packages #294), goals, non-goals, and alternatives considered for native coroutine orchestrators.
• Define native coroutine authoring across the core SDK, Azure Managed, and Azure Functions, including supported asyncio composition, cold operations versus reusable eager handles, and how orchestrators are classified as async or generator at registration.
• Specify ownership, cancellation, timeout, and dispatch-teardown behavior, including the limits of cancelling already-issued remote work.
• Establish deterministic replay constraints, unsupported I/O/composition APIs (asyncio.wait / asyncio.as_completed are documented as unsupported), and migration and Python-runtime compatibility limits, including keeping the Python minor version fixed for in-flight instances (Document Python runtime compatibility and safe upgrade guidance for durable orchestrations #337).

Differences from #293

The stack is roughly 800 lines larger than #293, mostly from hardening:

• A dedicated dispatch-local loop module (durabletask/internal/asyncio_loop.py).
• Cycle detection when classifying wrapped orchestrator callables.
• Skipping entity lock-release scheduling during async dispatch cleanup.
• An Any-typed overload for async sub-orchestration calls without return_type.
• Additional replay, cleanup, and typing tests.

[Copilot]

🟡 Changes recommended

The documentation incorrectly implies synchronous commands are awaitable, which can cause a TypeError after scheduling an action; it should explicitly state that these commands must be called without await.

1 open issue

• Document synchronous commands as calls without await · New

What changed in this PR

This documentation-only PR defines the async orchestrator contract for the core SDK, Azure Managed, and Azure Functions. It establishes behavior that later layers of the review-only stack will implement.

Changes:

• Describe coroutine authoring, cold operations, reusable handles, and Functions compatibility.
• Specify deterministic asyncio composition, cancellation, timeouts, and dispatch cleanup.
• Document replay migration constraints and Python-runtime compatibility limits.

File	Description
docs/​supported-patterns.md	Connects durable patterns to async authoring and clarifies root cancellation behavior.
docs/​features.md	Introduces coroutine orchestrators alongside generator orchestrators.
docs/​async-orchestrators.md	Defines the cross-package async contract and replay constraints.

_{Review effort: Balanced}

[andystaples]

Open question (resolve before merge): should async orchestrators ship as preview?

This change adds async orchestrators without a preview or experimental label. Two things could still change after release:

• The public surface: the cold AsyncOrchestrationContext versus eager handles via as_task_context().
• Replay behavior that depends on the Python minor version (Document Python runtime compatibility and safe upgrade guidance for durable orchestrations #337): Python 3.11 and 3.12+ record different histories for asyncio.wait_for.

Should core and durabletask.azuremanaged label async orchestrators as preview in the docs and changelogs until those settle, or ship them as generally available? Please answer and resolve this thread before the stack merges.