Deprecating ambiguous lifecycle cleanup functions

[danielorbach]

The lifecycle cleanup API currently offers four distinct functions: Cleanup, CleanupError, CleanupContext, and CleanupBackground. While this appears to provide flexibility, it creates confusion about which function to use and why. The most problematic member is CleanupContext, which passes the lifecycle's context to cleanup functions despite that context being cancelled at termination time.

The ambiguity stems from the question: what context should cleanup operations use? The lifecycle's context is almost always cancelled when cleanup runs, making CleanupContext unreliable for operations that need a valid context. This led to the creation of CleanupBackground, which sidesteps the issue by using context.Background(). However, neither solution is ideal. Background contexts lose tracing information and cancellation signals that might be useful during graceful shutdown.

Component authors face a decision tree every time they register cleanup: Does this cleanup need a context? If yes, will the lifecycle context work or do I need background? Can I handle the context being cancelled? These questions shouldn't exist. The API should guide users toward correct patterns rather than exposing implementation details about context lifecycle.

The proliferation of cleanup variants reflects an API that evolved reactively rather than being designed holistically. We need to step back and consider what cleanup operations actually need: the ability to run cleanup logic, optionally handle errors, and occasionally access a context that's guaranteed to be valid during the cleanup phase. A redesigned API should make the common case simple while still supporting the full range of cleanup scenarios.

Acceptance Criteria

• All cleanup functions are reviewed for ambiguity and design flaws
• CleanupContext is deprecated with clear migration guidance
• Alternative API is proposed that handles context requirements correctly
• Documentation explains when and why to use each cleanup variant
• Existing usage throughout the codebase is audited and updated