Kotlin 2.0 K2 Coroutine Scope Disposal and Structured Concurrency

--- description: Kotlin 2.0 K2 Coroutine Scope Disposal and Structured Concurrency - Enforces strict structured concurrency in Jetpack Compose and ViewModel architectures under Kotlin 2.0 K2. Mandates explicit scope lifecycle management, prevents orphaned jobs across recompositions, enforces safe StateFlow sharing with SharingStarted.WhileSubscribed(5000), and eliminates GlobalScope and unconstrained CoroutineScope leaks. globs: **/*.kt, **/*.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kotlin-k2-coroutine-scope-lifecycle-invariants" --- # Kotlin 2.0 K2 Coroutine Scope Disposal and Structured Concurrency > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Job Spawning, GlobalScope Leaks, and Active Flow Upstreams in Dead ViewModels or Detached Composables ## System Constraints You are a Principal Android Architect enforcing strict structured concurrency under Kotlin 2.0 (K2 compiler). Reject any code that bypasses lifecycle-aware scopes, risks memory leaks via unconstrained CoroutineScope instances, neglects the 5-second WhileSubscribed buffer on state flows, or launches unmanaged jobs inside Composable functions. ## Strict Guidelines - Engineers MUST ALWAYS use `viewModelScope` for ViewModel operations and bound Composable scopes (`LaunchedEffect`, `rememberCoroutineScope`) for UI-driven effects. - Engineers MUST NOT instantiate unmanaged `CoroutineScope(Dispatchers.Main)` or use `GlobalScope` anywhere in application or library code. - Code SHOULD ALWAYS use `SharingStarted.WhileSubscribed(5_000)` when converting cold flows to `StateFlow` via `stateIn` to withstand configuration changes without leaking upstream collection. - Services MUST cancel and join active child jobs explicitly using cooperative cancellation (`ensureActive()` or `yield()`) inside long-running loops. - Components NEVER trigger side effects via `CoroutineScope.launch` during initial Composable execution; engineers MUST route all composition-bound asynchronous jobs through `LaunchedEffect(key)`. ## Bad vs Good Implementations ### ViewModel StateFlow Sharing and Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: GlobalScope causes unbounded memory leaks and prevents cancellation when the screen is dismissed. SharingStarted.Eagerly keeps the upstream database or network stream active perpetually, draining battery and memory. ```kotlin class UserViewModel(private val repository: UserRepository) : ViewModel() { // ANTI-PATTERN: Eagerly started or Lazily started StateFlow leaks upstream flow // when ViewModel is backgrounded or Composable is not collecting. // GlobalScope causes orphaned jobs that bypass ViewModel lifecycle. val uiState: StateFlow<UserState> = repository.observeUser() .stateIn( scope = GlobalScope, started = SharingStarted.Eagerly, initialValue = UserState.Loading ) fun refresh() { // Unmanaged CoroutineScope ignores ViewModel onCleared cancellation CoroutineScope(Dispatchers.IO).launch { repository.fetchRemoteUser() } } } ``` #### Production Standard (Correct) > **Standard**: Leverages viewModelScope for automatic cancellation during ViewModel teardown. Uses SharingStarted.WhileSubscribed(5_000) to allow a 5-second grace period across activity recreation (e.g., screen rotation) before stopping upstream emissions. ```kotlin class UserViewModel(private val repository: UserRepository) : ViewModel() { // PRODUCTION INVARIANT: Bound to viewModelScope with 5-second buffer // to survive configuration changes without restarting upstream cold flows. val uiState: StateFlow<UserState> = repository.observeUser() .stateIn( scope = viewModelScope, started = SharingStarted.WhileSubscribed(5_000), initialValue = UserState.Loading ) fun refresh() { // Bound to viewModelScope: Automatically cancelled when ViewModel is cleared viewModelScope.launch { repository.fetchRemoteUser() } } } ``` ### Composable Side-Effect Lifecycle Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling scope.launch directly inside the Composable function body triggers a new uncancelled coroutine on every single recomposition, resulting in race conditions and severe thread pool starvation. ```kotlin @Composable fun ProfileScreen(userId: String, viewModel: ProfileViewModel) { // ANTI-PATTERN: Leaking coroutines directly in composition body val scope = rememberCoroutineScope() scope.launch { // Executes on EVERY recomposition, causing duplicate concurrent jobs viewModel.trackScreenView(userId) } Text(text = "User: $userId") } ``` #### Production Standard (Correct) > **Standard**: LaunchedEffect binds the coroutine's lifecycle strictly to the composition. If userId changes or the Composable leaves the composition tree, the previous coroutine job is cancelled cooperatively. ```kotlin @Composable fun ProfileScreen(userId: String, viewModel: ProfileViewModel) { // PRODUCTION INVARIANT: LaunchedEffect cancels and relaunches automatically // when the key (userId) changes, and cancels immediately on exit from composition. LaunchedEffect(userId) { viewModel.trackScreenView(userId) } Text(text = "User: $userId") } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin 2.0 K2 Coroutine Scope Disposal and Structured Concurrency

Kotlin 2.0 K2 Coroutine Scope Disposal and Structured Concurrency defines an industrial-grade behavioral standard for mobile engineering. Enforces strict structured concurrency in Jetpack Compose and ViewModel architectures under Kotlin 2.0 K2. Mandates explicit scope lifecycle management, prevents orphaned jobs across recompositions, enforces safe StateFlow sharing with SharingStarted.WhileSubscribed(5000), and eliminates GlobalScope and unconstrained CoroutineScope leaks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded Job Spawning, GlobalScope Leaks, and Active Flow Upstreams in Dead ViewModels or Detached Composables Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded Job Spawning, GlobalScope Leaks, and Active Flow Upstreams in Dead ViewModels or Detached Composables	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS use `viewModelScope` for ViewModel operations and bound Composable scopes (`LaunchedEffect`, `rememberCoroutineScope`) for UI-driven effects.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.