Deterministic Teardown of KMP Coroutine Flows on Swift Task Cancellation

Bridging Kotlin Multiplatform (KMP) Flows into Swift Concurrency AsyncSequences or Task scopes requires deterministic lifecycle propagation. Unbridged or naively wrapped KMP flows leak background Kotlin Job coroutines and platform resources on iOS when the parent Swift Task is cancelled. All boundary adapters must register cooperative cancellation handlers using withTaskCancellationHandler or SKIE/KMP-NativeCoroutines lifecycle primitives to cancel underlying Job subscriptions immediately.

--- description: Deterministic Teardown of KMP Coroutine Flows on Swift Task Cancellation - Bridging Kotlin Multiplatform (KMP) Flows into Swift Concurrency AsyncSequences or Task scopes requires deterministic lifecycle propagation. Unbridged or naively wrapped KMP flows leak background Kotlin Job coroutines and platform resources on iOS when the parent Swift Task is cancelled. All boundary adapters must register cooperative cancellation handlers using withTaskCancellationHandler or SKIE/KMP-NativeCoroutines lifecycle primitives to cancel underlying Job subscriptions immediately. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt, **/*FlowAdapters.swift, **/*Bridge.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-flow-swift-task-cancellation-boundary" --- # Deterministic Teardown of KMP Coroutine Flows on Swift Task Cancellation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Swift AsyncStream Consumption Leaking Kotlin Coroutine Jobs on Task Cancellation ## System Constraints You are a Principal Mobile Architect enforcing rock-solid concurrency interop between Kotlin Multiplatform Coroutine Flows and Swift Structured Concurrency. Mandate deterministic cancellation propagation across the ObjC/Swift bridge so that parent Swift Task cancellations immediately tear down underlying Kotlin Jobs. ## Strict Guidelines - Engineers MUST ALWAYS tie the lifespan of an exported Kotlin Coroutine Job or SKIE/KMP-NativeCoroutines Task directly to the lifecycle of the consumer Swift Task. - Engineers MUST NOT rely on unmonitored AsyncStream.Continuation alone without binding `continuation.onTermination` to explicit Kotlin `Closeable.close()` or `Job.cancel()` handles. - Swift adapters bridging Kotlin Flows MUST use `withTaskCancellationHandler` or equivalent low-level primitives to propagate `Task.isCancelled` into `job.cancel(cause: nil)` deterministically. - Kotlin-side export APIs SHOULD expose a explicit `Cancellable` or `Disposable` handle returning type (e.g., Ktor/SKIE `Task<T>` or custom `JobDisposable`) rather than bare callback delegates with untracked Job scopes. - Shared KMP view models exposing Flows to iOS MUST NEVER launch collection in an unbounded `GlobalScope` or detached iOS-native root Scope without an explicit teardown trigger invoked during Swift view dismissal (`onDisappear` / `deinit`). ## Bad vs Good Implementations ### Naive AsyncStream Bridge Leaking Kotlin Job vs Deterministic Task Cancellation Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin's collect invocation starts a coroutine under the hood or delegates via Objective-C runtime callbacks. The standard AsyncStream closure does not register an onTermination callback or hook into Swift's cancellation signals. When the parent Swift Task is cancelled, the Kotlin Flow collection continues executing in background thread pools, leaking network sockets, memory, and engine resources. ```swift import Shared // ANTI-PATTERN: Collecting KMP Flow into Swift AsyncStream without binding cancellation. // When consumer Task is cancelled or the view deallocates, the Kotlin coroutine continues indefinitely. func observeDeviceTelemetry(repository: TelemetryRepository) -> AsyncStream<TelemetryData> { return AsyncStream { continuation in repository.deviceTelemetryFlow.collect { continuation.yield($0) } completionHandler: { error in continuation.finish() } } } // Usage in SwiftUI / Swift Concurrency Task: func startMonitoring(repository: TelemetryRepository) -> Task<Void, Never> { return Task { for await data in observeDeviceTelemetry(repository: repository) { process(data) } // Cancelling this Task will NOT stop repository.deviceTelemetryFlow! } } ``` #### Production Standard (Correct) > **Standard**: The production implementation wraps the Kotlin Flow collector and captures the returned `CancellableHandle`. It attaches to `continuation.onTermination`, ensuring that whether the Swift consumer Task is explicitly cancelled, times out, or finishes normally, the underlying Kotlin coroutine Job is immediately cancelled via `dispose()`. ```swift import Shared // PRODUCTION FIX: Deterministic cancellation boundary mapping Swift Task -> Kotlin Job/Closeable. func observeDeviceTelemetry(repository: TelemetryRepository) -> AsyncThrowingStream<TelemetryData, Error> { return AsyncThrowingStream { continuation in var cancellableHandle: CancellableHandle? cancellableHandle = repository.watchDeviceTelemetry( onEach: { data in continuation.yield(data) }, onCompletion: { error in if let error = error { continuation.finish(throwing: error) } else { continuation.finish() } } ) continuation.onTermination = { @Sendable termination in switch termination { case .cancelled, .finished: // Explicit deterministic teardown of KMP Coroutine Job cancellableHandle?.dispose() @unknown default: cancellableHandle?.dispose() } } } } // Direct Task boundary with withTaskCancellationHandler func consumeTelemetrySafely(repository: TelemetryRepository) async throws { let stream = observeDeviceTelemetry(repository: repository) try await withTaskCancellationHandler { for try await item in stream { try Task.checkCancellation() process(item) } } onCancel: { // Cancellation signal propagates synchronously to stream subscribers } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Teardown of KMP Coroutine Flows on Swift Task Cancellation

Deterministic Teardown of KMP Coroutine Flows on Swift Task Cancellation defines an industrial-grade behavioral standard for mobile engineering. Bridging Kotlin Multiplatform (KMP) Flows into Swift Concurrency AsyncSequences or Task scopes requires deterministic lifecycle propagation. Unbridged or naively wrapped KMP flows leak background Kotlin Job coroutines and platform resources on iOS when the parent Swift Task is cancelled. All boundary adapters must register cooperative cancellation handlers using withTaskCancellationHandler or SKIE/KMP-NativeCoroutines lifecycle primitives to cancel underlying Job subscriptions immediately. 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 Swift AsyncStream Consumption Leaking Kotlin Coroutine Jobs on Task Cancellation 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 Swift AsyncStream Consumption Leaking Kotlin Coroutine Jobs on Task Cancellation	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 tie the lifespan of an exported Kotlin Coroutine Job or SKIE/KMP-NativeCoroutines Task directly to the lifecycle of the consumer Swift Task.

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.