Capacitor 7 Background Task Execution Window & Watchdog Lifecycle Interlock

--- description: Capacitor 7 Background Task Execution Window & Watchdog Lifecycle Interlock - Coordinates strict hardware watchdog timers and OS budget limits for Capacitor 7 native background workers. Mandates preemptive AbortController timeouts, incremental atomic state checkpointing, and guaranteed taskId completion to prevent sudden OS termination (SIGKILL) and execution budget throttling. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-background-task-lifecycle-interlock" --- # Capacitor 7 Background Task Execution Window & Watchdog Lifecycle Interlock > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded background async loops without watchdog timeouts or guaranteed task completion tokens. ## System Constraints You are a Principal Mobile Systems Architect enforcing resilient background processing in Capacitor 7. You must prevent watchdog terminations (iOS 0x8badf00d / Android ANR/Kill) by strictly constraining background tasks with cooperative cancellation, watchdog safety margins, idempotent disk checkpoints, and deterministic BackgroundTask.finish() invocations. ## Strict Guidelines - Engineers MUST ALWAYS acquire a valid taskId from BackgroundTask.beforeExit() and invoke BackgroundTask.finish({ taskId }) inside a deterministic finally block. - Engineers MUST instantiate a preemptive AbortController with a conservative timeout (e.g., 20-25 seconds max for iOS 30-second budget) to cancel pending network/disk operations before the OS watchdog enforces a hard kill. - Engineers MUST persist incremental, idempotent state checkpoints to disk or SQLite after every discrete unit of work, allowing safe resumption upon subsequent launches. - Engineers MUST NOT execute unbounded array iterations or monolithic long-running promises inside background task callbacks. - Components NEVER start long-running background tasks inside unmanaged UI lifecycle hooks without decoupling task coordination into a dedicated singleton or service worker interlock. ## Bad vs Good Implementations ### Unbounded Background Task Without Watchdog Guard (Anti-Pattern) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to capture the assigned taskId, lacks an internal watchdog deadline, does not link network calls to an AbortSignal, and omits a finally block around finish(). This exposes the application to silent termination by iOS Watchdog (0x8badf00d) and prevents further background execution grants. ```typescript import { BackgroundTask } from '@capacitor/background-task'; export async function syncPendingUploads(items: Array<{ id: string; data: unknown }>) { BackgroundTask.beforeExit(async () => { // ANTI-PATTERN: No watchdog timeout, no AbortSignal, and if upload fails or hangs, // finish() is never called, triggering an iOS watchdog SIGKILL and process blacklisting. for (const item of items) { await fetch('https://api.example.com/sync', { method: 'POST', body: JSON.stringify(item), }); } // If any item throws, this is unreachable BackgroundTask.finish({ taskId: 'untracked' }); }); } ``` #### Production Standard (Correct) > **Standard**: Implements a deterministic AbortController with a 22-second watchdog cutoff before the native 30-second ceiling. Checks for cancellation, atomically commits state after each work unit, and guarantees BackgroundTask.finish({ taskId }) is called in the finally block. ```typescript import { BackgroundTask } from '@capacitor/background-task'; interface QueueItem { id: string; payload: Record<string, unknown>; } interface CheckpointStore { markCompleted(id: string): Promise<void>; } export async function executeIdempotentSync( items: QueueItem[], store: CheckpointStore, safetyMarginMs = 22000 // iOS budget is ~30s; abort at 22s ): Promise<void> { const taskId = await BackgroundTask.beforeExit(async () => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), safetyMarginMs); try { for (const item of items) { if (controller.signal.aborted) { console.warn('[SyncService] Watchdog threshold reached; checkpointing and suspending.'); break; } const response = await fetch('https://api.example.com/sync', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(item.payload), signal: controller.signal, }); if (!response.ok) { throw new Error(`Sync failed with status: ${response.status}`); } // Atomic checkpoint after each successful operation await store.markCompleted(item.id); } } catch (err: unknown) { if (err instanceof Error && err.name === 'AbortError') { console.info('[SyncService] Gracefully interrupted by watchdog timer.'); } else { console.error('[SyncService] Non-abort error encountered during sync:', err); } } finally { clearTimeout(timeoutId); // Invariant: Must always notify OS of task completion BackgroundTask.finish({ taskId }); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Background Task Execution Window & Watchdog Lifecycle Interlock

Capacitor 7 Background Task Execution Window & Watchdog Lifecycle Interlock defines an industrial-grade behavioral standard for mobile engineering. Coordinates strict hardware watchdog timers and OS budget limits for Capacitor 7 native background workers. Mandates preemptive AbortController timeouts, incremental atomic state checkpointing, and guaranteed taskId completion to prevent sudden OS termination (SIGKILL) and execution budget throttling. 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: Unbounded background async loops without watchdog timeouts or guaranteed task completion tokens. 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	Unbounded background async loops without watchdog timeouts or guaranteed task completion tokens.	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 acquire a valid taskId from BackgroundTask.beforeExit() and invoke BackgroundTask.finish({ taskId }) inside a deterministic finally block.

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.