Swift 6 Actor Isolation and Sendable Boundaries for Native Bridge Interfaces

--- description: Swift 6 Actor Isolation and Sendable Boundaries for Native Bridge Interfaces - Enforces Swift 6 complete strict concurrency checking across native platform hardware listeners and hybrid cross-platform runtimes (React Native, Flutter, Kotlin Multiplatform). Eliminates thread sanitizer (TSan) race conditions by mandating Sendable DTOs and isolating native bridge modules to dedicated actors or @MainActor boundaries. globs: ios/**/*.{swift,h,m}, packages/**/ios/**/*.{swift,h,m}, **/NativeModules/**/*.{swift,h,m}, **/*Bridge*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swift-6-strict-concurrency-actor-bridge-guardrail" --- # Swift 6 Actor Isolation and Sendable Boundaries for Native Bridge Interfaces > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Accessing Mutable Native Sensor and Bridge State Across Arbitrary Hardware Callback Queues ## System Constraints You are a Principal Mobile Architect enforcing Swift 6 Strict Concurrency invariants across native bridging boundaries. Reject any code sharing mutable references between native hardware listener delegates (CoreLocation, CoreMotion, AVFoundation) and bridge runtime dispatchers. Enforce actor isolation, Sendable value semantics, and structured task hops for cross-thread boundary crossings. ## Strict Guidelines - Engineers MUST ALWAYS isolate native bridge modules to either '@MainActor' or a custom dedicated 'actor' when interfacing with cross-platform event dispatchers. - Engineers MUST NOT capture mutable class instances or non-Sendable dictionaries directly within asynchronous hardware delegate callbacks. - Hardware listener delegates (e.g., CLLocationManagerDelegate, AVCaptureVideoDataOutputSampleBufferDelegate) MUST bridge data through immutable, frozen 'Sendable' structs before dispatching cross-thread. - Bridge export methods exposed to JavaScript or foreign runtimes MUST mark incoming payloads with concrete Sendable conformance and validate cross-actor isolation boundaries. - Services MUST NEVER invoke cross-platform event emitters synchronously from background hardware threads; state updates MUST hop safely across actor boundaries via structured asynchronous Tasks. ## Bad vs Good Implementations ### Native Hardware Sensor Bridge: Unsafe Global Dispatch vs. Actor-Isolated Sendable Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Violates Swift 6 strict concurrency: captures mutable state inside a non-isolated delegate closure, modifies non-synchronized dictionary state across queues, and leaks non-Sendable collection references across concurrency domains without compiler enforcement. ```swift import Foundation import CoreMotion // UNSAFE: Unchecked mutable state captured across concurrent hardware queues @objc(SensorBridge) public class SensorBridge: NSObject { private let motionManager = CMMotionManager() private var latestData: [String: Double] = [:] @objc public func startUpdates(callback: @escaping ([String: Double]) -> Void) { motionManager.startAccelerometerUpdates(to: .main) { [weak self] data, error in guard let self = self, let data = data else { return } // Data race: mutates class-level dictionary on arbitrary dispatch self.latestData["x"] = data.acceleration.x self.latestData["y"] = data.acceleration.y self.latestData["z"] = data.acceleration.z callback(self.latestData) // Non-Sendable reference escaping isolation } } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates sensor telemetry inside an immutable Sendable value struct and isolates the native bridge module to @MainActor. Safely bridges the background hardware OperationQueue to the runtime boundary using a structured Task with compiler-verified actor hops. ```swift import Foundation import CoreMotion // SAFE: Immutable, compiler-enforced Sendable payload public struct SensorReading: Sendable, Codable { public let x: Double public let y: Double public let z: Double } // SAFE: Strict actor isolation guaranteeing race-free cross-boundary communication @MainActor public final class SensorBridge: NSObject { private let motionManager = CMMotionManager() private let updateQueue: OperationQueue = { let queue = OperationQueue() queue.name = "com.app.sensor.hardware" queue.maxConcurrentOperationCount = 1 return queue }() public func startUpdates(onReading: @escaping @Sendable @MainActor (SensorReading) -> Void) { motionManager.startAccelerometerUpdates(to: updateQueue) { data, _ in guard let data = data else { return } let reading = SensorReading( x: data.acceleration.x, y: data.acceleration.y, z: data.acceleration.z ) // Structured actor hop delivering immutable Sendable data Task { @MainActor in onReading(reading) } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Swift 6 Actor Isolation and Sendable Boundaries for Native Bridge Interfaces

Swift 6 Actor Isolation and Sendable Boundaries for Native Bridge Interfaces defines an industrial-grade behavioral standard for mobile engineering. Enforces Swift 6 complete strict concurrency checking across native platform hardware listeners and hybrid cross-platform runtimes (React Native, Flutter, Kotlin Multiplatform). Eliminates thread sanitizer (TSan) race conditions by mandating Sendable DTOs and isolating native bridge modules to dedicated actors or @MainActor boundaries. 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: Accessing Mutable Native Sensor and Bridge State Across Arbitrary Hardware Callback 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	Accessing Mutable Native Sensor and Bridge State Across Arbitrary Hardware Callback 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 native bridge modules to either '@MainActor' or a custom dedicated 'actor' when interfacing with cross-platform event dispatchers.

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.