KMP Swift-Export Cross-Runtime ARC/GC Memory Lifecycle Guardrail

--- description: KMP Swift-Export Cross-Runtime ARC/GC Memory Lifecycle Guardrail - Enforces strict lifecycle decoupling and deterministic cancellation bridges between Apple ARC and Kotlin Native GC. Prevents permanent cross-runtime memory leaks caused by circular references between Swift modern concurrency tasks and Kotlin coroutine Flow collectors. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-memory-lifecycle-guardrail-kotlin-multiplat-178" --- # KMP Swift-Export Cross-Runtime ARC/GC Memory Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Swift Concurrency AsyncStream Retaining Kotlin Coroutines Creating Invisible Cross-Runtime Zombie Islands ## System Constraints You are a Principal Mobile Architect enforcing strict cross-runtime ARC-GC memory safety in Kotlin Multiplatform (KMP) codebases utilizing Swift-Export and Swift Concurrency. Mandate deterministic cancellation bridges, explicit weak captures, and structured teardown to prevent uncollected cross-runtime reference cycles. ## Strict Guidelines - Engineers MUST ALWAYS bind Swift Concurrency Task cancellation directly to Kotlin coroutine Job cancellation using AsyncStream.onTermination or withTaskCancellationHandler. - Engineers MUST NOT strongly capture Swift reference types (such as @Observable models, actors, or UIViewController instances) within Kotlin Flow collection closures. - Swift bridging wrappers MUST manage Swift AsyncStream continuations with explicit termination guards to prevent indefinite retain graph pinning across the Objective-C/Swift-Export boundary. - Kotlin-exported coroutine bridge classes MUST expose an idempotent, thread-safe close() or cancel() method conforming to Swift's Sendable lifecycle patterns. - Native Swift UI layers NEVER subscribe to raw Kotlin Flow or StateFlow instances without scoping the subscription to a managed Swift Task tied to a visible view hierarchy lifecycle. ## Bad vs Good Implementations ### Bridging Kotlin StateFlow to Swift AsyncStream with Lifecycle Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The watch closure retains self strongly in Swift ARC, while the Kotlin StateFlow collector retains the closure in Kotlin GC. Because neither garbage collector can traverse the foreign runtime's heap references, an invisible, uncollectable cross-runtime circular retain leak occurs. ```swift import SwiftUI import SharedKit @Observable final class UserProfileViewModel { var state: UserState = .initial private let userFlow: KotlinStateFlow<UserState> init(userFlow: KotlinStateFlow<UserState>) { self.userFlow = userFlow // ANTI-PATTERN: Strong capture of self across the Swift-Kotlin bridge; // Kotlin GC holds the observer closure, while Swift ARC holds userFlow. // No cancellation hook exists, pinning both runtimes permanently. userFlow.watch { state in self.state = state } } } ``` #### Production Standard (Correct) > **Standard**: Wraps the Kotlin StateFlow in a lifecycle-aware Swift AsyncStream. The continuation uses [weak continuation] and registers continuation.onTermination to cancel the underlying Kotlin collector. The consuming Task captures self weakly and cleanly cancels upon viewModel deinit. ```swift import SwiftUI import SharedKit @Observable @MainActor final class UserProfileViewModel { private(set) var state: UserState = .initial private var streamTask: Task<Void, Never>? func bind(to userFlow: KotlinStateFlow<UserState>) { streamTask?.cancel() let stream = AsyncStream<UserState> { continuation in let cancellable = userFlow.watch { [weak continuation] state in continuation?.yield(state) } continuation.onTermination = { _ in cancellable.cancel() } } streamTask = Task { [weak self] in for await nextState in stream { guard !Task.isCancelled, let self else { break } self.state = nextState } } } deinit { streamTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift-Export Cross-Runtime ARC/GC Memory Lifecycle Guardrail

KMP Swift-Export Cross-Runtime ARC/GC Memory Lifecycle Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict lifecycle decoupling and deterministic cancellation bridges between Apple ARC and Kotlin Native GC. Prevents permanent cross-runtime memory leaks caused by circular references between Swift modern concurrency tasks and Kotlin coroutine Flow collectors. 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: Unbounded Swift Concurrency AsyncStream Retaining Kotlin Coroutines Creating Invisible Cross-Runtime Zombie Islands 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	Unbounded Swift Concurrency AsyncStream Retaining Kotlin Coroutines Creating Invisible Cross-Runtime Zombie Islands	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 bind Swift Concurrency Task cancellation directly to Kotlin coroutine Job cancellation using AsyncStream.onTermination or withTaskCancellationHandler.

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.