Capacitor 7 Native Bridge Background Task Execution & OS Watchdog Invariants

--- description: Capacitor 7 Native Bridge Background Task Execution & OS Watchdog Invariants - Enforces deterministic off-thread execution boundaries for prolonged native bridge operations, cryptographic handshakes, and synchronization routines in Capacitor 7. Prevents WebKit/Chromium main-thread UI freeze and immediate OS watchdog terminations (iOS 0x8badf00d, Android ANR) during lifecycle background transitions. Mandates explicit OS background task token acquisition, native thread offloading, and deterministic execution budgeting. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/main/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-native-bridge-background-execution-boundary" --- # Capacitor 7 Native Bridge Background Task Execution & OS Watchdog Invariants > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dispatching blocking crypto or sync tasks directly over the bridge without native background token allocation or thread isolation ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 bridge safety, off-thread asynchronous dispatching, and background execution boundaries. Mandate that all cryptographic operations, bulk data serialization, and network handshakes lasting longer than 50ms transition off the UI thread and bind strictly to native background execution tokens (UIBackgroundTaskIdentifier / WorkManager / ForegroundService) with deterministic watchdog timeouts. ## Strict Guidelines - Engineers MUST ALWAYS isolate heavy cryptographic handshakes and bulk synchronization into background threads via native thread pools (iOS DispatchQueue.global(qos: .userInitiated) or Android Coroutines Dispatchers.IO) instead of the main bridge thread. - Engineers MUST request explicit OS background task tokens (e.g., UIBackgroundTaskIdentifier on iOS or WorkManager/ForegroundService on Android) before initiating long-running bridge jobs that can cross an appStateChange transition. - Engineers MUST NOT execute blocking synchronous WebKit bridge calls or intensive CPU loops within Web Worker contexts expecting background survival without an active native background registration token. - Services MUST implement a strict 25-second execution ceiling on background tasks to guarantee graceful cleanup before iOS (30s) or Android OS-level watchdog kills (0x8badf00d / ANR). - Components NEVER execute raw long-running async bridge calls without handling appStateChange events and registering native task completion callbacks to prevent leaked system background assertion budgets. ## Bad vs Good Implementations ### Naive Bridge Invocation Subject to Freeze & Termination vs. Resilient Task Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling an unbudgeted native bridge action without acquiring an OS background execution token causes immediate freeze upon backgrounding on iOS, risking corrupt crypto state. Furthermore, passing raw arrays across the bridge blocks JSON serialization on the UI thread. ```typescript import { Plugins } from '@capacitor/core'; const { CryptoSyncPlugin } = Plugins; // ANTI-PATTERN: Direct invocation during UI cycle or backgrounding without task bounds export async function performCryptoSync(payload: Uint8Array): Promise<void> { // If the user backgrounds the app here, WebKit pauses execution immediately, // causing incomplete cryptographic writes or termination by the OS watchdog. const result = await CryptoSyncPlugin.executeSyncHandshake({ data: Array.from(payload) }); console.log('Sync finished', result); } ``` #### Production Standard (Correct) > **Standard**: Acquires an explicit native background token (preventing OS suspension), enforces an explicit 25-second watchdog ceiling before the iOS 30-second kill trigger, optimizes bridge serialization via base64, and guarantees token release in a finally block. ```typescript import { Capacitor } from '@capacitor/core'; import { App } from '@capacitor/app'; import { registerPlugin } from '@capacitor/core'; interface SyncPlugin { executeSyncHandshake(options: { base64Data: string; timeoutMs: number }): Promise<{ success: boolean }>; requestBackgroundTask(): Promise<{ taskId: string }>; endBackgroundTask(options: { taskId: string }): Promise<void>; } const NativeSync = registerPlugin<SyncPlugin>('CryptoSyncPlugin'); const WATCHDOG_SAFETY_CEILING_MS = 25000; export async function performCryptoSync(payload: Uint8Array): Promise<void> { let taskId: string | null = null; const abortController = new AbortController(); // Convert binary to Base64 to bypass heavy JSON array parsing on the main bridge thread const base64Data = btoa(String.fromCharCode(...payload)); try { if (Capacitor.isNativePlatform()) { const token = await NativeSync.requestBackgroundTask(); taskId = token.taskId; } const timeoutPromise = new Promise<never>((_, reject) => { setTimeout(() => { abortController.abort(); reject(new Error('Operation exceeded watchdog safety ceiling')); }, WATCHDOG_SAFETY_CEILING_MS); }); await Promise.race([ NativeSync.executeSyncHandshake({ base64Data, timeoutMs: WATCHDOG_SAFETY_CEILING_MS }), timeoutPromise ]); } catch (error) { console.error('Critical sync handshake failure or watchdog trigger:', error); throw error; } finally { if (taskId && Capacitor.isNativePlatform()) { await NativeSync.endBackgroundTask({ taskId }); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native Bridge Background Task Execution & OS Watchdog Invariants

Capacitor 7 Native Bridge Background Task Execution & OS Watchdog Invariants defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic off-thread execution boundaries for prolonged native bridge operations, cryptographic handshakes, and synchronization routines in Capacitor 7. Prevents WebKit/Chromium main-thread UI freeze and immediate OS watchdog terminations (iOS 0x8badf00d, Android ANR) during lifecycle background transitions. Mandates explicit OS background task token acquisition, native thread offloading, and deterministic execution budgeting. 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 blocking crypto or sync tasks directly over the bridge without native background token allocation or thread isolation 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 blocking crypto or sync tasks directly over the bridge without native background token allocation or thread isolation	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 heavy cryptographic handshakes and bulk synchronization into background threads via native thread pools (iOS DispatchQueue.global(qos

Engineers MUST ALWAYS isolate heavy cryptographic handshakes and bulk synchronization into background threads via native thread pools (iOS DispatchQueue.global(qos: .userInitiated) or Android Coroutines Dispatchers.IO) instead of the main bridge thread.

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.