KMP 2.1 Swift-Export Actor-Bound Concurrency Barrier Contract

--- description: KMP 2.1 Swift-Export Actor-Bound Concurrency Barrier Contract - Enforces strict isolation barriers and actor boundaries when bridging Kotlin Coroutines Flows and suspend functions into Swift via KMP 2.1 Swift-Export. Unfenced consumption across direct native boundaries induces Swift 6 data races, untracked Task deallocations, and thread-pool pool desynchronization. Native bridge calls must explicitly establish AsyncSequence fences bound to explicit Swift Actors. 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-concurrency-barrier" --- # KMP 2.1 Swift-Export Actor-Bound Concurrency Barrier Contract > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Direct Unscoped Flow Collection and Unfenced Continuation Resumptions Across Native Swift-Export Boundaries ## System Constraints You are a Principal Mobile Architect enforcing absolute memory safety and structured concurrency across Kotlin Multiplatform 2.1 Direct Swift-Export native boundaries. Direct invocation of Kotlin suspend functions or raw Flow collectors across the Objective-C/Swift interop layer without explicit actor isolation triggers catastrophic memory safety violations under Swift 6 strict concurrency checks. You must mandate actor-isolated bridging wrappers, explicit Task cancellation propagation, and AsyncSequence barriers. ## Strict Guidelines - Engineers MUST ALWAYS wrap Swift-Export generated Flows into an actor-isolated AsyncSequence wrapper before consumption in the UI or service layer. - Engineers MUST NOT invoke Swift-Export async functions directly from non-isolated synchronous contexts or fire-and-forget Task blocks without explicit MainActor or custom Actor binding. - Bridge adapters MUST enforce bidirectional cancellation: cancelling the Swift Task MUST immediately invoke the Kotlin Job.cancel() handle to prevent coroutine leaks. - Flow collection crossing the native barrier MUST pass through a dedicated @Sendable memory fence ensuring all emitted values conform to Sendable. - Engineers MUST NOT rely on implicit thread hop semantics; native Kotlin Dispatchers.Main and Swift @MainActor must be explicitly synchronized across boundary crossings. ## Bad vs Good Implementations ### Swift-Export Flow Bridging into Actor-Isolated AsyncSequence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly collecting a Kotlin Multiplatform Flow in an unscoped Swift Task bypasses Swift 6 strict concurrency checking. It introduces unsafe concurrent mutations to ViewModel state, does not guarantee thread jumping back to the MainActor, and permanently leaks the underlying Kotlin Job when the ViewModel deinitializes. ```swift import SwiftUI import SharedKit // Generated via Swift-Export @Observable final class DeviceTelemetryViewModel { var telemetryData: String = "" func startObserving() { // ANTI-PATTERN: Non-isolated Task collecting directly from Kotlin Flow export // Missing memory barrier, no Sendable enforcement, and leaking coroutine execution on dealloc Task { let flow = TelemetryRepository().observeMetrics() flow.collect { data in // Direct mutation without actor boundary verification self.telemetryData = data.description } } } } ``` #### Production Standard (Correct) > **Standard**: The production implementation wraps the Kotlin Flow emission pipeline into an actor-fenced AsyncThrowingStream. It bounds emissions to @MainActor, guarantees thread safety under Swift 6 strict checking, and wires up continuation.onTermination directly to cancel the Kotlin coroutine Job upon Swift Task teardown. ```swift import SwiftUI import SharedKit @MainActor @Observable final class DeviceTelemetryViewModel { private(set) var telemetryData: String = "" private var observationTask: Task<Void, Never>? func startObserving(repository: TelemetryRepository) { observationTask?.cancel() observationTask = Task { [weak self] in // PRODUCTION BARRIER: Adapter converts KMP Flow into Actor-fenced AsyncSequence with cancellation link let stream = AsyncThrowingStream<TelemetryMetrics, Error> { continuation in let job = repository.observeMetrics().subscribe( onEach: { item in continuation.yield(item) }, onCompletion: { error in if let error { continuation.finish(throwing: error) } else { continuation.finish() } } ) continuation.onTermination = { @Sendable _ in job.cancel() } } do { for try await metric in stream { guard !Task.isCancelled else { break } self?.telemetryData = metric.description } } catch { // Structured error handling on MainActor } } } deinit { observationTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP 2.1 Swift-Export Actor-Bound Concurrency Barrier Contract

KMP 2.1 Swift-Export Actor-Bound Concurrency Barrier Contract defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation barriers and actor boundaries when bridging Kotlin Coroutines Flows and suspend functions into Swift via KMP 2.1 Swift-Export. Unfenced consumption across direct native boundaries induces Swift 6 data races, untracked Task deallocations, and thread-pool pool desynchronization. Native bridge calls must explicitly establish AsyncSequence fences bound to explicit Swift Actors. 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: Direct Unscoped Flow Collection and Unfenced Continuation Resumptions Across Native Swift-Export Boundaries 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	Direct Unscoped Flow Collection and Unfenced Continuation Resumptions Across Native Swift-Export Boundaries	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 wrap Swift-Export generated Flows into an actor-isolated AsyncSequence wrapper before consumption in the UI or service layer.

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.