[andystaples]

Warning

Do not merge this PR, or any other PR in this stack, on its own. The stack was split out of the closed #293 to make review easier. Once every PR in the stack is approved, the whole stack will be squash-merged together.

Stack layer 2/6, built on the coroutine dispatch layer (#357).

Summary

This layer adds general asyncio composition and durable timers to the replay-safe event loop that coroutine orchestrators run on.

Task composition

• Adds _DurableAsyncTask. A task is retired once its result or exception has been observed, so replaying discarded gather batches and handled failures does not keep decoded payloads or tracebacks alive.
• Tasks hash by creation sequence. TaskGroup iterates a set of tasks to cancel them, so this keeps cancellation order independent of memory addresses; the reason is documented in code.
• Cancellation callbacks run in a deterministic order, keyed by when each task was created. Retired tasks never reuse that ordering.
• TaskGroup, gather, wait_for, and asyncio.timeout compose over durable work:
  • Cancelling a local waiter does not cancel the underlying shared durable operation.
  • The actions emitted when a TaskGroup is cancelled stay the same across replays.
• A waiter finalized after the dispatch has closed (for example, an asyncio.Task constructed directly rather than through asyncio.create_task) no longer raises during garbage collection. Directly constructed tasks are documented as unsupported.

Durable timers

• call_later and call_at are backed by durable timers and return _DurableTimerHandle, which compares by identity.
• Deadlines are rounded up to the next microsecond, so a timer never fires before the loop's deadline. Timezone-aware orchestration clocks are normalized.
• Deadlines already in the past run immediately, and non-finite delays raise an error.
• Cancelling a handle cancels its durable timer.
• asyncio.sleep and timeouts use the existing chunking for long timers.

Unsupported work

• Every asyncio loop API the durable loop does not implement (executors, cross-thread scheduling, sockets, pipes, subprocesses, readers/writers, signal handlers, TLS, sendfile, task factories, exception handlers, and loop lifecycle) fails through one table with an actionable error, instead of a bare NotImplementedError.
• asyncio.wait and asyncio.as_completed are not rejected at run time; the contract documents them as unsupported because their ordering is not replay-stable.

Docs (docs/async-orchestrators.md)

• States that successive dispatches can run on different workers and that all workers processing an instance must use the pinned environment.
• Notes that delays below the resolution of loop.time() are effectively zero, and that tasks must be created with asyncio.create_task or a task group.

Code docs

• Extends the list of private asyncio hooks in the asyncio_loop.py module docstring, and clarifies the Task.wait() docstring for asyncio.create_task and task groups.

Scope

Left for later layers

• Dispatch teardown, async-generator hooks, the cleanup quiescence limit, and the cleanup error policy belong to layer 3/6 ([Async stack 3/6] Dispatch cleanup for coroutine orchestrators #360). This layer keeps the minimal close() from layer 1/6, extended only to release the new timer and cancellation state.
• Orchestrators still receive the eager OrchestrationContext. The cold AsyncOrchestrationContext arrives in layer 4/6 ([Async stack 4/6] Add cold async orchestration context #361), which updates these tests to use it.
• No changelog changes; release notes are added in layer 6/6 ([Async stack 6/6] Document coroutine orchestrators and add Managed compatibility tests #364).

Tests

• Adds tests/durabletask/test_asyncio_orchestrators.py, covering:
  • composition
  • memory retirement
  • shared-wait cancellation
  • timers
  • unsupported work, including every unimplemented loop API
  • fanout scaling