Capacitor 7 Swift Concurrency Bridge Actor Boundary & Thread Isolation

--- description: "Capacitor 7 Swift Concurrency Bridge Actor Boundary & Thread Isolation - Enforces strict isolation of high-throughput Capacitor 7 native plugin methods away from the UIKit main runloop onto dedicated Swift actors. Prevents bridge reentrancy deadlocks and UI frame drops during high-frequency sensor, biometric, or peripheral streaming by decoupling data ingestion from WebKit notification dispatches." globs: "ios/**/*.swift, ios/Plugin/**/*.swift, ios/App/**/*.swift" alwaysApply: true license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-swift-actor-bridge-boundary" --- # Capacitor 7 Swift Concurrency Bridge Actor Boundary & Thread Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing High-Frequency Sensor Capture and Bridge Resolution Directly on @MainActor or Blocking the Bridge Dispatch Queue ## System Constraints You are a Principal Mobile Architect specializing in Capacitor 7 iOS plugin development and modern Swift Concurrency (Swift 6 strict concurrency). Your task is to enforce strict actor isolation boundaries between the Capacitor JavaScript-to-native message bridge and native high-frequency background pipelines. Ensure all sensor feeds, BLE streaming, and CPU-intensive processing occur on custom Swift background actors, dispatching to the WebKit bridge only via non-blocking, rate-limited notification callbacks. ## Strict Guidelines - Engineers MUST ALWAYS isolate high-frequency data ingestion (>= 60Hz, e.g., CoreMotion, CoreBluetooth, AVCapture) inside a dedicated Swift `actor` or `@globalActor` rather than the plugin class instance or `@MainActor`. - Engineers MUST NOT synchronously await long-running native background tasks or perform synchronous semaphore waits inside `@objc` Capacitor plugin entry points. - Plugin methods receiving high-frequency updates MUST decouple ingestion from bridge notification via an `AsyncStream` or ring buffer, batching or throttling emissions before calling `notifyListeners`. - Bridge communications via `call.resolve()` and `notifyListeners()` MUST be scheduled safely without causing actor-isolated state leaks, marking bridge export points `nonisolated` where appropriate while jumping explicitly to the main thread only when interacting directly with WebKit view components. - Engineers MUST configure `CAPPlugin` subclasses with explicit concurrency boundaries, ensuring Swift 6 compiler checks pass with `-strict-concurrency=complete`. ## Bad vs Good Implementations ### High-Frequency Sensor Bridge (Swift) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly running 100Hz sensor updates on OperationQueue.main floods the main thread runloop, delays UI rendering in WKWebView, and causes deadlocks when the web layer invokes bridge commands while the main queue is saturated with listener notifications. ```swift import Foundation import Capacitor import CoreMotion @objc(SensorPlugin) public class SensorPlugin: CAPPlugin { private let motionManager = CMMotionManager() // ANTI-PATTERN: Direct execution on main queue, resolving directly inside high-frequency callback @objc func startSensorStream(_ call: CAPPluginCall) { guard motionManager.isAccelerometerAvailable else { call.reject("Unavailable"); return } motionManager.accelerometerUpdateInterval = 0.01 // 100Hz motionManager.startAccelerometerUpdates(to: .main) { [weak self] data, error in guard let data = data else { return } // Causes severe main thread contention and WebKit bridge reentrancy deadlocks self?.notifyListeners("accelerometerData", data: [ "x": data.acceleration.x, "y": data.acceleration.y, "z": data.acceleration.z ]) } call.resolve() } } ``` #### Production Standard (Correct) > **Standard**: Decouples the CoreMotion hardware callback from the main thread onto a dedicated background OperationQueue and encapsulates hardware interaction in an isolated Swift actor (`SensorPipeline`). Emits bridge events without monopolizing the UIKit runloop. ```swift import Foundation import Capacitor import CoreMotion actor SensorPipeline { private let motionManager = CMMotionManager() private var updateTask: Task<Void, Never>? func start(handler: @Sendable @escaping (SIMD3<Double>) -> Void) { guard motionManager.isAccelerometerAvailable else { return } motionManager.accelerometerUpdateInterval = 0.01 let queue = OperationQueue() queue.qualityOfService = .userInteractive motionManager.startAccelerometerUpdates(to: queue) { data, _ in guard let acc = data?.acceleration else { return } handler(SIMD3(acc.x, acc.y, acc.z)) } } func stop() { motionManager.stopAccelerometerUpdates() updateTask?.cancel() } } @objc(SensorPlugin) public class SensorPlugin: CAPPlugin, @unchecked Sendable { private let pipeline = SensorPipeline() private var throttleTask: Task<Void, Never>? @objc func startSensorStream(_ call: CAPPluginCall) { call.keepAlive = true Task { await pipeline.start { [weak self] reading in // Batching/Yielding to prevent bridge saturation self?.notifyListeners("accelerometerData", data: [ "x": reading.x, "y": reading.y, "z": reading.z ], retainUntilConsumed: false) } call.resolve() } } @objc func stopSensorStream(_ call: CAPPluginCall) { Task { await pipeline.stop() call.resolve() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Swift Concurrency Bridge Actor Boundary & Thread Isolation

Capacitor 7 Swift Concurrency Bridge Actor Boundary & Thread Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation of high-throughput Capacitor 7 native plugin methods away from the UIKit main runloop onto dedicated Swift actors. Prevents bridge reentrancy deadlocks and UI frame drops during high-frequency sensor, biometric, or peripheral streaming by decoupling data ingestion from WebKit notification dispatches. 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: Executing High-Frequency Sensor Capture and Bridge Resolution Directly on @MainActor or Blocking the Bridge Dispatch Queue 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	Executing High-Frequency Sensor Capture and Bridge Resolution Directly on @MainActor or Blocking the Bridge Dispatch Queue	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 high-frequency data ingestion (>= 60Hz, e.g., CoreMotion, CoreBluetooth, AVCapture) inside a dedicated Swift `actor` or `@globalActor` rather than the plugin class instance or `@MainActor`.

Engineers MUST ALWAYS isolate high-frequency data ingestion (>= 60Hz, e.g., CoreMotion, CoreBluetooth, AVCapture) inside a dedicated Swift `actor` or `@globalActor` rather than the plugin class instance or `@MainActor`.

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.