compiler(coro): lower static child awaits and root factories

[cpunion]

Summary

• retain canonical explicit coroutine roots in the whole-program plan and plan digest
• add PhysicalABIV1 / SchedulerChildAwaitABIV0 lifecycle identities and task-aware frame hooks
• lower one closed static CallDirect + DirectCoro call as a stackless child handoff
• emit a typed (g, out, startup) -> handle factory only for explicit AsyncDemand roots
• retain root descriptors and their factories through final-link dead stripping with llvm.used
• preserve the existing v0 ABI, hooks, header state, and fail-closed diagnostics unchanged

The generated parent evaluates arguments left-to-right, creates the child only through its initial suspend, publishes the parent/child relationship, calls __llgo_coro_await_prepare_v1, and suspends. Generated Go code never directly resumes or destroys the child; those operations remain scheduler-owned.

Scope

This is an ABI/lowering slice, not a runnable scheduler. It remains opt-in and fail-closed for CFG/recursion, dynamic calls, spawn, park, preemption, channel/select, defer/panic, methods/closures/generics, aggregate results, and main/init bootstrap. The next slice will add the explicit descriptor registry, frame registry, root bootstrap, and deterministic single-P scheduler.

Validation

• LLVM 19, 21, and 22: SSA coroutine helpers, child-await lowering, root factories, pre/post-CoroSplit
• native64 and wasm32 descriptor layout/alignment
• v0 header-state regression
• llvm.used, GlobalDCE, object retention, and manual Darwin -dead_strip / Linux --gc-sections final-link checks
• go test -race ./internal/coro
• full go test ./ssa and go test ./internal/build
• coroutine workflow vet commands

The local full go test ./cl still reports pre-existing Go 1.26 float-format golden differences; the same failure reproduces on the Phase 9 base and is unrelated to this diff.

LLVM 22 binding baseline: cpunion/llvm#4 (merged), upstream xgo-dev/llvm#43 (all checks green, awaiting approval).

Progresses xgo-dev#1546.

[gemini-code-assist]

Code Review

This pull request implements the first scheduler handoff slice for the experimental LLVM coroutine physical ABI, enabling a physical coroutine to await a statically resolved coroutine child (ordinary child await) and generating typed factories and descriptors for explicit async roots. It introduces the EnableCoroChildAwait configuration, upgrades the physical ABI version to V1, adds task-aware frame allocation/free hooks, and implements child-await lowering and explicit async root factory emission. The review feedback identifies critical opportunities to prevent potential nil pointer dereferences by adding defensive nil checks for p.compilation.CoroPlan in both tryCompileCoroStaticAwait and emitCoroRootFactory before accessing its fields.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.