Kotlin Multiplatform Swift-Export Cancellation Interlock Standard

--- description: Kotlin Multiplatform Swift-Export Cancellation Interlock Standard - Guarantees Swift Concurrency Task cancellation trees bidirectionally propagate into native Kotlin Multiplatform Job hierarchies and vice versa. Prevents orphaned background dispatchers, unmanaged CoroutineScopes, and native memory leaks caused by retained Cinterop/Obj-C blocks. globs: iosApp/**/*.swift, **/iosMain/**/*.kt, **/appleMain/**/*.kt, **/commonMain/**/interop/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-cancellation-interlock-guardrail" --- # Kotlin Multiplatform Swift-Export Cancellation Interlock Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unlinked Swift Task wrapping that drops cooperative cancellation signals and leaks Kotlin Native worker threads ## System Constraints You are a Principal Software Architect enforcing rigorous Swift Concurrency to Kotlin Multiplatform (KMP) cancellation interlock. You must mandate that every bridged suspend function, Flow, or async sequence bound across the Swift-Export or Objective-C export barrier establishes an atomic, bidirectional cancellation contract. Ensure that cancelling an enclosing Swift Task immediately cancels the underlying Kotlin Job via Job.cancel(cause:), and that Kotlin Coroutine failures or cancellations are non-destructively reflected into Swift's error propagation without leaving active Kotlin Native background dispatchers or ARC reference cycles. ## Strict Guidelines - Engineers MUST ALWAYS wrap bridged Kotlin suspend calls inside Swift's `withTaskCancellationHandler` to immediately relay cancellation to the active Kotlin `Job` or `Cancellable` wrapper. - Engineers MUST NOT rely on unchecked Swift `Task { await ... }` blocks when calling KMP suspend functions without retaining and linking the underlying Kotlin Job reference. - Code SHOULD enforce structured lifecycle bridging where Swift `AsyncSequence` adapters for Kotlin `Flow` explicitly invoke `Closeable.close()` or `Job.cancel()` upon iterator termination or task deallocation. - Services MUST ensure Kotlin Native dispatchers release native memory references immediately when `CancellationException` is caught across the Cinterop boundary. - Components NEVER hold strong bidirectional references between Swift completion handlers and Kotlin CoroutineScope instances; weak reference semantics or explicit unbinding MUST be enforced. ## Bad vs Good Implementations ### Bridging Swift Task Cancellation to Kotlin Coroutine Job #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The continuation ignores Swift Task cancellation. When the caller's Task is cancelled (e.g., SwiftUI view dismissal), the Kotlin repository continues fetching data, burning CPU cycles on native worker threads and creating an ARC/Kotlin Native retention cycle until completion. ```swift // ANTI-PATTERN: Fire-and-forget Task bridge ignoring Swift cancellation. // Cancelling the parent Swift Task will leave the Kotlin coroutine running on Dispatchers.Default. func fetchUserProfile(id: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in // Strong reference leak: KMP repository retains closure, ignoring Task cancellation UserRepositoryCompanion.shared.fetchProfile(id: id) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } } } ``` #### Production Standard (Correct) > **Standard**: Wraps the execution in `withTaskCancellationHandler` and retains the returned native Kotlin `Job`. If the Swift `Task` is cancelled, `onCancel` immediately invokes `jobRef?.cancel(cause: nil)`, which propagates cooperative cancellation down the Kotlin CoroutineScope hierarchy and frees native dispatcher resources. ```swift // PRODUCTION STANDARD: Explicit cancellation interlock with bidirectional teardown. func fetchUserProfile(id: String) async throws -> UserProfile { var jobRef: Kotlinx_coroutines_coreJob? = nil return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in jobRef = UserRepositoryCompanion.shared.fetchProfileJob( id: id, onSuccess: { profile in continuation.resume(returning: profile) }, onError: { error in continuation.resume(throwing: error) } ) } } onCancel: { // Atomically abort native Kotlin Job when enclosing Swift Task cancels jobRef?.cancel(cause: nil) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift-Export Cancellation Interlock Standard

Kotlin Multiplatform Swift-Export Cancellation Interlock Standard defines an industrial-grade behavioral standard for mobile engineering. Guarantees Swift Concurrency Task cancellation trees bidirectionally propagate into native Kotlin Multiplatform Job hierarchies and vice versa. Prevents orphaned background dispatchers, unmanaged CoroutineScopes, and native memory leaks caused by retained Cinterop/Obj-C blocks. 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: Unlinked Swift Task wrapping that drops cooperative cancellation signals and leaks Kotlin Native worker threads 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	Unlinked Swift Task wrapping that drops cooperative cancellation signals and leaks Kotlin Native worker threads	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 bridged Kotlin suspend calls inside Swift's `withTaskCancellationHandler` to immediately relay cancellation to the active Kotlin `Job` or `Cancellable` wrapper.

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.