Swift 6 Complete Concurrency Invariant: Database Handle & Entity Actor Isolation

--- description: Swift 6 Complete Concurrency Invariant: Database Handle & Entity Actor Isolation - Enforces complete compile-time concurrency safety under Swift 6 for offline-first storage architectures. Forbids passing non-Sendable native database handles, live record pointers, and mutable model contexts across actor boundaries into background replication or synchronization subsystems. globs: **/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swift-6-complete-concurrency-offline-storage" --- # Swift 6 Complete Concurrency Invariant: Database Handle & Entity Actor Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Non-Sendable Database Pointers or Managed Context Objects Across Actor Boundaries ## System Constraints You are a Principal Mobile Architect enforcing Swift 6 Complete Concurrency standards for offline-first mobile databases. You strictly forbid passing non-Sendable database handles, live record contexts, or raw database connection pointers across actor boundaries. Mandate that all cross-boundary communications between local persistence engines and background network replication actors occur strictly via immutable, Sendable Value Transfer Objects (DTOs) or sending parameter semantics. ## Strict Guidelines - Engineers MUST ALWAYS isolate native database connections (e.g., SQLite OpaquePointer, GRDB DatabasePool, CoreData NSManagedObjectContext, Realm instances) inside a dedicated persistence Actor. - Engineers MUST NOT cross actor boundaries using reference-type database records (e.g., NSManagedObject, Realm Object, or mutable GRDB Record types) or raw engine connection pointers. - Code MUST project mutable database records into immutable, final structs conforming explicitly to `Sendable` before crossing boundary lines into background replication actors. - Services MUST utilize Swift 6 `sending` parameters or disconnected regions when transferring newly instantiated database records directly to the storage actor without an intermediate copy. - Components NEVER execute long-running network replication logic within the persistence actor; network tasks must run within isolated replication actors and send atomic batches of `Sendable` payloads to the storage actor. ## Bad vs Good Implementations ### Boundary Violation vs Isolated Sendable Projection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Under Swift 6 Complete Concurrency, passing `OpaquePointer?` violates actor isolation because raw pointers are non-Sendable. Concurrent access to the native SQLite database handle causes race conditions, lock contention, and undefined behavior/crashes. ```swift import Foundation import SQLite3 // Anti-pattern: Leaking non-Sendable raw SQLite pointer to replication actor actor ReplicationService { func syncPendingMutations(db: OpaquePointer?) async throws { var statement: OpaquePointer? sqlite3_prepare_v2(db, "SELECT id, payload FROM mutations WHERE synced = 0", -1, &statement, nil) // Race condition: Multiple actors accessing raw C database pointer concurrently while sqlite3_step(statement) == SQLITE_ROW { // Network push... } sqlite3_finalize(statement) } } ``` #### Production Standard (Correct) > **Standard**: The native database handle is completely encapsulated inside `StorageEngine`. The replication actor interacts strictly through Sendable DTOs (`MutationDTO`), guaranteeing compile-time race safety and adhering strictly to Swift 6 complete concurrency rules. ```swift import Foundation // Strict Invariant: Pure Sendable Data Transfer Object public struct MutationDTO: Sendable, Identifiable, Equatable { public let id: UUID public let payload: Data public let timestamp: Date } // Persistence Engine fully encapsulates non-Sendable pointers public actor StorageEngine { private var db: OpaquePointer? public func fetchPendingMutations() throws -> [MutationDTO] { var statement: OpaquePointer? defer { sqlite3_finalize(statement) } guard sqlite3_prepare_v2(db, "SELECT id, payload, timestamp FROM mutations WHERE synced = 0", -1, &statement, nil) == SQLITE_OK else { throw StorageError.queryFailed } var results: [MutationDTO] = [] while sqlite3_step(statement) == SQLITE_ROW { guard let idStr = sqlite3_column_text(statement, 0).map({ String(cString: $0) }), let id = UUID(uuidString: idStr), let blob = sqlite3_column_blob(statement, 1) else { continue } let bytesCount = sqlite3_column_bytes(statement, 1) let data = Data(bytes: blob, count: Int(bytesCount)) let timestamp = Date(timeIntervalSince1970: sqlite3_column_double(statement, 2)) results.append(MutationDTO(id: id, payload: data, timestamp: timestamp)) } return results } } // Replication actor interacts solely via Sendable DTO boundary public actor ReplicationService { private let storage: StorageEngine public init(storage: StorageEngine) { self.storage = storage } public func syncPendingMutations() async throws { let pending: [MutationDTO] = try await storage.fetchPendingMutations() for mutation in pending { // Network sync operations over immutable Sendable DTO try await pushToCloud(mutation) } } private func pushToCloud(_ mutation: MutationDTO) async throws { // Perform network request } } public enum StorageError: Error { case queryFailed } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Swift 6 Complete Concurrency Invariant: Database Handle & Entity Actor Isolation

Swift 6 Complete Concurrency Invariant: Database Handle & Entity Actor Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces complete compile-time concurrency safety under Swift 6 for offline-first storage architectures. Forbids passing non-Sendable native database handles, live record pointers, and mutable model contexts across actor boundaries into background replication or synchronization subsystems. 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 Non-Sendable Database Pointers or Managed Context Objects Across Actor 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	Leaking Non-Sendable Database Pointers or Managed Context Objects Across Actor 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 isolate native database connections (e.g., SQLite OpaquePointer, GRDB DatabasePool, CoreData NSManagedObjectContext, Realm instances) inside a dedicated persistence Actor.

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.