AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: kmp-swift-export-concurrency-isolation-standard

Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation

Enforces strict isolation boundaries and execution context affinity when bridging Kotlin Multiplatform (KMP) 2.1 Swift Export coroutine primitives into native Swift 6 Actor environments. Prevents cross-runtime thread pool corruption, un-isolated data races, and Swift 6 Sendable conformance violations by mandating disciplined AsyncStream transformations and explicit MainActor context dispatching.

Prohibited Anti-Pattern: Leaking unconfined Kotlin coroutine jobs or un-isolated Flow collectors directly into Swift 6 actors, triggering silent data races and thread-pool deadlock.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation - Enforces strict isolation boundaries and execution context affinity when bridging Kotlin Multiplatform (KMP) 2.1 Swift Export coroutine primitives into native Swift 6 Actor environments. Prevents cross-runtime thread pool corruption, un-isolated data races, and Swift 6 Sendable conformance violations by mandating disciplined AsyncStream transformations and explicit MainActor context dispatching.
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-isolation-standard"
---

# Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Leaking unconfined Kotlin coroutine jobs or un-isolated Flow collectors directly into Swift 6 actors, triggering silent data races and thread-pool deadlock.

## System Constraints
You are a Principal Mobile Architect specializing in Kotlin Multiplatform 2.1 and Swift 6 runtime interop. Your role is to mandate strict memory and concurrency isolation boundaries across the KMP Swift Export layer. You must enforce that raw Kotlin coroutine scopes, Flow emitters, and mutable references are never directly ingested into Swift actors without deterministic cancellation propagation, explicit Sendable value copying, and strict actor/MainActor isolation.

## Strict Guidelines
- Engineers MUST ALWAYS bridge Kotlin Flows into Swift 6 `AsyncStream<T>` using value-type or `Sendable`-conforming payloads before consumption in native actors.
- Engineers MUST NOT expose raw mutable Kotlin classes across the Swift Export boundary; all shared data structures crossing the bridge MUST be immutable data classes mapped to Swift Sendable structs.
- Engineers MUST ALWAYS tie Kotlin Coroutine cancellation to native Swift `Task` cancellation using `withTaskCancellationHandler` or structured cooperative cancellation primitives.
- Code SHOULD wrap UI-bound Kotlin suspend functions directly within `@MainActor` isolated Swift methods to prevent implicit thread hops to generic Swift cooperative worker threads.
- Services MUST NOT execute blocking Kotlin synchronous interop functions from within a Swift 6 `actor` isolation domain without dispatching to a dedicated non-cooperative background queue.
- Components NEVER store direct long-lived references to native Swift actors inside long-running Kotlin shared singletons or companion objects due to retain-cycle and dead-lock hazards during actor re-entrancy.

## Bad vs Good Implementations
### Unsafe Swift 6 Actor Ingestion of KMP Flow vs. Isolated AsyncStream Adapter

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Directly consuming Kotlin Multiplatform callback mechanisms inside a Swift 6 actor breaks actor isolation. The Kotlin callback executes on an unmanaged Kotlin native worker thread, bypassing the Swift actor's cooperative executor and inducing silent data corruption or runtime isolation panics under -strict-concurrency=complete.
```swift
// BAD: Consuming raw KMP suspend / callback flow inside an actor without isolation or task lifecycle linking
import SharedKit

actor AccountStateManager {
    private var currentState: AccountState? = nil
    private let repository = AccountRepository() // Kotlin KMP Class

    func observeState() {
        // Violates Swift 6 strict concurrency: KMP Flow callback invokes on arbitrary Kotlin worker thread
        repository.watchAccount { [weak self] rawKotlinState in
            // Direct mutation across isolation boundary causes data races
            self?.currentState = rawKotlinState
        }
    }
}
```

