Deprecating the ambiguous GraceContext function

[danielorbach]

The L.GraceContext() function exposes a context that cancels during graceful shutdown, creating an unorthodox branch in the context tree that confuses component authors. Users must choose between L.Context() and L.GraceContext() for every blocking operation, with no clear guidance about which to prefer. This decision point appears throughout component code, particularly in receive loops and blocking calls.

The design creates a two-tier context hierarchy where the grace context cancels first (during graceful shutdown) and the main context cancels second (during forced termination). While this seemed elegant initially, it violates the principle that context trees should flow naturally from parent to child. Component authors find themselves reasoning about which context represents "the right level" for their particular blocking operation, a mental model that doesn't match standard Go context patterns.

Consider a component receiving messages from a subscription. Should sub.Receive() use GraceContext() or Context()? The former allows graceful shutdown to interrupt the receive, while the latter continues receiving until forced termination. Neither choice is obviously correct, and the decision depends on subtle requirements about shutdown behavior. This ambiguity spreads throughout the codebase, with different components making different choices based on individual interpretations.

The real issue is that we're encoding shutdown policy into context selection rather than providing explicit signals. Component authors need clear answers to two questions: Am I being asked to stop gracefully? Am I being forced to stop immediately? These are distinct signals that shouldn't be conflated into context hierarchy. A better API would expose both signals explicitly, allowing components to react appropriately without reasoning about context cancellation order.

Acceptance Criteria

• GraceContext() is deprecated with clear migration guidance
• Alternative API is proposed that provides explicit graceful/forced termination signals
• Documentation explains the problems with context branching and the new approach
• Example components demonstrate proper handling of both shutdown modes
• Migration guide shows how to convert existing GraceContext() usage