Kotlin Multiplatform Swift Interop Concurrent Mutation and ABI Memory Safety

--- description: Kotlin Multiplatform Swift Interop Concurrent Mutation and ABI Memory Safety - Prevents SIGSEGV native memory corruption, race conditions, and reference counting deadlocks across the Kotlin/Native and Swift Objective-C ABI boundary under aggressive background concurrency. Mandates strict value-type bridging or thread-confined isolation using Swift actors and Kotlin StateFlow to avoid concurrent mutation of shared ObjC-bridged heap pointers. Enforces thread-safe lifecycle containment to prevent deallocation races during asynchronous dispatch. globs: iosApp/**/*.swift, shared/**/*.kt, **/*Bridge*.swift, **/*Repository*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-interop-concurrent-mutation-guardrail" --- # Kotlin Multiplatform Swift Interop Concurrent Mutation and ABI Memory Safety > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Directly Mutating Kotlin/Native Shared Mutable Objects Across Concurrent Swift GCD Queues or Async Tasks ## System Constraints You are a Principal Mobile Architect enforcing absolute memory safety and thread containment at the Kotlin Multiplatform (K/N) to Swift ABI interop boundary. Kotlin Native objects exposed via the Objective-C runtime bridge are subject to dual garbage collection (Kotlin GC) and Automatic Reference Counting (ARC). You must strictly mandate that mutable K/N heap instances are never concurrently mutated across Swift async/await tasks or GCD queues. You must enforce immutable DTO transfers, Swift Actor isolation, and structured coroutine-to-AsyncSequence adapters. ## Strict Guidelines - Engineers MUST ALWAYS isolate K/N bridged instances within a dedicated Swift `actor` or `@MainActor` context when instances contain internal state. - Engineers MUST NEVER expose Kotlin mutable collections (e.g., `KtMutableList`, `KtMutableMap`) directly to Swift callers across thread boundaries. - Engineers MUST project Kotlin reactive state via read-only `StateFlow` or `SharedFlow` transformed into immutable primitives or Swift value types (`struct`). - Swift background tasks MUST NOT retain or mutate a Kotlin reference across detached `Task.detached` or unconstrained `DispatchQueue.global()` executions without thread confinement. - Kotlin export models SHOULD implement `@ObjCName` and provide thread-safe factory methods or copy-on-write semantics for complex nested structures. ## Bad vs Good Implementations ### Concurrent Mutation across Swift Concurrency Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly invoking Kotlin Native instance methods from arbitrary Swift background GCD threads leads to concurrent mutation of non-synchronized native memory pointers. Although Kotlin 1.9+ features a new memory manager with shared heap, simultaneous read/write operations without synchronized wrappers cause Swift ARC retain/release races and memory corruption in the Objective-C bridging runtime. ```swift import Shared // ANTI-PATTERN: Directly sharing and mutating a Kotlin stateful class across GCD queues class AccountSyncManager { let accountStore: SharedAccountStore // Kotlin/Native bridged class with internal mutable state init(accountStore: SharedAccountStore) { self.accountStore = accountStore } func synchronizeAll(accounts: [String]) { for accountId in accounts { DispatchQueue.global(qos: .userInitiated).async { // Concurrent invocation into Kotlin/Native runtime // Causes ARC race condition, native ref-count tearing, or memory corruption self.accountStore.updateSession(accountId: accountId, timestamp: Int64(Date().timeIntervalSince1970)) } } } } ``` #### Production Standard (Correct) > **Standard**: By encapsulating the Kotlin `SharedAccountStore` inside a Swift `actor`, all cross-thread dispatch is serialized under the actor's isolation domain. Furthermore, mutating operations are exposed as async suspend functions and converted immediately into a Swift `Sendable` value-type `struct`, preventing Kotlin heap pointer leaks across arbitrary thread boundaries. ```swift import Shared // PRODUCTION FIX: Confining Kotlin access to a Swift Actor and passing immutable value DTOs actor AccountSyncManager { private let accountStore: SharedAccountStore init(accountStore: SharedAccountStore) { self.accountStore = accountStore } // All mutations are serial and isolated to the actor's execution context func synchronize(accountId: String, timestamp: Int64) async throws -> AccountSessionSnapshot { // Kotlin method invoked safely under actor isolation let kmpSnapshot = try await accountStore.updateSessionAsync(accountId: accountId, timestamp: timestamp) // Project into a pure Swift immutable struct before crossing concurrency boundaries return AccountSessionSnapshot( id: kmpSnapshot.id, lastUpdated: kmpSnapshot.timestamp, isActive: kmpSnapshot.isActive ) } } struct AccountSessionSnapshot: Sendable { let id: String let lastUpdated: Int64 let isActive: Bool } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift Interop Concurrent Mutation and ABI Memory Safety

Kotlin Multiplatform Swift Interop Concurrent Mutation and ABI Memory Safety defines an industrial-grade behavioral standard for mobile engineering. Prevents SIGSEGV native memory corruption, race conditions, and reference counting deadlocks across the Kotlin/Native and Swift Objective-C ABI boundary under aggressive background concurrency. Mandates strict value-type bridging or thread-confined isolation using Swift actors and Kotlin StateFlow to avoid concurrent mutation of shared ObjC-bridged heap pointers. Enforces thread-safe lifecycle containment to prevent deallocation races during asynchronous dispatch. 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: Directly Mutating Kotlin/Native Shared Mutable Objects Across Concurrent Swift GCD Queues or Async Tasks 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	Directly Mutating Kotlin/Native Shared Mutable Objects Across Concurrent Swift GCD Queues or Async Tasks	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 isolate K/N bridged instances within a dedicated Swift `actor` or `@MainActor` context when instances contain internal state.

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.