#### Production Standard (Correct)
> **Standard**: The good implementation uses Swift's AsyncStream to establish a clean boundary. It maps incoming Kotlin emissions into an immutable Sendable value struct and connects native task lifecycle termination to the Kotlin Coroutine Job cancellation, guaranteeing strict Swift 6 actor isolation.
```swift
// GOOD: Wrapping KMP Flow into a strictly isolated Sendable AsyncStream linked to native Task cancellation
import SharedKit

actor AccountStateManager {
    private var currentState: ImmutableAccountState? = nil
    private let repository: AccountRepository

    init(repository: AccountRepository) {
        self.repository = repository
    }

    func observeState() async {
        let stream = AsyncStream<ImmutableAccountState> { continuation in
            let job = repository.subscribeToAccountState {
                continuation.yield(ImmutableAccountState(from: $0))
            }
            continuation.onTermination = { @Sendable _ in
                job.cancel()
            }
        }

        for await state in stream {
            // Safely isolated within the Swift 6 Actor execution domain
            self.currentState = state
        }
    }
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Xcode Build Server MCP
Validates Swift 6 strict concurrency compiler flags (-strict-concurrency=complete) and flags actor boundary leaks in hybrid builds.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

KMP Swift Export Boundary Linter
Static analysis CLI tool checking for Sendable conformance and safe suspend function bridging across Kotlin 2.1 Swift Export modules.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation

Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation boundaries and execution context affinity when bridging Kotlin Multiplatform (KMP) 2.1 Swift Export coroutine primitives into native Swift 6 Actor environments. Prevents cross-runtime thread pool corruption, un-isolated data races, and Swift 6 Sendable conformance violations by mandating disciplined AsyncStream transformations and explicit MainActor context dispatching. 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: Leaking unconfined Kotlin coroutine jobs or un-isolated Flow collectors directly into Swift 6 actors, triggering silent data races and thread-pool deadlock. 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftLeaking unconfined Kotlin coroutine jobs or un-isolated Flow collectors directly into Swift 6 actors, triggering silent data races and thread-pool deadlock.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 InconsistencyAI 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:

1

Engineers MUST ALWAYS bridge Kotlin Flows into Swift 6 `AsyncStream<T>` using value-type or `Sendable`-conforming payloads before consumption in native actors.

Engineers MUST ALWAYS bridge Kotlin Flows into Swift 6 `AsyncStream<T>` using value-type or `Sendable`-conforming payloads before consumption in native actors.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT expose raw mutable Kotlin classes across the Swift Export boundary

Engineers MUST NOT expose raw mutable Kotlin classes across the Swift Export boundary; all shared data structures crossing the bridge MUST be immutable data classes mapped to Swift Sendable structs.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST ALWAYS tie Kotlin Coroutine cancellation to native Swift `Task` cancellation using `withTaskCancellationHandler` or structured cooperative cancellation primitives.

Engineers MUST ALWAYS tie Kotlin Coroutine cancellation to native Swift `Task` cancellation using `withTaskCancellationHandler` or structured cooperative cancellation primitives.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Code SHOULD wrap UI-bound Kotlin suspend functions directly within `@MainActor` isolated Swift methods to prevent implicit thread hops to generic Swift cooperative worker threads.

Code SHOULD wrap UI-bound Kotlin suspend functions directly within `@MainActor` isolated Swift methods to prevent implicit thread hops to generic Swift cooperative worker threads.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Services MUST NOT execute blocking Kotlin synchronous interop functions from within a Swift 6 `actor` isolation domain without dispatching to a dedicated non-cooperative background queue.

Services MUST NOT execute blocking Kotlin synchronous interop functions from within a Swift 6 `actor` isolation domain without dispatching to a dedicated non-cooperative background queue.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Components NEVER store direct long-lived references to native Swift actors inside long-running Kotlin shared singletons or companion objects due to retain-cycle and dead-lock hazards during actor re-entrancy.

Components NEVER store direct long-lived references to native Swift actors inside long-running Kotlin shared singletons or companion objects due to retain-cycle and dead-lock hazards during actor re-entrancy.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Kotlin 2.1 Swift Export and Swift 6 Actor Boundary Isolation critical for AI coding assistants?

Enforces strict isolation boundaries and execution context affinity when bridging Kotlin Multiplatform (KMP) 2.1 Swift Export coroutine primitives into native Swift 6 Actor environments. Prevents cross-runtime thread pool corruption, un-isolated data races, and Swift 6 Sendable conformance violations by mandating disciplined AsyncStream transformations and explicit MainActor context dispatching. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Leaking unconfined Kotlin coroutine jobs or un-isolated Flow collectors directly into Swift 6 actors, triggering silent data races and thread-pool deadlock.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →
mobile
106

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

mobile
70

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

mobile
58

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

Kotlin