Strict Threading Isolation for KMP SQLite WAL Mode across Native Apple Queues and Coroutines

--- description: Strict Threading Isolation for KMP SQLite WAL Mode across Native Apple Queues and Coroutines - Enforces a strict single-writer, dedicated-reader thread boundary for SQLite Write-Ahead Logging (WAL) in Kotlin Multiplatform targets. Prevents priority inversion, thread pool starvation, and hard database lock deadlocks between Apple Grand Central Dispatch (GCD) workloops and Kotlin Coroutine dispatchers by isolating SQLite connections to specialized, confined dispatchers. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/appleMain/**/*.kt, **/database/**/*.kt, **/db/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-sqlite-wal-threading-boundary" --- # Strict Threading Isolation for KMP SQLite WAL Mode across Native Apple Queues and Coroutines > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dispatching SQLite WAL Mutations Across Unconfined Coroutine Pools and Native Apple GCD Queues ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform database internals. Enforce strict single-threaded write boundaries and dedicated concurrent reader boundaries for SQLite WAL configurations across JVM/Android and Apple Native targets. Forbid raw Dispatchers.IO, GlobalScope, or unconfined GCD queue switching during active SQLite transactions. ## Strict Guidelines - Engineers MUST ALWAYS isolate SQLite write transactions to a dedicated single-threaded dispatcher (e.g., `newSingleThreadContext` or limited parallelisms `Dispatchers.IO.limitedParallelism(1)`) on Apple and common native targets. - Engineers MUST configure SQLite WAL mode explicitly with PRAGMA synchronous = NORMAL and busy_timeout set before any read or write transactions execute. - Engineers MUST NOT switch Coroutine contexts (e.g., calling `withContext(Dispatchers.Main)` or calling out to asynchronous GCD queues) while holding an open SQLite write transaction lock. - Code SHOULD enforce separate connection handles for read pools and write pools on Apple native runtimes to prevent iOS GCD threads from blocking the WAL writer thread. - Services MUST ensure database operations initiated from Swift/Objective-C interop are routed through the confined Kotlin multiplatform dispatcher rather than capturing the calling GCD queue. ## Bad vs Good Implementations ### Unconfined Context Switching Inside SQLite Write Transactions #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using unconfined Dispatchers.IO allows concurrent executions of write transactions on multiple OS threads. Furthermore, invoking nested coroutines or suspension points within an active SQLite transaction violates WAL single-writer invariants, stalling Apple GCD threads and leading to SQLITE_BUSY or SQLITE_LOCKED deadlocks. ```kotlin class NoteRepository(private val database: AppDatabase) { // ANTI-PATTERN: Default IO dispatcher permits multi-threaded concurrent write attempts // and switching context while inside a transaction causes WAL lock-wait deadlocks on iOS. suspend fun saveNoteWithAudit(note: Note, auditEvent: suspend () -> Unit) = withContext(Dispatchers.IO) { database.transaction { database.noteQueries.insert(note.id, note.title, note.content) // Suspending and potentially switching threads inside an open SQLite transaction! runBlocking { auditEvent() } } } } ``` #### Production Standard (Correct) > **Standard**: Constraining write operations to `Dispatchers.IO.limitedParallelism(1)` guarantees that exactly one thread accesses the WAL write lock at any time. Reads execute concurrently on a limited read dispatcher pool without context switches during SQLite transactions, fully resolving iOS GCD and KMP thread contention. ```kotlin class NoteRepository( private val database: AppDatabase, // Dedicated single-threaded writer boundary ensures invariant adherence across platforms private val writeDispatcher: CoroutineDispatcher = Dispatchers.IO.limitedParallelism(1), private val readDispatcher: CoroutineDispatcher = Dispatchers.IO.limitedParallelism(4) ) { suspend fun saveNote(note: Note) = withContext(writeDispatcher) { // Transaction is atomic, strictly synchronous within the write thread, with zero context switching database.transaction { database.noteQueries.insert(note.id, note.title, note.content) } } suspend fun getNote(id: String): Note? = withContext(readDispatcher) { database.noteQueries.selectById(id).executeAsOneOrNull() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict Threading Isolation for KMP SQLite WAL Mode across Native Apple Queues and Coroutines

Strict Threading Isolation for KMP SQLite WAL Mode across Native Apple Queues and Coroutines defines an industrial-grade behavioral standard for mobile engineering. Enforces a strict single-writer, dedicated-reader thread boundary for SQLite Write-Ahead Logging (WAL) in Kotlin Multiplatform targets. Prevents priority inversion, thread pool starvation, and hard database lock deadlocks between Apple Grand Central Dispatch (GCD) workloops and Kotlin Coroutine dispatchers by isolating SQLite connections to specialized, confined dispatchers. 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 SQLite WAL Mutations Across Unconfined Coroutine Pools and Native Apple GCD Queues 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 SQLite WAL Mutations Across Unconfined Coroutine Pools and Native Apple GCD Queues	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 SQLite write transactions to a dedicated single-threaded dispatcher (e.g., `newSingleThreadContext` or limited parallelisms `Dispatchers.IO.limitedParallelism(1)`) on Apple and common native targets.

Engineers MUST ALWAYS isolate SQLite write transactions to a dedicated single-threaded dispatcher (e.g., `newSingleThreadContext` or limited parallelisms `Dispatchers.IO.limitedParallelism(1)`) on Apple and common native targets.

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.