KMP Coroutine Cancellation and Memory Retention Swift-Interop Guardrail

--- description: KMP Coroutine Cancellation and Memory Retention Swift-Interop Guardrail - Enforces strict bidirectional cancellation propagation and memory lifecycle bridging between Kotlin Multiplatform Coroutine Jobs and Swift Concurrency Task trees. Prevents Objective-C ARC to Kotlin/Native GC retain cycles and unhandled Kotlin CancellationException panics escaping into Swift callers. globs: **/*.swift, **/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-coroutine-cancellation-swift-boundary" --- # KMP Coroutine Cancellation and Memory Retention Swift-Interop Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Kotlin Coroutine Jobs across the Swift-ObjC bridge and converting CancellationExceptions into fatal runtime errors ## System Constraints You are a Principal Mobile Architect enforcing strict Kotlin Multiplatform (KMP) and Swift Concurrency interop standards. Kotlin suspend functions and Flows exported via Objective-C bridges do not natively bind Swift Task cancellation to Kotlin Job cancellation unless explicitly wired via structured cancellation bridges (e.g., SKIE or custom C-pointer/Disposable patterns). You must ensure: (1) Swift Task cancellation propagates immediately to KMP coroutines via cancellation handlers; (2) CancellationException is caught and mapped strictly to Swift's CancellationError without invoking crash handlers; and (3) Closures bridging the ARC/GC boundary do not create cyclic strong references between Swift instances and Kotlin native objects. ## Strict Guidelines - Engineers MUST ALWAYS wrap raw Objective-C-exported Kotlin suspend calls in 'withTaskCancellationHandler' to explicitly invoke the Kotlin coroutine's cancellation handle upon Swift Task cancellation. - Engineers MUST NOT allow unhandled Kotlin 'kotlinx.coroutines.CancellationException' instances to cross the ObjC boundary as uncaught NSErrors; they MUST be re-thrown natively as Swift 'CancellationError()'. - Bridge adapters MUST capture Kotlin Job references weakly or clear them immediately upon termination to eliminate cross-runtime ARC-to-GC retention cycles. - Engineers MUST NOT rely on default Swift-async wrappers generated by Kotlin/Native compiler without verifying cooperative cancellation support or utilizing SKIE / KMP-NativeCoroutines compile-time plugins. - Swift AsyncSequences consuming KMP Flows MUST explicitly invoke flow collector disposal inside a 'defer' block or termination handler to cancel the upstream Kotlin CoroutineScope. ## Bad vs Good Implementations ### Bridging Swift Task cancellation to Kotlin suspending function handle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin/Native default ObjC bridge async methods do not observe Swift Task cancellation. The Kotlin Job keeps running, leaking network/CPU resources. If cancellation occurs, Kotlin's CancellationException surfaces as an unexpected NSError instead of Swift's cooperative CancellationError. ```swift // BAD: Direct async call generated by K/N ObjC export without cooperative cancellation or ARC safety func fetchUserData(userId: String) async throws -> UserProfile { // If the enclosing Swift Task is cancelled, the underlying KMP Coroutine continues running indefinitely. // A CancellationException from Kotlin may bubble up as an unhandled NSError or crash the runtime. return try await SharedRepositoryKt.fetchUserProfile(userId: userId) } ``` #### Production Standard (Correct) > **Standard**: Properly hooks into Swift's cooperative cancellation via withTaskCancellationHandler, invokes the Kotlin cancellation handle on cancellation, clears memory references across the runtime bridge, and re-throws Swift CancellationError instead of exposing native Kotlin exception internals. ```swift // GOOD: Structured Task cancellation handler with ARC safety and CancellationError remapping func fetchUserData(userId: String) async throws -> UserProfile { let cancellableHolder = AtomicReference<SharedCancellable?>(nil) return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in let handle = SharedRepositoryKt.fetchUserProfile(userId: userId) { profile, error in cancellableHolder.value = nil if let error = error { let nsError = error as NSError if nsError.isKotlinCancellationException { continuation.resume(throwing: CancellationError()) } else { continuation.resume(throwing: error) } } else if let profile = profile { continuation.resume(returning: profile) } } cancellableHolder.value = handle } } onCancel: { cancellableHolder.value?.cancel() cancellableHolder.value = nil } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Coroutine Cancellation and Memory Retention Swift-Interop Guardrail

KMP Coroutine Cancellation and Memory Retention Swift-Interop Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict bidirectional cancellation propagation and memory lifecycle bridging between Kotlin Multiplatform Coroutine Jobs and Swift Concurrency Task trees. Prevents Objective-C ARC to Kotlin/Native GC retain cycles and unhandled Kotlin CancellationException panics escaping into Swift callers. 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: Leaking Kotlin Coroutine Jobs across the Swift-ObjC bridge and converting CancellationExceptions into fatal runtime errors 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	Leaking Kotlin Coroutine Jobs across the Swift-ObjC bridge and converting CancellationExceptions into fatal runtime errors	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 wrap raw Objective-C-exported Kotlin suspend calls in 'withTaskCancellationHandler' to explicitly invoke the Kotlin coroutine's cancellation handle upon Swift Task cancellation.

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.