Capacitor 7 Headless Background Runner Memory and Watchdog Execution Quotas

--- description: Capacitor 7 Headless Background Runner Memory and Watchdog Execution Quotas - Enforces deterministic watchdog timeout budgets and strict heap allocation boundaries for @capacitor/background-runner headless workers. Preempts silent OS termination (iOS Jetsam/0x8badf00d and Android WorkManager 10-minute/OOM kills) by mandating cooperative AbortController timeouts, state checkpointing, and zero-allocation payload streaming. globs: capacitor.config.ts, src/background/**/*.{ts,js}, src/**/background*.{ts,js}, src/**/workers/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-background-runner-execution-quota-guardrail" --- # Capacitor 7 Headless Background Runner Memory and Watchdog Execution Quotas > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Headless Background Execution Without Cooperative Watchdog Abort or Memory Constraints ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Background Runner reliability guardrails. Headless JavaScript workers run in constrained native engines (JavaScriptCore on iOS, V8/WebView on Android) with aggressive OS watchdogs and low Jetsam/OOM memory ceilings. You must mandate cooperative cancellation via AbortSignal with strict watchdog budgets (< 20s on iOS), incremental state checkpointing, and memory bounded chunk processing to prevent unlogged OS SIGKILLs. ## Strict Guidelines - Engineers MUST ALWAYS bound headless background event handlers with a cooperative watchdog timeout (strictly <= 20,000ms for iOS compatibility) via AbortController. - Engineers MUST NOT buffer unbounded JSON responses, Blobs, or large ArrayBuffers (> 2MB) inside the background runner context. - Code MUST checkpoint progress incrementally to native persistent storage (e.g., CapacitorKV) after processing each granular chunk to survive OS preemption. - Services MUST explicitly nullify transient buffers and detach event listeners in a finally block to facilitate immediate garbage collection prior to native suspension. - Background handlers NEVER initiate open-ended recursion, unbounded loops, or persistent WebSocket connections in headless task definitions. ## Bad vs Good Implementations ### Headless Background Runner Task Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fetches an unbounded payload directly into memory and lacks an internal execution timeout. When iOS BackgroundTasks or Android WorkManager limits are reached, the OS terminates the process with 0x8badf00d or Jetsam with zero logging, leaving local state corrupted. ```typescript import { CapacitorKV } from '@capacitor/background-runner'; // ANTI-PATTERN: No watchdog budget, unbound memory allocation, vulnerable to OS Jetsam/0x8badf00d addEventListener('syncData', async (resolve, reject, args) => { try { const response = await fetch('https://api.example.com/v1/sync/all-records'); const massivePayload = await response.json(); // May exceed 15MB heap threshold in headless worker for (const record of massivePayload.items) { await processRecord(record); } CapacitorKV.set({ key: 'lastSync', value: Date.now().toString() }); resolve(); } catch (err) { reject(err); } }); ``` #### Production Standard (Correct) > **Standard**: Implements a strict 20-second watchdog timer matching mobile OS background execution limits. Uses chunked memory payloads, incremental KV checkpointing, and cooperative AbortSignal checks to exit cleanly before native termination. ```typescript import { CapacitorKV } from '@capacitor/background-runner'; const WATCHDOG_TIMEOUT_MS = 20_000; // iOS allows ~30s max; 20s provides safe margin for checkpointing const CHUNK_SIZE = 50; addEventListener('syncData', async (resolve, reject, args) => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), WATCHDOG_TIMEOUT_MS); try { const lastCursor = (await CapacitorKV.get({ key: 'sync_cursor' }))?.value ?? '0'; const response = await fetch(`https://api.example.com/v1/sync/chunked?cursor=${lastCursor}&limit=${CHUNK_SIZE}`, { signal: controller.signal }); if (!response.ok) throw new Error(`HTTP error: ${response.status}`); const chunk = await response.json(); let processedCursor = lastCursor; for (const item of chunk.items) { if (controller.signal.aborted) { break; // Preempt loop before native watchdog strikes } await processRecord(item); processedCursor = item.id; } // Incremental checkpoint before teardown await CapacitorKV.set({ key: 'sync_cursor', value: processedCursor }); clearTimeout(timeoutId); resolve(); } catch (error: unknown) { clearTimeout(timeoutId); if (error instanceof Error && error.name === 'AbortError') { // Gracefully resolve so native runner registers partial success instead of hard crash resolve(); return; } reject(error); } finally { clearTimeout(timeoutId); } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Headless Background Runner Memory and Watchdog Execution Quotas

Capacitor 7 Headless Background Runner Memory and Watchdog Execution Quotas defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic watchdog timeout budgets and strict heap allocation boundaries for @capacitor/background-runner headless workers. Preempts silent OS termination (iOS Jetsam/0x8badf00d and Android WorkManager 10-minute/OOM kills) by mandating cooperative AbortController timeouts, state checkpointing, and zero-allocation payload streaming. 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 Headless Background Execution Without Cooperative Watchdog Abort or Memory Constraints 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 Headless Background Execution Without Cooperative Watchdog Abort or Memory Constraints	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 bound headless background event handlers with a cooperative watchdog timeout (strictly <= 20,000ms for iOS compatibility) via AbortController.

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.