Kotlin Multiplatform Swift Interop ARC Retain-Cycle Fence

--- description: Kotlin Multiplatform Swift Interop ARC Retain-Cycle Fence - Enforces strict weak-proxy and listener boundary decoupling across the Kotlin/Native runtime and Apple Swift ARC bridge in long-lived background synchronization services. Eliminates bi-directional cyclic references where Swift delegates held strongly by Kotlin GC roots prevent deallocation across runtime memory models. Mandates explicit teardown protocols and weak-referencing wrapper adapters across the bridge. globs: iosApp/**/*.swift, shared/src/iosMain/kotlin/**/*.kt, shared/src/commonMain/kotlin/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-arc-retain-cycle-fence" --- # Kotlin Multiplatform Swift Interop ARC Retain-Cycle Fence > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bi-directional strong reference cycles crossing the K/N Garbage Collector and Swift ARC memory barrier. ## System Constraints You are a Principal Mobile Architect enforcing rock-solid memory safety across Kotlin Multiplatform and Swift interoperability boundaries. The Kotlin/Native runtime and Swift ARC operate on distinct memory management models: Swift uses deterministic Automatic Reference Counting, while Kotlin/Native employs a tracing garbage collector with foreign reference bridging. When a long-lived Kotlin background service holds a direct reference to a Swift class (such as a delegate or callback closure), and that Swift class directly or transitively holds a reference back to the Kotlin service or its scope, a cross-runtime cycle is created. Neither the K/N GC nor Swift ARC can break this bridge cycle natively without explicit intervention. You must mandate weak-proxy bridge boundaries, explicit listener detachment, and teardown lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS implement Swift-side weak wrappers or Kotlin `WeakReference` containers when registering Swift listeners, observers, or delegates with long-lived Kotlin/Native services. - Engineers MUST NOT pass strong self-referencing Swift closures or raw class instances directly into Kotlin singleton or long-lived background sync registries. - Services MUST expose explicit `detach()`, `unsubscribe()`, or `dispose()` methods that decouple references on both sides of the K/N Objective-C bridge during view controller or coordinator teardown. - Code SHOULD prefer Kotlin `StateFlow` or `SharedFlow` consumed via lifecycle-aware Swift AsyncStreams over bi-directional delegate protocols to eliminate cyclic pointer graphs. - Components NEVER store persistent Kotlin/Native object references in Swift closures captured by escaping callbacks without `[weak self]` capture semantics. ## Bad vs Good Implementations ### Swift/Kotlin Bridge Delegate Retain-Cycle Prevention #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: BackgroundSyncEngine is a long-lived Kotlin object holding a strong Objective-C bridge reference to SyncCoordinator. SyncCoordinator holds a strong reference to BackgroundSyncEngine. Swift ARC cannot reclaim SyncCoordinator because K/N holds an external retain count, and K/N will not collect BackgroundSyncEngine because it is rooted in Swift, creating an intractable cross-runtime memory leak. ```swift // BAD: Direct bi-directional strong bridge causing ARC/GC deadlock import SharedKit final class SyncCoordinator: SyncStatusListener { private let syncEngine: BackgroundSyncEngine init(syncEngine: BackgroundSyncEngine) { self.syncEngine = syncEngine // Anti-pattern: Kotlin engine retains Swift self strongly; // self retains syncEngine strongly. Memory cycle across K/N & ARC boundary. self.syncEngine.registerListener(listener: self) } func onSyncProgress(progress: Double) { print("Progress: \(progress)") } } ``` #### Production Standard (Correct) > **Standard**: The WeakSyncListenerProxy breaks the cycle. BackgroundSyncEngine holds a strong reference only to the proxy, which holds a zeroing weak reference back to SyncCoordinator. When SyncCoordinator's owner releases it, deinit fires cleanly, allowing the coordinator to be deallocated and explicitly unregistering the proxy. ```swift // GOOD: Weak-proxy fence isolating Swift ARC from Kotlin/Native GC roots import SharedKit private final class WeakSyncListenerProxy: SyncStatusListener { private weak var target: SyncStatusListener? init(target: SyncStatusListener) { self.target = target } func onSyncProgress(progress: Double) { target?.onSyncProgress(progress: progress) } } final class SyncCoordinator: SyncStatusListener { private let syncEngine: BackgroundSyncEngine private var proxy: WeakSyncListenerProxy? init(syncEngine: BackgroundSyncEngine) { self.syncEngine = syncEngine let proxy = WeakSyncListenerProxy(target: self) self.proxy = proxy self.syncEngine.registerListener(listener: proxy) } deinit { // Explicitly clear fence reference on teardown if let proxy = proxy { syncEngine.unregisterListener(listener: proxy) } } func onSyncProgress(progress: Double) { print("Progress: \(progress)") } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift Interop ARC Retain-Cycle Fence

Kotlin Multiplatform Swift Interop ARC Retain-Cycle Fence defines an industrial-grade behavioral standard for mobile engineering. Enforces strict weak-proxy and listener boundary decoupling across the Kotlin/Native runtime and Apple Swift ARC bridge in long-lived background synchronization services. Eliminates bi-directional cyclic references where Swift delegates held strongly by Kotlin GC roots prevent deallocation across runtime memory models. Mandates explicit teardown protocols and weak-referencing wrapper adapters across the bridge. 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: Bi-directional strong reference cycles crossing the K/N Garbage Collector and Swift ARC memory barrier. 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	Bi-directional strong reference cycles crossing the K/N Garbage Collector and Swift ARC memory barrier.	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 implement Swift-side weak wrappers or Kotlin `WeakReference` containers when registering Swift listeners, observers, or delegates with long-lived Kotlin/Native services.

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.