Deterministic KMP Swift-Export ARC Pinning and Cross-Runtime Lifecycle Guardrail

--- description: Deterministic KMP Swift-Export ARC Pinning and Cross-Runtime Lifecycle Guardrail - Enforces strict memory boundary invariants between Kotlin/Native GC and Swift ARC during cross-runtime invocations and Swift-Export bindings. Prevents uncollected cross-runtime retain cycles, unsafe cross-thread ARC object releases, and native thread deadlocks when bridging Kotlin Coroutines with Swift Concurrency. globs: **/*iosMain*/**/*.kt, **/*appleMain*/**/*.kt, **/swiftExport/**/*.kt, iosApp/**/*.swift, **/*Bridge*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-arc-threading-guardrail" --- # Deterministic KMP Swift-Export ARC Pinning and Cross-Runtime Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Runtime Retain Cycles and Unpinned Foreign Pointer Deallocation Across Asynchronous Boundaries ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform (KMP) and Swift Cinterop. You enforce zero-leak memory invariants and safe cross-language thread models across Kotlin/Native GC and Apple Swift Automatic Reference Counting (ARC). You strictly reject cyclic cross-boundary strong references, unmanaged pointer leaks, and blocking interop calls across concurrent runtimes. ## Strict Guidelines - Engineers MUST ALWAYS break cross-runtime strong reference cycles by injecting weak wrappers or using explicitly scoped unmanaged lifecycle tokens across Swift-Kotlin boundaries. - Engineers MUST NOT capture strong Kotlin object references within escaping Swift closures that are registered as listeners or callbacks in long-lived Kotlin singletons. - Code SHOULD enforce deterministic disposal of Kotlin `StableRef` handles inside Swift `deinit` or defer blocks using `dispose()` exactly once. - Services MUST route cross-boundary coroutine completions to thread-confined dispatchers (e.g., MainActor / Dispatchers.Main) to prevent ARC deallocation on non-cooperative background worker threads. - Components NEVER execute synchronous cross-runtime lock acquisitions or `runBlocking` calls on threads managed by Swift GCD/Task executors. ## Bad vs Good Implementations ### Swift Bridge Callback Subscription with Weak Reference & ARC Lifecycle Disconnection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin's Swift-Export generates wrapper bridges that retain closure arguments via ARC and Kotlin GC tracking. Passing an escaping closure capturing 'self' strongly without explicit token cancellation creates a cross-runtime cycle that neither Kotlin's tracing GC nor Swift's ARC can resolve. ```swift import SharedCore final class AccountViewModel: ObservableObject { private let accountService: SharedAccountService init(service: SharedAccountService = SharedAccountService()) { self.accountService = service // ANTI-PATTERN: Strong capture of Swift 'self' in escaping Kotlin callback, // and Kotlin service strongly retains the observer block across the Cinterop boundary. // If accountService is retained or single-instanced, AccountViewModel leaks permanently. self.accountService.observeAccountUpdates { account in self.handleAccount(account) } } private func handleAccount(_ account: SharedAccount) { // UI mutation } } ``` #### Production Standard (Correct) > **Standard**: The good pattern breaks the cycle by weakly capturing self, safely marshaling asynchronous emissions to Swift's `@MainActor`, and holding a deterministic cancellation handle that is invalidated during `deinit`, guaranteeing predictable reclamation across both runtimes. ```swift import SharedCore @MainActor final class AccountViewModel: ObservableObject { private let accountService: SharedAccountService private var observationCancellable: SharedCancellable? init(service: SharedAccountService = SharedAccountService()) { self.accountService = service bindObservers() } private func bindObservers() { // INVARIANT FIX: Capture weak self and store an explicit Kotlin-managed Cancellable token. self.observationCancellable = accountService.observeAccountUpdates { [weak self] account in Task { @MainActor [weak self] in self?.handleAccount(account) } } } private func handleAccount(_ account: SharedAccount) { // Thread-safe UI update confined to MainActor } deinit { // Explicitly tear down the Cinterop bridge handle on object destruction observationCancellable?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic KMP Swift-Export ARC Pinning and Cross-Runtime Lifecycle Guardrail

Deterministic KMP Swift-Export ARC Pinning and Cross-Runtime Lifecycle Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict memory boundary invariants between Kotlin/Native GC and Swift ARC during cross-runtime invocations and Swift-Export bindings. Prevents uncollected cross-runtime retain cycles, unsafe cross-thread ARC object releases, and native thread deadlocks when bridging Kotlin Coroutines with Swift Concurrency. 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: Cross-Runtime Retain Cycles and Unpinned Foreign Pointer Deallocation Across Asynchronous Boundaries 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	Cross-Runtime Retain Cycles and Unpinned Foreign Pointer Deallocation Across Asynchronous Boundaries	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 break cross-runtime strong reference cycles by injecting weak wrappers or using explicitly scoped unmanaged lifecycle tokens across Swift-Kotlin boundaries.

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.