KMP SQLDelight Thread-Confined Isolation & Zero-Deadlock Concurrency

--- description: KMP SQLDelight Thread-Confined Isolation & Zero-Deadlock Concurrency - Enforces deterministic, thread-confined transaction boundaries and isolated driver instances across Kotlin Multiplatform targets. Prevents SQLite POSIX-thread deadlocks (SQLITE_BUSY/SQLITE_LOCKED) caused by Coroutine worker hopping on Android Dispatchers.IO and native iOS Grand Central Dispatch queue context switching during active transaction locks. globs: **/commonMain/**/*.kt, **/androidMain/**/*.kt, **/iosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-sqldelight-thread-confined-isolation" --- # KMP SQLDelight Thread-Confined Isolation & Zero-Deadlock Concurrency > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dispatching Suspending SQLDelight Transactions Across Multi-Threaded Dispatchers Causing SQLite Thread-Ownership Violation ## System Constraints You are a Principal Engineer enforcing Kotlin Multiplatform SQLDelight Thread-Confined Cross-Platform Isolation. Mandate strict single-thread write confinement, non-suspending synchronous atomic transaction blocks, and dedicated serial dispatchers to guarantee zero SQLite deadlocks across Android Coroutines and Apple Grand Central Dispatch. ## Strict Guidelines - Engineers MUST ALWAYS isolate all write transactions to a dedicated, single-threaded CoroutineDispatcher (e.g., via `newSingleThreadContext` or bounded platform serial queues) on both Android and Native platforms. - Engineers MUST NOT invoke suspending functions or switch Coroutine dispatchers within an active SQLDelight `transaction { ... }` block. - Code SHOULD configure iOS `NativeSqliteDriver` with explicit connection pooling and single-threaded execution (`maxReaderConnections = 1` or thread-confined serial execution) when concurrent write access is possible. - Services MUST ensure that read-only queries utilizing `asFlow()` are mapped and observed with `.flowOn(Dispatchers.Default)` without borrowing or locking the dedicated write-confined dispatcher. - Components NEVER execute concurrent nested write transactions across disparate thread boundaries or native GCD background queues. ## Bad vs Good Implementations ### Anti-Pattern: Suspending Transaction across Multi-Threaded Dispatcher Pool #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing transactions on `Dispatchers.IO` allows coroutines to suspend and resume on different OS threads. Because SQLite native locks on iOS/Android bind to the originating POSIX thread ID, resuming on a different thread triggers `SQLITE_MISUSE` or permanent deadlocks under iOS GCD. ```kotlin class UserRepository(private val db: AppDatabase) { // DANGEROUS: Dispatchers.IO uses an elastic thread pool. // Resuming a coroutine inside transaction can hop OS threads, // violating SQLite POSIX thread-affinity and deadlocking native iOS. suspend fun updateUserAndProfile(user: User, profile: Profile) = withContext(Dispatchers.IO) { db.transaction { db.userQueries.updateUser(user.name, user.id) // Bad: Suspending call inside a transaction // Causes coroutine suspension and thread hopping mid-transaction delay(10) db.profileQueries.updateProfile(profile.bio, user.id) } } } ``` #### Production Standard (Correct) > **Standard**: Confines write operations to a deterministic single-threaded dispatcher, preventing coroutine thread-hopping while guaranteeing that the native SQLite transaction lock remains on a single OS thread from `BEGIN` to `COMMIT`. ```kotlin class UserRepository( private val db: AppDatabase, // Dedicated single-threaded dispatcher strictly for DB writes @Named("DbWriteDispatcher") private val dbWriteDispatcher: CoroutineDispatcher ) { suspend fun updateUserAndProfile(user: User, profile: Profile) = withContext(dbWriteDispatcher) { // Guarantees all writes and atomic transactions execute on the exact same thread db.transaction { db.userQueries.updateUser(user.name, user.id) // Invariant: Non-suspending, synchronous execution within transaction boundaries db.profileQueries.updateProfile(profile.bio, user.id) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP SQLDelight Thread-Confined Isolation & Zero-Deadlock Concurrency

KMP SQLDelight Thread-Confined Isolation & Zero-Deadlock Concurrency defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, thread-confined transaction boundaries and isolated driver instances across Kotlin Multiplatform targets. Prevents SQLite POSIX-thread deadlocks (SQLITE_BUSY/SQLITE_LOCKED) caused by Coroutine worker hopping on Android Dispatchers.IO and native iOS Grand Central Dispatch queue context switching during active transaction locks. 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: Dispatching Suspending SQLDelight Transactions Across Multi-Threaded Dispatchers Causing SQLite Thread-Ownership Violation 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	Dispatching Suspending SQLDelight Transactions Across Multi-Threaded Dispatchers Causing SQLite Thread-Ownership Violation	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 isolate all write transactions to a dedicated, single-threaded CoroutineDispatcher (e.g., via `newSingleThreadContext` or bounded platform serial queues) on both Android and Native platforms.

Engineers MUST ALWAYS isolate all write transactions to a dedicated, single-threaded CoroutineDispatcher (e.g., via `newSingleThreadContext` or bounded platform serial queues) on both Android and Native platforms.

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.