Kotlin/Native to Swift ARC Dual-GC Bridge Lifecycle Detachment Invariant

--- description: Kotlin/Native to Swift ARC Dual-GC Bridge Lifecycle Detachment Invariant - Governs the boundary between Kotlin/Native concurrent tracing GC and Swift Automatic Reference Counting (ARC) to prevent cross-runtime reference cycles and memory leaks. Requires explicit lifecycle detachment, deterministic cancellation of asynchronous subscriptions, and weak callback references across the Objective-C/Swift bridge. 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-native-dual-gc-cross-bridge-lifecycle" --- # Kotlin/Native to Swift ARC Dual-GC Bridge Lifecycle Detachment Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Cross-Bridge Closures and Undisposed Flow Observers Between Kotlin GC and Swift ARC ## System Constraints You are a Principal Software Architect enforcing Kotlin Multiplatform (KMP) Kotlin/Native Dual-GC Cross-Bridge invariants. The Swift/Objective-C ARC runtime and the Kotlin/Native concurrent tracing GC do not possess unified heap visibility; reference cycles spanning the boundary cannot be detected or collected automatically. Mandate strict deterministic lifecycle teardown, explicit disposable/cancellation tokens, weak capture semantics on all cross-bridge delegates, and zero circular strong dependencies between Kotlin ViewModels and Swift UI hosts. ## Strict Guidelines - Engineers MUST ALWAYS implement and invoke an explicit deterministic detachment mechanism (such as `DisposableHandle.dispose()`, `Job.cancel()`, or a dedicated `detach()` lifecycle method) in Swift `deinit` or SwiftUI `onDisappear` for any Kotlin Flow, coroutine, or listener. - Engineers MUST NOT capture Swift instances strongly inside closures or delegate adapters passed into Kotlin/Native exported objects. - Swift wrapper classes binding Kotlin state SHOULD store bridge references inside a single lifecycle-scoped container that nullifies references upon view hierarchy dismissal. - Services MUST ensure any Kotlin coroutine scope bridged to iOS terminates when the associated Swift UI coordinator is dismantled, preventing orphan coroutines from retaining Swift bridge handles indefinitely. - Components NEVER rely on Swift ARC deinit or Kotlin finalizers alone to resolve cross-boundary cycles; circular references between ARC proxies and Kotlin heap references permanently pin native memory. ## Bad vs Good Implementations ### SwiftUI ViewModel Observing Kotlin CommonFlow Across Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Kotlin Flow watcher creates an Objective-C block wrapper retaining 'self' strongly, while 'ProfileViewModel' retains 'kotlinViewModel'. Because ARC and Kotlin GC have disjoint heaps, neither runtime detects the cycle, causing permanent native heap leaks and runaway coroutine execution. ```swift import SwiftUI import SharedKit final class ProfileViewModel: ObservableObject { @Published var uiState: ProfileUiState = .initial private let kotlinViewModel: SharedProfileViewModel init(kotlinViewModel: SharedProfileViewModel) { self.kotlinViewModel = kotlinViewModel // ANTI-PATTERN: Strong capture of self in Kotlin callback closure; // DisposableHandle is ignored. Kotlin/Native GC retains proxy; Swift ARC retains Kotlin object. // Neither GC nor ARC can detect this cross-runtime cycle. kotlinViewModel.uiState.watch { state in self.uiState = state } } } ``` #### Production Standard (Correct) > **Standard**: Enforces dual-GC isolation: [weak self] breaks the ARC-to-Kotlin closure cycle, the DisposableHandle is explicitly stored, and Swift deinit/detach guarantees deterministic disposal of the Kotlin coroutine collector. ```swift import SwiftUI import SharedKit final class ProfileViewModel: ObservableObject { @Published var uiState: ProfileUiState = .initial private let kotlinViewModel: SharedProfileViewModel private var stateWatcherTask: SharedKit.DisposableHandle? init(kotlinViewModel: SharedProfileViewModel) { self.kotlinViewModel = kotlinViewModel } func startObserving() { // Invariant: Weak capture of Swift target + explicit DisposableHandle tracking stateWatcherTask = kotlinViewModel.uiState.watch { [weak self] state in guard let self = self else { return } self.uiState = state } } func detach() { // Invariant: Deterministic cross-bridge detachment stateWatcherTask?.dispose() stateWatcherTask = nil kotlinViewModel.onCleared() } deinit { detach() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin/Native to Swift ARC Dual-GC Bridge Lifecycle Detachment Invariant

Kotlin/Native to Swift ARC Dual-GC Bridge Lifecycle Detachment Invariant defines an industrial-grade behavioral standard for mobile engineering. Governs the boundary between Kotlin/Native concurrent tracing GC and Swift Automatic Reference Counting (ARC) to prevent cross-runtime reference cycles and memory leaks. Requires explicit lifecycle detachment, deterministic cancellation of asynchronous subscriptions, and weak callback references across the Objective-C/Swift 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: Unbounded Cross-Bridge Closures and Undisposed Flow Observers Between Kotlin GC and Swift ARC 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 Cross-Bridge Closures and Undisposed Flow Observers Between Kotlin GC and Swift ARC	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 and invoke an explicit deterministic detachment mechanism (such as `DisposableHandle.dispose()`, `Job.cancel()`, or a dedicated `detach()` lifecycle method) in Swift `deinit` or SwiftUI `onDisappear` for any Kotlin Flow, coroutine, or listener.

Engineers MUST ALWAYS implement and invoke an explicit deterministic detachment mechanism (such as `DisposableHandle.dispose()`, `Job.cancel()`, or a dedicated `detach()` lifecycle method) in Swift `deinit` or SwiftUI `onDisappear` for any Kotlin Flow, coroutine, or listener.

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.