Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard

--- description: Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard - Enforces strict thread-boundary isolation and atomic synchronization handshakes between native Darwin dispatch queues and Android ART worker threads in Kotlin Multiplatform. Prevents priority-inversion deadlocks and memory tearing caused by holding platform-specific OS locks across coroutine suspension points or mixing unconfined atomic updates with native thread schedulers. globs: shared/**/commonMain/**/*.kt, shared/**/iosMain/**/*.kt, shared/**/androidMain/**/*.kt, **/*Repository*.kt, **/*Bridge*.kt, **/*Store*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-thread-boundary-mutex-handshake-standard" --- # Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Boundary Lock Leaks, Suspension Point Lock-Holding, and Mixed Dispatcher Priority Inversion ## System Constraints You are a Principal Mobile Architect enforcing the Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard. Mandate invariants that prevent priority-inversion deadlocks, state torn writes, and thread starvation across Darwin GCD queues and Android ART thread pools. Forbid holding OS-level locks (such as NSRecursiveLock, os_unfair_lock, or Java platform monitors) across Kotlin coroutine suspension points. Enforce non-blocking lock-free state machines or kotlinx.coroutines.sync.Mutex strictly confined to cooperative coroutine scopes. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict separation between platform synchronization primitives (e.g., NSRecursiveLock, NSLock, synchronized blocks) and cooperative coroutine suspension points. - Engineers MUST NOT acquire or hold platform-native mutexes, spinlocks, or dispatch semaphores across any suspending function invocation. - Code SHOULD use non-blocking lock-free atomic references (`kotlinx.atomicfu` or `kotlin.concurrent.AtomicReference`) for cross-boundary state handshakes between native platforms and common coroutine dispatchers. - Services MUST route platform-native callbacks (e.g., Darwin GCD dispatch blocks or Android AIDL/Binder threads) into a confined, non-suspending atomic transition queue before delegating to coroutines. - Components NEVER execute blocking platform-wait primitives inside coroutine dispatchers or cross-dispatch uncoordinated Mutex locks that bridge different Quality-of-Service (QoS) queues without explicit priority inheritance. ## Bad vs Good Implementations ### Darwin/Android Thread Boundary State Handshake #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Holding a native Darwin or JVM OS lock across coroutine suspension points causes priority inversion and deadlock. When the coroutine suspends, the underlying OS thread is yielded, but the platform lock remains locked. If another native queue attempts to acquire the lock at a higher priority or on the same thread pool, deadlocks and queue starvation occur. ```kotlin import kotlinx.coroutines.* import platform.Foundation.NSLock class SharedSessionStore { private val platformLock = NSLock() private var sessionState: String = "INITIAL" // ANTI-PATTERN: Holding platform OS lock across a coroutine suspension point. // Leads to priority-inversion deadlocks between GCD dispatch threads and coroutine worker pools. suspend fun updateSessionState(newState: String, syncRemote: suspend () -> Unit) { platformLock.lock() try { sessionState = newState // Suspending while holding native lock causes thread starvation and memory tear risk syncRemote() } finally { platformLock.unlock() } } } ``` #### Production Standard (Correct) > **Standard**: Replaces platform-blocking OS locks with `kotlinx.coroutines.sync.Mutex` and an `AtomicReference`. Coroutine suspension yields cooperatively without blocking native OS threads or Darwin GCD queues, preventing priority-inversion deadlocks and memory tearing. ```kotlin import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.withLock import kotlin.concurrent.AtomicReference sealed interface SessionState { data object Initial : SessionState data class Active(val token: String) : SessionState } class SharedSessionStore { // INVARIANT: Cooperative coroutine Mutex for suspension boundaries private val coroutineMutex = Mutex() // Lock-free atomic reference accessible safely across native thread boundaries without OS blocking private val atomicState = AtomicReference<SessionState>(SessionState.Initial) fun getSnapshot(): SessionState = atomicState.value suspend fun updateSessionState(newToken: String, syncRemote: suspend () -> Unit) { // Handshake: Cooperative Mutex protects the asynchronous operation coroutineMutex.withLock { val nextState = SessionState.Active(newToken) // Atomic lock-free CAS guarantees memory barrier visibility across ART and Darwin GCD atomicState.value = nextState syncRemote() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard

Kotlin Multiplatform Thread-Boundary Mutex Handshake Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread-boundary isolation and atomic synchronization handshakes between native Darwin dispatch queues and Android ART worker threads in Kotlin Multiplatform. Prevents priority-inversion deadlocks and memory tearing caused by holding platform-specific OS locks across coroutine suspension points or mixing unconfined atomic updates with native thread schedulers. 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: Cross-Boundary Lock Leaks, Suspension Point Lock-Holding, and Mixed Dispatcher Priority Inversion 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	Cross-Boundary Lock Leaks, Suspension Point Lock-Holding, and Mixed Dispatcher Priority Inversion	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 enforce strict separation between platform synchronization primitives (e.g., NSRecursiveLock, NSLock, synchronized blocks) and cooperative coroutine suspension points.

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.