Kotlin Multiplatform 2.1 Swift-Export ABI Exception Boundary Fencing

--- description: Kotlin Multiplatform 2.1 Swift-Export ABI Exception Boundary Fencing - Enforces deterministic ABI boundary fencing across Kotlin 2.1 Swift-Export surfaces. Prevents unhandled Kotlin coroutine panics and unwrapped Native runtime exceptions from crossing into Darwin threads and triggering fatal SIGABRT crashes in native iOS host processes. globs: **/shared/src/iosMain/**/*.kt, **/shared/src/commonMain/**/*.kt, **/iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-exception-fencing" --- # Kotlin Multiplatform 2.1 Swift-Export ABI Exception Boundary Fencing > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Naked Suspend Functions and Unchecked Kotlin Exceptions Across Direct Swift-Export ABI Boundaries ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform (KMP 2.1+) and native iOS interop. Your mandate is to enforce strict ABI exception boundary fences on all APIs exposed to Swift via Swift-Export. In Kotlin/Native, any unhandled Kotlin Throwable that escapes an exported function across the direct Swift ABI boundary without an explicit @Throws annotation or defensive envelope will invoke the runtime abort hook (SIGABRT), immediately terminating the iOS app. You must ensure all boundary functions intercept unhandled panics, preserve coroutine cancellation semantics, and return safe typed envelopes or strictly annotated throws. ## Strict Guidelines - Engineers MUST ALWAYS annotate Swift-exported functions that throw exceptions with `@Throws` listing explicit exception classes, or encapsulate the return type in an explicit boundary `Result` or `SwiftExportEnvelope`. - Engineers MUST NEVER allow unhandled `RuntimeException` or `Error` types to unwind across foreign function boundaries into Swift call frames without capture. - Engineers MUST ALWAYS rethrow `kotlinx.coroutines.CancellationException` directly when catching exceptions in suspend functions to preserve iOS Swift Task cooperative cancellation. - Swift-Export direct-call interop bridges MUST install a dedicated `CoroutineExceptionHandler` at the native dispatcher root to capture orphan asynchronous coroutine failures. - Components NEVER expose raw Kotlin `suspend` functions to Swift without a top-level defensive `runCatchingSafe` fence that translates unexpected domain failures into structured bridge errors. ## Bad vs Good Implementations ### Unfenced Swift-Export Suspend Function vs. Hardened Safe-Result Marshal Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin/Native 2.1 Swift-Export bridges suspend functions to Swift `async throws`. However, if the Kotlin function throws an exception not declared in an `@Throws` annotation, the Kotlin/Native runtime treats it as an unhandled panic at the ABI boundary and aborts the iOS host process via SIGABRT, rendering Swift's `do { try await ... } catch` useless. ```kotlin // shared/src/iosMain/kotlin/com/example/api/UserProfileBridge.kt package com.example.api import kotlinx.coroutines.delay class UserProfileBridge(private val repository: UserRepository) { // VIOLATION: Naked suspend function exported to Swift. // If repository throws an unannotated exception (e.g. NetworkException, DatabaseException), // Kotlin/Native runtime triggers fatal terminate_handler() (SIGABRT), crashing the iOS app. suspend fun fetchUserProfile(userId: String): UserProfile { delay(100) if (userId.isBlank()) { throw IllegalArgumentException("Invalid user ID") } return repository.getUser(userId) // Can throw arbitrary unchecked exceptions } } ``` #### Production Standard (Correct) > **Standard**: The hardened boundary catches all unexpected non-cancellation throwables and serializes them into a sealed `BridgeResult` envelope. `CancellationException` is explicitly rethrown and documented via `@Throws(NativeCancellationException::class)`, maintaining Swift `async`/`await` Task cancellation invariants without risking unhandled process termination. ```kotlin // shared/src/iosMain/kotlin/com/example/api/UserProfileBridge.kt package com.example.api import kotlinx.coroutines.CancellationException import kotlin.coroutines.cancellation.CancellationException as NativeCancellationException sealed interface BridgeResult<out T> { data class Success<out T>(val value: T) : BridgeResult<T> data class Failure(val message: String, val code: String) : BridgeResult<Nothing> } class UserProfileBridge(private val repository: UserRepository) { // COMPLIANT: Explicit boundary fence. Catches non-cancellation errors, preserves // structured concurrency cancellation, and guarantees no unexpected panics hit the ABI. @Throws(NativeCancellationException::class) suspend fun fetchUserProfile(userId: String): BridgeResult<UserProfile> { return try { if (userId.isBlank()) { BridgeResult.Failure("Invalid user ID", "INVALID_ARGUMENT") } else { BridgeResult.Success(repository.getUser(userId)) } } catch (e: CancellationException) { // Mandatory: cooperative Swift Task cancellation must propagate throw e } catch (t: Throwable) { // Defensive fallback: prevent SIGABRT on foreign call frame BridgeResult.Failure(t.message ?: "Unknown error", t::class.simpleName ?: "Throwable") } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 Swift-Export ABI Exception Boundary Fencing

Kotlin Multiplatform 2.1 Swift-Export ABI Exception Boundary Fencing defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic ABI boundary fencing across Kotlin 2.1 Swift-Export surfaces. Prevents unhandled Kotlin coroutine panics and unwrapped Native runtime exceptions from crossing into Darwin threads and triggering fatal SIGABRT crashes in native iOS host processes. 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: Exposing Naked Suspend Functions and Unchecked Kotlin Exceptions Across Direct Swift-Export ABI 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	Exposing Naked Suspend Functions and Unchecked Kotlin Exceptions Across Direct Swift-Export ABI 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 annotate Swift-exported functions that throw exceptions with `@Throws` listing explicit exception classes, or encapsulate the return type in an explicit boundary `Result` or `SwiftExportEnvelope`.

Engineers MUST ALWAYS annotate Swift-exported functions that throw exceptions with `@Throws` listing explicit exception classes, or encapsulate the return type in an explicit boundary `Result` or `SwiftExportEnvelope`.

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.