Kotlin 2.1 Swift Direct-Export Memory Ownership & Dual-Runtime Boundary Standard

--- description: Kotlin 2.1 Swift Direct-Export Memory Ownership & Dual-Runtime Boundary Standard - Governs inter-runtime reference topologies across Swift direct-export boundaries in Kotlin Multiplatform 2.1. Prevents uncollected dual-runtime retain cycles between Swift ARC and Kotlin/Native Concurrent Mark-Sweep GC by prohibiting cross-boundary bidirectional strong handles and mandating explicit lifecycle tokens. globs: **/iosApp/**/*.swift, **/shared/src/iosMain/**/*.kt, **/shared/src/commonMain/**/*.kt, **/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-2-1-swift-direct-export-memory-boundary" --- # Kotlin 2.1 Swift Direct-Export Memory Ownership & Dual-Runtime Boundary Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Runtime Retain Cycles via Closures Capturing Swift Self Passing to Kotlin GC Roots ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform 2.1 Swift Direct-Export Memory Ownership Boundaries. Mandate disjoint runtime topologies between Swift ARC and Kotlin/Native Concurrent GC. Forbid cross-boundary cyclic references, unescaped closure captures, and untracked observer registrations without explicit cancellation handles. ## Strict Guidelines - Engineers MUST ALWAYS treat Swift ARC and Kotlin/Native GC as strictly disjoint memory domains lacking cross-boundary cycle detection. - Engineers MUST NOT allow a Swift instance holding a direct-exported Kotlin object to pass escaping closures or callbacks into Kotlin that strongly capture `self`. - Code MUST pass Swift closures capturing dependencies with explicit `[weak self]` or `[unowned self]` (when lifespan is strictly bounded) across any direct Kotlin export boundary. - Services exposing Kotlin StateFlow, SharedFlow, or Coroutine streams MUST return a deterministic `DisposableHandle` or `CancellationHandle` consumed by Swift lifecycle coordinators. - Components NEVER store direct Swift closures or interface implementations in Kotlin-side long-lived singletons or top-level GC roots without explicit Kotlin `WeakReference` encapsulation. ## Bad vs Good Implementations ### Cross-Boundary Subscription and Listener Retention #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: KotlinUserManager is held strongly by UserProfileViewModel (ARC). The subscription closure strongly captures self (ARC) and is stored in KotlinUserManager (Kotlin GC). Because neither ARC nor Kotlin's GC can trace across the direct-export boundary into the other runtime's heap, this creates a permanent silent cross-runtime memory leak. ```swift import SwiftUI import SharedKit // Kotlin 2.1 Direct Swift Export final class UserProfileViewModel: ObservableObject { @Published var userName: String = "" // Kotlin direct-exported state manager held strongly by Swift ARC private let sessionManager: KotlinUserManager = KotlinUserManager() func bindSession() { // ANTI-PATTERN: Strong capture of Swift 'self' passed directly to Kotlin GC. // KotlinUserManager holds the lambda strongly in its internal observer list. // ARC cannot collect UserProfileViewModel; Kotlin GC cannot detect Swift retain graph. sessionManager.subscribeToUserUpdates { user in self.userName = user.name } } } ``` #### Production Standard (Correct) > **Standard**: Applying [weak self] prevents the Swift closure from retaining the ViewModel instance in Swift ARC. Returning an explicit KotlinDisposableHandle and calling dispose() during deinit unregisters the closure from the Kotlin GC root, completely severing bidirectional lifetime couplings. ```swift import SwiftUI import SharedKit // Kotlin 2.1 Direct Swift Export final class UserProfileViewModel: ObservableObject { @Published var userName: String = "" private let sessionManager: KotlinUserManager = KotlinUserManager() // Explicit boundary token to sever cross-runtime reference private var subscriptionHandle: KotlinDisposableHandle? func bindSession() { // Break ARC cycle with [weak self] subscriptionHandle = sessionManager.subscribeToUserUpdates { [weak self] user in Task { @MainActor in self?.userName = user.name } } } deinit { // Deterministic boundary cleanup: explicitly unbind from Kotlin GC root subscriptionHandle?.dispose() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin 2.1 Swift Direct-Export Memory Ownership & Dual-Runtime Boundary Standard

Kotlin 2.1 Swift Direct-Export Memory Ownership & Dual-Runtime Boundary Standard defines an industrial-grade behavioral standard for mobile engineering. Governs inter-runtime reference topologies across Swift direct-export boundaries in Kotlin Multiplatform 2.1. Prevents uncollected dual-runtime retain cycles between Swift ARC and Kotlin/Native Concurrent Mark-Sweep GC by prohibiting cross-boundary bidirectional strong handles and mandating explicit lifecycle tokens. 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 via Closures Capturing Swift Self Passing to Kotlin GC Roots 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 via Closures Capturing Swift Self Passing to Kotlin GC Roots	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 treat Swift ARC and Kotlin/Native GC as strictly disjoint memory domains lacking cross-boundary cycle detection.

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.