feat: async/await as cooperative coroutines (Phase 1) + lazy itertools.islice

[ivarvong]

Why

TODO.txt's audit ranked async/await as Tier-1 #1 — the single largest blocker for LLM-emitted code, since modern FastAPI handlers and agent loops are `async def` by default and one such function blew up Pyex at parse time. Lazy `itertools.islice` was Tier-1 #6 — a flagship correctness gap given the README's generators-as-continuations framing (`list(islice(infinite_gen, 5))` used to time out).

Constraint

Pyex is a pure function on the BEAM. No spawning, no global state, no `Process.*` (the `BannedCallTracer` checks every CI build). The runtime doesn't own concurrency on the tenant's behalf — the host application does. So whatever "async" looks like, it can't reach for BEAM processes inside Pyex itself.

Decision

Coroutines as tagged sync functions, driven by a synchronous trampoline.

• The `:function` pyvalue grew a `kind` field (`:sync` | `:async`) — a single discriminator instead of a parallel `:async_function` tag that would have required N parallel pattern-match clauses across attribute lookup, bound-method construction, callable?, repr, etc.
• Calling an async function binds parameters and returns a `:coroutine` value without running the body. `await` and `asyncio.run` drive that coroutine via `Pyex.Interpreter.Invocation.drive_coroutine/3`.
• Async generators (`async def` + `yield`) ride the existing `:lazy_iter` machinery, so FastAPI streaming patterns work transparently.
• Strict on shape — `await 42` and `asyncio.run(99)` raise CPython-shaped TypeError. The error message includes a hint about the most common LLM mistake (forgetting to call the async function).

This trades fan-out parallelism for simplicity and determinism. Same answer as CPython, sequential wall-clock when fan-out matters. Phase 2 territory: a host-driven trampoline that lets the Elixir application actually overlap awaitable capabilities (HTTP, DB) as real BEAM Tasks. The wire shape for that lives in the divergence tests, not in speculative API.

What ships

```python
import asyncio

async def fetch(user_id):
return {"id": user_id, "name": "Ada"}

async def handler(req):
user = await fetch(req)
return user

asyncio.run(handler(42))

{'id': 42, 'name': 'Ada'}

```

• Parser: `async def`, `async for`, `async with`, `await` (at unary precedence)
• Interpreter: kind-aware dispatch, strict await, bound-method routing for async instance / static / class methods
• `asyncio` module: `run`, `gather`, `sleep`, `create_task`, `ensure_future`, `wait_for`, `iscoroutine`, `iscoroutinefunction`
• Real `Task` value with `.result()` / `.done()` / `.cancel()` / `.exception()`
• `gather(return_exceptions=True)` returns real exception instances (not strings) so `isinstance(r, ValueError)` works
• Async generators via the existing lazy_iter machinery
• 52 conformance tests in `test/pyex/async_conformance_test.exs`

Phase 1 divergences from CPython (pinned in tests)

• `gather` is sequential, not interleaved at await points
• `create_task` drives eagerly rather than scheduling
• Nested `asyncio.run` is silently allowed (CPython errors)
• Async list comprehensions (`[x async for x in g()]`) not yet parsed

Each is a real test that demonstrates the divergence rather than asserting behavior identical to CPython. When a future Phase 2 changes any of these, the corresponding test will flip — exactly the signal we want.

Bonus: lazy `itertools.islice`

Independent fix shipped as the first commit. `islice` over an infinite generator used to time out because the iterator was materialized into a list before the builtin ran. Fixed by registering `islice` in the no-drain set and converting it to an `:islice_call` signal evaluated by a bounded-step iterator handler. Same shape extends naturally to `takewhile`/`dropwhile`/`filterfalse` if those become load-bearing.

Commits

• `itertools.islice: stop cleanly on infinite generators` — independent fix
• `refactor: add :sync | :async kind discriminator to function values` — pure prep, no behavior change (5295 tests pass before/after)
• `feat: async/await as cooperative coroutines` — the substance
• `test: async conformance suite (52 tests, sharp coverage)` — including pinned divergences
• `docs: README, TODO, CHANGELOG for async/await + islice`

Test plan

• `mix format --check-formatted` clean
• `mix compile --warnings-as-errors` clean
• `mix test` — 5344 tests, 0 failures, 2 skipped
• `mix dialyzer` — 41 errors / 41 skipped (baseline unchanged)
• Phase 1 divergence tests demonstrate real divergences, not CPython-identical behavior
• `asyncio.run` strict on non-coroutine input
• `await` strict on non-awaitable input
• `gather(return_exceptions=True)` returns real exception instances (`isinstance(r, ValueError)` works)
• `Task.done()`/`.result()`/`.cancel()`/`.exception()` work
• Async methods (instance, @staticmethod, @classmethod, subclass override)
• `async for` over sync iterables and async generators
• FastAPI-shaped async handler round-trip

🤖 Generated with Claude Code