[andystaples]

Summary

Implements the coordinated async authoring contract discussed in #294 across durabletask, durabletask.azuremanaged, and azure-functions-durable. Existing synchronous generator orchestrators remain supported. This stays one draft PR and one customer-facing release unit; it must not be merged as a partial feature.

Shared runtime and supported contract

• Native async def orchestrators and nested helpers await existing durable activities, timers, external events, sub-orchestrations, combinators, and supported entity operations. Generator/coroutine parents and children interoperate. Functions supports native two-argument and compatibility single-argument entry points.
• A dispatch-local AbstractEventLoop supplies native asyncio Task/Future semantics and FIFO scheduling on top of the existing history/retry/payload/entity engine, not a separate provider runtime. Each history completion resumes its ready branches immediately, rather than waiting for a whole batch.
• Ordered asyncio.gather, local tasks/futures, ready callbacks, and sleep(0) are supported. loop.time() uses the durable clock; call_at/call_later create durable timers, including asyncio.sleep, wait_for, and Python 3.11+ timeout/timeout_at.
• Python 3.11+ TaskGroup, and the actual AnyIO asyncio task-group/cancel-scope/shielded-cleanup/fail_after paths, use native task semantics. Task-group cancellation wakeups are sorted by task creation rather than object hashes. gather fails fast without cancelling siblings; durable when_all retains wait-all behavior.
• Local waiter cancellation does not cancel a durable activity, child, entity operation or event subscription, and does not undo external side effects. An unhandled root-coroutine cancellation fails deterministically with TaskCancelledError; scheduler termination remains a client operation.

The full supported contract and migration guidance are in docs/async-orchestrators.md.

Lifecycle and current-main integration

The branch integrates current main, including the dispatch-finalization/exceptional-exit behavior from #300, #303, #306 and #307. The response and entity-release obligations are captured before teardown. Local tasks are cancelled/drained, nested cooperative finalizers and async context managers run, and tracked async generators are closed. New durable work is rejected during teardown. Ordinary cleanup errors and unobserved background-task errors are reported without changing the decided response; unexpected BaseException exits retain the existing failure/recovery policy. Cleanup is bounded, and one cleanup failure does not hide other task errors.

Tests exercise suspension, termination, continue-as-new, history failure, cancellation, action ordering, retries, long/tiny timers, shared waiters, outer event-loop restoration, payload behavior, and generator regressions. Cleanup at a dispatch boundary is explicitly not workflow cancellation or a durable compensation boundary.

Real framework proof

Checked Tamir's integration branch; its head still matches reviewed snapshot 8e9ae67a492171b7839a94f72ff44238f03d597a. The SDK proof uses an actual Pydantic AI Agent.run, deterministic TestModel, and its parallel-tool AnyIO path, covering success, recorded tool failure, and repeated identical-history replay without paid model calls. The agent runs directly inside the orchestrator without an adapter event loop, trampoline, or batch-wide join.

The small proof adapter deliberately retains ordinary model/tool activities, registration, JSON codecs, stable IDs/deadline clock, and canonicalization of volatile framework message metadata. This is not a production Pydantic adapter or blanket compatibility promise. The test-only framework dependency is conditional on Python 3.11+; no framework dependency was added to the shipped SDK.

Deliberate exclusions and limitations

• No local/virtual activities, arbitrary-await interception, or automatic checkpointing of helper return values. Helpers rerun during replay; is_replaying is not result recording.
• No general external I/O, threads, executors, subprocesses, custom/eager task factories, or cross-thread scheduling inside orchestrators. Common detectable violations raise actionable errors; not all unsafe operations can be detected.
• asyncio.wait and as_completed were explicitly investigated and are not deterministic supported composition APIs because of unordered sets/hash-dependent task creation and tie ordering. Successful execution alone is not support.
• No blanket asyncio/AnyIO/library compatibility. Activities remain at least once and need appropriate idempotency/deduplication.
• Generator-to-coroutine migration of in-flight instances requires preserving IDs/order, names, payloads, timers/retries/events and entity releases; sequential parity is not blanket migration safety.
• Functions' mock orchestrator_generator_wrapper handles direct durable awaits, not simulation of the asyncio scheduler.

Validation

Final implementation head: 8c050a7c1ca11b0372151592151f8776796e4485. Local evidence (overlapping suites, not an additive total):

• Full core run with Azurite: 1,511 passed, 3 skipped.
• Focused asyncio/coroutine/Pydantic regressions: 55 passed on Python 3.14; 51 passed, 4 skipped on Python 3.10 (version-gated framework/TaskGroup APIs).
• Azure Managed service-free suite: 192 passed; DTS emulator suite: 86 passed, 1 skipped. Final mixed-style gather/durable-timer emulator probes: 2 passed.
• Functions unit suite: 420 passed. Full real Functions-host E2E suite: 86 passed, 6 skipped in each payload-typing mode, default and strict.
• Repository-standard strict Pyright checks pass for core/Azure Managed and Functions with zero errors/warnings. Package source/tests Flake8, changed-document Markdown lint, and diff checks pass.

All final-head CI checks pass, including:

• Core Linux Python 3.10–3.15 and Windows async/replay/lifecycle Python 3.10–3.15.
• Azure Managed/DTS Linux Python 3.10–3.15.
• Functions Python 3.13–3.15 units and real-host E2E in both payload modes.
• Strict typing, lint and CodeQL.

Deployed Azure cloud-service validation has not been performed. Reported skips remain visible in the test results; green CI is not a blanket claim of arbitrary library or migration compatibility.

Release coordination

All three affected changelogs and entry-point documentation are updated. Package versions and dependency minimums are unchanged. The PR remains draft for review as requested. Nothing has been merged or released. Once the full contract is approved, publish core first through the coordinated release process and update provider minimums/versions in the dedicated release PR so resolvers cannot select an incompatible core.