Kotlin 2.1 SharedFlow & Swift 6 AsyncSequence Sendable Isolation Guardrail

--- description: Kotlin 2.1 SharedFlow & Swift 6 AsyncSequence Sendable Isolation Guardrail - Enforces thread-safe, data-race-free interoperability between Kotlin Multiplatform 2.1 SharedFlow/StateFlow emissions and Swift 6 Complete Concurrency AsyncSequences. Eliminates cross-runtime thread pool exhaustion and cooperative thread starvation deadlocks caused by unmanaged coroutine collectors. Mandates strict Sendable isolation and deterministic cancellation bridging across the Darwin runtime boundary. globs: **/*.kt, **/*.swift, iosApp/**/*.swift, shared/src/commonMain/**/*.kt, shared/src/iosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-shared-flow-swift6-sendable-guardrail" --- # Kotlin 2.1 SharedFlow & Swift 6 AsyncSequence Sendable Isolation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unchecked Cross-Boundary Flow Bridging Causing Swift 6 Isolation Escapes and Cooperative Thread Starvation Deadlocks ## System Constraints You are a Principal Software Architect enforcing Kotlin Multiplatform 2.1 and Swift 6 Concurrency boundaries. Your task is to enforce strict compile-time data race freedom across KMP Kotlin Coroutines (StateFlow/SharedFlow) and native Swift AsyncSequences. Prevent non-Sendable Objective-C bridged object escapes across Swift actors and eliminate runtime deadlocks originating from synchronous blocking on Swift's cooperative pool or unmanaged KMP Job lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS bridge Kotlin Flow instances to Swift using an AsyncStream or AsyncThrowingStream that deterministically cancels the underlying Kotlin kotlinx.coroutines.Job within `onTermination`. - Engineers MUST NOT cross Swift 6 actor boundaries with mutable Kotlin reference classes; emitted payload models MUST be immutable, marked `@Sendable` on the Swift wrapper side, or strictly confined to the `@MainActor`. - Code MUST NEVER invoke `runBlocking` or block a Swift cooperative thread awaiting a Kotlin suspend function or Flow emission. - Services MUST route UI-bound Flow consumption explicitly through `@MainActor` isolated wrappers, preventing cross-thread mutation of Swift state by Kotlin Darwin workers. - Components NEVER hold strong unmanaged references to Kotlin CoroutineScope instances inside Swift async contexts without structured lifetime binding. ## Bad vs Good Implementations ### Bridging Kotlin Flow to Swift 6 AsyncSequence with Sendable Safety and Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad code triggers Swift 6 complete concurrency warnings/errors because UserProfile bridged from Obj-C/KMP is non-Sendable across actor boundaries. Crucially, it omits `continuation.onTermination`, causing the Kotlin coroutine collector to leak indefinitely. If the caller's Task is cancelled, the Kotlin coroutine continues collecting, risking memory leaks and dispatch queue starvation. ```swift // Anti-Pattern: Flow collection without Sendable conformance, leaking Job lifecycle and risking deadlock import SharedKit final class FlowBridge { func observeEvents(flow: SharedFlowWrapper<UserProfile>) -> AsyncStream<UserProfile> { AsyncStream { continuation in // Violates Swift 6: UserProfile is not Sendable, closure runs asynchronously across boundaries flow.collect { profile in continuation.yield(profile) } // BUG: No onTermination handler. Kotlin coroutine Job is never cancelled! } } } ``` #### Production Standard (Correct) > **Standard**: The production code enforces Swift 6 data-race freedom by mapping the non-Sendable native Kotlin object into a Swift-native `Sendable` value type (`UserProfileDTO`). It isolates the stream construction and wires `continuation.onTermination` to synchronously invoke `cancellable.cancel()`, tearing down the Kotlin Coroutine Job and preventing memory leaks or deadlocks. ```swift // Production Standard: Thread-safe, Sendable-isolated bridge with deterministic Job lifecycle import SharedKit // Sendable DTO guaranteed to be deep-copied or immutable across boundary public struct UserProfileDTO: Sendable, Equatable { public let id: String public let name: String } extension SharedFlowWrapper where T == NativeUserProfile { @MainActor public func makeAsyncSequence() -> AsyncStream<UserProfileDTO> { AsyncStream(UserProfileDTO.self) { continuation in let cancellable = self.collect(onEmit: { nativeProfile in let dto = UserProfileDTO(id: nativeProfile.id, name: nativeProfile.name) continuation.yield(dto) }) continuation.onTermination = { @Sendable _ in // Deterministically cancel the underlying Kotlin Job across the boundary cancellable.cancel() } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin 2.1 SharedFlow & Swift 6 AsyncSequence Sendable Isolation Guardrail

Kotlin 2.1 SharedFlow & Swift 6 AsyncSequence Sendable Isolation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces thread-safe, data-race-free interoperability between Kotlin Multiplatform 2.1 SharedFlow/StateFlow emissions and Swift 6 Complete Concurrency AsyncSequences. Eliminates cross-runtime thread pool exhaustion and cooperative thread starvation deadlocks caused by unmanaged coroutine collectors. Mandates strict Sendable isolation and deterministic cancellation bridging across the Darwin runtime boundary. 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: Unchecked Cross-Boundary Flow Bridging Causing Swift 6 Isolation Escapes and Cooperative Thread Starvation Deadlocks 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	Unchecked Cross-Boundary Flow Bridging Causing Swift 6 Isolation Escapes and Cooperative Thread Starvation Deadlocks	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 bridge Kotlin Flow instances to Swift using an AsyncStream or AsyncThrowingStream that deterministically cancels the underlying Kotlin kotlinx.coroutines.Job within `onTermination`.

Engineers MUST ALWAYS bridge Kotlin Flow instances to Swift using an AsyncStream or AsyncThrowingStream that deterministically cancels the underlying Kotlin kotlinx.coroutines.Job within `onTermination`.

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.